extensions/common/api/content_scripts.idl

// Copyright 2020 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Stub namespace for the "content_scripts" manifest key.
[generate_error_messages]
namespace contentScripts {
  // The stage in the document lifecycle when the javascript file is injected.
  enum RunAt {
    // The browser chooses a time to inject scripts between "document_end" and
    // immediately after the window.onload event fires. The exact moment of
    // injection depends on how complex the document is and how long it is
    // taking to load, and is optimized for page load speed.
    // Content scripts running at "document_idle" do not need to listen for the
    // window.onload event; they are guaranteed to run after the DOM is
    // complete. If a script definitely needs to run after window.onload, the
    // extension can check if onload has already fired by using the
    // document.readyState property.
    document_idle,
    // Scripts are injected after any files from css, but before any other DOM
    // is constructed or any other script is run.
    document_start,
    // Scripts are injected immediately after the DOM is complete, but before
    // subresources like images and frames have loaded.
    document_end
  };

  // Describes a content script to be injected into a web page.
  dictionary ContentScript {
    // Specifies which pages this content script will be injected into. See
    // <a href="match_patterns">Match Patterns</a> for more details on the
    // syntax of these strings.
    DOMString[] matches;
    // Excludes pages that this content script would otherwise be injected into.
    // See <a href="match_patterns">Match Patterns</a> for more details on the
    // syntax of these strings.
    DOMString[]? exclude_matches;
    // The list of CSS files to be injected into matching pages. These are
    // injected in the order they appear in this array, before any DOM is
    // constructed or displayed for the page.
    DOMString[]? css;
    // The list of JavaScript files to be injected into matching pages. These
    // are injected in the order they appear in this array.
    DOMString[]? js;
    // If specified 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? all_frames;
    // TODO(devlin): Add documentation once the implementation is complete. See
    // crbug.com/55084.
    [nodoc]
    boolean? match_origin_as_fallback;
    // Whether the script should inject into an about:blank frame where the
    // parent or opener frame matches one of the patterns declared in matches.
    // Defaults to false.
    boolean? match_about_blank;
    // Applied after matches to include only those URLs that also match this
    // glob. Intended to emulate the
    // <a href="http://wiki.greasespot.net/Metadata_Block#.40include">@include
    // </a> Greasemonkey keyword.
    DOMString[]? include_globs;
    // Applied after matches to exclude URLs that match this glob. Intended to
    // emulate the
    // <a href="https://wiki.greasespot.net/Metadata_Block#.40exclude">@exclude
    // </a> Greasemonkey keyword.
    DOMString[]? exclude_globs;
    // Specifies when JavaScript files are injected into the web page. The
    // preferred and default value is <code>document_idle</code>.
    RunAt? run_at;
  };

  dictionary ManifestKeys {
    ContentScript[] content_scripts;
  };
};