chrome.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 chrome.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 chrome.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 chrome.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() { ... }

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

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

function getTabId() { ... }

chrome.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 identyfikatory poszczególnych ramek. Więcej informacji o identyfikatorach ramek znajdziesz w chrome.webNavigationinterfejsie API.

function getTabId() { ... }

chrome.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. Ten kod wstrzyknie plik script.js do głównej ramki karty.

function getTabId() { ... }

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

Funkcje środowiska wykonawczego

Wstawiając kod JavaScript za pomocą funkcji 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; }

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

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

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

chrome.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;
}

chrome.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; }";

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

Obsługa wyników

Wyniki wykonania JavaScriptu są przekazywane do rozszerzenia. W każdej klatce jest uwzględniany jeden wynik. Główna klatka jest zawsze pierwszym indeksem w wynikowej tablicy. Pozostałe klatki są w niej ułożone w nieokreślonej kolejności.

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

chrome.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, aż obietnica zostanie 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;
}

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

Wyłącz wszystkie skrypty treści dynamicznych

Poniższy fragment kodu zawiera funkcję, która wyrejestrowuje wszystkie skrypty treści dynamicznych zarejestrowane wcześniej przez rozszerzenie.

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await chrome.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return chrome.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 chrome.scripting API, zainstaluj przykładowy skrypt z repozytorium przykładowych rozszerzeń do Chrome.

Typy

ContentScriptFilter

Chrome w wersji 96 lub nowszej

Właściwości

  • identyfikatory,

    string[] opcjonalne

    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

    string opcjonalny

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

  • pliki

    string[] opcjonalne

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

  • pochodzenie

    StyleOrigin opcjonalny

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

  • Szczegóły określające element docelowy, do którego ma zostać wstawiony kod CSS.

ExecutionWorld

Chrome 95 lub nowszy

Środowisko JavaScript, w którym ma być wykonywany 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

    ciąg znaków

    Chrome 106 lub nowsza

    Dokument powiązany z wstrzyknięciem.

  • frameId

    liczba

    Chrome w wersji 90 lub nowszej

    Ramka powiązana z wstrzyknięciem.

  • wynik

    dowolny opcjonalny

    Wynik wykonania skryptu.

InjectionTarget

Właściwości

  • allFrames

    wartość logiczna opcjonalna

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

  • documentIds

    string[] opcjonalne

    Chrome 106 lub nowsza

    Identyfikatory konkretnych identyfikatorów dokumentów, do których mają być wstawione dane. Nie może być ustawiona, jeśli ustawiona jest wartość frameIds.

  • 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 w wersji 96 lub nowszej

Właściwości

  • allFrames

    wartość logiczna opcjonalna

    Jeśli ma wartość true, kod zostanie wstawiony 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, nie zostanie ona wstawiona do ramek podrzędnych. Domyślnie ma wartość false, co oznacza, że dopasowywana jest tylko ramka najwyższego poziomu.

  • css

    string[] opcjonalne

    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[] opcjonalne

    Wyklucza strony, do których w inny sposób 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

    ciąg znaków

    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[] opcjonalne

    Lista plików JavaScript, które mają być wstrzykiwane na pasujące strony. Są one wstrzykiwane 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[] opcjonalne

    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” JavaScript, 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. Obowiązuje tylko wtedy, gdy określono parametr func. Te argumenty muszą być serializowane w formacie JSON.

  • pliki

    string[] opcjonalne

    Ś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 miejscu docelowym jak najszybciej. Pamiętaj, że nie gwarantuje to wstrzyknięcia 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ć wstawiony skrypt.

  • świat

    ExecutionWorld opcjonalny

    Chrome 95 lub nowszy

    „Świat” JavaScript, 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[]>

Umieszcza skrypt w kontekście docelowym. Domyślnie skrypt zostanie uruchomiony w momencie 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

getRegisteredContentScripts()

Chrome w wersji 96 lub nowszej 
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 dynamicznie zarejestrowanych skryptów rozszerzenia.

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

registerContentScripts()

Chrome w wersji 96 lub nowszej 
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>

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>

unregisterContentScripts()

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

Wyłącza skrypty treści dla tego rozszerzenia.

Parametry

  • filtr

    ContentScriptFilter opcjonalny

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

Zwroty

  • Promise<void>

updateContentScripts()

Chrome w wersji 96 lub nowszej 
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>