chrome.userScripts

Opis

Użyj interfejsu userScripts API, aby wykonać skrypty użytkownika w kontekście skryptów użytkownika.

Uprawnienia

userScripts

Aby korzystać z interfejsu API chrome.userScripts, dodaj uprawnienie "userScripts" do pliku manifest.json i do stron, na których chcesz uruchamiać skrypty."host_permissions"

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

Dostępność

Chrome 120+ MV3+

Pojęcia i zastosowanie

Skrypt użytkownika to krótki fragment kodu wstrzyknięty do strony internetowej w celu modyfikacji jej wyglądu lub działania. Skrypty są tworzone przez użytkowników lub pobierane z repozytorium skryptów lub z rozszerzenia skryptu użytkownika.

Tryb programisty dla użytkowników rozszerzeń

Jako deweloper rozszerzeń 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.

  1. Otwórz stronę Rozszerzenia, wpisując chrome://extensions w nowej karcie. (adresy URL chrome:// nie można łączyć).

  2. Włącz tryb programisty, klikając przełącznik obok opcji Tryb programisty.

    na stronie Rozszerzenia,

    Strona Rozszerzenia (chrome://extensions)

Aby sprawdzić, czy tryb dla deweloperów jest włączony, sprawdź, czy wywołanie chrome.userScripts zwraca 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 odizolowanych światach

Zarówno skrypty użytkownika, jak i skrypty treści mogą działać w świecie izolowanym, jak i w świecie głównym. Odseparowany świat to środowisko wykonania, które nie jest dostępne dla strony hosta ani innych rozszerzeń. Dzięki temu skrypt użytkownika może zmienić środowisko JavaScript bez wpływu na stronę hosta ani skrypty użytkownika i treści innych rozszerzeń. Z drugiej strony skrypty użytkownika (i skrypty treści) nie są widoczne dla strony hosta ani skryptów użytkownika i skryptów treści innych rozszerzeń. Skrypty działające w świecie głównym są dostępne dla stron hosta i innych rozszerzeń oraz są widoczne dla stron hosta i innych rozszerzeń. Aby wybrać cały świat, prześlij wartość "USER_SCRIPT" lub "MAIN", gdy wywołujesz funkcję userScripts.register().

Aby skonfigurować zasady zabezpieczeń treści dla wszystkich użytkowników na świecie, USER_SCRIPT:userScripts.configureWorld()

chrome.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ć metody runtime.sendMessage() i runtime.connect() tak samo jak każda inna część rozszerzenia). Są one jednak odbierane za pomocą specjalnych modułów obsługi zdarzeń (czyli nie używają funkcji onMessage ani onConnect). Te moduły obsługi mają nazwy runtime.onUserScriptMessage i runtime.onUserScriptConnect. Dedykowane procedury obsługi ułatwiają identyfikację wiadomości ze skryptów użytkownika, które są mniej wiarygodnym kontekstem.

Przed wysłaniem wiadomości musisz wywołać funkcję configureWorld(), ustawiając argument messaging na wartość true. Pamiętaj, że argumenty csp i messaging mogą być przekazywane jednocześnie.

chrome.userScripts.configureWorld({
  messaging: true
});

Aktualizacje rozszerzeń

Skrypty użytkownika są usuwane, gdy rozszerzenie jest aktualizowane. Możesz je dodać ponownie, uruchamiając kod w obiekcie runtime.onInstalled w obiekcie rozszerzenia service worker. Odpowiadaj tylko na "update"powód przekazany do wywołania zwrotnego zdarzenia.

Przykład

Ten przykład pochodzi z przykładowego skryptu userScript w naszym repozytorium przykładów.

Rejestrowanie skryptu

Ten przykład pokazuje podstawowy wywołanie funkcji register(). Pierwszy argument to tablica obiektów definiujących skrypty, które mają zostać zarejestrowane. Dostępnych jest więcej opcji niż pokazano tutaj.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

Typy

ExecutionWorld

Środowisko JavaScript, w którym ma działać skrypt użytkownika.

Typ wyliczeniowy

„MAIN”
Określa środowisko wykonania DOM, czyli środowisko wykonania udostępnione kodom JavaScript strony hosta.

„USER_SCRIPT”
Określa środowisko wykonania, które jest specyficzne dla skryptów użytkownika i nie podlega zasadom CSP strony.

RegisteredUserScript

Właściwości

  • allFrames

    wartość logiczna opcjonalna

    Jeśli ma wartość prawda, zostanie wstrzyknięty do wszystkich ramek, nawet jeśli nie jest to najwyższa ramka na karcie. Każda ramka jest sprawdzana niezależnie pod kątem wymagań dotyczących adresu URL. Jeśli wymagania te nie są spełnione, nie zostanie wstrzyknięta do ramek podrzędnych. Domyślnie ustawiona jest wartość false, co oznacza, że dopasowywany jest tylko górny element.

  • excludeGlobs

    string[] opcjonalnie

    Określa wzorce symboli wieloznacznych dla stron, na które NIE będzie wstrzykiwany skrypt użytkownika.

  • excludeMatches

    string[] opcjonalnie

    Wyklucza strony, na które skrypt użytkownika miałby zostać wstrzyknięty. Więcej informacji o składni tych ciągów znajdziesz w artykule Wzorce dopasowania.

  • id

    ciąg znaków

    Identyfikator skryptu użytkownika określonego w wywołaniu interfejsu API. Ta właściwość nie może się zaczynać od „_”, ponieważ jest zarezerwowana jako prefiks wygenerowanych identyfikatorów skryptu.

  • includeGlobs

    string[] opcjonalnie

    Określa wzorce symboli wieloznacznych dla stron, na które zostanie wstrzyknięty skrypt użytkownika.

  • js

    ScriptSource[] opcjonalnie

    Lista obiektów ScriptSource definiujących źródła skryptów, które mają być wstrzykiwane na pasujące strony. Ta właściwość musi być określona w przypadku ${ref:register} i musi być niepustym tablicą.

  • pasuje do

    string[] opcjonalnie

    Określa, na których stronach ma być wstrzykiwany 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 ${ref:register}.

  • runAt

    RunAt opcjonalny

    Określa, kiedy pliki JavaScript są wstrzykiwane na stronę internetową. Preferowaną i domyślną wartością jest document_idle.

  • świat

    ExecutionWorld opcjonalny

    Środowisko wykonawcze JavaScript, w którym ma być wykonywany skrypt. Wartość domyślna to `USER_SCRIPT`.

  • worldId

    string opcjonalny

    Oczekuje

    W przypadku podania określa konkretny identyfikator świata skryptu użytkownika, w którym ma być wykonywany. Obowiązuje tylko wtedy, gdy world jest pominięty lub ma wartość USER_SCRIPT. Jeśli pominiesz ten parametr, skrypt zostanie wykonany w domyślnym świecie skryptu użytkownika. Wartości z początkowym podkreśleniem (_) są zarezerwowane.

ScriptSource

Właściwości

  • kod

    string opcjonalny

    Ciąg tekstowy zawierający kod JavaScript do wstrzyknięcia. Należy podać dokładnie jedną z tych właściwości: file lub code.

  • plik

    string opcjonalny

    Ścieżka do pliku JavaScript, który ma zostać wstrzyknięty względem katalogu głównego rozszerzenia. Należy podać dokładnie jedną z tych właściwości: file lub code.

UserScriptFilter

Właściwości

  • ids

    string[] opcjonalnie

    getScripts zwraca tylko skrypty o identyfikatorach podanych na tej liście.

WorldProperties

Właściwości

  • csp

    string opcjonalny

    Określa csp na całym świecie. Wartość domyślna to `ISOLATED` csp na całym świecie.

  • SMS

    wartość logiczna opcjonalna

    Określa, czy interfejsy API wiadomości są dostępne. Wartość domyślna to false.

  • worldId

    string opcjonalny

    Oczekuje

    Określa identyfikator konkretnego świata skryptu użytkownika, który ma zostać zaktualizowany. Jeśli nie zostanie podany, właściwości zostaną zaktualizowane w domyślnym świecie skryptu użytkownika. Wartości z początkowym podkreśleniem (_) są zarezerwowane.

Metody

configureWorld()

Obietnice 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

Konfiguruje środowisko wykonawcze `USER_SCRIPT`.

Parametry

  • usługi

    WorldProperties

    Zawiera konfigurację świata skryptu użytkownika.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

getScripts()

Obietnice 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

Zwraca wszystkie skrypty użytkownika zarejestrowane dynamicznie w przypadku tego rozszerzenia.

Parametry

Zwroty

  • Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

getWorldConfigurations()

Obietnica Oczekuje
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

Pobiera wszystkie zarejestrowane konfiguracje świata.

Parametry

Zwroty

  • Promise<WorldProperties[]>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

register()

Obietnice 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Rejestruje co najmniej 1 skrypt użytkownika dla tego rozszerzenia.

Parametry

  • Zawiera listę skryptów użytkownika do zarejestrowania.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

resetWorldConfiguration()

Obietnica Oczekuje
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

Resetuje konfigurację świata skryptu użytkownika. Wszystkie skrypty, które wstrzykują do świata określony identyfikator, będą używać domyślnej konfiguracji świata.

Parametry

  • worldId

    string opcjonalny

    Identyfikator świata skryptu użytkownika, który ma zostać zresetowany. W przypadku pominięcia zresetuje domyślną konfigurację świata.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

unregister()

Obietnice 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

Rejestruje wszystkie skrypty użytkownika zarejestrowane dynamicznie w przypadku tego rozszerzenia.

Parametry

  • filtr

    UserScriptFilter opcjonalny

    Jeśli jest określona, ta metoda rejestruje tylko skrypty użytkownika, które się z nią zgadzają.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

update()

Obietnice 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Zaktualizuje co najmniej 1 skrypt użytkownika dla tej wtyczki.

Parametry

  • Zawiera listę skryptów użytkownika, które mają zostać zaktualizowane. Właściwość jest aktualizowana tylko w przypadku istniejącego skryptu, jeśli jest ona określona w tym obiekcie. Jeśli podczas analizowania skryptu lub sprawdzania pliku wystąpią błędy albo podane identyfikatory nie będą odpowiadać w pełni zarejestrowanemu skryptowi, żadne skrypty nie zostaną zaktualizowane.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.