chrome.scripting

Opis

Interfejs API chrome.scripting umożliwia wykonywanie skryptu w różnych kontekstach.

Uprawnienia

scripting

Dostępność

Chrome 88 i nowsze wersje MV3 i nowsze

Plik manifestu

Aby korzystać z interfejsu chrome.scripting API, zadeklaruj w pliku manifestu uprawnienia "scripting" oraz uprawnienia hosta dla stron, na których mogą wstrzykiwać skrypty. użyj klucza "host_permissions" lub uprawnienia "activeTab", które przyznają tymczasowe uprawnienia hosta. W przykładzie poniżej użyto uprawnienia ActiveTab.

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

Pojęcia i zastosowanie

Możesz używać interfejsu API chrome.scripting, aby wstawiać w witrynach JavaScript i CSS. Działa to podobnie do skryptów treści. Jednak korzystanie z przestrzeni nazw chrome.scripting sprawia, że rozszerzenia mogą podejmować decyzje w czasie działania.

Cele wstrzykiwania

Możesz użyć parametru target, by określić środowisko docelowe, do którego będzie wstrzykiwany JavaScript lub CSS.

Jedyne wymagane pole to tabId. Domyślnie wstrzykiwanie jest wykonywane w głównej ramce na określonej karcie.

function getTabId() { ... }

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

Aby były uruchamiane we wszystkich ramkach na określonej karcie, możesz ustawić wartość logiczną allFrames 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ż stosować je do konkretnych ramek karty, określając ich identyfikatory. Więcej informacji o identyfikatorach ramek znajdziesz w artykule chrome.webNavigationAPI.

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 za pomocą zewnętrznego pliku lub zmiennej środowiska wykonawczego.

Files

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 w ramce głównej karty.

function getTabId() { ... }

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

Funkcje środowiska wykonawczego

Gdy wstrzykujesz 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; }

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

Aby obejść ten problem, użyj 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 tekstowe w środowisku wykonawczym

Jeśli wstrzykujesz kod CSS na stronie, możesz też określić ciąg znaków do użycia we właściwości css. Ta opcja jest dostępna tylko w przypadku scripting.insertCSS(); nie można wykonywać 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"));

Sprawdź wyniki

Wyniki wykonania JavaScriptu są przekazywane do rozszerzenia. W ramach każdej klatki uwzględniany jest 1 wynik. Ramka główna jest gwarantowana, że jest pierwszym indeksem w tablicy wynikowej. Wszystkie pozostałe klatki są uporządkowane w kolejności niedeterministycznej.

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 obietnica, Chrome poczeka, aż obietnica się ustabilizuje 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

Wyrejestruj wszystkie skrypty zawartości dynamicznej

Poniższy fragment kodu zawiera funkcję, która wyrejestrowuje wszystkie skrypty zawartości dynamicznej 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(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 96 i nowsze wersje

Właściwości

  • ids

    string[] opcjonalny

    Jeśli zostanie określony, getRegisteredContentScripts będzie zwracać tylko skrypty o identyfikatorze wskazanym 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 i css.

  • pliki

    string[] opcjonalny

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

  • pochodzenie

    Opcjonalny StyleOrigin

    Pochodzenie stylu dla 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 i nowsze

Świat JavaScriptu, w którym ma być wykonywany skrypt.

Enum

"ISOLATED"
Określa odizolowany świat, czyli środowisko wykonawcze unikalne dla tego rozszerzenia.

"MAIN"
Określa główny świat DOM, czyli środowisko wykonawcze udostępniane skryptowi JavaScript strony hosta.

InjectionResult

Właściwości

  • documentId

    string,

    Chrome 106 i nowsze wersje

    Dokument powiązany z wstrzykiwaniem.

  • frameId

    Liczba

    Chrome 90 i nowsze

    Ramka powiązana z wstrzykiwaniem.

  • wynik

    dowolne opcjonalne

    Wynik wykonania skryptu.

InjectionTarget

Właściwości

  • allFrames

    wartość logiczna opcjonalna

    Określa, czy skrypt ma być wstrzykiwany we wszystkich ramkach na karcie. Wartość domyślna to fałsz. Ta wartość nie może mieć wartości prawda, jeśli określono frameIds.

  • documentIds

    string[] opcjonalny

    Chrome 106 i nowsze wersje

    Identyfikatory konkretnych dokumentów documentId, w których ma być przeprowadzana wstrzykiwanie. Jeśli ustawiona jest zasada frameIds, nie można jej ustawić.

  • frameIds

    number[] opcjonalny

    Identyfikatory konkretnych ramek, do których ma być stosowana reklama.

  • tabId

    Liczba

    Identyfikator karty, na którą ma zostać wstrzyknięta strona.

RegisteredContentScript

Chrome 96 i nowsze wersje

Właściwości

  • allFrames

    wartość logiczna opcjonalna

    Jeśli zasada ma wartość prawda, kod jest wstrzykiwany do wszystkich klatek, 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. Jeśli te wymagania nie zostaną spełnione, nie będzie wstrzykiwana do ramek podrzędnych. Wartość domyślna to fałsz, co oznacza, że dopasowywana jest tylko górna klatka.

  • css

    string[] opcjonalny

    Lista plików CSS, które mają zostać wstawione na pasujących stronach. Są one wstrzykiwane w kolejności, w jakiej pojawiają się w tej tablicy, przed utworzeniem lub wyświetleniem elementu DOM na stronie.

  • excludeMatches

    string[] opcjonalny

    Wyklucza strony, do których w innym przypadku zostałby wstrzyknięty ten skrypt treści. Więcej informacji o składni tych ciągów znaków znajdziesz w sekcji Wzorce dopasowania.

  • id

    string,

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

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

  • matchOriginAsFallback

    wartość logiczna opcjonalna

    Chrome 119 i nowsze wersje

    Wskazuje, czy skrypt może być wstrzykiwany do ramek, w przypadku których adres URL zawiera nieobsługiwany schemat, w szczególności: about:, data:, blob: lub filesystem:. W takich przypadkach sprawdzamy źródło adresu URL, by określić, czy należy wstrzyknąć skrypt. Jeśli źródłem jest null (tak jak w przypadku adresów URL w przypadku danych), użytym źródłem jest ramka, która utworzyła bieżącą ramkę, lub ramka, która zainicjowała nawigację do tej ramki. Pamiętaj, że może to nie być ramka nadrzędna.

  • dopasowania

    string[] opcjonalny

    Określa strony, na których będzie wstrzykiwany ten skrypt treści. Więcej informacji o składni tych ciągów znaków znajdziesz w sekcji Wzorce dopasowania. Musisz określić dla registerContentScripts.

  • persistAcrossSessions

    wartość logiczna opcjonalna

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

  • runAt

    RunAt opcjonalnie

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

  • ze świata

    ExecutionWorld opcjonalnie

    Chrome 102 i nowsze wersje

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

ScriptInjection

Właściwości

  • args

    any[] opcjonalny

    Chrome 92 i nowsze wersje

    Argumenty do przekazania do podanej funkcji. Ta zasada obowiązuje tylko wtedy, gdy jest określony parametr func. Te argumenty muszą być możliwe do serializowania w formacie JSON.

  • pliki

    string[] opcjonalny

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

  • injectImmediately

    wartość logiczna opcjonalna

    Chrome 102 i nowsze wersje

    Określa, czy wstrzyknięcie powinno zostać aktywowane w miejscu docelowym tak szybko, jak to możliwe. Pamiętaj, że nie gwarantujemy, że wstrzyknięcie kodu nastąpi przed wczytaniem strony, ponieważ strona mogła już zostać załadowana, zanim skrypt osiągnie cel.

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

  • ze świata

    ExecutionWorld opcjonalnie

    Chrome 95 i nowsze

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

  • func

    void opcjonalny

    Chrome 92 i nowsze wersje

    Funkcja JavaScript do wstrzyknięcia. Ta funkcja zostanie zserializowana, a następnie poddana deserializacji w celu wstrzykiwania. Oznacza to, że wszystkie powiązane parametry i kontekst wykonania zostaną utracone. Należy podać dokładnie jedno z tych elementów: files lub func.

    Funkcja func wygląda tak: 

    ()=> {...}

StyleOrigin

Źródło zmiany stylu. Więcej informacji znajdziesz w sekcji na temat początków stylów.

Enum

Metody

executeScript()

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

Wstawia skrypt w kontekście docelowym. Domyślnie skrypt będzie uruchamiany document_idle lub od razu, jeśli strona została już wczytana. Jeśli ustawiona jest właściwość injectImmediately, skrypt wykonuje wstrzykiwanie bez oczekiwania, nawet jeśli strona się nie wczyta. Jeśli skrypt zwróci odpowiedź na obietnicę, przeglądarka zaczeka na jej ustabilizowanie i zwrócenie wynikowej wartości.

Parametry

Akcje powrotne

  • Promise<InjectionResult[]>

    Chrome 90 i nowsze

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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 danego filtra.

Parametry

Akcje powrotne

  • Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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 wiele klatek, nieudane wstrzykiwanie będą ignorowane.

Parametry

  • zastrzyk

    CSSInjection

    Szczegóły stylów do wstawienia.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 90 i nowsze

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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 dla tego rozszerzenia.

Parametry

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

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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 docelowy arkusz stylów CSS, który został wcześniej wstawiony przez to rozszerzenie.

Parametry

  • zastrzyk

    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 kończy się niepowodzeniem.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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

  • filter

    Opcjonalny ContentScriptFilter

    Jeśli jest określony, tylko wyrejestrowuje skrypty zawartości dynamicznej pasujące do filtra. W przeciwnym razie wszystkie skrypty treści dynamicznych w rozszerzeniu zostaną wyrejestrowane.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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 dla tego rozszerzenia.

Parametry

  • Zawiera listę skryptów do zaktualizowania. Właściwość jest aktualizowana tylko wtedy, gdy jest określona w tym obiekcie. Jeśli w trakcie analizy lub weryfikacji pliku wystąpią błędy albo określone identyfikatory nie odpowiadają w pełni zarejestrowanego skryptu, żaden skrypt nie zostanie zaktualizowany.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.