browser.scripting

Opis

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

Uprawnienia

scripting

Dostępność

Chrome 88 lub nowsza wersja browser.* od Chrome 148 MV3 lub nowsza wersja

Plik manifestu

Aby używać interfejsu API browser.scripting, zadeklaruj uprawnienie "scripting" w pliku manifestu oraz uprawnienia hosta dla stron, na których chcesz wstrzykiwać skrypty. Użyj klucza "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 użycie

Za pomocą interfejsu API browser.scripting możesz wstrzykiwać kod JavaScript i CSS do witryn. Jest to podobne do tego, co można zrobić za pomocą skryptów treści. Jednak dzięki przestrzeni nazw browser.scripting rozszerzenia mogą podejmować decyzje w czasie działania.

Cele wstrzykiwania

Możesz użyć parametru target, aby określić środowisko docelowe, do którego chcesz wstrzyknąć kod JavaScript lub CSS.

Jedynym wymaganym polem jest tabId. Domyślnie wstrzyknięcie zostanie uruchomione w ramce głównej określonej karty.

function getTabId() { ... }

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

Aby uruchomić rozszerzenie we wszystkich ramkach określonej karty, możesz ustawić wartość logiczną allFrames 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ć skrypty do określonych ramek karty, podając ich identyfikatory. Więcej informacji o identyfikatorach klatek znajdziesz w interfejsie API browser.webNavigation.

function getTabId() { ... }

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

Uwaga: nie możesz określić jednocześnie właściwości "frameIds" i "allFrames".

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ędem katalogu głównego rozszerzenia. Ten kod wstrzyknie plik script.js do ramki głównej karty.

function getTabId() { ... }

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

Funkcje środowiska wykonawczego

Podczas wstrzykiwania kodu JavaScript za pomocą scripting.executeScript() możesz określić funkcję, która ma zostać wykonana, 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 ma być 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"));

Przetwarzanie wyników

Wyniki wykonania kodu JavaScript są przekazywane do rozszerzenia. Dla każdej klatki uwzględniany jest 1 wynik. Główna ramka jest zawsze pierwszym indeksem w wynikowej tablicy. Wszystkie pozostałe ramki są w niedeterministycznej 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 wynikowa wartość wykonania skryptu jest obietnicą, Chrome poczeka na jej rozstrzygnięcie 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 zawartości dynamicznej

Poniższy fragment kodu zawiera funkcję, która wyrejestrowuje wszystkie skrypty zawartości dynamicznej, które zostały wcześniej zarejestrowane przez rozszerzenie.

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});
  }
}

Ważna uwaga: wyrejestrowanie skryptów treści nie spowoduje usunięcia skryptów ani stylów, które zostały już wstrzyknięte.

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

Typy

ContentScriptFilter

Chrome 96 lub nowsza wersja browser.* od Chrome 148

Właściwości

• identyfikatory

  string[] opcjonalne

  Jeśli podasz tę wartość, getRegisteredContentScripts zwróci tylko skrypty o identyfikatorach podanych 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. Należy podać tylko jedną z tych wartości: files lub css.

• pliki

  string[] opcjonalne

  Ścieżka do plików CSS, które mają zostać wstrzyknięte, względem katalogu głównego rozszerzenia. Należy podać tylko jedną z tych wartości: files lub css.

• pochodzenie

  StyleOrigin opcjonalny

  Pochodzenie stylu wstrzykiwania. Domyślna wartość to 'AUTHOR'.

• cel

  InjectionTarget

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

ExecutionWorld

Chrome 95 lub nowsza wersja browser.* od Chrome 148

Środowisko JavaScript, w którym ma zostać wykonany skrypt.

Typ wyliczeniowy

"ISOLATED"
Określa odizolowany świat, 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 browser.* od Chrome 148

  Dokument powiązany z wstrzyknięciem.

• frameId

  liczba

  Chrome 90 lub nowsza browser.* od Chrome 148

  Ramka powiązana z wstrzyknięciem.

• wynik

  any optional

  Wynik wykonania skryptu.

InjectionTarget

Właściwości

• allFrames

  boolean opcjonalne

  Określa, czy skrypt ma być wstrzykiwany do wszystkich ramek na karcie. Wartość domyślna to fałsz. Jeśli określono parametr frameIds, nie może to być prawda.

• documentIds

  string[] opcjonalne

  Chrome 106 lub nowsza browser.* od Chrome 148

  Identyfikatory konkretnych identyfikatorów dokumentów, do których mają zostać wstawione dane. Nie można ustawić tej wartości, jeśli ustawiono frameIds.

• frameIds

  number[] opcjonalny

  Identyfikatory konkretnych ramek, do których ma zostać wstrzyknięty kod.

• tabId

  liczba

  Identyfikator karty, do której ma zostać wstrzyknięty skrypt.

RegisteredContentScript

Chrome 96 lub nowsza wersja browser.* od Chrome 148

Właściwości

• allFrames

  boolean opcjonalne

  Jeśli ma wartość true (prawda), zostanie wstrzyknięty do wszystkich ramek, nawet jeśli ramka nie jest najwyższą ramką na karcie. Każda ramka jest sprawdzana niezależnie pod kątem wymagań dotyczących adresów URL. Jeśli wymagania nie są spełnione, kod nie zostanie wstrzyknięty do ramek podrzędnych. Wartość domyślna to false, co oznacza, że dopasowywana jest tylko górna ramka.

• css

  string[] opcjonalne

  Lista plików CSS do wstrzyknięcia na stronach z dopasowaniem. Są one wstrzykiwane w kolejności, w jakiej występują w tej tablicy, zanim zostanie utworzony lub wyświetlony model DOM strony.

• excludeMatches

  string[] opcjonalne

  Wyklucza strony, na których w przeciwnym razie zostałby wstrzyknięty ten skrypt treści. Więcej informacji o składni tych ciągó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 wygenerowanych identyfikatorów skryptów.

• js

  string[] opcjonalne

  Lista plików JavaScript, które mają zostać wstrzyknięte na stronach z dopasowaniem. Są one wstrzykiwane w kolejności, w jakiej pojawiają się w tej tablicy.

• matchOriginAsFallback

  boolean opcjonalne

  Chrome 119 lub nowsza browser.* od Chrome 148

  Wskazuje, czy skrypt może zostać wstrzyknięty do ramek, w których adres URL zawiera nieobsługiwany schemat, np. about:, data:, blob: lub filesystem:. W takich przypadkach sprawdzane jest źródło adresu URL, aby określić, czy skrypt powinien zostać wstrzyknięty. Jeśli źródłem jest null (jak w przypadku adresów URL data:), używane jest źródło ramki, która utworzyła bieżącą ramkę, lub ramki, która zainicjowała przejście do tej ramki. Pamiętaj, że może to nie być ramka nadrzędna.

• pasuje do

  string[] opcjonalne

  Określa, na których stronach zostanie wstrzyknięty ten skrypt treści. Więcej informacji o składni tych ciągów znajdziesz w artykule Wzorce dopasowania. Musisz go określić w przypadku registerContentScripts.

• persistAcrossSessions

  boolean opcjonalne

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

• runAt

  RunAt opcjonalny

  Określa, kiedy pliki JavaScript są wstrzykiwane na stronę internetową. Preferowana i domyślna wartość to document_idle.

• świat

  ExecutionWorld opcjonalny

  Chrome 102 lub nowsza browser.* od Chrome 148

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

ScriptInjection

Właściwości

• args

  any[] opcjonalny

  Chrome 92 lub nowsza wersja browser.* od Chrome 148

  Argumenty, które mają zostać przekazane do podanej funkcji. Jest to prawidłowe tylko wtedy, gdy określono parametr func. Te argumenty muszą być możliwe do serializacji w formacie JSON.

• pliki

  string[] opcjonalne

  Ścieżka do plików JS lub CSS, które mają zostać wstrzyknięte, względem katalogu głównego rozszerzenia. Należy podać tylko jedną z tych wartości: files lub func.

• injectImmediately

  boolean opcjonalne

  Chrome 102 lub nowsza browser.* od Chrome 148

  Określa, czy wstrzyknięcie powinno zostać wywołane w celu jak najszybciej. Pamiętaj, że nie gwarantuje to, że wstrzyknięcie nastąpi przed wczytaniem strony, ponieważ strona może już zostać wczytana, zanim skrypt dotrze do celu.

• cel

  InjectionTarget

  Szczegóły określające cel, do którego ma zostać wstrzyknięty skrypt.

• świat

  ExecutionWorld opcjonalny

  Chrome 95 lub nowsza wersja browser.* od Chrome 148

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

• func

  void optional

  Chrome 92 lub nowsza wersja browser.* od Chrome 148

  Funkcja JavaScript do wstrzyknięcia. Ta funkcja zostanie zserializowana, a następnie zdeserializowana na potrzeby wstrzyknięcia. Oznacza to, że wszystkie powiązane parametry i kontekst wykonania zostaną utracone. Należy podać tylko 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 Źródła stylów.

Typ wyliczeniowy

"AUTHOR"

"USER"

Metody

executeScript()

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

Wstawia skrypt w kontekście docelowym. Domyślnie skrypt zostanie uruchomiony o 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 jeszcze wczytana. Jeśli skrypt zwraca obietnicę, przeglądarka poczeka na jej spełnienie i zwróci wynikową wartość.

Parametry

• wstrzykiwanie

  ScriptInjection

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

Zwroty

• Promise<InjectionResult[]>

  Chrome 90 lub nowsza browser.* od Chrome 148

  Zwraca obiekt Promise, który jest rozwiązywany po zakończeniu wstrzykiwania. Wynikowa tablica zawiera wynik wykonania dla każdej klatki, w której wstrzyknięcie się powiodło.

getRegisteredContentScripts()

Chrome 96 lub nowsza wersja browser.* od Chrome 148

browser.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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

Parametry

• filtr

  ContentScriptFilter opcjonalne

  Obiekt do filtrowania dynamicznie zarejestrowanych skryptów rozszerzenia.

Zwroty

• Promise<RegisteredContentScript[]>

insertCSS()

browser.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

• wstrzykiwanie

  CSSInjection

  Szczegóły stylów do wstawienia.

Zwroty

• thought Promise<void>

  Chrome 90 lub nowsza browser.* od Chrome 148

  Zwraca obietnicę, która jest spełniana po zakończeniu wstawiania.

registerContentScripts()

Chrome 96 lub nowsza wersja browser.* od Chrome 148

browser.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

Parametry

• skrypty

  RegisteredContentScript[]

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

Zwroty

• thought Promise<void>

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

removeCSS()

Chrome 90 lub nowsza browser.* od Chrome 148

browser.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

Usuwa arkusz stylów CSS, który został wcześniej wstawiony przez to rozszerzenie z kontekstu docelowego.

Parametry

• wstrzykiwanie

  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 powoduje żadnego działania.

Zwroty

• thought Promise<void>

  Zwraca obietnicę, która jest spełniana po zakończeniu usuwania.

unregisterContentScripts()

Chrome 96 lub nowsza wersja browser.* od Chrome 148

browser.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

Wyrejestrowuje skrypty treści dla tego rozszerzenia.

Parametry

• filtr

  ContentScriptFilter opcjonalne

  Jeśli zostanie określony, wyrejestrowuje tylko skrypty zawartości dynamicznej, które pasują do filtra. W przeciwnym razie wszystkie skrypty zawartości dynamicznej rozszerzenia zostaną wyrejestrowane.

Zwroty

• thought 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 wersja browser.* od Chrome 148

browser.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

Parametry

• skrypty

  RegisteredContentScript[]

  Zawiera listę skryptów do zaktualizowania. Właściwość jest aktualizowana w przypadku istniejącego skryptu tylko wtedy, gdy jest określona w tym obiekcie. Jeśli podczas analizowania skryptu lub sprawdzania poprawności pliku wystąpią błędy albo podane identyfikatory nie odpowiadają w pełni zarejestrowanemu skryptowi, żadne skrypty nie zostaną zaktualizowane.

Zwroty

• thought Promise<void>

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