WebExtensionContentScript.webidl (7478B)
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/. */ 4 5 interface LoadInfo; 6 interface URI; 7 interface WindowProxy; 8 9 typedef (MatchPatternSet or sequence<DOMString>) MatchPatternSetOrStringSequence; 10 typedef (MatchGlob or UTF8String) MatchGlobOrString; 11 12 [ChromeOnly, Exposed=Window] 13 interface MozDocumentMatcher { 14 [Throws] 15 constructor(MozDocumentMatcherInit options); 16 17 /** 18 * Returns true if the script's match and exclude patterns match the given 19 * URI, without reference to attributes such as `allFrames`. 20 */ 21 boolean matchesURI(URI uri); 22 23 /** 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. 27 */ 28 boolean matchesWindowGlobal(WindowGlobalChild windowGlobal, 29 optional boolean ignorePermissions = false); 30 31 /** 32 * If true, match all frames. If false, match only top-level frames. 33 */ 34 [Constant] 35 readonly attribute boolean allFrames; 36 37 /** 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. 41 */ 42 [Constant] 43 readonly attribute boolean checkPermissions; 44 45 /** 46 * If true, this causes us to match about:blank and about:srcdoc documents by 47 * the URL of the inherit principal, usually the initial URL of the document 48 * that triggered the navigation. 49 * If false, we only match frames with an explicit matching URL. 50 */ 51 [Constant] 52 readonly attribute boolean matchAboutBlank; 53 54 /** 55 * If true, this causes us to match documents with opaque URLs (such as 56 * about:blank, about:srcdoc, data:, blob:, and sandboxed versions thereof) 57 * by the document principal's origin URI. In case of null principals, their 58 * precursor is used for matching. 59 * When true, matchAboutBlank is implicitly true. 60 * If false, we only match frames with an explicit matching URL. 61 */ 62 [Constant] 63 readonly attribute boolean matchOriginAsFallback; 64 65 /** 66 * The outer window ID of the frame in which to run the script, or 0 if it 67 * should run in the top-level frame. Should only be used for 68 * dynamically-injected scripts. 69 */ 70 [Constant] 71 readonly attribute unsigned long long? frameID; 72 73 /** 74 * The set of match patterns for URIs of pages in which this script should 75 * run. This attribute is mandatory, and is a prerequisite for all other 76 * match patterns. 77 */ 78 [Constant] 79 readonly attribute MatchPatternSet matches; 80 81 /** 82 * A set of match patterns for URLs in which this script should not run, 83 * even if they match other include patterns or globs. 84 */ 85 [Constant] 86 readonly attribute MatchPatternSet? excludeMatches; 87 88 /** 89 * Whether the matcher is used by the MV3 userScripts API. 90 * If true, URLs are matched when they match "matches" OR "includeGlobs", 91 * instead of the usual AND. 92 */ 93 [Constant] 94 readonly attribute boolean isUserScript; 95 96 /** 97 * The originAttributesPattern for which this script should be enabled for. 98 */ 99 [Constant, Throws] 100 readonly attribute any originAttributesPatterns; 101 102 /** 103 * The policy object for the extension that this matcher belongs to. 104 */ 105 [Constant] 106 readonly attribute WebExtensionPolicy? extension; 107 }; 108 109 dictionary MozDocumentMatcherInit { 110 boolean allFrames = false; 111 112 boolean checkPermissions = false; 113 114 sequence<OriginAttributesPatternDictionary>? originAttributesPatterns = null; 115 116 boolean matchAboutBlank = false; 117 118 boolean matchOriginAsFallback = false; 119 120 unsigned long long? frameID = null; 121 122 required MatchPatternSetOrStringSequence matches; 123 124 MatchPatternSetOrStringSequence? excludeMatches = null; 125 126 sequence<MatchGlobOrString>? includeGlobs = null; 127 128 sequence<MatchGlobOrString>? excludeGlobs = null; 129 130 boolean isUserScript = false; 131 132 boolean hasActiveTabPermission = false; 133 }; 134 135 /** 136 * Describes the earliest point in the load cycle at which a script should 137 * run. 138 */ 139 enum ContentScriptRunAt { 140 /** 141 * The point in the load cycle just after the document element has been 142 * inserted, before any page scripts have been allowed to run. 143 */ 144 "document_start", 145 /** 146 * The point after which the page DOM has fully loaded, but before all page 147 * resources have necessarily been loaded. Corresponds approximately to the 148 * DOMContentLoaded event. 149 */ 150 "document_end", 151 /** 152 * The first point after the page and all of its resources has fully loaded 153 * when the event loop is idle, and can run scripts without delaying a paint 154 * event. 155 */ 156 "document_idle", 157 }; 158 159 /** 160 * Describes the world where a script should run. 161 */ 162 enum ContentScriptExecutionWorld { 163 /** 164 * The default execution environment of content scripts. 165 * The name refers to "isolated world", which is a concept from Chromium and 166 * WebKit, used to enforce isolation of the JavaScript execution environments 167 * of content scripts and web pages. 168 * 169 * Not supported when isUserScript=true. 170 */ 171 "ISOLATED", 172 /** 173 * The execution environment of the web page. 174 */ 175 "MAIN", 176 /** 177 * The execution environment of a sandbox running scripts registered through 178 * the MV3 userScripts API. 179 * 180 * Only supported when isUserScript=true. 181 */ 182 "USER_SCRIPT", 183 }; 184 185 enum ContentScriptCssOrigin { 186 "author", 187 "user", 188 }; 189 190 [ChromeOnly, Exposed=Window] 191 interface WebExtensionContentScript : MozDocumentMatcher { 192 [Throws] 193 constructor(WebExtensionPolicy extension, 194 WebExtensionContentScriptInit options); 195 196 /** 197 * The earliest point in the load cycle at which this script should run. For 198 * static content scripts, in extensions which were present at browser 199 * startup, the browser makes every effort to make sure that the script runs 200 * no later than this point in the load cycle. For dynamic content scripts, 201 * and scripts from extensions installed during this session, the scripts 202 * may run at a later point. 203 */ 204 [Constant] 205 readonly attribute ContentScriptRunAt runAt; 206 207 /** 208 * The world where the script should run. 209 */ 210 [Constant] 211 readonly attribute ContentScriptExecutionWorld world; 212 213 /** 214 * When world is "USER_SCRIPT", worldId can be used to specify a specific 215 * extension-specific sandbox to execute in, instead of the default one. 216 */ 217 [Constant] 218 readonly attribute DOMString? worldId; 219 220 /** 221 * The css origin of the stylesheet to inject. 222 */ 223 [Constant] 224 readonly attribute ContentScriptCssOrigin cssOrigin; 225 226 /** 227 * A set of paths, relative to the extension root, of CSS sheets to inject 228 * into matching pages. 229 */ 230 [Cached, Constant, Frozen] 231 readonly attribute sequence<DOMString> cssPaths; 232 233 /** 234 * A set of paths, relative to the extension root, of JavaScript scripts to 235 * execute in matching pages. 236 */ 237 [Cached, Constant, Frozen] 238 readonly attribute sequence<DOMString> jsPaths; 239 }; 240 241 dictionary WebExtensionContentScriptInit : MozDocumentMatcherInit { 242 ContentScriptRunAt runAt = "document_idle"; 243 244 ContentScriptExecutionWorld world = "ISOLATED"; 245 246 DOMString? worldId = null; 247 248 ContentScriptCssOrigin cssOrigin = "author"; 249 250 sequence<DOMString> cssPaths = []; 251 252 sequence<DOMString> jsPaths = []; 253 };