chrome.userScripts

Opis

Używaj interfejsu API userScripts do wykonywania skryptów użytkownika w kontekście skryptów użytkownika.

Uprawnienia

userScripts

Aby używać 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 w wersji 120 lub nowszej MV3 lub nowszy

Pojęcia i wykorzystanie

Skrypt użytkownika to fragment kodu wstawiany na stronę internetową w celu modyfikacji jej wyglądu lub działania. Skrypty są tworzone przez użytkowników albo pobierane z repozytorium skryptów lub rozszerzenia skryptu użytkownika.

Tryb programisty dla użytkowników rozszerzenia

Jako programista rozszerzeń masz już włączony tryb programisty w swojej instalacji Chrome. W przypadku rozszerzeń skryptów użytkownicy muszą też włączyć tryb programisty. Poniżej znajdziesz instrukcje, które możesz skopiować i wkleić do swojej dokumentacji.

  1. Otwórz stronę Rozszerzenia, wpisując chrome://extensions w nowej karcie. (Z założenia chrome:// adresów URL nie można tworzyć linków).

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

    na stronie Rozszerzenia,

    Strona rozszerzeń (chrome://extensions)
    .

Aby dowiedzieć się, czy tryb programisty jest włączony, sprawdź, czy chrome.userScripts wyświetla 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

Skrypty użytkownika i treści mogą być uruchamiane w osobnym świecie lub w głównym świecie. Odizolowany ś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ę hosta ani inne rozszerzenia skrypty użytkownika i treści. I odwrotnie, skrypty użytkownika (i skrypty treści) nie są widoczne dla strony hostującej ani dla 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ć świat, prześlij "USER_SCRIPT" lub "MAIN" podczas rozmowy telefonicznej userScripts.register().

Aby skonfigurować zasadę bezpieczeństwa treści dla świata USER_SCRIPT, wywołaj 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ą komunikatów (co oznacza, że mogą wywoływać runtime.sendMessage() i runtime.connect(), jak każda inna część rozszerzenia). Są jednak odbierane za pomocą dedykowanych modułów obsługi zdarzeń (co oznacza, że nie używają one onMessage ani onConnect). Te moduły obsługi noszą nazwy runtime.onUserScriptMessage i runtime.onUserScriptConnect. Dedykowane moduły obsługi ułatwiają identyfikowanie wiadomości na podstawie 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 przekazać w tym samym czasie.

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

Aktualizacje rozszerzeń

Skrypty użytkownika są usuwane po aktualizacji rozszerzenia. Możesz je dodać ponownie, uruchamiając kod w module obsługi zdarzeń runtime.onInstalled w skrypcie service worker. Odpowiadaj tylko na "update"powód przekazany do wywołania zwrotnego zdarzenia.

Przykład

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

Zarejestruj skrypt

Poniższy przykład pokazuje podstawowe wywołanie 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 skrypt użytkownika ma zostać wykonany.

Typ wyliczeniowy

"MAIN"
Określa środowisko wykonawcze DOM, czyli środowisko wykonawcze współużytkowane z kodem JavaScript strony hosta.

"USER_SCRIPT"
Określa środowisko wykonawcze, które jest specyficzne dla skryptów użytkownika i które jest wykluczone z CSP strony.

RegisteredUserScript

Właściwości

  • allFrames

    Wartość logiczna opcjonalna

    Jeśli ma wartość true (prawda), wstrzyki będzie we wszystkich klatkach, 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. nie będzie on wstrzyknięty do ramek podrzędnych, jeśli wymagania dotyczące adresów URL nie zostaną spełnione. Wartość domyślna to fałsz, co oznacza, że dopasowywana jest tylko górna klatka.

  • excludeGlobs

    string[] opcjonalnie

    Określa wzorce symboli wieloznacznych na stronach, na których ten skrypt użytkownika NIE będzie wstrzykiwany.

  • excludeMatches

    string[] opcjonalnie

    Nie obejmuje stron, na których ten skrypt zostałby wstrzykiwany. Więcej informacji o składni tych ciągów znajdziesz w sekcji 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 zaczynać się od znaku „_” , bo jest on zarezerwowany jako prefiks generowanych identyfikatorów skryptów.

  • includeGlobs

    string[] opcjonalnie

    Określa wzorce symboli wieloznacznych na stronach, na których ten skrypt użytkownika będzie wstrzykiwany.

  • Lista obiektów ScriptSource określających źródła skryptów, które mają być wstrzykiwane na pasujących stronach.

  • pasuje do

    string[] opcjonalnie

    Określa strony, na których ten skrypt użytkownika będzie wstrzykiwany. Więcej informacji o składni tych ciągów znajdziesz w sekcji Wzorce dopasowania. Tę właściwość należy podać w przypadku: ${ref:register}.

  • runAt

    Opcjonalnie RunAt

    Określa, kiedy pliki JavaScript są wstrzykiwane do strony internetowej. Wartość preferowana i domyślna to document_idle.

  • świat

    ExecutionWorld opcjonalnie

    środowisko wykonawcze JavaScriptu, 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 wstrzykiwania. Należy podać tylko jedną z tych właściwości: file lub code.

  • plik

    ciąg znaków opcjonalny

    Ścieżka pliku JavaScript do wstrzykiwania odnosząca się do katalogu głównego rozszerzenia. Należy podać tylko jedną z tych właściwości: file lub code.

UserScriptFilter

Właściwości

  • identyfikatory

    string[] opcjonalnie

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

WorldProperties

Właściwości

  • protokół CSP

    ciąg znaków opcjonalny

    Określa światowy protokół csp. Wartość domyślna to csp światowy (`ISOLATED`).

  • SMS

    Wartość logiczna opcjonalna

    Określa, czy interfejsy API do przesyłania wiadomości są udostępniane. 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 skryptów użytkownika.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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 dla danego rozszerzenia.

Parametry

Zwroty

  • Promise&lt;RegisteredUserScript[]&gt;

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

register()

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

Rejestruje co najmniej jeden skrypt użytkownika na potrzeby tego rozszerzenia.

Parametry

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

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

unregister()

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

Wyrejestrowuje wszystkie dynamicznie zarejestrowane skrypty użytkownika na potrzeby tego rozszerzenia.

Parametry

  • filtr

    Opcjonalny UserScriptFilter

    Jeśli została określona, ta metoda wyrejestruje tylko pasujące do niej skrypty użytkownika.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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 tego rozszerzenia.

Parametry

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

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.