chrome.userScripts

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

Chrome 120 i nowsze MV3 i nowsze

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.

1. Na stronie Rozszerzenia wpisz adres chrome://extensions w nowej karcie. (Z założenia chrome:// adresów URL nie da się utworzyć linków).

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

   

   Strona Rozszerzenia (chrome://extensions)

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

  ScriptSource[]

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

• 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 lub code.

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

Obietnica

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

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

Obietnica

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

    RegisteredUserScript[]

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

Obietnica

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

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

Obietnica

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

Obietnica

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

Aktualizuje co najmniej 1 skrypt użytkownika w tym rozszerzeniu.

Parametry

• skrypty

  RegisteredUserScript[]

  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.