Opis
Użyj interfejsu API userScripts, aby wykonywać skrypty użytkownika w kontekście skryptów użytkownika.
Uprawnienia
userScriptsAby używać interfejsu User Scripts API, browser.userScripts, dodaj uprawnienie "userScripts" do pliku manifest.json i "host_permissions" w przypadku witryn, w których chcesz uruchamiać skrypty.
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
Dostępność
Pojęcia i użycie
Skrypt użytkownika to fragment kodu wstrzykiwany na stronę internetową w celu zmiany jej wyglądu lub działania. W przeciwieństwie do innych funkcji rozszerzeń, takich jak skrypty treści i interfejs API browser.scripting, interfejs User Scripts API umożliwia uruchamianie dowolnego kodu. Ten interfejs API jest wymagany w przypadku rozszerzeń, które uruchamiają skrypty dostarczone przez użytkownika i nie mogą być dostarczane jako część pakietu rozszerzenia.
Włącz korzystanie z interfejsu userScripts API
Gdy rozszerzenie otrzyma uprawnienia do korzystania z interfejsu userScripts API, użytkownicy muszą włączyć określony przełącznik, aby zezwolić rozszerzeniu na korzystanie z tego interfejsu. Wymagany przełącznik i działanie interfejsu API po wyłączeniu zależą od wersji Chrome.
Aby określić, który przełącznik użytkownik musi włączyć, np. podczas wprowadzania nowego użytkownika, użyj tego sprawdzenia:
let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
// Allow User Scripts toggle will be used.
} else {
// Developer mode toggle will be used.
}
W sekcjach poniżej opisujemy różne przełączniki i sposób ich włączania.
Chrome w wersjach starszych niż 138 (przełącznik trybu programisty)
Jeśli jesteś deweloperem rozszerzeń, masz już włączony tryb dewelopera w swojej instalacji Chrome. Użytkownicy muszą też włączyć tryb programisty.
Możesz skopiować i wkleić te instrukcje do dokumentacji rozszerzenia dla użytkowników.
- Otwórz stronę Rozszerzenia, wpisując
chrome://extensionsw nowej karcie. (Z założenia adresy URLchrome://nie są linkami). Włącz tryb programisty, klikając przełącznik obok opcji Tryb programisty.
Strona Rozszerzenia (chrome://extensions)
Chrome w wersji 138 i nowszych (przełącznik Zezwalaj na skrypty użytkownika)
Przełącznik Zezwalaj na skrypty użytkownika znajduje się na stronie z informacjami o każdym rozszerzeniu (np. chrome://extensions/?id=YOUR_EXTENSION_ID).
Możesz skopiować i wkleić te instrukcje do dokumentacji rozszerzenia dla użytkowników:
- Otwórz stronę Rozszerzenia, wpisując
chrome://extensionsw nowej karcie. (Z założenia adresy URLchrome://nie są linkami). - Aby wyświetlić szczegółowe informacje o rozszerzeniu, kliknij przycisk „Szczegóły” na karcie rozszerzenia.
- Kliknij przełącznik obok opcji Zezwalaj na skrypty użytkownika.
Sprawdzanie dostępności interfejsu API
Zalecamy wykonanie poniższego sprawdzenia, aby określić, czy interfejs API userScripts jest włączony, ponieważ działa on we wszystkich wersjach Chrome. Ta kontrola próbuje wywołać metodę browser.userScripts(), która powinna zawsze zakończyć się powodzeniem, gdy interfejs API jest dostępny. Jeśli to wywołanie zwróci błąd, interfejs API jest niedostępny:
function isUserScriptsAvailable() {
try {
// Method call which throws if API permission or toggle is not enabled.
browser.userScripts.getScripts();
return true;
} catch {
// Not available.
return false;
}
}
Praca w izolowanych światach
Zarówno skrypty użytkownika, jak i skrypty treści mogą działać w izolowanym lub głównym świecie. Izolowany świat to środowisko wykonawcze, które nie jest dostępne dla strony hosta ani innych rozszerzeń. Dzięki temu skrypt użytkownika może zmienić swoje środowisko JavaScript bez wpływu na stronę hosta lub skrypty użytkownika i skrypty treści innych rozszerzeń. Z kolei skrypty użytkownika (i skrypty treści) nie są widoczne dla strony hosta ani dla skryptów użytkownika i skryptów treści innych rozszerzeń. Skrypty działające w głównym świecie są dostępne dla stron hosta i innych rozszerzeń oraz są widoczne dla stron hosta i innych rozszerzeń. Aby wybrać świat, podczas wywoływania funkcji userScripts.register() przekaż "USER_SCRIPT" lub "MAIN".
Aby skonfigurować zasady zabezpieczeń treści dla świata USER_SCRIPT, wywołaj userScripts.configureWorld():
browser.userScripts.configureWorld({
csp: "script-src 'self'"
});
Wiadomości
Podobnie jak skrypty treści i dokumenty poza ekranem, skrypty użytkownika komunikują się z innymi częściami rozszerzenia za pomocą wiadomości (co oznacza, że mogą wywoływać runtime.sendMessage() i runtime.connect() tak samo jak każda inna część rozszerzenia). Są one jednak odbierane za pomocą dedykowanych modułów obsługi zdarzeń (co oznacza, że nie używają onMessage ani onConnect). Te moduły obsługi to runtime.onUserScriptMessage i runtime.onUserScriptConnect. Dedykowane moduły obsługi ułatwiają identyfikowanie wiadomości ze skryptów użytkownika, które są mniej zaufanym kontekstem.
Przed wysłaniem wiadomości musisz wywołać configureWorld() z argumentem messaging ustawionym na true. Pamiętaj, że argumenty csp i messaging można przekazywać jednocześnie.
browser.userScripts.configureWorld({
messaging: true
});
Aktualizacje rozszerzeń
Skrypty użytkownika są czyszczone podczas aktualizacji rozszerzenia. Możesz je dodać z powrotem, uruchamiając kod w module obsługi zdarzeń runtime.onInstalled w skrypcie service worker rozszerzenia. Odpowiadaj tylko na zdarzenie "update" reason przekazywane do wywołania zwrotnego zdarzenia.
Przykład
Ten przykład pochodzi z przykładowego skryptu userScript w naszym repozytorium przykładów.
Rejestrowanie skryptu
Poniższy przykład pokazuje podstawowe wywołanie register(). Pierwszy argument to tablica obiektów definiujących skrypty do zarejestrowania. Dostępnych jest więcej opcji niż te, które są tu widoczne.
browser.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
Typy
ExecutionWorld
Środowisko JavaScriptu, w którym ma zostać wykonany skrypt użytkownika.
Typ wyliczeniowy
"MAIN"
Określa środowisko wykonawcze DOM, które jest środowiskiem wykonawczym współdzielonym z kodem JavaScript strony hosta.
"USER_SCRIPT"
Określa środowisko wykonawcze, które jest specyficzne dla skryptów użytkownika i jest wyłączone z zasad CSP strony.
InjectionResult
Właściwości
-
documentId
tekst
Dokument powiązany z wstrzyknięciem.
-
błąd
ciąg znaków opcjonalny
Błąd (jeśli wystąpił).
erroriresultwykluczają się nawzajem. -
frameId
liczba
Ramka powiązana z wstrzyknięciem.
-
wynik
any optional
Wynik wykonania skryptu.
InjectionTarget
Właściwości
-
allFrames
boolean opcjonalne
Określa, czy skrypt ma być wstrzykiwany do wszystkich ramek na karcie. Wartość domyślna to fałsz. Jeśli określono parametr
frameIds, nie może to być prawda. -
documentIds
string[] opcjonalne
Identyfikatory konkretnych dokumentów, do których mają zostać wstawione dane. Nie można ustawić tej wartości, jeśli ustawiono
frameIds. -
frameIds
number[] opcjonalny
Identyfikatory konkretnych ramek, do których ma zostać wstrzyknięty skrypt.
-
tabId
liczba
Identyfikator karty, do której ma zostać wstrzyknięty skrypt.
RegisteredUserScript
Właściwości
-
allFrames
boolean opcjonalne
Jeśli ma wartość „true”, zostanie wstrzyknięty do wszystkich ramek, nawet jeśli ramka nie jest najwyższą ramką na karcie. Każda ramka jest sprawdzana niezależnie pod kątem wymagań dotyczących adresów URL. Jeśli wymagania nie są spełnione, kod nie zostanie wstrzyknięty do ramek podrzędnych. Wartość domyślna to false, co oznacza, że dopasowywana jest tylko górna ramka.
-
excludeGlobs
string[] opcjonalne
Określa wzorce symboli wieloznacznych dla stron, na których ten skrypt użytkownika NIE będzie wstrzykiwany.
-
excludeMatches
string[] opcjonalne
Wyklucza strony, na których w przeciwnym razie zostałby wstrzyknięty ten skrypt użytkownika. Więcej informacji o składni tych ciągów znajdziesz w artykule Wzorce dopasowania.
-
id
tekst
Identyfikator skryptu użytkownika określony w wywołaniu interfejsu API. Ta właściwość nie może zaczynać się od „_”, ponieważ jest to zarezerwowany prefiks dla wygenerowanych identyfikatorów skryptów.
-
includeGlobs
string[] opcjonalne
Określa wzorce symboli wieloznacznych dla stron, na których zostanie wstrzyknięty ten skrypt użytkownika.
-
js
ScriptSource[] opcjonalny
Lista obiektów ScriptSource definiujących źródła skryptów, które mają zostać wstrzyknięte na strony z dopasowaniem. Ta właściwość musi być określona dla typu ${ref:register} i musi być niepustą tablicą.
-
pasuje do
string[] opcjonalne
Określa, na których stronach zostanie wstrzyknięty ten skrypt użytkownika. Więcej informacji o składni tych ciągów znajdziesz w artykule Wzorce dopasowania. Ta właściwość musi być określona w przypadku elementu ${ref:register}.
-
runAt
RunAt opcjonalny
Określa, kiedy pliki JavaScript są wstrzykiwane na stronę internetową. Preferowana i domyślna wartość to
document_idle. -
świat
ExecutionWorld opcjonalny
Środowisko wykonawcze JavaScriptu, w którym ma zostać uruchomiony skrypt. Wartość domyślna to
`USER_SCRIPT`. -
worldId
ciąg znaków opcjonalny
Chrome 133 lub nowsza browser.* od Chrome 148Określa identyfikator środowiska skryptu użytkownika, w którym ma zostać wykonany. Jeśli zostanie pominięty, skrypt zostanie wykonany w domyślnym środowisku skryptu użytkownika. Jest prawidłowa tylko wtedy, gdy parametr
worldzostanie pominięty lub ma wartośćUSER_SCRIPT. Wartości z podkreśleniami na początku (_) są zarezerwowane.
ScriptSource
Właściwości
-
kod
ciąg znaków opcjonalny
Ciąg tekstowy zawierający kod JavaScript do wstawienia. Należy podać tylko jedną z tych wartości:
filelubcode. -
plik
ciąg znaków opcjonalny
Ścieżka pliku JavaScript do wstrzyknięcia, podana w odniesieniu do katalogu głównego rozszerzenia. Należy podać tylko jedną z tych wartości:
filelubcode.
UserScriptFilter
Właściwości
-
identyfikatory
string[] opcjonalne
getScriptszwraca tylko skrypty o identyfikatorach podanych na tej liście.
UserScriptInjection
Właściwości
-
injectImmediately
boolean opcjonalne
Określa, czy wstrzyknięcie powinno zostać wywołane w celu jak najszybciej. Pamiętaj, że nie gwarantuje to, że wstrzyknięcie nastąpi przed wczytaniem strony, ponieważ strona może już zostać wczytana, zanim skrypt dotrze do celu.
-
js
Lista obiektów ScriptSource definiujących źródła skryptów, które mają zostać wstrzyknięte do celu.
-
cel
Szczegóły określające cel, do którego ma zostać wstrzyknięty skrypt.
-
świat
ExecutionWorld opcjonalny
„Środowisko” JavaScriptu, w którym ma zostać uruchomiony skrypt. Wartość domyślna to
USER_SCRIPT. -
worldId
ciąg znaków opcjonalny
Określa identyfikator środowiska skryptu użytkownika, w którym ma zostać wykonany. Jeśli zostanie pominięty, skrypt zostanie wykonany w domyślnym środowisku skryptu użytkownika. Jest prawidłowa tylko wtedy, gdy parametr
worldzostanie pominięty lub ma wartośćUSER_SCRIPT. Wartości z podkreśleniami na początku (_) są zarezerwowane.
WorldProperties
Właściwości
-
csp
ciąg znaków opcjonalny
Określa dostawcę usług komunikacyjnych na świecie. Domyślna wartość to
`ISOLATED`world csp. -
SMS
boolean opcjonalne
Określa, czy interfejsy API do obsługi wiadomości są widoczne. Wartość domyślna to
false. -
worldId
ciąg znaków opcjonalny
Chrome 133 lub nowsza browser.* od Chrome 148Określa identyfikator konkretnego środowiska skryptu użytkownika, które ma zostać zaktualizowane. Jeśli nie zostanie podany, aktualizuje właściwości domyślnego środowiska skryptów użytkownika. Wartości z podkreśleniami na początku (
_) są zarezerwowane.
Metody
configureWorld()
browser.userScripts.configureWorld(
properties: WorldProperties,
): Promise<void>
Konfiguruje środowisko wykonawcze `USER_SCRIPT`.
Parametry
-
właściwości
Zawiera konfigurację świata skryptu użytkownika.
Zwroty
-
thought Promise<void>
Obietnica, która zostanie spełniona po skonfigurowaniu świata.
execute()
browser.userScripts.execute(
injection: UserScriptInjection,
): Promise<InjectionResult[]>
Wstawia skrypt w kontekście docelowym. Domyślnie skrypt zostanie uruchomiony o 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 jeszcze wczytana. Jeśli skrypt zwraca obietnicę, przeglądarka poczeka na jej spełnienie i zwróci wynikową wartość.
Parametry
-
wstrzykiwanie
Zwroty
-
Promise<InjectionResult[]>
getScripts()
browser.userScripts.getScripts(
filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>
Zwraca wszystkie dynamicznie zarejestrowane skrypty użytkownika dla tego rozszerzenia.
Parametry
-
filtr
UserScriptFilter opcjonalny
Jeśli zostanie określony, ta metoda zwraca tylko pasujące skrypty użytkownika.
Zwroty
-
Promise<RegisteredUserScript[]>
Obiekt Promise, który jest rozwiązywany za pomocą zarejestrowanych skryptów. Jeśli wystąpi błąd, obietnica zostanie odrzucona.
getWorldConfigurations()
browser.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>
Pobiera wszystkie zarejestrowane konfiguracje świata.
Zwroty
-
Promise<WorldProperties[]>
Obiekt Promise, który jest rozwiązywany za pomocą zarejestrowanych konfiguracji świata.
register()
browser.userScripts.register(
scripts: RegisteredUserScript[],
): Promise<void>
Rejestruje co najmniej 1 skrypt użytkownika dla tego rozszerzenia.
Parametry
-
skrypty
Zawiera listę skryptów użytkownika do zarejestrowania.
Zwroty
-
thought Promise<void>
Obietnica, która zostanie spełniona po pełnym zarejestrowaniu skryptów. Jeśli wystąpi błąd, obietnica zostanie odrzucona.
resetWorldConfiguration()
browser.userScripts.resetWorldConfiguration(
worldId?: string,
): Promise<void>
Resetuje konfigurację świata skryptu użytkownika. Wszystkie skryptu wstrzykiwane do świata o określonym identyfikatorze będą używać domyślnej konfiguracji świata.
Parametry
-
worldId
ciąg znaków opcjonalny
Identyfikator środowiska skryptu użytkownika, które ma zostać zresetowane. Jeśli zostanie pominięty, resetuje konfigurację domyślnego świata.
Zwroty
-
thought Promise<void>
Obietnica, która zostanie spełniona po zresetowaniu konfiguracji.
unregister()
browser.userScripts.unregister(
filter?: UserScriptFilter,
): Promise<void>
Wyrejestrowuje wszystkie dynamicznie zarejestrowane skrypty użytkownika dla tego rozszerzenia.
Parametry
-
filtr
UserScriptFilter opcjonalny
Jeśli zostanie określona, ta metoda wyrejestruje tylko pasujące skrypty użytkownika.
Zwroty
-
thought Promise<void>
Obietnica, która zostanie spełniona po całkowitym wyrejestrowaniu skryptów. Jeśli wystąpi błąd, obietnica zostanie odrzucona.
update()
browser.userScripts.update(
scripts: RegisteredUserScript[],
): Promise<void>
Aktualizuje co najmniej 1 skrypt użytkownika dla tego rozszerzenia.
Parametry
-
skrypty
Zawiera listę skryptów użytkownika do zaktualizowania. Właściwość jest aktualizowana w przypadku istniejącego skryptu tylko wtedy, gdy jest określona w tym obiekcie. Jeśli podczas analizowania skryptu lub sprawdzania poprawności pliku wystąpią błędy albo podane identyfikatory nie odpowiadają w pełni zarejestrowanemu skryptowi, żadne skrypty nie zostaną zaktualizowane.
Zwroty
-
thought Promise<void>
Obietnica, która zostanie spełniona po pełnym zaktualizowaniu skryptów. Jeśli wystąpi błąd, obietnica zostanie odrzucona.