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 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 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 są przeznaczone do łączenia).

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

    na stronie Rozszerzenia,

    Strona Rozszerzenia (chrome://extensions)

Aby sprawdzić, czy tryb programisty jest włączony, sprawdź, czy funkcja 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, wywołaj funkcję userScripts.configureWorld():USER_SCRIPT

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ą onMessage ani onConnect). Te moduły obsługi mają nazwy runtime.onUserScriptMessage i runtime.onUserScriptConnect. Dedykowane procedury obsługi ułatwiają identyfikację komunikatów ze skryptów użytkownika, które są kontekstem o mniejszym zaufaniu.

Przed wysłaniem wiadomości musisz wywołać funkcję configureWorld(), podając jako argument messaging 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 podczas aktualizacji rozszerzenia. Możesz je ponownie dodać, uruchamiając kod w obiekcie runtime.onInstalled w obiekcie rozszerzenia service worker. Odpowiedz tylko na "update"reason przekazany do funkcji 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 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 JavaScriptowi 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ść true, 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[] opcjonalny

    Określa wzorce symboli wieloznacznych dla stron, na które skrypt użytkownika NIE BĘDZIE wstrzykiwany.

  • excludeMatches

    string[] opcjonalny

    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 (artykuł w języku angielskim).

  • 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 dla wygenerowanych identyfikatorów skryptu.

  • includeGlobs

    string[] opcjonalny

    Określa wzorce symboli wieloznacznych dla stron, na które ma być wstrzykiwany skrypt użytkownika.

  • js

    ScriptSource[] opcjonalnie

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

  • pasuje do

    string[] opcjonalny

    Określa, na których stronach ma być wstrzykiwane to skrypt użytkownika. Więcej informacji o składni tych ciągów znajdziesz w artykule Wzorce dopasowania (artykuł w języku angielskim). 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 wykonywania JavaScriptu, w którym ma być uruchamiany skrypt. Wartość domyślna to `USER_SCRIPT`.

  • worldId

    ciąg znaków opcjonalny

    Oczekuje

    Określa identyfikator świata skryptu użytkownika, w którym ma być wykonywany. Jeśli go pominiesz, skrypt zostanie wykonany w domyślnym świecie skryptu użytkownika. Obowiązuje tylko wtedy, gdy world jest 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 wstrzyknięcia. Należy podać dokładnie jedną wartość file lub code.

  • plik

    ciąg znaków opcjonalny

    Ścieżka do pliku JavaScript, który ma zostać wstrzyknięty w stosunku do katalogu głównego rozszerzenia. Musisz podać dokładnie jedną wartość file lub code.

UserScriptFilter

Właściwości

  • ids

    string[] opcjonalny

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

WorldProperties

Właściwości

  • csp

    ciąg znaków opcjonalny

    Określa csp na całym świecie. Domyślnie jest 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

    ciąg znaków opcjonalny

    Oczekuje

    Określa identyfikator konkretnego świata skryptu użytkownika, który ma zostać zaktualizowany. Jeśli nie zostanie podany, zaktualizuje właściwości domyślnego świata skryptu użytkownika. Wartości z podkreśleniami na początku (_) 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żna używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwraca ten sam typ, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

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żna używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwraca ten sam typ, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

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żna używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwraca ten sam typ, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

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żna używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwraca ten sam typ, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

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

    ciąg znaków opcjonalny

    Identyfikator świata skryptu użytkownika, który ma zostać zresetowany. W przypadku pominięcia spowoduje zresetowanie domyślnej konfiguracji ś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żna używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwraca ten sam typ, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

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żna używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwraca ten sam typ, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

update()

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

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

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 on podany 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żna używać obu w tym samym wywołaniu funkcji. Obiet na obietnice jest rozwiązywany z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.