1 /* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
9 typedef (MatchPatternSet or sequence<DOMString>) MatchPatternSetOrStringSequence;
10 typedef (MatchGlob or UTF8String) MatchGlobOrString;
12 [ChromeOnly, Exposed=Window]
13 interface MozDocumentMatcher {
15 constructor(MozDocumentMatcherInit options);
18 * Returns true if the script's match and exclude patterns match the given
19 * URI, without reference to attributes such as `allFrames`.
21 boolean matchesURI(URI uri);
24 * Returns true if the given window matches. This should be used to
25 * determine whether to run a script in a window at load time. Use
26 * ignorePermissions to match without origin permissions in MV3.
28 boolean matchesWindowGlobal(WindowGlobalChild windowGlobal,
29 optional boolean ignorePermissions = false);
32 * If true, match all frames. If false, match only top-level frames.
35 readonly attribute boolean allFrames;
38 * If we can't check extension has permissions to access the URI upfront,
39 * set the flag to perform the origin check at runtime, upon matching.
40 * This is always true in MV3, where host permissions are optional.
43 readonly attribute boolean checkPermissions;
46 * If true, this (misleadingly-named, but inherited from Chrome) attribute
47 * causes us to match frames with URLs which inherit a principal that
48 * matches one of the match patterns, such as about:blank or about:srcdoc.
49 * If false, we only match frames with an explicit matching URL.
52 readonly attribute boolean matchAboutBlank;
55 * The outer window ID of the frame in which to run the script, or 0 if it
56 * should run in the top-level frame. Should only be used for
57 * dynamically-injected scripts.
60 readonly attribute unsigned long long? frameID;
63 * The set of match patterns for URIs of pages in which this script should
64 * run. This attribute is mandatory, and is a prerequisite for all other
68 readonly attribute MatchPatternSet matches;
71 * A set of match patterns for URLs in which this script should not run,
72 * even if they match other include patterns or globs.
75 readonly attribute MatchPatternSet? excludeMatches;
78 * The originAttributesPattern for which this script should be enabled for.
81 readonly attribute any originAttributesPatterns;
84 * The policy object for the extension that this matcher belongs to.
87 readonly attribute WebExtensionPolicy? extension;
90 dictionary MozDocumentMatcherInit {
91 boolean allFrames = false;
93 boolean checkPermissions = false;
95 sequence<OriginAttributesPatternDictionary>? originAttributesPatterns = null;
97 boolean matchAboutBlank = false;
99 unsigned long long? frameID = null;
101 required MatchPatternSetOrStringSequence matches;
103 MatchPatternSetOrStringSequence? excludeMatches = null;
105 sequence<MatchGlobOrString>? includeGlobs = null;
107 sequence<MatchGlobOrString>? excludeGlobs = null;
109 boolean hasActiveTabPermission = false;
113 * Describes the earliest point in the load cycle at which a script should
116 enum ContentScriptRunAt {
118 * The point in the load cycle just after the document element has been
119 * inserted, before any page scripts have been allowed to run.
123 * The point after which the page DOM has fully loaded, but before all page
124 * resources have necessarily been loaded. Corresponds approximately to the
125 * DOMContentLoaded event.
129 * The first point after the page and all of its resources has fully loaded
130 * when the event loop is idle, and can run scripts without delaying a paint
136 [ChromeOnly, Exposed=Window]
137 interface WebExtensionContentScript : MozDocumentMatcher {
139 constructor(WebExtensionPolicy extension,
140 WebExtensionContentScriptInit options);
143 * The earliest point in the load cycle at which this script should run. For
144 * static content scripts, in extensions which were present at browser
145 * startup, the browser makes every effort to make sure that the script runs
146 * no later than this point in the load cycle. For dynamic content scripts,
147 * and scripts from extensions installed during this session, the scripts
148 * may run at a later point.
151 readonly attribute ContentScriptRunAt runAt;
154 * A set of paths, relative to the extension root, of CSS sheets to inject
155 * into matching pages.
157 [Cached, Constant, Frozen]
158 readonly attribute sequence<DOMString> cssPaths;
161 * A set of paths, relative to the extension root, of JavaScript scripts to
162 * execute in matching pages.
164 [Cached, Constant, Frozen]
165 readonly attribute sequence<DOMString> jsPaths;
168 dictionary WebExtensionContentScriptInit : MozDocumentMatcherInit {
169 ContentScriptRunAt runAt = "document_idle";
171 sequence<DOMString> cssPaths = [];
173 sequence<DOMString> jsPaths = [];