1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235
|
// Copyright 2023 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// Use the <code>userScripts</code> API to execute user scripts in the User
// Scripts context.
namespace userScripts {
// The JavaScript world for a user script to execute within.
enum ExecutionWorld {
// Specifies the execution environment of the DOM, which is the execution
// environment shared with the host page's JavaScript.
MAIN,
// Specifies the execution environment that is specific to user scripts and
// is exempt from the page's CSP.
USER_SCRIPT
};
// The source of the script to inject.
dictionary ScriptSource {
// A string containing the JavaScript code to inject. Exactly one of
// <code>file</code> or <code>code</code> must be specified.
DOMString? code;
// The path of the JavaScript file to inject relative to the extension's
// root directory. Exactly one of <code>file</code> or <code>code</code>
// must be specified.
DOMString? file;
};
// Describes a user script to be injected into a web page registered through
// this API. The script is injected into a page if its URL matches any of
// "matches" or "include_globs" patterns, and the URL doesn't match
// "exclude_matches" and "exclude_globs" patterns.
dictionary RegisteredUserScript {
// If 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.
boolean? allFrames;
// Excludes pages that this user script would otherwise be injected into.
// See <a href="develop/concepts/match-patterns">Match Patterns</a> for more details on
// the syntax of these strings.
DOMString[]? excludeMatches;
// The ID of the user script specified in the API call. This property must
// not start with a '_' as it's reserved as a prefix for generated script
// IDs.
DOMString id;
// Specifies wildcard patterns for pages this user script will be injected
// into.
DOMString[]? includeGlobs;
// Specifies wildcard patterns for pages this user script will NOT be
// injected into.
DOMString[]? excludeGlobs;
// The list of ScriptSource objects defining sources of scripts to be
// injected into matching pages.
// This property must be specified for ${ref:register}, and when specified
// it must be a non-empty array.
ScriptSource[]? js;
// Specifies which pages this user script will be injected into. See
// <a href="develop/concepts/match-patterns">Match Patterns</a> for more details on the
// syntax of these strings. This property must be specified for
// ${ref:register}.
DOMString[]? matches;
// Specifies when JavaScript files are injected into the web page. The
// preferred and default value is <code>document_idle</code>.
extensionTypes.RunAt? runAt;
// The JavaScript execution environment to run the script in. The default is
// <code>`USER_SCRIPT`</code>.
ExecutionWorld? world;
// Specifies the user script world ID to execute in. If omitted, the script
// will execute in the default user script world. Only valid if `world` is
// omitted or is `USER_SCRIPT`. Values with leading underscores (`_`) are
// reserved.
DOMString? worldId;
};
// An object used to filter user scripts for ${ref:getScripts}.
dictionary UserScriptFilter {
// $(ref:getScripts) only returns scripts with the IDs specified in this
// list.
DOMString[]? ids;
};
dictionary InjectionTarget {
// 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.
boolean? allFrames;
// The IDs of specific documentIds to inject into. This must not be set if
// <code>frameIds</code> is set.
DOMString[]? documentIds;
// The IDs of specific frames to inject into.
long[]? frameIds;
// The ID of the tab into which to inject.
long tabId;
};
dictionary InjectionResult {
// The document associated with the injection.
DOMString documentId;
// The frame associated with the injection.
long frameId;
// The result of the script execution.
any? result;
// The error, if any. <code>error</code> and <code>result</code> are
// mutually exclusive.
DOMString? error;
};
dictionary UserScriptInjection {
// Whether the injection should be triggered in the target as soon as
// possible. Note that this is not a guarantee that injection will occur
// prior to page load, as the page may have already loaded by the time the
// script reaches the target.
boolean? injectImmediately;
// The list of ScriptSource objects defining sources of scripts to be
// injected into the target.
ScriptSource[] js;
// Details specifying the target into which to inject the script.
InjectionTarget target;
// The JavaScript "world" to run the script in. The default is
// <code>USER_SCRIPT</code>.
ExecutionWorld? world;
// Specifies the user script world ID to execute in. If omitted, the script
// will execute in the default user script world. Only valid if `world` is
// omitted or is `USER_SCRIPT`. Values with leading underscores (`_`) are
// reserved.
DOMString? worldId;
};
// An object used to update the <code>`USER_SCRIPT`</code> world
// configuration. If a property is not specified, it will reset it to its
// default value.
dictionary WorldProperties{
// Specifies the ID of the specific user script world to update.
// If not provided, updates the properties of the default user script world.
// Values with leading underscores (`_`) are reserved.
DOMString? worldId;
// Specifies the world csp. The default is the <code>`ISOLATED`</code>
// world csp.
DOMString? csp;
// Specifies whether messaging APIs are exposed. The default is
// <code>false</code>.
boolean? messaging;
};
callback RegisterCallback = void();
callback GetScriptsCallback = void(RegisteredUserScript[] scripts);
callback UnregisterCallback = void();
callback UpdateCallback = void();
callback ExecuteCallback = void(InjectionResult[] result);
callback ConfigureWorldCallback = void();
callback GetAllWorldConfigurationsCallback = void(WorldProperties[] worlds);
callback ResetWorldConfigurationCallback = void();
interface Functions {
// Registers one or more user scripts for this extension.
// |scripts|: Contains a list of user scripts to be registered.
// |callback|: Called once scripts have been fully registered or if an error
// has ocurred.
static void register(
RegisteredUserScript[] scripts,
optional RegisterCallback callback);
// Returns all dynamically-registered user scripts for this extension.
// |filter|: If specified, this method returns only the user scripts that
// match it.
// |callback|: Called once scripts have been fully registered or if an error
// occurs.
static void getScripts(
optional UserScriptFilter filter,
GetScriptsCallback callback);
// Unregisters all dynamically-registered user scripts for this extension.
// |filter|: If specified, this method unregisters only the user scripts
// that match it.
// |callback|: Called once scripts have been fully unregistered or if an
// error ocurs
static void unregister(
optional UserScriptFilter filter,
UnregisterCallback callback);
// Updates one or more user scripts for this extension.
// |scripts|: Contains a list of user scripts to be updated. A property is
// only updated for the existing script if it is specified in this object.
// If there are errors during script parsing/file validation, or if the IDs
// specified do not correspond to a fully registered script, then no scripts
// are updated.
// |callback|: Called once scripts have been fully updated or if an error
// occurs.
static void update(
RegisteredUserScript[] scripts,
optional UpdateCallback callback);
// Injects a script into a target context. By default, the script will be
// run at <code>document_idle</code>, or immediately if the page has already
// loaded. If the <code>injectImmediately</code> property is set, the script
// will inject without waiting, even if the page has not finished loading.
// If the script evaluates to a promise, the browser will wait for the
// promise to settle and return the resulting value.
static void execute(
UserScriptInjection injection,
optional ExecuteCallback callback);
// Configures the <code>`USER_SCRIPT`</code> execution environment.
// |properties|: Contains the user script world configuration.
// |callback|: Called once world hase been configured.
static void configureWorld(
WorldProperties properties,
optional ConfigureWorldCallback callback);
// Retrieves all registered world configurations.
// |callback|: Called with the registered world configurations.
static void getWorldConfigurations(
GetAllWorldConfigurationsCallback callback);
// Resets the configuration for a user script world. Any scripts that inject
// into the world with the specified ID will use the default world
// configuration.
// |worldId|: The ID of the user script world to reset. If omitted, resets
// the default world's configuration.
// |callback|: Called when the configuration is reset.
static void resetWorldConfiguration(
optional DOMString worldId,
ResetWorldConfigurationCallback callback);
};
};
|