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.

   

   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

• filtr

  UserScriptFilter opcjonalny

  Jeśli jest podany, zwraca tylko skrypty użytkownika, które mu odpowiadają.

• wywołanie zwrotne

  function opcjonalny

  Parametr callback ma postać:

  (scripts: RegisteredUserScript[]) => void

  • skrypty

    RegisteredUserScript[]

Zwroty

• Promise<RegisteredUserScript[]>

  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

• wywołanie zwrotne

  function opcjonalny

  Parametr callback ma postać:

  (worlds: WorldProperties[]) => void

  • światów

    WorldProperties[]

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

• skrypty

  RegisteredUserScript[]

  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

• skrypty

  RegisteredUserScript[]

  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.