File: user_scripts.idl

package info (click to toggle)
chromium 139.0.7258.127-1
  • links: PTS, VCS
  • area: main
  • in suites:
  • size: 6,122,068 kB
  • sloc: cpp: 35,100,771; ansic: 7,163,530; javascript: 4,103,002; python: 1,436,920; asm: 946,517; xml: 746,709; pascal: 187,653; perl: 88,691; sh: 88,436; objc: 79,953; sql: 51,488; cs: 44,583; fortran: 24,137; makefile: 22,147; tcl: 15,277; php: 13,980; yacc: 8,984; ruby: 7,485; awk: 3,720; lisp: 3,096; lex: 1,327; ada: 727; jsp: 228; sed: 36
file content (235 lines) | stat: -rw-r--r-- 10,003 bytes parent folder | download | duplicates (6)
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);
  };
};