Opis
Interfejs API userScripts
umożliwia wykonywanie skryptów użytkownika w kontekście Skrypty użytkownika.
Uprawnienia
userScripts
Aby korzystać z interfejsu API chrome.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 zastosowanie
Skrypt użytkownika to fragment kodu wstawiony na stronie internetowej w celu modyfikacji jej wyglądu lub działania. Skrypty są tworzone przez użytkowników lub pobierane z repozytorium skryptów lub rozszerzenia skryptów użytkownika.
Tryb programisty dla użytkowników rozszerzeń
Jako deweloper masz już włączony tryb programisty w swojej instalacji Chrome. W przypadku rozszerzeń skryptów użytkownika użytkownicy muszą też włączyć tryb programisty. Oto instrukcje, które możesz skopiować i wkleić do swojej dokumentacji.
- Na stronie Rozszerzenia wpisz adres
chrome://extensions
w nowej karcie. (Z założeniachrome://
adresów URL nie da się utworzyć linków). Włącz tryb programisty, klikając przełącznik obok Trybu programisty.
Aby sprawdzić, czy tryb programisty jest włączony, sprawdź, czy chrome.userScripts
zgłasza błąd. Na przykład:
function isUserScriptsAvailable() {
try {
// Property access which throws if developer mode is not enabled.
chrome.userScripts;
return true;
} catch {
// Not available.
return false;
}
}
Praca w izolowanym świecie
Zarówno skrypty użytkownika, jak i skrypty dotyczące treści mogą działać w odizolowanym świecie lub w 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 zmieniać środowisko JavaScript bez wpływu na stronę hostującą czy skrypty użytkownika i treści innych rozszerzeń. I na odwrót: skrypty użytkownika (i skrypty treści) nie są widoczne dla strony hostującej ani dla użytkownika i skryptów treści w innych rozszerzeniach. Skrypty działające w głównym świecie są dostępne dla stron hostujących i innych rozszerzeń oraz są widoczne dla stron hostujących oraz innych rozszerzeń. Aby wybrać świat, miń "USER_SCRIPT"
lub "MAIN"
, dzwoniąc pod numer userScripts.register()
.
Aby skonfigurować politykę bezpieczeństwa treści w środowisku USER_SCRIPT
, wywołaj połączenie userScripts.configureWorld()
:
chrome.userScripts.configureWorld({
csp: "script-src 'self'"
});
Wiadomości
Podobnie jak skrypty treści i dokumenty spoza ekranu, 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 jak dowolną inną część rozszerzenia). Są one jednak odbierane za pomocą specjalnych modułów obsługi zdarzeń (czyli nie używają onMessage
ani onConnect
). Takie moduły noszą nazwy runtime.onUserScriptMessage
i runtime.onUserScriptConnect
. Dedykowane moduły obsługi ułatwiają identyfikowanie wiadomości pochodzących ze skryptów użytkownika, które są mniej zaufanym kontekstem.
Przed wysłaniem wiadomości musisz wywołać metodę configureWorld()
z argumentem messaging
ustawionym na true
. Pamiętaj, że argumenty csp
i messaging
można przekazywać w tym samym czasie.
chrome.userScripts.configureWorld({
messaging: true
});
Aktualizacje rozszerzeń
Skrypty użytkownika są czyszczone po zaktualizowaniu rozszerzenia. Możesz je ponownie dodać, uruchamiając kod w module obsługi zdarzeń runtime.onInstalled
w skrypcie service worker rozszerzenia. Odpowiadaj tylko na "update"
przyczynę przekazanej do wywołania zwrotnego zdarzenia.
Przykład
Ten przykład pochodzi z przykładowego skryptu userScript w naszym repozytorium przykładów.
Zarejestruj skrypt
Poniższy przykład przedstawia podstawowe wywołanie do register()
. Pierwszy argument to tablica obiektów definiujących skrypty do zarejestrowania. Dostępnych jest więcej opcji niż pokazano tutaj.
chrome.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
Typy
ExecutionWorld
Świat JavaScriptu, w którym uruchamiany jest skrypt użytkownika.
Typ wyliczeniowy
"MAIN"
Określa środowisko wykonawcze DOM, czyli środowisko wykonawcze udostępniane skryptowi JavaScript strony hosta.
"USER_SCRIPT"
Określa środowisko wykonawcze specyficzne dla skryptów użytkownika i jest wykluczone z CSP strony.
RegisteredUserScript
Właściwości
-
allFrames
wartość logiczna opcjonalna
Jeśli 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.
-
excludeGlobs
string[] opcjonalny
Określa wzorce symboli wieloznacznych na stronach, na których ten skrypt użytkownika NIE będzie wstrzykiwany.
-
excludeMatches
string[] opcjonalny
Wyklucza strony, do których w innym przypadku zostałby wstrzyknięty ten skrypt użytkownika. Więcej informacji o składni tych ciągów znaków znajdziesz w sekcji Wzorce dopasowania.
-
id
string,
Identyfikator skryptu użytkownika określony w wywołaniu interfejsu API. Ta właściwość nie może zaczynać się od znaku „_”, ponieważ jest on zarezerwowany jako prefiks dla wygenerowanych identyfikatorów skryptów.
-
includeGlobs
string[] opcjonalny
Określa wzorce symboli wieloznacznych na stronach, na których będzie wstrzykiwany ten skrypt użytkownika.
-
js
Lista obiektów ScriptSource definiujących źródła skryptów, które mają być wstrzykiwane na pasujących stronach.
-
dopasowania
string[] opcjonalny
Określa, na których stronach będzie wstrzykiwany ten skrypt użytkownika. Więcej informacji o składni tych ciągów znaków znajdziesz w sekcji Wzorce dopasowania. Ta właściwość musi być określona dla ${ref:register}.
-
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
Środowisko wykonawcze JavaScript, w którym ma zostać uruchomiony skrypt. Wartość domyślna to
`USER_SCRIPT`
.
ScriptSource
Właściwości
-
kod
ciąg znaków opcjonalny
Ciąg tekstowy zawierający kod JavaScript do wstrzyknięcia. Należy podać dokładnie jedno z tych elementów:
file
lubcode
. -
plik
ciąg znaków opcjonalny
Ścieżka pliku JavaScript do wstrzyknięcia względem katalogu głównego rozszerzenia. Należy podać dokładnie jedno z tych elementów:
file
lubcode
.
UserScriptFilter
Właściwości
-
ids
string[] opcjonalny
getScripts
zwraca tylko skrypty o identyfikatorach określonych na tej liście.
WorldProperties
Właściwości
-
CSP
ciąg znaków opcjonalny
Określa światowy csp. Wartość domyślna to
`ISOLATED`
światowy csp. -
przesyłanie wiadomości
wartość logiczna opcjonalna
Określa, czy interfejsy API do przesyłania wiadomości są ujawniane. Wartość domyślna to
false
.
Metody
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
Konfiguruje środowisko wykonawcze `USER_SCRIPT`
.
Parametry
-
usługi
Zawiera konfigurację świata skryptu użytkownika.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Zwroty
-
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.
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
Zwraca wszystkie dynamicznie zarejestrowane skrypty użytkownika dotyczące tego rozszerzenia.
Parametry
-
filter
Opcjonalny UserScriptFilter
Jeśli zostanie określona, zwraca tylko pasujące do niej skrypty użytkownika.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(scripts: RegisteredUserScript[]) => void
-
skrypty
-
Zwroty
-
Promise<RegisteredUserScript[]>
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.
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
Rejestruje co najmniej 1 skrypt użytkownika dla tego rozszerzenia.
Parametry
-
skrypty
Zawiera listę skryptów użytkownika do zarejestrowania.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Zwroty
-
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.
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
Wyrejestrowuje wszystkie dynamicznie rejestrowane skrypty użytkownika dla tego rozszerzenia.
Parametry
-
filter
Opcjonalny UserScriptFilter
Jeśli ta metoda zostanie określona, wyrejestruje tylko te skrypty użytkownika, które do niej pasują.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Zwroty
-
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.
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
Aktualizuje co najmniej 1 skrypt użytkownika w tym rozszerzeniu.
Parametry
-
skrypty
Zawiera listę skryptów użytkownika 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
Zwroty
-
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.