browser.scripting

Opis

Użyj interfejsu chrome.scripting API, aby wykonać skrypt w różnych kontekstach.

Uprawnienia

scripting

Dostępność

Chrome 88 lub nowsza MV3+

Plik manifestu

Aby używać interfejsu browser.scripting API, zadeklaruj uprawnienie "scripting" w manifeście oraz uprawnienia hosta dla stron, na których mają być wstrzykiwane skrypty. Użyj klawisza "host_permissions" lub uprawnienia "activeTab", które przyznaje tymczasowe uprawnienia hosta. W tym przykładzie użyto uprawnienia activeTab.

{
  "name": "Scripting Extension",
  "manifest_version": 3,
  "permissions": ["scripting", "activeTab"],
  ...
}

Pojęcia i zastosowanie

Za pomocą interfejsu browser.scripting API możesz wstrzykiwać JavaScript i CSS do witryn. Działa to podobnie jak w przypadku skryptów treści. Jednak dzięki przestrzeni nazw browser.scripting rozszerzenia mogą podejmować decyzje w czasie działania.

Cele wstrzyknięcia

Za pomocą parametru target możesz określić środowisko docelowe, do którego ma zostać wstrzyknięty kod JavaScript lub CSS.

Jedynym wymaganym polem jest tabId. Domyślnie wstrzykiwanie będzie wykonywane w głównej ramce określonej karty.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected"));

Aby wyświetlać reklamy we wszystkich ramkach na określonej karcie, możesz ustawić wartość allFrames boolean na true.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected in all frames"));

Możesz też wstrzykiwać kod do konkretnych ramek karty, podając poszczególne identyfikatory ramek. Więcej informacji o identyfikatorach ramek znajdziesz w browser.webNavigationinterfejsie API.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected on target frames"));

Wstrzyknięty kod

Rozszerzenia mogą określać kod do wstrzyknięcia za pomocą pliku zewnętrznego lub zmiennej środowiska wykonawczego.

Pliki

Pliki są określane jako ciągi znaków, które są ścieżkami względnymi do katalogu głównego rozszerzenia. Poniższy kod wstrzyknie plik script.js do głównej ramki karty.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("injected script file"));

Funkcje środowiska wykonawczego

Wstawiając kod JavaScript za pomocą scripting.executeScript(), możesz określić funkcję, która ma być wykonywana zamiast pliku. Ta funkcja powinna być zmienną funkcji dostępną w bieżącym kontekście rozszerzenia.

function getTabId() { ... }
function getTitle() { return document.title; }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : getTitle,
    })
    .then(() => console.log("injected a function"));

function getTabId() { ... }
function getUserColor() { ... }

function changeBackgroundColor() {
  document.body.style.backgroundColor = getUserColor();
}

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
    })
    .then(() => console.log("injected a function"));

Możesz to obejść, używając właściwości args:

function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
  document.body.style.backgroundColor = backgroundColor;
}

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
      args : [ getUserColor() ],
    })
    .then(() => console.log("injected a function"));

Ciągi środowiska wykonawczego

Jeśli wstrzykujesz CSS na stronie, możesz też określić ciąg znaków, który będzie używany we właściwości css. Ta opcja jest dostępna tylko w przypadku scripting.insertCSS(). Nie możesz wykonać ciągu znaków za pomocą scripting.executeScript().

function getTabId() { ... }
const css = "body { background-color: red; }";

browser.scripting
    .insertCSS({
      target : {tabId : getTabId()},
      css : css,
    })
    .then(() => console.log("CSS injected"));

Obsługa wyników

Wyniki wykonania kodu JavaScript są przekazywane do rozszerzenia. W każdej klatce uwzględniany jest jeden wynik. Główna klatka jest zawsze pierwszym indeksem w wynikowej tablicy. Wszystkie pozostałe klatki są w nieokreślonej kolejności.

function getTabId() { ... }
function getTitle() { return document.title; }

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : getTitle,
    })
    .then(injectionResults => {
      for (const {frameId, result} of injectionResults) {
        console.log(`Frame ${frameId} result:`, result);
      }
    });

scripting.insertCSS() nie zwraca żadnych wyników.

Obietnice

Jeśli wynik wykonania skryptu jest obietnicą, Chrome poczeka, aż zostanie ona spełniona, i zwróci wynikową wartość.

function getTabId() { ... }
async function addIframe() {
  const iframe = document.createElement("iframe");
  const loadComplete =
      new Promise(resolve => iframe.addEventListener("load", resolve));
  iframe.src = "https://example.com";
  document.body.appendChild(iframe);
  await loadComplete;
  return iframe.contentWindow.document.title;
}

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : addIframe,
    })
    .then(injectionResults => {
      for (const frameResult of injectionResults) {
        const {frameId, result} = frameResult;
        console.log(`Frame ${frameId} result:`, result);
      }
    });

Przykłady

Wyrejestrowywanie wszystkich skryptów treści dynamicznych

Poniższy fragment kodu zawiera funkcję, która wyrejestrowuje wszystkie skrypty treści dynamicznych, które rozszerzenie zarejestrowało wcześniej.

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await browser.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return browser.scripting.unregisterContentScripts({ ids: scriptIds });
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

Aby wypróbować interfejs browser.scripting API, zainstaluj przykładowy skrypt z repozytorium przykładowych rozszerzeń do Chrome.

Typy

ContentScriptFilter

Chrome 96 lub nowsza

Właściwości

  • identyfikatory,

    string[] opcjonalnie

    Jeśli ten parametr jest określony, getRegisteredContentScripts zwróci tylko skrypty z identyfikatorem podanym na tej liście.

CSSInjection

Właściwości

  • css

    ciąg znaków opcjonalny

    Ciąg tekstowy zawierający kod CSS do wstrzyknięcia. Musisz podać dokładnie jedną z tych wartości: files lub css.

  • pliki

    string[] opcjonalnie

    Ścieżka do plików CSS do wstrzyknięcia podana względem katalogu głównego rozszerzenia. Musisz podać dokładnie jedną z tych wartości: files lub css.

  • pochodzenie

    StyleOrigin opcjonalny

    Źródło stylu wstrzyknięcia. Domyślna wartość to 'AUTHOR'.

  • Szczegóły określające miejsce docelowe, w którym ma zostać wstawiony kod CSS.

ExecutionWorld

Chrome 95 lub nowsza

Środowisko JavaScript, w którym ma być wykonywany skrypt.

Typ wyliczeniowy

„ISOLATED”
Określa izolowane środowisko, czyli środowisko wykonawcze unikalne dla tego rozszerzenia.

„MAIN”
Określa główny świat DOM, czyli środowisko wykonawcze współdzielone z kodem JavaScript strony hosta.

InjectionResult

Właściwości

  • documentId

    tekst

    Chrome 106 lub nowsza

    Dokument powiązany z wstawieniem.

  • frameId

    liczba

    Chrome w wersji 90 lub nowszej

    Ramka powiązana z wstawieniem.

  • wynik

    dowolny opcjonalny

    Wynik wykonania skryptu.

InjectionTarget

Właściwości

  • allFrames

    wartość logiczna opcjonalna

    Określa, czy skrypt ma być wstrzykiwany we wszystkie ramki na karcie. Wartość domyślna to fałsz. Jeśli określono parametr frameIds, ta wartość nie może być prawdziwa.

  • documentIds

    string[] opcjonalnie

    Chrome 106 lub nowsza

    Identyfikatory konkretnych identyfikatorów dokumentów, które mają zostać wstawione. Jeśli ustawiono wartość frameIds, to pole nie może być ustawione.

  • frameIds

    number[] opcjonalny

    Identyfikatory konkretnych ramek, do których mają zostać wstawione reklamy.

  • tabId

    liczba

    Identyfikator karty, na której ma zostać wstawiony kod.

RegisteredContentScript

Chrome 96 lub nowsza

Właściwości

  • allFrames

    wartość logiczna opcjonalna

    Jeśli ma wartość true, skrypt zostanie wstrzyknięty do wszystkich ramek, nawet jeśli nie jest to ramka najwyższego poziomu na karcie. Każda ramka jest sprawdzana niezależnie pod kątem wymagań dotyczących adresu URL. Jeśli wymagania nie są spełnione, kod nie zostanie wstrzyknięty do ramek podrzędnych. Domyślnie ma wartość „false”, co oznacza, że dopasowywana jest tylko ramka najwyższego poziomu.

  • css

    string[] opcjonalnie

    Lista plików CSS, które mają być wstrzykiwane na pasujące strony. Są one wstrzykiwane w kolejności, w jakiej występują w tej tablicy, zanim zostanie utworzony lub wyświetlony jakikolwiek DOM strony.

  • excludeMatches

    string[] opcjonalnie

    Wyklucza strony, na których w innych okolicznościach zostałby wstrzyknięty ten skrypt treści. Więcej informacji o składni tych ciągów znaków znajdziesz w artykule Wzorce dopasowania.

  • id

    tekst

    Identyfikator skryptu treści określony w wywołaniu interfejsu API. Nie może zaczynać się od znaku „_”, ponieważ jest on zarezerwowany jako prefiks dla wygenerowanych identyfikatorów skryptów.

  • js

    string[] opcjonalnie

    Lista plików JavaScript, które mają być wstrzykiwane na pasujące strony. Są one wstawiane w kolejności, w jakiej występują w tej tablicy.

  • matchOriginAsFallback

    wartość logiczna opcjonalna

    Chrome 119 lub nowsza

    Określa, czy skrypt można wstrzykiwać do ramek, w których adres URL zawiera nieobsługiwany schemat, a mianowicie: about:, data:, blob: lub filesystem:. W takich przypadkach sprawdzane jest pochodzenie adresu URL, aby określić, czy należy wstawić skrypt. Jeśli źródłem jest null (jak w przypadku adresów URL danych), używane źródło to ramka, która utworzyła bieżącą ramkę, lub ramka, która zainicjowała nawigację do tej ramki. Pamiętaj, że nie musi to być ramka nadrzędna.

  • pasuje do

    string[] opcjonalnie

    Określa, na których stronach ma zostać wstrzyknięty ten skrypt treści. Więcej informacji o składni tych ciągów znaków znajdziesz w artykule Wzorce dopasowania. Musi być określony w przypadku registerContentScripts.

  • persistAcrossSessions

    wartość logiczna opcjonalna

    Określa, czy ten skrypt treści będzie działać w przyszłych sesjach. Wartość domyślna to true.

  • runAt

    RunAt opcjonalny

    Określa, kiedy pliki JavaScript są wstrzykiwane na stronę internetową. Preferowaną i domyślną wartością jest document_idle.

  • świat

    ExecutionWorld opcjonalny

    Chrome 102 lub nowsza

    „Świat” JavaScriptu, w którym ma być uruchomiony skrypt. Domyślna wartość to ISOLATED.

ScriptInjection

Właściwości

  • args

    any[] opcjonalny

    Chrome 92 lub nowsza

    Argumenty do przekazania do podanej funkcji. Jest to prawidłowe tylko wtedy, gdy określono parametr func. Te argumenty muszą być serializowane w formacie JSON.

  • pliki

    string[] opcjonalnie

    Ścieżka do plików JS lub CSS do wstrzyknięcia podana względem katalogu głównego rozszerzenia. Należy podać dokładnie jedną z tych wartości: files lub func.

  • injectImmediately

    wartość logiczna opcjonalna

    Chrome 102 lub nowsza

    Określa, czy wstrzykiwanie powinno zostać wywołane w obiekcie docelowym jak najszybciej. Pamiętaj, że nie gwarantuje to, że wstrzyknięcie nastąpi przed załadowaniem strony, ponieważ w momencie, gdy skrypt dotrze do celu, strona może być już załadowana.

  • Szczegóły określające miejsce docelowe, w którym ma zostać wstrzyknięty skrypt.

  • świat

    ExecutionWorld opcjonalny

    Chrome 95 lub nowsza

    „Świat” JavaScriptu, w którym ma być uruchomiony skrypt. Domyślna wartość to ISOLATED.

  • func

    void optional

    Chrome 92 lub nowsza

    Funkcja JavaScript do wstrzyknięcia. Ta funkcja zostanie serializowana, a następnie deserializowana w celu wstrzyknięcia. Oznacza to, że wszystkie powiązane parametry i kontekst wykonania zostaną utracone. Należy podać dokładnie jedną z tych wartości: files lub func.

    Funkcja func wygląda tak:

    () => {...}

StyleOrigin

Źródło zmiany stylu. Więcej informacji znajdziesz w sekcji Pochodzenie stylu.

Typ wyliczeniowy

„AUTHOR”

„USER”

Metody

executeScript()

chrome.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

Umieszczanie skryptu w kontekście docelowym. Domyślnie skrypt zostanie uruchomiony o godzinie document_idle lub natychmiast, jeśli strona została już wczytana. Jeśli właściwość injectImmediately jest ustawiona, skrypt zostanie wstrzyknięty bez oczekiwania, nawet jeśli strona nie została w pełni wczytana. Jeśli skrypt zwraca obietnicę, przeglądarka poczeka na jej rozstrzygnięcie i zwróci wynikową wartość.

Parametry

  • wstrzyknięcie,

    ScriptInjection

    Szczegóły skryptu, który ma zostać wstrzyknięty.

Zwroty

  • Promise<InjectionResult[]>

    Chrome w wersji 90 lub nowszej

    Zwraca obiekt Promise, który zostanie spełniony po zakończeniu wstrzykiwania. Wynikowa tablica zawiera wynik wykonania dla każdej ramki, w której wstrzykiwanie się powiodło.

getRegisteredContentScripts()

Chrome 96 lub nowsza 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

Zwraca wszystkie dynamicznie zarejestrowane skrypty treści dla tego rozszerzenia, które pasują do podanego filtra.

Parametry

  • filtr

    ContentScriptFilter opcjonalny

    Obiekt do filtrowania skryptów zarejestrowanych dynamicznie przez rozszerzenie.

Zwroty

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

Wstawia arkusz stylów CSS do kontekstu docelowego. Jeśli określono wiele ramek, nieudane wstrzyknięcia są ignorowane.

Parametry

  • wstrzyknięcie,

    CSSInjection

    Szczegóły stylów do wstawienia.

Zwroty

  • Promise<void>

    Chrome w wersji 90 lub nowszej

    Zwraca obiekt Promise, który zostanie spełniony po zakończeniu wstawiania.

registerContentScripts()

Chrome 96 lub nowsza 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Rejestruje co najmniej 1 skrypt treści dla tego rozszerzenia.

Parametry

  • Zawiera listę skryptów do zarejestrowania. Jeśli podczas analizowania skryptu lub weryfikacji pliku wystąpią błędy albo podane identyfikatory już istnieją, żadne skrypty nie zostaną zarejestrowane.

Zwroty

  • Promise<void>

    Zwraca obiekt Promise, który jest rozwiązywany po pełnej rejestracji skryptów lub odrzucany, jeśli wystąpił błąd.

removeCSS()

Chrome w wersji 90 lub nowszej 
chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

Usuwa arkusz stylów CSS, który został wcześniej wstawiony przez to rozszerzenie w kontekście docelowym.

Parametry

  • wstrzyknięcie,

    CSSInjection

    Szczegóły stylów do usunięcia. Pamiętaj, że właściwości css, files i origin muszą dokładnie odpowiadać arkuszowi stylów wstawionemu za pomocą insertCSS. Próba usunięcia nieistniejącego arkusza stylów nie przynosi żadnego efektu.

Zwroty

  • Promise<void>

    Zwraca obiekt Promise, który zostanie spełniony po zakończeniu usuwania.

unregisterContentScripts()

Chrome 96 lub nowsza 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

Usuwa rejestrację skryptów treści dla tego rozszerzenia.

Parametry

  • filtr

    ContentScriptFilter opcjonalny

    Jeśli zostanie określony, wyrejestrowuje tylko skrypty dynamicznych treści pasujące do filtra. W przeciwnym razie wszystkie skrypty treści dynamicznych rozszerzenia zostaną wyrejestrowane.

Zwroty

  • Promise<void>

    Zwraca obiekt Promise, który jest rozwiązywany po wyrejestrowaniu skryptów lub odrzucany, jeśli wystąpił błąd.

updateContentScripts()

Chrome 96 lub nowsza 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Aktualizuje co najmniej 1 skrypt dotyczący zawartości tego rozszerzenia.

Parametry

  • Zawiera listę skryptów do zaktualizowania. Usługa jest aktualizowana w przypadku istniejącego skryptu tylko wtedy, gdy jest określona w tym obiekcie. Jeśli podczas analizowania skryptu lub weryfikacji pliku wystąpią błędy albo podane identyfikatory nie będą odpowiadać w pełni zarejestrowanemu skryptowi, żadne skrypty nie zostaną zaktualizowane.

Zwroty

  • Promise<void>

    Zwraca obiekt Promise, który jest rozwiązywany po zaktualizowaniu skryptów lub odrzucany, jeśli wystąpił błąd.