chrome.scripting

Opis

Używaj interfejsu API chrome.scripting do wykonywania skryptu w różnych kontekstach.

Uprawnienia

scripting

Dostępność

Chrome 88 i nowsze MV3 lub nowszy

Plik manifestu

Aby użyć interfejsu API chrome.scripting, zadeklaruj uprawnienia "scripting" w manifeście oraz uprawnienia hosta dla stron, na których mogą być wstrzykiwane skrypty. Użyj klucza "host_permissions" lub uprawnienia "activeTab", które przyznają tymczasowe uprawnienia hosta. Ten przykład korzysta z uprawnienia ActiveTab.

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

Pojęcia i wykorzystanie

Za pomocą interfejsu API chrome.scripting możesz wstrzykiwać JavaScript i CSS do witryn. Działa to podobnie jak w przypadku treści skrypty. Jeśli jednak użyjesz przestrzeni nazw chrome.scripting, rozszerzenia mogą podejmować decyzje w czasie działania aplikacji.

Cele wstrzykiwania

Możesz użyć parametru target, aby określić środowisko docelowe do wstrzykiwania JavaScriptu lub .

Jedyne wymagane pole to tabId. Domyślnie wstrzykiwanie będzie wykonywane w głównej ramki określonej karty.

function getTabId() { ... }

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

Aby reklama była uruchamiana we wszystkich ramkach na określonej karcie, możesz ustawić wartość logiczną allFrames do: 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ż wstawiać elementy do określonych ramek karty, określając pojedynczą klatkę Identyfikatory. Więcej informacji o identyfikatorach ramek znajdziesz tutaj: chrome.webNavigation 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 wstrzykiwania z pliku zewnętrznego lub zmienną środowiska wykonawczego.

Pliki

Pliki są określone jako ciągi znaków będące ścieżkami względnymi względem katalogu głównego rozszerzenia katalogu. Ten kod wstrzykuje plik script.js do pliku głównego ramki karty.

function getTabId() { ... }

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

Funkcje środowiska wykonawczego

Podczas wstrzykiwania JavaScriptu za pomocą funkcji scripting.executeScript() możesz określić parametr do wykonania zamiast pliku. Ta funkcja powinna być funkcją zmienna dostępna 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 obejść ten problem, 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 znaków środowiska wykonawczego

Jeśli wstrzykujesz kod CSS w obrębie strony, możesz również określić ciąg znaków, który zostanie użyty w tagu css. Ta opcja jest dostępna tylko w przypadku scripting.insertCSS(); Ty nie można 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"));

Praca z wynikami

Wyniki wykonania kodu JavaScript są przekazywane do rozszerzenia. Pojedynczy wynik są uwzględniane w ramach każdej klatki. Ramka główna zawsze będzie pierwszym indeksem w tablica wynikowa; wszystkie pozostałe klatki są w porządku niedeterministycznym.

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

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

Obietnice

Jeśli wynikowa wartość wykonania skryptu jest obietnicą, Chrome poczeka dla obietnicy uzgodnienia i zwrócenia wynikowej wartości.

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

Wyrejestruj wszystkie skrypty treści dynamicznych

Ten fragment kodu zawiera funkcję, która wyrejestrowuje całą zawartość dynamiczną ze skryptami, które rozszerzenie zostało wcześniej zarejestrowane.

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

Typy

ContentScriptFilter

Chrome 96 lub nowszy

Właściwości

  • identyfikatory

    string[] opcjonalnie

    Jeśli określisz parametr, getRegisteredContentScripts będzie zwracać tylko skrypty o identyfikatorze określonym na tej liście.

CSSInjection

Właściwości

  • css

    ciąg znaków opcjonalny

    Ciąg tekstowy zawierający kod CSS do wstrzykiwania. Należy podać tylko jedną z tych wartości: files lub css.

  • pliki

    string[] opcjonalnie

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

  • pochodzenie

    StyleOrigin opcjonalny

    Źródło stylu dla wstrzykiwania. Domyślna wartość to 'AUTHOR'.

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

ExecutionWorld

Chrome w wersji 95 lub nowszej

Świat JavaScriptu, w którym skrypt ma zostać wykonany.

Typ wyliczeniowy

"ISOLATED"
Określa izolowany świat, który jest środowiskiem wykonawczym unikalnym dla tego rozszerzenia.

"MAIN"
Określa główny świat DOM, czyli środowisko wykonawcze współużytkowane z kodem JavaScript strony hostującej.

InjectionResult

Właściwości

  • documentId

    ciąg znaków

    Chrome 106 lub nowszy

    Dokument powiązany ze wstrzyknięciem.

  • frameId

    liczba

    Chrome w wersji 90 lub nowszej

    Ramka powiązana ze wstrzyknięciem.

  • wynik

    dowolne opcjonalne

    Wynik wykonania skryptu.

InjectionTarget

Właściwości

  • allFrames

    Wartość logiczna opcjonalna

    Określa, czy skrypt ma wstrzykiwać się do wszystkich klatek na karcie. Wartość domyślna to fałsz. Ta zasada nie może być spełniony, jeśli określono frameIds.

  • documentIds

    string[] opcjonalnie

    Chrome 106 lub nowszy

    Identyfikatory konkretnych identyfikatorów documentId do wstrzykiwania. Nie można tego ustawić, jeśli ustawiono frameIds.

  • frameIds

    liczba[] opcjonalnie

    Identyfikatory konkretnych ramek, w których ma być wstrzykiwana.

  • tabId

    liczba

    Identyfikator karty, w której chcesz wstrzyknąć.

RegisteredContentScript

Chrome 96 lub nowszy

Właściwości

  • allFrames

    Wartość logiczna opcjonalna

    Jeśli ma wartość true (prawda), wstrzyki będzie we wszystkich klatkach, nawet jeśli nie jest ona najwyższą klatką na karcie. Każda ramka jest sprawdzana niezależnie pod kątem wymagań dotyczących adresu URL. nie będzie on wstrzyknięty do ramek podrzędnych, jeśli wymagania dotyczące adresów URL nie zostaną spełnione. Wartość domyślna to fałsz, co oznacza, że dopasowywana jest tylko górna klatka.

  • css

    string[] opcjonalnie

    Lista plików CSS, które mają zostać wstrzyknięte do pasujących stron. Są one wstrzykiwane w kolejności, w jakiej występują w tej tablicy, przed utworzeniem lub wyświetleniem DOM strony.

  • excludeMatches

    string[] opcjonalnie

    Nie obejmuje stron, na których ten skrypt treści zostałby wstrzykiwany. Więcej informacji o składni tych ciągów znajdziesz w sekcji 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 „_” , bo jest on zarezerwowany jako prefiks generowanych identyfikatorów skryptów.

  • JS

    string[] opcjonalnie

    Lista plików JavaScript do wstrzykiwania na pasujących stronach. Są one wstrzykiwane w kolejności, w jakiej występują w tej tablicy.

  • matchOriginAsFallback

    Wartość logiczna opcjonalna

    Chrome w wersji 119 lub nowszej

    Wskazuje, czy skrypt można wstrzykiwać do ramek, w których URL zawiera nieobsługiwany schemat. konkretnie: about:, data:, blob: lub system filesystem:. W takich przypadkach sprawdzane jest źródło adresu URL, aby określić, czy skrypt powinien zostać wstrzykiwany. Jeśli źródło to null (tak jak w przypadku danych: adresy URL), to źródłem jest albo ramka, która utworzyła bieżącą ramkę, lub ramka, która zainicjowała przechodzenie do niej. Pamiętaj, że nie musi to być ramka nadrzędna.

  • pasuje do

    string[] opcjonalnie

    Określa strony, na których ten skrypt treści ma być wstrzykiwany. Więcej informacji o składni tych ciągów znajdziesz w sekcji Wzorce dopasowania. Należy podać wartość dla registerContentScripts.

  • persistAcrossSessions

    Wartość logiczna opcjonalna

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

  • runAt

    Opcjonalnie RunAt

    Określa, kiedy pliki JavaScript są wstrzykiwane do strony internetowej. Wartość preferowana i domyślna to document_idle.

  • świat

    ExecutionWorld opcjonalnie

    Chrome 102 lub nowszy

    „Świat” JavaScriptu aby uruchomić skrypt. Domyślna wartość to ISOLATED.

ScriptInjection

Właściwości

  • argumenty

    any[] opcjonalne

    Chrome w wersji 92 lub nowszej

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

  • pliki

    string[] opcjonalnie

    Ścieżka plików JS lub CSS do wstrzykiwania podana względem katalogu głównego rozszerzenia. Trzeba podać tylko jedną z tych właściwości files lub func.

  • injectImmediately

    Wartość logiczna opcjonalna

    Chrome 102 lub nowszy

    Określa, czy wstrzykiwanie ma zostać uruchomione w miejscu docelowym jak najszybciej. Pamiętaj, że nie gwarantuje to, że wstrzyknięta zostanie wstrzyknięta strona przed wczytaniem strony, bo mogła ona zostać już wczytana, zanim skrypt dotrze do miejsca docelowego.

  • Szczegóły określające środowisko docelowe, do którego ma zostać wstawiony skrypt.

  • świat

    ExecutionWorld opcjonalnie

    Chrome w wersji 95 lub nowszej

    „Świat” JavaScriptu aby uruchomić skrypt. Domyślna wartość to ISOLATED.

  • func

    void opcjonalnie

    Chrome w wersji 92 lub nowszej

    Funkcja JavaScript do wstrzykiwania. Ta funkcja zostanie zserializowana, a następnie deserializowana na potrzeby wstrzykiwania. Oznacza to, że wszystkie powiązane parametry i kontekst wykonania zostaną utracone. Trzeba podać tylko jedną z tych właściwości files lub func.

    Funkcja func wygląda tak: 

    () => {...}
    .

StyleOrigin

Punkt początkowy zmiany stylu. Więcej informacji znajdziesz w sekcji Pochodzenie stylu.

Typ wyliczeniowy

„AUTHOR”

"UŻYTKOWNIK"

Metody

executeScript()

Obietnica 
chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

Wstawia skrypt w kontekście docelowym. Domyślnie skrypt zostanie uruchomiony o document_idle lub natychmiast, gdy strona została już wczytana. Jeśli właściwość injectImmediately jest skonfigurowana, skrypt zostanie wstawiony bez oczekiwania, nawet jeśli strona jeszcze się nie wczytała. Jeśli skrypt zwróci wynik na obietnicę, przeglądarka poczeka na uzgodnienie tej obietnicy i zwróci otrzymaną wartość.

Parametry

Zwroty

  • Promise<InjectionResult[]>

    Chrome w wersji 90 lub nowszej

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getRegisteredContentScripts()

Obietnica Chrome w wersji 96 lub nowszej 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

Parametry

Zwroty

  • Promise<RegisteredContentScript[]>

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

insertCSS()

Obietnica 
chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

Wstawia arkusz stylów CSS w kontekście docelowym. Jeśli określisz większą liczbę klatek, nieudane wstrzykiwanie zostaną zignorowane.

Parametry

  • wstrzykiwanie

    CSSInjection

    Szczegóły stylów do wstawienia.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void
    .

Zwroty

  • Obietnica<void>

    Chrome w wersji 90 lub nowszej

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

registerContentScripts()

Obietnica Chrome w wersji 96 lub nowszej 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Rejestruje co najmniej 1 skrypt treści na potrzeby tego rozszerzenia.

Parametry

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

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void
    .

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

removeCSS()

Obietnica Chrome w wersji 90 lub nowszej 
chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

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

Parametry

  • wstrzykiwanie

    CSSInjection

    Szczegóły stylów do usunięcia. Pamiętaj, że właściwości css, files i origin muszą być dokładnie takie same jak w arkuszu stylów wstawionym za pomocą insertCSS. Próba usunięcia nieistniejącego arkusza stylów jest wykluczona.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void
    .

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

unregisterContentScripts()

Obietnica Chrome w wersji 96 lub nowszej 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

Wyrejestrowuje skrypty treści dla tego rozszerzenia.

Parametry

  • filtr

    Opcjonalny ContentScriptFilter

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

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void
    .

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

updateContentScripts()

Obietnica Chrome w wersji 96 lub nowszej 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Aktualizuje co najmniej 1 skrypt treści tego rozszerzenia.

Parametry

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

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void
    .

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.