Source code
Revision control
Copy as Markdown
Other Tools
[
{
"namespace": "manifest",
"types": [
{
"$extend": "OptionalPermissionNoPrompt",
"choices": [
{
"type": "string",
"enum": ["scripting"]
}
]
}
]
},
{
"namespace": "scripting",
"description": "Use the scripting API to execute script in different contexts.",
"permissions": ["scripting"],
"types": [
{
"id": "ScriptInjection",
"type": "object",
"description": "Details of a script injection",
"properties": {
"args": {
"type": "array",
"optional": true,
"description": "The arguments to curry into a provided function. This is only valid if the <code>func</code> parameter is specified. These arguments must be JSON-serializable.",
"items": { "type": "any" }
},
"files": {
"type": "array",
"optional": true,
"description": "The path of the JS files to inject, relative to the extension's root directory. Exactly one of <code>files</code> and <code>func</code> must be specified.",
"minItems": 1,
"items": { "type": "string" }
},
"func": {
"type": "function",
"optional": true,
"description": "A JavaScript function to inject. This function will be serialized, and then deserialized for injection. This means that any bound parameters and execution context will be lost. Exactly one of <code>files</code> and <code>func</code> must be specified."
},
"target": {
"$ref": "InjectionTarget",
"description": "Details specifying the target into which to inject the script."
},
"world": {
"$ref": "ExecutionWorld",
"optional": true
},
"injectImmediately": {
"type": "boolean",
"optional": true,
"description": "Whether the injection should be triggered in the target as soon as possible (but not necessarily prior to page load)."
}
}
},
{
"id": "InjectionResult",
"type": "object",
"description": "Result of a script injection.",
"properties": {
"frameId": {
"type": "integer",
"description": "The frame ID associated with the injection."
},
"result": {
"type": "any",
"optional": true,
"description": "The result of the script execution."
},
"error": {
"type": "any",
"optional": true,
"description": "The error property is set when the script execution failed. The value is typically an (Error) object with a message property, but could be any value (including primitives and undefined) if the script threw or rejected with such a value."
}
}
},
{
"id": "InjectionTarget",
"type": "object",
"properties": {
"frameIds": {
"type": "array",
"optional": true,
"description": "The IDs of specific frames to inject into.",
"items": { "type": "number" }
},
"allFrames": {
"type": "boolean",
"optional": true,
"description": "Whether the script should inject into all frames within the tab. Defaults to false. This must not be true if <code>frameIds</code> is specified."
},
"tabId": {
"type": "number",
"description": "The ID of the tab into which to inject."
}
}
},
{
"id": "CSSInjection",
"type": "object",
"properties": {
"css": {
"type": "string",
"optional": true,
"description": "A string containing the CSS to inject. Exactly one of <code>files</code> and <code>css</code> must be specified."
},
"files": {
"type": "array",
"optional": true,
"description": "The path of the CSS files to inject, relative to the extension's root directory. Exactly one of <code>files</code> and <code>css</code> must be specified.",
"minItems": 1,
"items": { "type": "string" }
},
"origin": {
"type": "string",
"optional": true,
"enum": ["USER", "AUTHOR"],
"default": "AUTHOR",
"description": "The style origin for the injection. Defaults to <code>'AUTHOR'</code>."
},
"target": {
"$ref": "InjectionTarget",
"description": "Details specifying the target into which to inject the CSS."
}
}
},
{
"id": "ContentScriptFilter",
"type": "object",
"properties": {
"ids": {
"type": "array",
"optional": true,
"description": "The IDs of specific scripts to retrieve with <code>getRegisteredContentScripts()</code> or to unregister with <code>unregisterContentScripts()</code>.",
"items": { "type": "string" }
}
}
},
{
"id": "ExecutionWorld",
"type": "string",
"enum": ["ISOLATED"],
"description": "The JavaScript world for a script to execute within. We currently only support the <code>'ISOLATED'</code> world."
},
{
"id": "RegisteredContentScript",
"type": "object",
"properties": {
"allFrames": {
"type": "boolean",
"optional": true,
"description": "If specified true, it will inject into all frames, even if the frame is not the top-most frame in the tab. Each frame is checked independently for URL requirements; it will not inject into child frames if the URL requirements are not met. Defaults to false, meaning that only the top frame is matched."
},
"excludeMatches": {
"type": "array",
"optional": true,
"description": "Excludes pages that this content script would otherwise be injected into.",
"items": { "type": "string" }
},
"id": {
"type": "string",
"description": "The id of the content script, specified in the API call."
},
"js": {
"type": "array",
"optional": true,
"description": "The list of JavaScript files to be injected into matching pages. These are injected in the order they appear in this array.",
"items": { "$ref": "manifest.ExtensionURL" }
},
"matches": {
"type": "array",
"optional": true,
"description": "Specifies which pages this content script will be injected into. Must be specified for <code>registerContentScripts()</code>.",
"items": { "type": "string" }
},
"runAt": {
"$ref": "extensionTypes.RunAt",
"optional": true,
"description": "Specifies when JavaScript files are injected into the web page. The preferred and default value is <code>document_idle</code>."
},
"persistAcrossSessions": {
"type": "boolean",
"optional": true,
"default": true,
"description": "Specifies if this content script will persist into future sessions. Defaults to true."
},
"css": {
"type": "array",
"optional": true,
"description": "The list of CSS files to be injected into matching pages. These are injected in the order they appear in this array.",
"items": { "$ref": "manifest.ExtensionURL" }
}
}
}
],
"functions": [
{
"name": "executeScript",
"type": "function",
"description": "Injects a script into a target context. The script will be run at <code>document_idle</code>.",
"async": "callback",
"parameters": [
{
"name": "injection",
"$ref": "ScriptInjection",
"description": "The details of the script which to inject."
},
{
"name": "callback",
"type": "function",
"description": "Invoked upon completion of the injection. The resulting array contains the result of execution for each frame where the injection succeeded.",
"parameters": [
{
"name": "results",
"type": "array",
"items": { "$ref": "InjectionResult" }
}
]
}
]
},
{
"name": "insertCSS",
"type": "function",
"description": "Inserts a CSS stylesheet into a target context. If multiple frames are specified, unsuccessful injections are ignored.",
"async": "callback",
"parameters": [
{
"name": "injection",
"$ref": "CSSInjection",
"description": "The details of the styles to insert."
},
{
"name": "callback",
"type": "function",
"description": "Invoked upon completion of the injection.",
"parameters": []
}
]
},
{
"name": "removeCSS",
"type": "function",
"description": "Removes a CSS stylesheet that was previously inserted by this extension from a target context.",
"async": "callback",
"parameters": [
{
"name": "injection",
"$ref": "CSSInjection",
"description": "The details of the styles to remove. Note that the <code>css</code>, <code>files</code>, and <code>origin</code> properties must exactly match the stylesheet inserted through <code>insertCSS</code>. Attempting to remove a non-existent stylesheet is a no-op."
},
{
"name": "callback",
"type": "function",
"description": "Invoked upon completion of the injection.",
"parameters": []
}
]
},
{
"name": "registerContentScripts",
"type": "function",
"description": "Registers one or more content scripts for this extension.",
"async": "callback",
"parameters": [
{
"name": "scripts",
"type": "array",
"description": "Contains a list of scripts to be registered. If there are errors during script parsing/file validation, or if the IDs specified already exist, then no scripts are registered.",
"items": { "$ref": "RegisteredContentScript" }
},
{
"name": "callback",
"type": "function",
"description": "Invoked upon completion of the registration.",
"parameters": []
}
]
},
{
"name": "getRegisteredContentScripts",
"type": "function",
"description": "Returns all dynamically registered content scripts for this extension that match the given filter.",
"async": "callback",
"parameters": [
{
"name": "filter",
"$ref": "ContentScriptFilter",
"optional": true,
"description": "An object to filter the extension's dynamically registered scripts."
},
{
"name": "callback",
"type": "function",
"description": "The resulting array contains the registered content scripts.",
"parameters": [
{
"name": "scripts",
"type": "array",
"items": { "$ref": "RegisteredContentScript" }
}
]
}
]
},
{
"name": "unregisterContentScripts",
"type": "function",
"description": "Unregisters one or more content scripts for this extension.",
"async": "callback",
"parameters": [
{
"name": "filter",
"$ref": "ContentScriptFilter",
"optional": true,
"description": "If specified, only unregisters dynamic content scripts which match the filter. Otherwise, all of the extension's dynamic content scripts are unregistered."
},
{
"name": "callback",
"type": "function",
"description": "Invoked upon completion of the unregistration.",
"parameters": []
}
]
},
{
"name": "updateContentScripts",
"type": "function",
"description": "Updates one or more content scripts for this extension.",
"async": "callback",
"parameters": [
{
"name": "scripts",
"type": "array",
"description": "Contains a list of scripts to be updated. If there are errors during script parsing/file validation, or if the IDs specified do not already exist, then no scripts are updated.",
"items": {
"type": "object",
"$import": "RegisteredContentScript",
"properties": {
"persistAcrossSessions": {
"type": "boolean",
"optional": true,
"description": "Specifies if this content script will persist into future sessions."
}
}
}
},
{
"name": "callback",
"type": "function",
"description": "Invoked when scripts have been updated.",
"parameters": []
}
]
}
]
}
]