A content script is a part of your extension that runs in the context of a particular web page (as opposed to background scripts which are part of the extension, or scripts which are part of the web site itself, such as those loaded using the
<script>
element).
Background scripts can access all the WebExtension JavaScript APIs , but they can't directly access the content of web pages. So if your extension needs to do that, you need content scripts.
Just like the scripts loaded by normal web pages, content scripts can read and modify the content of their pages using the standard DOM APIs.
Content scripts can only access a small subset of the WebExtension APIs , but they can communicate with background scripts using a messaging system, and thereby indirectly access the WebExtension APIs.
注意： Content scripts are blocked on the following domains:
If you try to inject a content script into a page in these domains, it fails and the page logs a CSP 错误。
Because these restrictions include addons.mozilla.org, users may attempt to use your extension immediately after installation—only to find that it doesn't work! You may want to add an appropriate warning, or an
onboarding page
to move users away from
addons.mozilla.org
.
注意：
Values added to the global scope of a content script with
let foo
or
window.foo = "bar"
may disappear due to bug
1408996
.
You can load a content script into a web page in one of three ways:
使用
content_scripts
key in your
manifest.json
, you can ask the browser to load a content script whenever the browser loads a page whose URL
matches a given pattern
.
使用
contentScripts
API, you can ask the browser to load a content script whenever the browser loads a page whose URL
matches a given pattern
. (This is similar to method 1,
except
that you can add and remove content scripts at runtime.)
使用
tabs.executeScript()
API, you can load a content script into a specific tab whenever you want. (For example, in response to the user clicking on a
browser action
)。
There is only one global scope per frame, per extension . This means that variables from one content script can directly be accessed by another content script, regardless of how the content script was loaded.
Using methods (1) and (2), you can only load scripts into pages whose URLs can be represented using a match pattern .
Using method (3), you can also load scripts into pages packaged with your extension, but you can't load scripts into privileged browser pages (like "
about:debugging
" or "
about:addons
").
注意： Dynamic JS module imports are now working in content scripts. For more details, see bug 1536094 . Only URLs with the moz-extension scheme are allowed, which excludes data URLs ( bug 1587336 ).
Content scripts can access and modify the page's DOM, just like normal page scripts can. They can also see any changes that were made to the DOM by page scripts.
However, content scripts get a "clean" view of the DOM. This means:
In Firefox, this behavior is called Xray vision .
Consider a web page like this:
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
</head>
<body>
<script src="page-scripts/page-script.js"></script>
</body>
</html>
脚本
page-script.js
does this:
// page-script.js
// add a new element to the DOM
let p = document.createElement("p");
p.textContent = "This paragraph was added by a page script.";
p.setAttribute("id", "page-script-para");
document.body.appendChild(p);
// define a new property on the window
window.foo = "This global variable was added by a page script";
// redefine the built-in window.confirm() function
window.confirm = function() {
alert("The page script has also redefined 'confirm'");
}
Now an extension injects a content script into the page:
// content-script.js
// can access and modify the DOM
let pageScriptPara = document.getElementById("page-script-para");
pageScriptPara.style.backgroundColor = "blue";
// can't see properties added by page-script.js
console.log(window.foo); // undefined
// sees the original form of redefined properties
window.confirm("Are you sure?"); // calls the original window.confirm()
The same is true in reverse; page scripts cannot see JavaScript properties added by content scripts.
This means that content scripts can rely on DOM properties behaving predictably, without worrying about its variables clashing with variables from the page script.
One practical consequence of this behavior is that a content script doesn't have access to any JavaScript libraries loaded by the page. So, for example, if the page includes jQuery, the content script can't see it.
If a content script needs to use a JavaScript library, then the library itself should be injected as a content script alongside the content script that wants to use it:
"content_scripts": [
{
"matches": ["*://*.mozilla.org/*"],
"js": ["jquery.js", "content-script.js"]
}
]
注意： Firefox does provide some APIs that enable content scripts to access JavaScript objects created by page scripts, and to expose their own JavaScript objects to page scripts.
见 Sharing objects with page scripts 了解更多细节。
In addition to the standard DOM APIs, content scripts can use the following WebExtension APIs:
从
extension
:
从
runtime
:
从
i18n
:
从
menus
:
Everything from:
Content scripts can make requests using the normal
window.XMLHttpRequest
and
window.fetch()
API。
注意：
In Firefox, content script requests (for example, using
fetch()
) happen in the context of an extension, so you must provide an absolute URL to reference page content.
In Chrome, these requests happen in context of the page, so they are made to a relative URL. For example,
/api
is sent to
https://«current page URL»/api
.
Content scripts get the same cross-domain privileges as the rest of the extension: so if the extension has requested cross-domain access for a domain using the
permissions
key in
manifest.json
, then its content scripts get access that domain as well.
This is accomplished by exposing more privileged XHR and fetch instances in the content script, which has the side-effect of not setting the
Origin
and
Referer
headers like a request from the page itself would; this is often preferable to prevent the request from revealing its cross-origin nature.
注意：
In Firefox, extensions that need to perform requests that behave as if they were sent by the content itself can use
content.XMLHttpRequest
and
content.fetch()
代替。
For cross-browser extensions, the presence of these methods must be feature-detected.
注意： In Chrome, starting with version 73, content scripts are subject to the same CORS policy as the page they are running within. Only backend scripts have elevated cross-domain privileges. See Changes to Cross-Origin Requests in Chrome Extension Content Scripts .
Although content scripts can't directly use most of the WebExtension APIs, they can communicate with the extension's background scripts using the messaging APIs, and can therefore indirectly access all the same APIs that the background scripts can.
There are two basic patterns for communicating between the background scripts and content scripts:
To send one-off messages, with an optional response, you can use the following APIs:
| In content script | In background script | |
|---|---|---|
| Send a message |
browser.runtime.sendMessage()
|
browser.tabs.sendMessage()
|
| Receive a message |
browser.runtime.onMessage
|
browser.runtime.onMessage
|
For example, here's a content script that listens for click events in the web page.
If the click was on a link, it sends a message to the background page with the target URL:
// content-script.js
window.addEventListener("click", notifyExtension);
function notifyExtension(e) {
if (e.target.tagName != "A") {
return;
}
browser.runtime.sendMessage({"url": e.target.href});
}
The background script listens for these messages and displays a notification using the
notifications
API:
// background-script.js
browser.runtime.onMessage.addListener(notify);
function notify(message) {
browser.notifications.create({
"type": "basic",
"iconUrl": browser.extension.getURL("link.png"),
"title": "You clicked a link!",
"message": message.url
});
}
(This example code is lightly adapted from the notify-link-clicks-i18n example on GitHub.)
Sending one-off messages can get cumbersome if you are exchanging a lot of messages between a background script and a content script. So an alternative pattern is to establish a longer-lived connection between the two contexts, and use this connection to exchange messages.
Both sides have a
runtime.Port
object, which they can use to exchange messages.
To create the connection:
runtime.onConnect
tabs.connect()
(if connecting to a content script)
runtime.connect()
(if connecting to a background script)
This returns a
runtime.Port
对象。
runtime.onConnect
listener gets passed its own
runtime.Port
对象。
Once each side has a port, the two sides can:
runtime.Port.postMessage()
runtime.Port.onMessage()
For example, as soon as it loads, the following content script:
Port
in a variable
myPort
myPort
(and logs them)
myPort
to sends messages to the background script when the user clicks the document
// content-script.js
let myPort = browser.runtime.connect({name:"port-from-cs"});
myPort.postMessage({greeting: "hello from content script"});
myPort.onMessage.addListener(function(m) {
console.log("In content script, received message from background script: ");
console.log(m.greeting);
});
document.body.addEventListener("click", function() {
myPort.postMessage({greeting: "they clicked the page!"});
});
The corresponding background script:
portFromCS
portFromCS
, when the user clicks the extension's browser action
// background-script.js
let portFromCS;
function connected(p) {
portFromCS = p;
portFromCS.postMessage({greeting: "hi there content script!"});
portFromCS.onMessage.addListener(function(m) {
portFromCS.postMessage({greeting: "In background script, received message from content script:" + m.greeting});
});
}
browser.runtime.onConnect.addListener(connected);
browser.browserAction.onClicked.addListener(function() {
portFromCS.postMessage({greeting: "they clicked the button!"});
});
If you have multiple content scripts communicating at the same time, you might want to store connections to them in an array.
// background-script.js
let ports = []
function connected(p) {
ports[p.sender.tab.id] = p
//...
}
browser.runtime.onConnect.addListener(connected)
browser.browserAction.onClicked.addListener(function() {
ports.forEach( p => {
p.postMessage({greeting: "they clicked the button!"})
})
});
The choice between one-off and connection-based messaging depends on how your extension expects to make use of messaging.
The recommended best practices are:
Use one-off messages when…
runtime.onMessage
calls).
Use connection-based messaging when…
By default, content scripts don't get access to objects created by page scripts. However, they can communicate with page scripts using the DOM
window.postMessage
and
window.addEventListener
API。
例如：
// page-script.js
let messenger = document.getElementById("from-page-script");
messenger.addEventListener("click", messageContentScript);
function messageContentScript() {
window.postMessage({
direction: "from-page-script",
message: "Message from the page"
}, "*");
}
// content-script.js
window.addEventListener("message", function(event) {
if (event.source == window &&
event.data &&
event.data.direction == "from-page-script") {
alert("Content script received message: \"" + event.data.message + "\"");
}
});
For a complete working example of this, visit the demo page on GitHub and follow the instructions.
警告： Be very careful when interacting with untrusted web content in this manner! Extensions are privileged code which can have powerful capabilities and hostile web pages can easily trick them into accessing those capabilities.
To give a trivial example, suppose the content script code that receives the message does something like this:
// content-script.js
window.addEventListener("message", function(event) {
if (event.source == window &&
event.data.direction &&
event.data.direction == "from-page-script") {
eval(event.data.message);
}
});
Now the page script can run any code with all the privileges of the content script.
eval()
in content scripts
eval
always runs code in the context of the
content script
, not in the context of the page.
若调用
eval()
, it runs code in the context of the
content script
.
若调用
window.eval()
, it runs code in the context of the
page
.
For example, consider a content script like this:
// content-script.js
window.eval('window.x = 1;');
eval('window.y = 2');
console.log(`In content script, window.x: ${window.x}`);
console.log(`In content script, window.y: ${window.y}`);
window.postMessage({
message: "check"
}, "*");
This code just creates some variables
x
and
y
使用
window.eval()
and
eval()
, logs their values, and then messages the page.
On receiving the message, the page script logs the same variables:
window.addEventListener("message", function(event) {
if (event.source === window && event.data && event.data.message === "check") {
console.log(`In page script, window.x: ${window.x}`);
console.log(`In page script, window.y: ${window.y}`);
}
});
In Chrome, this produces output like this:
In content script, window.x: 1 In content script, window.y: 2 In page script, window.x: undefined In page script, window.y: undefined
In Firefox, this produces output like this:
In content script, window.x: undefined In content script, window.y: 2 In page script, window.x: 1 In page script, window.y: undefined
The same applies to
setTimeout()
,
setInterval()
，和
Function()
.
警告： Be very careful when running code in the context of the page!
The page's environment is controlled by potentially malicious web pages, which can redefine objects you interact with to behave in unexpected ways:
// page.js redefines console.log
let original = console.log;
console.log = function() {
original(true);
}
// content-script.js calls the redefined version
window.eval('console.log(false)');
最后修改： , 由 MDN 贡献者