// 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.
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;
// If specified, specifies a specific user script world ID to execute in.
// Only valid if `world` is omitted or is `USER_SCRIPT`. If omitted, the
// script will execute in the default user script world.
// Values with leading underscores (`_`) are reserved.
// TODO(https://crbug.com/331680187): Remove nodoc.
[nodoc] 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;
};
// 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.
// TODO(https://crbug.com/331680187): Remove nodoc.
[nodoc] 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 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);
// 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.
// TODO(https://crbug.com/331680187): Remove nodoc.
[nodoc] 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.
// TODO(https://crbug.com/331680187): Remove nodoc.
[nodoc] static void resetWorldConfiguration(
optional DOMString worldId,
ResetWorldConfigurationCallback callback);
};
};
Codebase Browser
chromium