Opis
Interfejs API chrome.scripting
umożliwia wykonywanie skryptu w różnych kontekstach.
Uprawnienia
scripting
Dostępność
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.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 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
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
icss
. -
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
icss
. -
pochodzenie
Opcjonalny StyleOrigin
Pochodzenie stylu dla wstrzyknięcia. Domyślna wartość to
'AUTHOR'
. -
cel
Szczegóły określające element docelowy, do którego ma zostać wstawiony kod CSS.
ExecutionWorld
Ś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 wersjeDokument powiązany z wstrzykiwaniem.
-
frameId
Liczba
Chrome 90 i nowszeRamka 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 wersjeIdentyfikatory 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
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 wersjeWskazuje, 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 wersjeArgumenty 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
lubfunc
. -
injectImmediately
wartość logiczna opcjonalna
Chrome 102 i nowsze wersjeOkreś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.
-
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 wersjeFunkcja 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
lubfunc
.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()
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
-
zastrzyk
Szczegóły skryptu do wstrzyknięcia.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(results: InjectionResult[]) => void
-
wyniki
-
Akcje powrotne
-
Promise<InjectionResult[]>
Chrome 90 i nowszeObietnice 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()
chrome.scripting.getRegisteredContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Zwraca wszystkie dynamicznie zarejestrowane skrypty treści dla tego rozszerzenia, które pasują do danego filtra.
Parametry
-
filter
Opcjonalny ContentScriptFilter
Obiekt do filtrowania dynamicznie zarejestrowanych skryptów rozszerzenia.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(scripts: RegisteredContentScript[]) => void
-
skrypty
-
Akcje powrotne
-
Promise<RegisteredContentScript[]>
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()
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
Szczegóły stylów do wstawienia.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Akcje powrotne
-
Promise<void>
Chrome 90 i nowszeObietnice 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()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Rejestruje co najmniej 1 skrypt treści dla tego rozszerzenia.
Parametry
-
skrypty
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()
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
Szczegóły stylów do usunięcia. Pamiętaj, że właściwości
css
,files
iorigin
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()
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()
chrome.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Aktualizuje co najmniej 1 skrypt treści dla tego rozszerzenia.
Parametry
-
skrypty
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.