chrome.scripting (original) (raw)

Przejdź do głównej treści

chrome.scripting

Opis

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

Uprawnienia

scripting

Dostępność

Chrome 88 lub nowszaMV3+

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

CSSInjection

Właściwości

ExecutionWorld

Ś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

InjectionTarget

Właściwości

RegisteredContentScript

Chrome w wersji 96 lub nowszej

Właściwości

ScriptInjection

Właściwości

StyleOrigin

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

Typ wyliczeniowy

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

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

Zwroty

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise

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

Parametry

Zwroty

registerContentScripts()

Chrome w wersji 96 lub nowszej

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise

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

Parametry

Zwroty

removeCSS()

Chrome w wersji 90 lub nowszej

chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise

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

Parametry

Zwroty

unregisterContentScripts()

Chrome w wersji 96 lub nowszej

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise

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

Parametry

Zwroty

updateContentScripts()

Chrome w wersji 96 lub nowszej

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise

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

Parametry

Zwroty

O ile nie stwierdzono inaczej, treść tej strony jest objęta licencją Creative Commons – uznanie autorstwa 4.0, a fragmenty kodu są dostępne na licencji Apache 2.0. Szczegółowe informacje na ten temat zawierają zasady dotyczące witryny Google Developers. Java jest zastrzeżonym znakiem towarowym firmy Oracle i jej podmiotów stowarzyszonych.

Ostatnia aktualizacja: 2025-08-11 UTC.