chrome.userScripts

Opis

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

Uprawnienia

userScripts

Aby używać interfejsu User Scripts API, chrome.userScripts, dodaj do pliku manifest.json uprawnienia "userScripts" i "host_permissions" dla 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ść

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. W przeciwieństwie do innych funkcji rozszerzenia, takich jak skrypty treści i interfejs API chrome.scripting, interfejs API skryptów użytkownika umożliwia uruchamianie dowolnego kodu. Ten interfejs API jest wymagany w przypadku rozszerzeń, które uruchamiają skrypty dostarczone przez użytkownika i których nie można przesłać w ramach pakietu rozszerzenia.

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 własnej 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 lub 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ń. Scenariusze 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 USER_SCRIPT, wywołaj funkcję 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ć 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 podczas aktualizacji rozszerzenia. Możesz je dodać ponownie, uruchamiając kod w obiekcie runtime.onInstalled w obiekcie rozszerzenia service worker. Odpowiadaj tylko na "update"reason 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

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 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

  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 skrypt użytkownika NIE BĘDZIE wstrzykiwany.

• 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 ma być wstrzykiwany 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ć uruchamiany skrypt. Wartość domyślna to `USER_SCRIPT`.

• worldId

  string opcjonalny

  Chrome 133 lub nowszy

  Określa identyfikator świata skryptu użytkownika, w którym ma być wykonywany. Jeśli nie zostanie podany, 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 początkowym podkreśleniem (_) są zarezerwowane.

ScriptSource

Właściwości

• kod

  string opcjonalny

  Ciąg tekstowy zawierający kod JavaScript do wstrzyknięcia. Musisz 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. Musisz 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

  Chrome 133 lub nowszy

  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 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.

• callback

  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ą.

• callback

  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()

Obietnice Chrome 133 lub nowszy

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

Pobiera wszystkie zarejestrowane konfiguracje świata.

Parametry

• callback

  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.

• callback

  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()

Obietnice Chrome 133 lub nowszy

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.

• callback

  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,
)

Rejestrowanie wszystkich dynamicznie zarejestrowanych skryptów użytkownika w tym rozszerzeniu zostanie anulowane.

Parametry

• filtr

  UserScriptFilter opcjonalny

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

• callback

  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.

• callback

  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.