dom/chrome-webidl/WebExtensionContentScript.webidl

   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 (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.
  50    */
  51   [Constant]
  52   readonly attribute boolean matchAboutBlank;
  53
  54   /**
  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.
  58    */
  59   [Constant]
  60   readonly attribute unsigned long long? frameID;
  61
  62   /**
  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
  65    * match patterns.
  66    */
  67   [Constant]
  68   readonly attribute MatchPatternSet matches;
  69
  70   /**
  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.
  73    */
  74   [Constant]
  75   readonly attribute MatchPatternSet? excludeMatches;
  76
  77   /**
  78    * The originAttributesPattern for which this script should be enabled for.
  79    */
  80   [Constant, Throws]
  81   readonly attribute any originAttributesPatterns;
  82
  83   /**
  84    * The policy object for the extension that this matcher belongs to.
  85    */
  86   [Constant]
  87   readonly attribute WebExtensionPolicy? extension;
  88 };
  89
  90 dictionary MozDocumentMatcherInit {
  91   boolean allFrames = false;
  92
  93   boolean checkPermissions = false;
  94
  95   sequence<OriginAttributesPatternDictionary>? originAttributesPatterns = null;
  96
  97   boolean matchAboutBlank = false;
  98
  99   unsigned long long? frameID = null;
 100
 101   required MatchPatternSetOrStringSequence matches;
 102
 103   MatchPatternSetOrStringSequence? excludeMatches = null;
 104
 105   sequence<MatchGlobOrString>? includeGlobs = null;
 106
 107   sequence<MatchGlobOrString>? excludeGlobs = null;
 108
 109   boolean hasActiveTabPermission = false;
 110 };
 111
 112 /**
 113  * Describes the earliest point in the load cycle at which a script should
 114  * run.
 115  */
 116 enum ContentScriptRunAt {
 117   /**
 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.
 120    */
 121   "document_start",
 122   /**
 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.
 126    */
 127   "document_end",
 128   /**
 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
 131    * event.
 132    */
 133   "document_idle",
 134 };
 135
 136 [ChromeOnly, Exposed=Window]
 137 interface WebExtensionContentScript : MozDocumentMatcher {
 138   [Throws]
 139   constructor(WebExtensionPolicy extension,
 140               WebExtensionContentScriptInit options);
 141
 142   /**
 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.
 149    */
 150   [Constant]
 151   readonly attribute ContentScriptRunAt runAt;
 152
 153   /**
 154    * A set of paths, relative to the extension root, of CSS sheets to inject
 155    * into matching pages.
 156    */
 157   [Cached, Constant, Frozen]
 158   readonly attribute sequence<DOMString> cssPaths;
 159
 160   /**
 161    * A set of paths, relative to the extension root, of JavaScript scripts to
 162    * execute in matching pages.
 163    */
 164   [Cached, Constant, Frozen]
 165   readonly attribute sequence<DOMString> jsPaths;
 166 };
 167
 168 dictionary WebExtensionContentScriptInit : MozDocumentMatcherInit {
 169   ContentScriptRunAt runAt = "document_idle";
 170
 171   sequence<DOMString> cssPaths = [];
 172
 173   sequence<DOMString> jsPaths = [];
 174 };