browser.runtime

Opis

Użyj interfejsu API chrome.runtime, aby pobrać skrypt service worker, zwrócić szczegóły dotyczące pliku manifestu oraz nasłuchiwać zdarzeń w cyklu życia rozszerzenia i na nie reagować. Możesz też użyć tego interfejsu API, aby przekonwertować ścieżkę względną adresów URL na pełne adresy URL.

Większość elementów tego interfejsu API nie wymaga żadnych uprawnień. To uprawnienie jest wymagane w przypadku connectNative(), sendNativeMessage() i onNativeConnect.

Poniższy przykład pokazuje, jak zadeklarować uprawnienie "nativeMessaging" w pliku manifestu:

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

Pojęcia i użycie

Interfejs Runtime API udostępnia metody obsługi wielu obszarów, z których mogą korzystać rozszerzenia:

Przekazywanie wiadomości

Rozszerzenie może komunikować się z różnymi kontekstami w obrębie rozszerzenia, a także z innymi rozszerzeniami, korzystając z tych metod i zdarzeń: connect(), onConnect, onConnectExternal, sendMessage(), onMessage i  onMessageExternal. Dodatkowo rozszerzenie może przekazywać wiadomości do aplikacji natywnych na urządzeniu użytkownika za pomocą connectNative() i sendNativeMessage().

Uwaga: omówienie tego tematu znajdziesz w artykule Przekazywanie wiadomości.

Dostęp do metadanych rozszerzenia i platformy

Te metody umożliwiają pobieranie kilku konkretnych metadanych dotyczących rozszerzenia i platformy. Metody w tej kategorii to m.in. getManifest() i getPlatformInfo().

Zarządzanie cyklem życia i opcjami rozszerzenia

Te właściwości umożliwiają wykonywanie niektórych metaoperacji na rozszerzeniu i wyświetlanie strony opcji. Metody i zdarzenia w tej kategorii obejmują: onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() i  setUninstallURL().

Narzędzia pomocnicze

Te metody zapewniają takie funkcje jak konwersja wewnętrznych reprezentacji zasobów na formaty zewnętrzne. Metody w tej kategorii to m.in. getURL().

Narzędzia trybu kiosku

Te metody są dostępne tylko w ChromeOS i służą głównie do obsługi implementacji kiosku. Metody w tej kategorii to m.in. restart() i restartAfterDelay()`.

Działanie rozpakowanego rozszerzenia

Gdy rozpakowane rozszerzenie zostanie ponownie załadowane, jest to traktowane jako aktualizacja. Oznacza to, że zdarzenie browser.runtime.onInstalled zostanie wywołane z powodu "update". Dotyczy to też sytuacji, gdy rozszerzenie jest ponownie ładowane za pomocą browser.runtime.reload().

Przypadki użycia

Dodawanie obrazu do strony internetowej

Aby strona internetowa mogła uzyskać dostęp do zasobu hostowanego w innej domenie, musi podać pełny adres URL zasobu (np. <img src="https://example.com/logo.png">). To samo dotyczy umieszczania zasobu rozszerzenia na stronie internetowej. Różnice są 2: zasoby rozszerzenia muszą być udostępniane jako zasoby dostępne w internecie, a skrypty treści są zwykle odpowiedzialne za wstrzykiwanie zasobów rozszerzenia.

W tym przykładzie rozszerzenie doda logo.png do strony, do której wstrzykiwany jest skrypt treści, używając runtime.getURL() do utworzenia pełnego adresu URL. Najpierw jednak zasób musi zostać zadeklarowany w pliku manifestu jako zasób dostępny w internecie.

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = browser.runtime.getURL('logo.png');
  document.body.append(img);
}

Wysyłanie danych ze skryptu treści do skryptu service worker

Skrypty treści rozszerzenia często potrzebują danych zarządzanych przez inną część rozszerzenia, np. skrypt service worker. Podobnie jak w przypadku 2 okien przeglądarki otwartych na tej samej stronie internetowej te 2 konteksty nie mogą bezpośrednio uzyskiwać dostępu do swoich wartości. Zamiast tego rozszerzenie może używać przekazywania wiadomości do koordynowania działań w różnych kontekstach.

W tym przykładzie skrypt treści potrzebuje pewnych danych z skryptu service worker rozszerzenia, aby zainicjować interfejs. Aby uzyskać te dane, przekazuje do skryptu service worker zdefiniowany przez dewelopera komunikat get-user-data, a skrypt odpowiada kopią informacji o użytkowniku.

content.js:

// 1. Send a message to the service worker requesting the user's data
browser.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

service-worker.js:

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

Zbieranie opinii o odinstalowaniu

Wiele rozszerzeń korzysta z ankiet po odinstalowaniu, aby dowiedzieć się, jak rozszerzenie mogłoby lepiej służyć użytkownikom i zwiększyć ich utrzymanie. Poniższy przykład pokazuje, jak dodać tę funkcję.

background.js:

browser.runtime.onInstalled.addListener(details => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    browser.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

Przykłady

Więcej przykładów interfejsu Runtime API znajdziesz w demonstracji Manifest V3 – zasoby dostępne w internecie.

Typy

ContextFilter

Chrome 114 lub nowsza wersja

Filtr dopasowujący do określonych kontekstów rozszerzenia. Dopasowane konteksty muszą pasować do wszystkich określonych filtrów. Każdy filtr, który nie został określony, pasuje do wszystkich dostępnych kontekstów. Dlatego filtr `{}` będzie pasować do wszystkich dostępnych kontekstów.

Właściwości

• contextIds

  string[] opcjonalne

• contextTypes

  ContextType[] opcjonalny

• documentIds

  string[] opcjonalne

• documentOrigins

  string[] opcjonalne

• documentUrls

  string[] opcjonalne

• frameIds

  number[] opcjonalny

• incognito

  boolean opcjonalne

• tabIds

  number[] opcjonalny

• windowIds

  number[] opcjonalny

ContextType

Chrome 114 lub nowsza wersja

Typ wyliczeniowy

"TAB"
Określa typ kontekstu jako kartę

"POPUP"
Określa typ kontekstu jako wyskakujące okienko rozszerzenia

"BACKGROUND"
Określa typ kontekstu jako skrypt service worker.

"OFFSCREEN_DOCUMENT"
Określa typ kontekstu jako dokument poza ekranem.

"SIDE_PANEL"
Określa typ kontekstu jako panel boczny.

"DEVELOPER_TOOLS"
Określa typ kontekstu jako narzędzia dla programistów.

ExtensionContext

Chrome 114 lub nowsza wersja

Kontekst hostujący zawartość rozszerzenia.

Właściwości

• contextId

  tekst

  Unikalny identyfikator tego kontekstu

• contextType

  ContextType

  Typ kontekstu, któremu odpowiada ta wartość.

• documentId

  ciąg znaków opcjonalny

  Identyfikator UUID dokumentu powiązanego z tym kontekstem lub niezdefiniowany, jeśli ten kontekst nie jest hostowany w dokumencie.

• documentOrigin

  ciąg znaków opcjonalny

  Źródło dokumentu powiązanego z tym kontekstem lub niezdefiniowane, jeśli kontekst nie jest hostowany w dokumencie.

• documentUrl

  ciąg znaków opcjonalny

  Adres URL dokumentu powiązanego z tym kontekstem lub niezdefiniowany, jeśli kontekst nie jest hostowany w dokumencie.

• frameId

  liczba

  Identyfikator ramki dla tego kontekstu lub -1, jeśli ten kontekst nie jest hostowany w ramce.

• incognito

  wartość logiczna

  Określa, czy kontekst jest powiązany z profilem incognito.

• tabId

  liczba

  Identyfikator karty dla tego kontekstu lub -1, jeśli ten kontekst nie jest hostowany na karcie.

• windowId

  liczba

  Identyfikator okna dla tego kontekstu lub -1, jeśli ten kontekst nie jest hostowany w oknie.

ExtensionLoadDetails

Chrome 157 lub nowsza wersja

Szczegóły zdarzenia wczytania rozszerzenia.

Właściwości

• previousVersion

  ciąg znaków opcjonalny

  Wskazuje poprzednią wersję rozszerzenia. Ta wartość jest obecna tylko wtedy, gdy „reason” to „update” lub „enable”. Jeśli „reason” to „update”, jest to wersja rozszerzenia przed aktualizacją. Jeśli „reason” to „enable”, jest to bieżąca wersja rozszerzenia.

• reason

  OnLoadedReason

  Powód wysłania tego zdarzenia.

MessageSender

Obiekt zawierający informacje o kontekście skryptu, który wysłał wiadomość lub żądanie.

Właściwości

• documentId

  ciąg znaków opcjonalny

  Chrome 106 lub nowsza wersja

  Identyfikator UUID dokumentu, który otworzył połączenie.

• documentLifecycle

  ciąg znaków opcjonalny

  Chrome 106 lub nowsza wersja

  Cykl życia dokumentu, który otworzył połączenie, w momencie utworzenia portu. Pamiętaj, że stan cyklu życia dokumentu mógł się zmienić od czasu utworzenia portu.

• frameId

  number optional

  Ramka, która otworzyła połączenie. 0 w przypadku ramek najwyższego poziomu, wartość dodatnia w przypadku ramek podrzędnych. Ta wartość zostanie ustawiona tylko wtedy, gdy ustawiona jest wartość tab.

• id

  ciąg znaków opcjonalny

  Identyfikator rozszerzenia, które otworzyło połączenie (jeśli istnieje).

• nativeApplication

  ciąg znaków opcjonalny

  Chrome 74 lub nowsza wersja

  Nazwa aplikacji natywnej, która otworzyła połączenie (jeśli dotyczy).

• pochodzenie

  ciąg znaków opcjonalny

  Chrome 80 lub nowsza wersja

  Źródło strony lub ramki, która otworzyła połączenie. Może się różnić od właściwości adresu URL (np. about:blank) lub być nieprzezroczysty (np. elementy iframe w trybie piaskownicy). Jest to przydatne do określenia, czy źródło jest godne zaufania, jeśli nie możemy tego od razu stwierdzić na podstawie adresu URL.

• karta

  Tab opcjonalny

  tabs.Tab, który otworzył połączenie (jeśli dotyczy). Ta właściwość będzie obecna tylko wtedy, gdy połączenie zostało otwarte z karty (w tym skryptów treści), i tylko wtedy, gdy odbiorcą jest rozszerzenie, a nie aplikacja.

• tlsChannelId

  ciąg znaków opcjonalny

  Identyfikator kanału TLS strony lub ramki, która otworzyła połączenie, jeśli rozszerzenie o to poprosiło i jeśli jest dostępny.

• URL

  ciąg znaków opcjonalny

  Adres URL strony lub ramki, która otworzyła połączenie. Jeśli nadawca znajduje się w elemencie iframe, będzie to adres URL elementu iframe, a nie adres URL strony, na której się znajduje.

OnInstalledReason

Chrome 44 lub nowsza wersja

Powód wysłania tego zdarzenia.

Typ wyliczeniowy

"install"
Określa przyczynę zdarzenia jako instalację.

"update"
Określa przyczynę zdarzenia jako aktualizację rozszerzenia.

"chrome_update"
Określa przyczynę zdarzenia jako aktualizację Chrome.

"shared_module_update"
Określa przyczynę zdarzenia jako aktualizację udostępnionego modułu.

OnLoadedReason

Chrome 157 lub nowsza wersja

Powód wysłania tego zdarzenia.

Typ wyliczeniowy

"install"
Rozszerzenie zostało zainstalowane.

"update"
Rozszerzenie zostało ponownie załadowane po aktualizacji.

"browser_update"
Przeglądarka została zaktualizowana do nowej wersji.

"enable"
Rozszerzenie zostało ponownie włączone po wyłączeniu.

"startup"
Rozszerzenie jest ładowane podczas uruchamiania przeglądarki.

"reload"
Rozszerzenie zostało ponownie załadowane (np. za pomocą chrome.runtime.reload() lub ręcznie przez użytkownika).

OnRestartRequiredReason

Chrome 44 lub nowsza wersja

Powód wysłania zdarzenia. Wartość „app_update” jest używana, gdy ponowne uruchomienie jest wymagane, ponieważ aplikacja została zaktualizowana do nowszej wersji. Wartość „os_update” jest używana, gdy ponowne uruchomienie jest wymagane, ponieważ przeglądarka lub system operacyjny zostały zaktualizowane do nowszej wersji. Wartość „periodic” jest używana, gdy system działa dłużej niż dozwolony czas działania określony w zasadach firmy.

Typ wyliczeniowy

"app_update"
Określa przyczynę zdarzenia jako aktualizację aplikacji.

"os_update"
Określa przyczynę zdarzenia jako aktualizację systemu operacyjnego.

"periodic"
Określa przyczynę zdarzenia jako okresowe ponowne uruchomienie aplikacji.

PlatformArch

Chrome 44 lub nowsza wersja

Architektura procesora maszyny.

Typ wyliczeniowy

"arm"
Określa architekturę procesora jako ARM.

"arm64"
Określa architekturę procesora jako arm64.

"x86-32"
Określa architekturę procesora jako x86-32.

"x86-64"
Określa architekturę procesora jako x86-64.

"mips"
Określa architekturę procesora jako mips.

"mips64"
Określa architekturę procesora jako mips64.

"riscv64"
Określa architekturę procesora jako riscv64.

PlatformInfo

Obiekt zawierający informacje o bieżącej platformie.

Właściwości

• arch

  PlatformArch

  Architektura procesora maszyny.

• nacl_arch

  PlatformNaclArch opcjonalne

  Wycofane od Chrome 149

  Ten atrybut został wycofany po całkowitym usunięciu Native Client.

  Architektura klienta natywnego. Na niektórych platformach może się różnić od arch.

• os

  PlatformOs

  System operacyjny, na którym działa Chrome.

PlatformNaclArch

Chrome 44 lub nowsza wersja Wycofane od Chrome 149

Ten typ wyliczeniowy został wycofany po całkowitym usunięciu Native Client.

Architektura klienta natywnego. Na niektórych platformach może się różnić od arch.

Typ wyliczeniowy

"arm"
Określa architekturę klienta natywnego jako arm.

"x86-32"
Określa architekturę klienta natywnego jako x86-32.

"x86-64"
Określa architekturę klienta natywnego jako x86-64.

"mips"
Określa architekturę klienta natywnego jako mips.

"mips64"
Określa architekturę klienta natywnego jako mips64.

PlatformOs

Chrome 44 lub nowsza wersja

System operacyjny, na którym działa Chrome.

Typ wyliczeniowy

"mac"
Określa system operacyjny macOS.

"win"
Określa system operacyjny Windows.

"android"
Określa system operacyjny Android.

"cros"
Określa system operacyjny Chrome.

"linux"
Określa system operacyjny Linux.

"openbsd"
Określa system operacyjny OpenBSD.

Port

Obiekt, który umożliwia dwukierunkową komunikację z innymi stronami. Więcej informacji znajdziesz w sekcji Połączenia długotrwałe.

Właściwości

• nazwa

  tekst

  Nazwa portu określona w wywołaniu runtime.connect.

• onDisconnect

  Event<functionvoidvoid>

  Uruchamiane, gdy port zostanie odłączony od drugiego końca. Jeśli port został odłączony z powodu błędu, może być ustawiona wartość runtime.lastError. Jeśli port zostanie zamknięty przez rozłączenie, to zdarzenie zostanie wywołane tylko na drugim końcu. To zdarzenie jest wywoływane maksymalnie raz (patrz też Czas życia portu).

  Funkcja onDisconnect.addListener wygląda tak:

  (callback: function) => {...}

  • callback

    funkcja

    Parametr callback wygląda tak:

    (port: Port) => void

    • port

      Port

• onMessage

  Event<functionvoidvoid>

  To zdarzenie jest wywoływane, gdy postMessage jest wywoływane przez drugi koniec portu.

  Funkcja onMessage.addListener wygląda tak:

  (callback: function) => {...}

  • callback

    funkcja

    Parametr callback wygląda tak:

    (message: any, port: Port) => void

    • wiadomość

      każdy

    • port

      Port

• nadawca

  MessageSender opcjonalny

  Ta właściwość będzie obecna tylko w portach przekazywanych do detektorów onConnect / onConnectExternal / onConnectNative.

• rozłącz

  unieważnienie,

  Natychmiast odłącz port. Wywołanie metody disconnect() na porcie, który został już rozłączony, nie ma żadnego efektu. Gdy port zostanie odłączony, nie będą do niego wysyłane żadne nowe zdarzenia.

  Funkcja disconnect wygląda tak:

  () => {...}

• postMessage

  unieważnienie,

  Wyślij wiadomość na drugi koniec portu. Jeśli port jest odłączony, występuje błąd.

  Funkcja postMessage wygląda tak:

  (message: any) => {...}

  • wiadomość

    każdy

    Chrome 52 lub nowsza wersja

    Wiadomość do wysłania. Ten obiekt powinien być możliwy do przekształcenia w format JSON.

RequestUpdateCheckStatus

Chrome 44 lub nowsza wersja

Wynik sprawdzenia dostępności aktualizacji.

Typ wyliczeniowy

"throttled"
Określa, że sprawdzanie stanu zostało ograniczone. Może się tak zdarzyć, jeśli w krótkim czasie przeprowadzisz kilka kontroli.

"no_update"
Określa, że nie ma dostępnych aktualizacji do zainstalowania.

"update_available"
Określa, że dostępna jest aktualizacja do zainstalowania.

Właściwości

id

Identyfikator rozszerzenia lub aplikacji.

Typ

tekst

lastError

Jeśli wywołanie funkcji interfejsu API się nie powiedzie, zostanie wypełnione komunikatem o błędzie. W przeciwnym razie pozostanie niezdefiniowane. Jest ona zdefiniowana tylko w zakresie wywołania zwrotnego tej funkcji. Jeśli wystąpi błąd, ale nie zostanie wywołana funkcja runtime.lastError, w konsoli zostanie zarejestrowany komunikat z nazwą funkcji interfejsu API, która spowodowała błąd. Funkcje interfejsu API, które zwracają obietnice, nie ustawiają tej właściwości.

Typ

obiekt

Właściwości

• wiadomość

  ciąg znaków opcjonalny

  Szczegóły błędu, który wystąpił.

Metody

connect()

chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
): Port

Próbuje połączyć detektory w rozszerzeniu (np. na stronie działającej w tle) lub w innych rozszerzeniach/aplikacjach. Jest to przydatne w przypadku skryptów treści łączących się z procesami rozszerzeń, komunikacji między aplikacjami i rozszerzeniami oraz wiadomości internetowych. Pamiętaj, że nie powoduje to połączenia z żadnymi detektorami w skrypcie treści. Rozszerzenia mogą łączyć się ze skryptami treści umieszczonymi na kartach za pomocą tabs.connect.

Parametry

• extensionId

  ciąg znaków opcjonalny

  Identyfikator rozszerzenia, z którym chcesz się połączyć. Jeśli go pominiesz, zostanie podjęta próba połączenia z Twoim rozszerzeniem. Wymagane w przypadku wysyłania wiadomości ze strony internetowej na potrzeby wiadomości internetowych.

• connectInfo

  object opcjonalny

  • includeTlsChannelId

    boolean opcjonalne

    Określa, czy identyfikator kanału TLS będzie przekazywany do onConnectExternal w przypadku procesów, które nasłuchują zdarzenia połączenia.

  • nazwa

    ciąg znaków opcjonalny

    Zostanie przekazany do onConnect w przypadku procesów, które nasłuchują zdarzenia połączenia.

Zwroty

• Port

  Port, przez który można wysyłać i odbierać wiadomości. Jeśli rozszerzenie nie istnieje, wywoływane jest zdarzenie onDisconnect portu.

connectNative()

chrome.runtime.connectNative(
  application: string,
): Port

Łączy się z aplikacją natywną na komputerze hosta. Ta metoda wymaga uprawnienia "nativeMessaging". Więcej informacji znajdziesz w artykule na temat natywnego przesyłania wiadomości.

Parametry

• aplikacja

  tekst

  Nazwa zarejestrowanej aplikacji, z którą chcesz się połączyć.

Zwroty

• Port

  Port, przez który można wysyłać i odbierać wiadomości za pomocą aplikacji.

getBackgroundPage()

Tylko na pierwszym planie Wycofane od wersji Chrome 133

chrome.runtime.getBackgroundPage(): Promise<Window | undefined>

W rozszerzeniach MV3 nie ma stron działających w tle.

Pobiera obiekt „window” JavaScriptu dla strony działającej w tle w ramach bieżącego rozszerzenia lub aplikacji. Jeśli strona działająca w tle jest stroną zdarzenia, system upewni się, że została wczytana, zanim wywoła wywołanie zwrotne. Jeśli nie ma strony tła, ustawiany jest błąd.

Zwroty

• Promise<Window | undefined>

  Chrome 99 lub nowsza wersja

getContexts()

Chrome 116 lub nowsza wersja MV3 lub nowsza wersja

chrome.runtime.getContexts(
  filter: ContextFilter,
): Promise<ExtensionContext[]>

Pobiera informacje o aktywnych kontekstach powiązanych z tym rozszerzeniem

Parametry

• filtr

  ContextFilter

  Filtr do znajdowania pasujących kontekstów. Kontekst pasuje, jeśli pasuje do wszystkich określonych pól w filtrze. Każde nieokreślone pole w filtrze pasuje do wszystkich kontekstów.

Zwroty

• Promise<ExtensionContext[]>

  Obiekt Promise, który jest rozwiązywany za pomocą pasujących kontekstów (jeśli takie istnieją).

getManifest()

chrome.runtime.getManifest(): object

Zwraca szczegółowe informacje o aplikacji lub rozszerzeniu z pliku manifestu. Zwracany obiekt jest serializacją pełnego pliku manifestu.

Zwroty

• obiekt

  Szczegóły pliku manifestu.

getPackageDirectoryEntry()

Tylko na pierwszym planie

chrome.runtime.getPackageDirectoryEntry(): Promise<DirectoryEntry>

Zwraca DirectoryEntry dla katalogu pakietu.

Zwroty

• Promise<DirectoryEntry>

  Chrome 122 lub nowsza wersja

getPlatformInfo()

chrome.runtime.getPlatformInfo(): Promise<PlatformInfo>

Zwraca informacje o bieżącej platformie.

Zwroty

• Promise<PlatformInfo>

  Chrome 99 lub nowsza wersja

  Obiekt Promise, który zwraca informacje o bieżącej platformie.

getURL()

chrome.runtime.getURL(
  path: string,
): string

Konwertuje ścieżkę względną w katalogu instalacyjnym aplikacji lub rozszerzenia na pełny i jednoznaczny URL.

Parametry

• ścieżka

  tekst

  Ścieżka do zasobu w aplikacji lub rozszerzeniu wyrażona względem katalogu instalacyjnego.

Zwroty

• tekst

  Pełny i jednoznaczny URL zasobu.

getVersion()

Chrome 143 lub nowsza wersja

chrome.runtime.getVersion(): string

Zwraca wersję rozszerzenia zadeklarowaną w pliku manifestu.

Zwroty

• tekst

  Wersja rozszerzenia.

openOptionsPage()

chrome.runtime.openOptionsPage(): Promise<void>

Jeśli to możliwe, otwórz stronę opcji rozszerzenia.

Dokładne działanie może zależeć od klucza options_ui lub options_page w pliku manifestu lub od tego, co Chrome obsługuje w danym momencie. Strona może na przykład zostać otwarta na nowej karcie, w chrome://extensions, w aplikacji lub może po prostu skupić się na otwartej stronie opcji. Nigdy nie powoduje ponownego załadowania strony wywołującej.

Jeśli rozszerzenie nie deklaruje strony opcji lub Chrome nie może jej utworzyć z innego powodu, wywołanie zwrotne ustawi lastError.

Zwroty

• thought Promise<void>

  Chrome 99 lub nowsza wersja

reload()

chrome.runtime.reload(): void

Ponownie ładuje aplikację lub rozszerzenie. Ta metoda nie jest obsługiwana w trybie kiosku. W trybie kiosku użyj metody chrome.runtime.restart().

requestUpdateCheck()

chrome.runtime.requestUpdateCheck(): Promise<object>

Żąda natychmiastowego sprawdzenia dostępności aktualizacji tej aplikacji lub rozszerzenia.

Ważne: większość rozszerzeń i aplikacji nie powinna używać tej metody, ponieważ Chrome automatycznie sprawdza dostępność aktualizacji co kilka godzin, a zdarzenie runtime.onUpdateAvailable można nasłuchiwać bez konieczności wywoływania metody requestUpdateCheck.

Tę metodę należy wywoływać tylko w bardzo ograniczonych okolicznościach, np. gdy rozszerzenie komunikuje się z usługą backendu, a usługa backendu ustaliła, że wersja rozszerzenia klienta jest bardzo nieaktualna i chcesz poprosić użytkownika o jej zaktualizowanie. Większość innych zastosowań metody requestUpdateCheck, takich jak wywoływanie jej bezwarunkowo na podstawie powtarzającego się licznika czasu, prawdopodobnie marnuje tylko zasoby klienta, sieci i serwera.

Uwaga: gdy funkcja jest wywoływana z wywołaniem zwrotnym, zamiast zwracać obiekt, zwraca te 2 właściwości jako osobne argumenty przekazywane do wywołania zwrotnego.

Zwroty

• Promise<object>

  Chrome 109 lub nowsza wersja

restart()

chrome.runtime.restart(): void

ponowne uruchamianie urządzenia z ChromeOS, gdy aplikacja działa w trybie kiosku; W przeciwnym razie nie jest wykonywana żadna operacja.

restartAfterDelay()

Chrome 53 lub nowsza wersja,

chrome.runtime.restartAfterDelay(
  seconds: number,
): Promise<void>

Ponownie uruchamia urządzenie z ChromeOS, gdy aplikacja działa w trybie kiosku, po upływie określonej liczby sekund. Jeśli zostanie wywołana ponownie przed upływem tego czasu, ponowne uruchomienie zostanie opóźnione. Jeśli zostanie wywołana z wartością -1, ponowne uruchomienie zostanie anulowane. W trybie innym niż tryb kiosku nie wykonuje żadnych działań. Może być wielokrotnie wywoływany tylko przez pierwsze rozszerzenie, które wywoła ten interfejs API.

Parametry

• s

  liczba

  Czas oczekiwania w sekundach przed ponownym uruchomieniem urządzenia lub -1, aby anulować zaplanowane ponowne uruchomienie.

Zwroty

• thought Promise<void>

  Chrome 99 lub nowsza wersja

  Obiekt Promise, który jest rozwiązywany, gdy prośba o ponowne uruchomienie została pomyślnie przełożona.

sendMessage()

chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
): Promise<any>

Wysyła pojedynczą wiadomość do detektorów zdarzeń w Twoim rozszerzeniu lub w innym rozszerzeniu bądź aplikacji. Podobnie jak runtime.connect, ale wysyła tylko jedną wiadomość z opcjonalną odpowiedzią. Jeśli wysyłasz do rozszerzenia, zdarzenie runtime.onMessage zostanie wywołane w każdej ramce rozszerzenia (z wyjątkiem ramki nadawcy) lub runtime.onMessageExternal, jeśli jest to inne rozszerzenie. Pamiętaj, że rozszerzenia nie mogą wysyłać wiadomości do skryptów treści za pomocą tej metody. Aby wysyłać wiadomości do skryptów treści, użyj tabs.sendMessage.

Parametry

• extensionId

  ciąg znaków opcjonalny

  Identyfikator rozszerzenia, do którego ma zostać wysłana wiadomość. Jeśli go pominiesz, wiadomość zostanie wysłana do Twojego rozszerzenia lub aplikacji. Jest wymagany, jeśli wysyłasz wiadomości ze strony internetowej na potrzeby komunikacji internetowej.

• wiadomość

  każdy

  Wiadomość do wysłania. Ta wiadomość powinna być obiektem, który można przekonwertować na format JSON.

• Opcje

  object opcjonalny

  • includeTlsChannelId

    boolean opcjonalne

    Określa, czy identyfikator kanału TLS będzie przekazywany do onMessageExternal w przypadku procesów, które nasłuchują zdarzenia połączenia.

Zwroty

• Promise<any>

  Chrome 99 lub nowsza wersja

  W Chrome 99 dodano obsługę obietnic w kontekstach rozszerzeń. W przypadku komunikacji między stroną internetową a rozszerzeniem obiekty Promise są dostępne od wersji Chrome 118.

sendNativeMessage()

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
): Promise<any>

Wysyłanie pojedynczej wiadomości do aplikacji natywnej. Ta metoda wymaga uprawnienia "nativeMessaging".

Parametry

• aplikacja

  tekst

  Nazwa hosta natywnego przesyłania komunikatów lub szczegóły celu.

• wiadomość

  obiekt

  Wiadomość, która zostanie przekazana do hosta natywnego przesyłania komunikatów.

Zwroty

• Promise<any>

  Chrome 99 lub nowsza wersja

setUninstallURL()

chrome.runtime.setUninstallURL(
  url: string,
): Promise<void>

Ustawia adres URL, który ma zostać odwiedzony po odinstalowaniu. Może to służyć do czyszczenia danych po stronie serwera, przeprowadzania analiz i wdrażania ankiet. Maksymalnie 1023 znaki.

Parametry

• URL

  tekst

  Adres URL, który ma zostać otwarty po odinstalowaniu rozszerzenia. Ten adres URL musi mieć schemat http: lub https:. Ustaw pusty ciąg znaków, aby po odinstalowaniu nie otwierała się nowa karta.

Zwroty

• thought Promise<void>

  Chrome 99 lub nowsza wersja

  Obietnica, która zostanie spełniona po ustawieniu adresu URL odinstalowania. Jeśli podany adres URL jest nieprawidłowy, obietnica zostanie odrzucona.

Wydarzenia

onBrowserUpdateAvailable

Wycofane

chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

Użyj runtime.onRestartRequired.

Uruchamiane, gdy dostępna jest aktualizacja Chrome, ale nie jest instalowana natychmiast, ponieważ wymagane jest ponowne uruchomienie przeglądarki.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  () => void

onConnect

chrome.runtime.onConnect.addListener(
  callback: function,
)

Uruchamiane, gdy połączenie jest nawiązywane z procesu rozszerzenia lub skryptu treści (przez runtime.connect).

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  (port: Port) => void

  • port

    Port

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

Uruchamiane, gdy nawiązywane jest połączenie z innego rozszerzenia (przez runtime.connect) lub z witryny, z którą można się połączyć zewnętrznie.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  (port: Port) => void

  • port

    Port

onConnectNative

Chrome 76 lub nowsza wersja

chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Uruchamiane, gdy połączenie jest nawiązywane z aplikacji natywnej. To zdarzenie wymaga uprawnienia "nativeMessaging". Jest obsługiwana tylko w ChromeOS.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  (port: Port) => void

  • port

    Port

onEnabled

Chrome 155 lub nowsza wersja

chrome.runtime.onEnabled.addListener(
  callback: function,
)

Uruchamiane, gdy rozszerzenie przechodzi ze stanu wyłączonego do włączonego.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  () => void

onExtensionLoaded

Chrome 157 lub nowsza wersja

chrome.runtime.onExtensionLoaded.addListener(
  callback: function,
)

Uruchamiane, gdy rozszerzenie zostanie dodane do zbioru aktywnych rozszerzeń. Może się to zdarzyć w kilku sytuacjach: gdy rozszerzenie jest instalowane po raz pierwszy, aktualizowane do nowej wersji, ponownie włączane po wyłączeniu, ponownie wczytywane, wczytywane podczas uruchamiania przeglądarki lub wczytywane po zaktualizowaniu przeglądarki do nowej wersji.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  (details: ExtensionLoadDetails) => void

  • szczegóły

    ExtensionLoadDetails

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

Uruchamiane po pierwszej instalacji rozszerzenia, po jego aktualizacji do nowej wersji i po aktualizacji Chrome do nowej wersji.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  (details: object) => void

  • szczegóły

    obiekt

    • id

      ciąg znaków opcjonalny

      Wskazuje identyfikator zaimportowanego rozszerzenia modułu udostępnionego, które zostało zaktualizowane. Ta wartość jest obecna tylko wtedy, gdy „reason” to „shared_module_update”.

    • previousVersion

      ciąg znaków opcjonalny

      Wskazuje poprzednią wersję rozszerzenia, która została właśnie zaktualizowana. Ta wartość jest obecna tylko wtedy, gdy „reason” to „update”.

    • reason

      OnInstalledReason

      Powód wysłania tego zdarzenia.

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

Uruchamiane, gdy wiadomość jest wysyłana z runtime.sendMessage lub tabs.sendMessage.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | Promise<any> | undefined

  • wiadomość

    każdy

  • nadawca

    MessageSender

  • sendResponse

    funkcja

    Parametr sendResponse wygląda tak:

    (response?: any) => void

    • odpowiedź

      any optional

      Odpowiedź, która ma zostać zwrócona nadawcy wiadomości.

  • returns

    boolean | Promise<any> | undefined

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

Uruchamiane, gdy wiadomość jest wysyłana z innego rozszerzenia (przez runtime.sendMessage). Nie można używać w skrypcie treści.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | Promise<any> | undefined

  • wiadomość

    każdy

  • nadawca

    MessageSender

  • sendResponse

    funkcja

    Parametr sendResponse wygląda tak:

    (response?: any) => void

    • odpowiedź

      any optional

      Odpowiedź, która ma zostać zwrócona nadawcy wiadomości.

  • returns

    boolean | Promise<any> | undefined

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

Uruchamiane, gdy aplikacja lub urządzenie, na którym działa, musi zostać ponownie uruchomione. Aplikacja powinna zamknąć wszystkie okna w najbliższym dogodnym momencie, aby umożliwić ponowne uruchomienie. Jeśli aplikacja nie podejmie żadnych działań, po upływie 24-godzinnego okresu prolongaty zostanie wymuszone ponowne uruchomienie. Obecnie to zdarzenie jest wywoływane tylko w przypadku aplikacji kiosku w ChromeOS.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  (reason: OnRestartRequiredReason) => void

  • reason

    OnRestartRequiredReason

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

Uruchamiane, gdy profil, na którym zainstalowano to rozszerzenie, jest uruchamiany po raz pierwszy. To zdarzenie nie jest wywoływane, gdy uruchamiany jest profil incognito, nawet jeśli rozszerzenie działa w trybie incognito „split”.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  () => void

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

Wysyłane na stronę zdarzenia tuż przed jej wyładowaniem. Dzięki temu rozszerzenie może wykonać pewne czynności porządkowe. Pamiętaj, że strona jest wyładowywana, więc nie ma gwarancji, że wszystkie operacje asynchroniczne rozpoczęte podczas obsługi tego zdarzenia zostaną ukończone. Jeśli przed wyładowaniem strony zdarzenia wystąpi więcej aktywności, zostanie wysłane zdarzenie onSuspendCanceled, a strona nie zostanie wyładowana.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  () => void

onSuspendCanceled

chrome.runtime.onSuspendCanceled.addListener(
  callback: function,
)

Wysyłane po onSuspend, aby wskazać, że aplikacja nie zostanie jednak wyładowana.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  () => void

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

Uruchamiane, gdy aktualizacja jest dostępna, ale nie jest instalowana natychmiast, ponieważ aplikacja jest obecnie uruchomiona. Jeśli nic nie zrobisz, aktualizacja zostanie zainstalowana przy następnym wyładowaniu strony działającej w tle. Jeśli chcesz, aby została zainstalowana wcześniej, możesz wywołać funkcję chrome.runtime.reload(). Jeśli rozszerzenie używa trwałej strony działającej w tle, taka strona nigdy nie zostanie wyładowana, więc jeśli nie wywołasz ręcznie funkcji chrome.runtime.reload() w odpowiedzi na to zdarzenie, aktualizacja nie zostanie zainstalowana do czasu ponownego uruchomienia Chrome. Jeśli nie ma modułów obsługi, które nasłuchują tego zdarzenia, a rozszerzenie ma stałą stronę w tle, zachowuje się ono tak, jakby w odpowiedzi na to zdarzenie wywołano funkcję chrome.runtime.reload().

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  (details: object) => void

  • szczegóły

    obiekt

    • wersja

      tekst

      Numer wersji dostępnej aktualizacji.

onUserScriptConnect

Chrome 115 lub nowsza wersja MV3 lub nowsza wersja

chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

Uruchamiane, gdy nawiązywane jest połączenie ze skryptu użytkownika z tego rozszerzenia.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  (port: Port) => void

  • port

    Port

onUserScriptMessage

Chrome 115 lub nowsza wersja MV3 lub nowsza wersja

chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

Uruchamiane, gdy wiadomość jest wysyłana ze skryptu użytkownika powiązanego z tym samym rozszerzeniem.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • wiadomość

    każdy

  • nadawca

    MessageSender

  • sendResponse

    funkcja

    Parametr sendResponse wygląda tak:

    (response?: any) => void

    • odpowiedź

      any optional

      Odpowiedź, która ma zostać zwrócona nadawcy wiadomości.

  • returns

    boolean | undefined