chrome.runtime

Opis

Użyj interfejsu API chrome.runtime, aby pobrać usługę workera, zwrócić szczegóły manifestu i słuchać oraz odpowiadać na zdarzenia w cyklu życia rozszerzenia. Za pomocą tego interfejsu API możesz też konwertować względną ścieżkę 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.

Ten przykład pokazuje, jak zadeklarować uprawnienie "nativeMessaging" w pliku manifestu:

manifest.json:

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

Pojęcia i zastosowanie

Interfejs Runtime API udostępnia metody obsługujące kilka obszarów, które mogą być używane przez Twoje rozszerzenia:

Przekazywanie wiadomości
Rozszerzenie może komunikować się z różnymi kontekstami w ramach rozszerzenia, a także z innymi rozszerzeniami za pomocą tych metod i wydarzeń: connect(), onConnect, onConnectExternal, sendMessage(), onMessage i onMessageExternal. Rozszerzenie może też przekazywać wiadomości do natywnych aplikacji na urządzeniu użytkownika za pomocą funkcji connectNative() i sendNativeMessage().
Dostęp do metadanych rozszerzeń i platform
Te metody umożliwiają pobieranie określonych metadanych dotyczących rozszerzenia i platformy. Metody w tej kategorii to getManifest() i getPlatformInfo().
Zarządzanie cyklem życia i opcjami rozszerzenia
Te właściwości umożliwiają wykonywanie niektórych operacji meta na rozszerzeniu oraz wyświetlanie strony opcji. Metody i zdarzenia w tej kategorii to onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() i setUninstallURL().
Pomocnicze narzędzia
Te metody umożliwiają np. konwersję wewnętrznych reprezentacji zasobów na formaty zewnętrzne. Metody w tej kategorii to m.in. getURL().
Narzędzia do trybu kiosku
Te metody są dostępne tylko w ChromeOS i służą głównie do obsługi implementacji kiosków. Metody w tej kategorii to restart() i restartAfterDelay()`.

Zachowanie rozpakowanego rozszerzenia

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

Przypadki użycia

Dodawanie obrazu do strony internetowej

Aby strona internetowa miała dostęp do zasobu hostowanego w innej domenie, musi zawierać pełny adres URL zasobu (np. <img src="https://example.com/logo.png">). To samo dotyczy zasobu rozszerzenia na stronie internetowej. Różnica polega na tym, że zasoby rozszerzenia muszą być dostępne jako zasoby dostępne w internecie, a wstrzykiwanie zasobów rozszerzenia jest zwykle realizowane przez skrypty treści.

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

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 = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

Wysyłanie danych ze skryptu treści do usługi pomocniczej

Skrypty treści rozszerzenia często potrzebują danych zarządzanych przez inną część rozszerzenia, np. przez usługę workera. Podobnie jak 2 okna przeglądarki z tą samą stroną internetową, te 2 konteksty nie mają bezpośredniego dostępu do wartości siebie nawzajem. Zamiast tego rozszerzenie może używać przekazywania wiadomości do koordynowania tych różnych kontekstów.

W tym przykładzie skrypt treści potrzebuje pewnych danych z serwera workera rozszerzenia, aby zainicjować interfejs użytkownika. Aby uzyskać te dane, przekazuje zdefiniowaną przez dewelopera wiadomość get-user-data do serwisu workera, który odpowiada kopią informacji o użytkowniku.

content.js:

// 1. Send a message to the service worker requesting the user's data
chrome.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'
};

chrome.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 może lepiej służyć użytkownikom i utrzymać ich przy sobie. Poniżej znajdziesz przykład, jak dodać tę funkcję.

background.js:

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

Przykłady

Więcej przykładów interfejsu API w czasie działania znajdziesz w prezentacji Manifest V3 – zasoby dostępne przez internet – demonstracja.

Typy

ContextFilter

Chrome 114 lub nowszy

Filtr dopasowujący do określonych kontekstów rozszerzeń. Dopasowane konteksty muszą pasować do wszystkich określonych filtrów. Filtr, który nie jest 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[] opcjonalnie

  • contextTypes

    ContextType[] opcjonalnie

  • documentIds

    string[] opcjonalnie

  • documentOrigins

    string[] opcjonalnie

  • documentUrls

    string[] opcjonalnie

  • frameIds

    number[] opcjonalny

  • incognito

    logiczna opcjonalna

  • tabIds

    number[] opcjonalny

  • windowIds

    number[] opcjonalny

ContextType

Chrome 114 lub nowszy

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 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 deweloperów.

ExtensionContext

Chrome 114 lub nowszy

Treści kontekstowe hostowane przez rozszerzenie.

Właściwości

  • contextId

    ciąg znaków

    Unikalny identyfikator tego kontekstu

  • contextType

    ContextType

    Typ kontekstu, do którego to pasuje.

  • documentId

    ciąg znaków opcjonalny

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

  • documentOrigin

    ciąg znaków opcjonalny

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

  • documentUrl

    ciąg znaków opcjonalny

    Adres URL dokumentu powiązanego z tym kontekstem lub nieokreślony, 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

    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 kontekst nie jest hostowany w oknie.

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 nowszy

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

  • documentLifecycle

    ciąg znaków opcjonalny

    Chrome 106 lub nowszy

    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 opcjonalny

    Ramka, która otworzyła połączenie. 0 – ramki najwyższego poziomu, dodatnie – ramki podrzędne. To ustawienie będzie stosowane tylko wtedy, gdy tab ma 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 nowszy

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

  • pochodzenie

    ciąg znaków opcjonalny

    Chrome 80+

    Źródło strony lub ramki, które otworzyły połączenie. Może się różnić w zależności od właściwości adresu URL (np. about:blank) lub może być nieprzezroczysty (np. ramki iframe w piaskownicy). Jest to przydatne, gdy nie możemy od razu stwierdzić, czy źródło jest wiarygodne, na podstawie adresu URL.

  • tabulator

    Tabulator opcjonalny

    tabs.Tab, który otworzył połączenie (jeśli takie istnieje). 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 odbiorca jest rozszerzeniem, a nie aplikacją.

  • tlsChannelId

    ciąg znaków opcjonalny

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

  • URL

    ciąg znaków opcjonalny

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

OnInstalledReason

Chrome 44 lub nowszy

Powodem wysłania tego zdarzenia.

Typ wyliczeniowy

„install”
Określa powód zdarzenia jako instalację.

„update”
Określa przyczynę zdarzenia jako aktualizację rozszerzenia.

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

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

OnRestartRequiredReason

Chrome 44 lub nowszy

Przyczyna wysłania zdarzenia. Wartość „app_update” jest używana, gdy wymagane jest ponowne uruchomienie, 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” (okresowa) 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” (okresowy)
Określa przyczynę zdarzenia jako okresowy restart aplikacji.

PlatformArch

Chrome 44 lub nowszy

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.

PlatformInfo

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

Właściwości

  • Architektura procesora maszyny.

  • nacl_arch

    PlatformNaclArch

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

  • System operacyjny, w którym działa Chrome.

PlatformNaclArch

Chrome 44 lub nowszy

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

Typ wyliczeniowy

"arm"
Określa natywną architekturę klienta jako arm.

„x86-32”
Określa natywną architekturę klienta jako x86-32.

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

„mips”
Określa natywną architekturę klienta jako mips.

„mips64”
Określa natywną architekturę klienta jako mips64.

PlatformOs

Chrome 44 lub nowszy

System operacyjny, w 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.

"fuchsia"
Określa system operacyjny Fuchsia.

Port

Obiekt umożliwiający dwukierunkową komunikację z innymi stronami. Więcej informacji znajdziesz w artykule Długotrwałe połączenia.

Właściwości

  • nazwa

    ciąg znaków

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

  • onDisconnect

    Zdarzenie<functionvoidvoid>

    Uruchamiane, gdy port jest odłączony od innych końców. runtime.lastError może być ustawiona, jeśli port został rozłączony z powodu błędu. Jeśli port jest zamknięty za pomocą disconnect, to zdarzenie jest tylko wywoływane po drugiej stronie. To zdarzenie jest wywoływane najwyżej raz (patrz też Lifetime port).

    Funkcja onDisconnect.addListener ma postać:

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

    • wywołanie zwrotne

      funkcja

      Parametr callback ma postać:

      (port: Port) => void

  • onMessage

    Zdarzenie<functionvoidvoid>

    To zdarzenie jest wywoływane, gdy funkcja postMessage jest wywoływana po drugiej stronie portu.

    Funkcja onMessage.addListener ma postać:

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

    • wywołanie zwrotne

      funkcja

      Parametr callback ma postać:

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

      • wiadomość

        każdy

      • port

        Port

  • nadawca

    MessageSender opcjonalny

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

  • rozłącz

    nieważne

    Natychmiast odłącz port. Wywołanie funkcji disconnect() na porcie, który nie jest już połączony, nie przynosi żadnego efektu. Gdy port zostanie odłączony, żadne nowe zdarzenia nie zostaną do niego wysłane.

    Funkcja disconnect ma postać:

    () => {...}

  • postMessage

    nieważne

    Wyślij wiadomość do drugiego końca portu. Jeśli port jest odłączony, pojawia się błąd.

    Funkcja postMessage ma postać:

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

    • wiadomość

      każdy

      Chrome 52+

      Wiadomość do wysłania. Obiekt powinien być w stanie obsługiwać format JSON.

RequestUpdateCheckStatus

Chrome 44 lub nowszy

Wynik sprawdzania dostępności aktualizacji.

Typ wyliczeniowy

"throttled"
Określa, że sprawdzenie stanu zostało ograniczone. Może się to zdarzyć po wielokrotnym sprawdzeniu w krótkim czasie.

"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

ciąg znaków

lastError

Wypełniony komunikatem o błędzie, jeśli wywołanie funkcji interfejsu API zakończyło się niepowodzeniem; w przeciwnym razie nieokreślony. Jest on zdefiniowany tylko w zakresie funkcji wywołania zwrotnego. Jeśli wystąpi błąd, ale funkcja runtime.lastError nie jest wywoływana w ramach funkcji zwrotnej, w konsoli zostanie zarejestrowany komunikat z wyszczególnieniem 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,
)

próby połączenia odbiorców w rozszerzeniu (np. na stronie 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 lub rozszerzeniami oraz wiadomości internetowych. Pamiętaj, że nie łączy się to z żadnymi słuchaczami w skrypcie treści. Rozszerzenia mogą łączyć się ze skryptami treści wbudowanymi w karty za pomocą tabs.connect.

Parametry

  • extensionId

    ciąg znaków opcjonalny

    Identyfikator rozszerzenia, z którym chcesz się połączyć. Jeśli ten argument zostanie pominięty, zostanie podjęta próba połączenia z Twoim własnym rozszerzeniem. Wymagane, jeśli wysyłasz wiadomości ze strony internetowej w ramach wiadomości internetowych.

  • connectInfo

    object opcjonalne

    • includeTlsChannelId

      logiczna opcjonalna

      Określa, czy identyfikator kanału TLS zostanie przekazany do onConnectExternal dla procesów, które nasłuchują zdarzenia połączenia.

    • nazwa

      ciąg znaków opcjonalny

      Jest przekazywany do onConnect w przypadku procesów nasłuchujących na zdarzenie połączenia.

Zwroty

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

connectNative()

chrome.runtime.connectNative(
  application: string,
)

Łączy się z natywną aplikacją na komputerze hosta. Ta metoda wymaga uprawnienia "nativeMessaging". Więcej informacji znajdziesz w artykule Komunikacja natywnych aplikacji.

Parametry

  • aplikacja

    ciąg znaków

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

Zwroty

  • Port, przez który aplikacja może wysyłać i odbierać wiadomości.

getBackgroundPage()

Obietnice Tylko na pierwszym planie 
chrome.runtime.getBackgroundPage(
  callback?: function,
)

Pobiera obiekt „window” kodu JavaScript dla strony w tle, która działa w bieżącym rozszerzeniu lub aplikacji. Jeśli strona w tle jest stroną zdarzenia, system wczyta ją przed wywołaniem funkcji zwracającej wywołanie. Jeśli nie ma strony w tle, ustawiany jest błąd.

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (backgroundPage?: Window) => void

    • backgroundPage

      Okno opcjonalne

      Obiekt JavaScript „window” dla strony w tle.

Zwroty

  • Obietkwarzeczenia<Window | undefined>

    Chrome 99+

    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 obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getContexts()

Promise Chrome 116+ MV3+ 
chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

Pobiera informacje o aktywnych kontekstach powiązanych z tym rozszerzeniem

Parametry

  • Filtr do znajdowania pasujących kontekstów. Kontekst pasuje, jeśli jest zgodny ze wszystkimi polami określonymi w filtrze. Każde niewyspecyfikowane pole w filtrze pasuje do wszystkich kontekstów.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (contexts: ExtensionContext[]) => void

Zwroty

  • Promise<ExtensionContext[]>

    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 obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getManifest()

chrome.runtime.getManifest()

Zwraca szczegóły aplikacji lub rozszerzenia z pliku manifestu. Zwracany obiekt to serializacja pełnego pliku manifestu.

Zwroty

  • Obiekt

    Szczegóły pliku manifestu.

getPackageDirectoryEntry()

Obietnice Tylko na pierwszym planie 
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

Zwraca DirectoryEntry dla katalogu pakietu.

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

Zwroty

  • Promise<DirectoryEntry>

    Chrome 122 lub nowszy

    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 obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getPlatformInfo()

Obietnice 
chrome.runtime.getPlatformInfo(
  callback?: function,
)

Zwraca informacje o bieżącej platformie.

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (platformInfo: PlatformInfo) => void

Zwroty

  • Obietnice<PlatformInfo>

    Chrome 99+

    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 obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getURL()

chrome.runtime.getURL(
  path: string,
)

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

Parametry

  • ścieżka

    ciąg znaków

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

Zwroty

  • ciąg znaków

    Pełny adres URL zasobu.

openOptionsPage()

Obietnice 
chrome.runtime.openOptionsPage(
  callback?: function,
)

Otwórz stronę opcji rozszerzenia (jeśli to możliwe).

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. Może ona na przykład otworzyć się na nowej karcie, w chrome://extensions lub w aplikacji albo po prostu otworzyć stronę opcji. Nigdy nie spowoduje odświeżenia strony wywołującej.

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

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 99+

    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 obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

Obietnice 
chrome.runtime.requestUpdateCheck(
  callback?: function,
)

Prośba o natychmiastowe zaktualizowanie tej aplikacji lub rozszerzenia.

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

Ta metoda jest odpowiednia tylko w bardzo ograniczonych okolicznościach, np. gdy Twoje rozszerzenie komunikuje się z usługą w backendzie, a ta ostatnia stwierdza, że wersja rozszerzenia klienta jest bardzo przestarzała i chcesz poprosić użytkownika o jej zaktualizowanie. Większość innych zastosowań funkcji requestUpdateCheck, np. wywoływanie jej bezwarunkowo na podstawie powtarzającego się timera, prawdopodobnie tylko marnuje zasoby klienta, sieci i serwera.

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

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (result: object) => void

    • wynik

      Obiekt

      Chrome 109 lub nowszy

      Obiekt RequestUpdateCheckResult, który zawiera stan sprawdzania aktualizacji i wszystkie szczegóły wyniku, jeśli dostępna jest aktualizacja.

      • Wynik sprawdzania dostępności aktualizacji.

      • wersja

        ciąg znaków opcjonalny

        Jeśli aktualizacja jest dostępna, zawiera wersję tej aktualizacji.

Zwroty

  • Obietkw<object>

    Chrome 109 lub nowszy

    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 obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

restart()

chrome.runtime.restart()

Uruchom ponownie urządzenie z ChromeOS, gdy aplikacja działa w trybie kiosku. W przeciwnym razie nie będzie działać.

restartAfterDelay()

Obietnica Chrome 53 lub nowszy 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

Uruchom ponownie urządzenie z ChromeOS, gdy aplikacja będzie działać w trybie kiosku po określonym czasie. Jeśli zostanie ponownie wywołany przed upływem tego czasu, ponowne uruchomienie zostanie opóźnione. Jeśli wywołanie zawiera wartość -1, ponowne uruchamianie zostanie anulowane. W trybie innym niż kiosk nie ma to żadnego znaczenia. Może być wywoływane wielokrotnie tylko przez pierwsze rozszerzenie, które wywołało ten interfejs API.

Parametry

  • s

    liczba

    Czas oczekiwania w sekundach przed ponownym uruchomieniem urządzenia lub -1, aby anulować zaplanowany restart.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 99+

    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 obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

sendMessage()

Obietnice 
chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
)

Wysyła jedną wiadomość do odbiorców zdarzeń w rozszerzeniu lub innym rozszerzeniu/aplikacji. Działa podobnie jak runtime.connect, ale wysyła tylko jedną wiadomość z opcjonalną odpowiedzią. Jeśli wysyłasz do swojego rozszerzenia, zdarzenie runtime.onMessage zostanie wywołane w każdej klatce 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. Wymagane, jeśli wysyłasz wiadomości z witryny do wyświetlania wiadomości w internecie.

  • wiadomość

    każdy

    Wiadomość do wysłania. Ta wiadomość powinna być obiektem JSON.

  • Opcje

    object opcjonalne

    • includeTlsChannelId

      logiczna opcjonalna

      Określa, czy identyfikator kanału TLS zostanie przekazany do onMessageExternal dla procesów, które nasłuchują zdarzenia połączenia.

  • wywołanie zwrotne

    function opcjonalny

    Chrome 99+

    Parametr callback ma postać:

    (response: any) => void

    • odpowiedź

      każdy

      Obiekt odpowiedzi JSON wysłany przez moduł obsługi wiadomości. Jeśli podczas łączenia z rozszerzeniem wystąpi błąd, funkcja wywołania zwrotnego zostanie wywołana bez argumentów, a wartość runtime.lastError zostanie ustawiona jako komunikat o błędzie.

Zwroty

  • Promise<any>

    Chrome 99+

    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 obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

sendNativeMessage()

Obietnice 
chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

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

Parametry

  • aplikacja

    ciąg znaków

    Nazwa hosta natywnego przesyłania komunikatów.

  • wiadomość

    Obiekt

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

  • wywołanie zwrotne

    function opcjonalny

    Chrome 99+

    Parametr callback ma postać:

    (response: any) => void

    • odpowiedź

      każdy

      wiadomość odpowiedzi wysłana przez hosta natywnego przesyłania komunikatów; Jeśli podczas nawiązywania połączenia z natywnym hostem wiadomości wystąpi błąd, wywołanie zwrotne zostanie wywołane bez argumentów, a runtime.lastError zostanie ustawione jako komunikat o błędzie.

Zwroty

  • Promise<any>

    Chrome 99+

    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 obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

setUninstallURL()

Obietnice 
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

Ustawia adres URL, który ma zostać otwarty po odinstalowaniu. Możesz go używać do oczyszczania danych po stronie serwera, przeprowadzania analiz i wdrażania ankiet. Maksymalnie 1023 znaków.

Parametry

  • URL

    ciąg znaków

    Adres URL, który ma zostać otwarty po odinstalowaniu rozszerzenia. Adres URL musi mieć schemat http: lub https:. Aby nie otwierać nowej karty po odinstalowaniu, ustaw pusty ciąg znaków.

  • wywołanie zwrotne

    function opcjonalny

    Chrome 45 i nowsze

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 99+

    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 obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

Wydarzenia

onBrowserUpdateAvailable

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

Użyj wartości runtime.onRestartRequired.

Wywoływany, gdy dostępna jest aktualizacja Chrome, ale nie jest ona instalowana od razu, ponieważ wymagane jest ponowne uruchomienie przeglądarki.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    () => void

onConnect

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

Wywoływany, gdy połączenie jest nawiązywane z procesu rozszerzenia lub skryptu treści (za pomocą runtime.connect).

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    (port: Port) => void

onConnectExternal

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

Wywoływany, gdy połączenie jest nawiązywane z innego rozszerzenia (za pomocą runtime.connect) lub z witryny internetowej, z którą można połączyć zewnętrznie.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    (port: Port) => void

onConnectNative

Chrome 76 lub nowszy 
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

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

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    (port: Port) => void

onInstalled

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

Wywoływany, gdy rozszerzenie jest po raz pierwszy instalowane, gdy jest aktualizowane do nowej wersji i gdy przeglądarka Chrome jest aktualizowana do nowej wersji.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    (details: object) => void

    • szczegóły

      Obiekt

      • id

        ciąg znaków opcjonalny

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

      • previousVersion

        ciąg znaków opcjonalny

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

      • Powodem wysłania tego zdarzenia.

onMessage

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

Wywoływany, gdy wiadomość jest wysyłana z procesu rozszerzenia (za pomocą runtime.sendMessage) lub skryptu treści (za pomocą tabs.sendMessage).

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

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

    • wiadomość

      każdy

    • nadawca

      MessageSender

    • sendResponse

      funkcja

      Parametr sendResponse ma postać:

      () => void

    • returns

      wartość logiczna | nieokreślona

onMessageExternal

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

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

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

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

    • wiadomość

      każdy

    • nadawca

      MessageSender

    • sendResponse

      funkcja

      Parametr sendResponse ma postać:

      () => void

    • returns

      wartość logiczna | nieokreślona

onRestartRequired

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

Wywoływane, gdy aplikacja lub urządzenie, na którym jest uruchomiona, wymaga ponownego uruchomienia. Aplikacja powinna zamknąć wszystkie okna w najdogodniejszym momencie, aby umożliwić ponowne uruchomienie. Jeśli aplikacja nie wykona żadnej akcji, po upływie 24-godzinnego okresu prolongaty zostanie ona ponownie uruchomiona. Obecnie to zdarzenie jest wywoływane tylko w przypadku aplikacji kioskowych w ChromeOS.

Parametry

onStartup

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

Wywoływane, gdy uruchamia się profil, na którym zainstalowano to rozszerzenie. To zdarzenie nie jest wywoływane, gdy uruchamiasz profil incognito, nawet jeśli to rozszerzenie działa w „podzielonym” trybie incognito.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    () => void

onSuspend

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

Wysyłane na stronę zdarzenia tuż przed jej wyładowaniem. Daje to rozszerzeniu możliwość usunięcia niepotrzebnych elementów. Pamiętaj, że skoro strona jest odwieszana, nie ma gwarancji, że operacje asynchroniczne rozpoczęte podczas obsługi tego zdarzenia zostaną ukończone. Jeśli przed zwolnieniem wystąpi więcej aktywności na stronie zdarzenia, zostanie wysłane zdarzenie onSuspendCanceled, a strona nie zostanie zwolniona.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    () => void

onSuspendCanceled

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

Wysyłane po onSuspend, aby wskazać, że aplikacja nie zostanie wczytana.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    () => void

onUpdateAvailable

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

Wywoływany, gdy dostępna jest aktualizacja, ale nie jest instalowana od razu, ponieważ aplikacja jest uruchomiona. Jeśli nic nie zrobisz, aktualizacja zostanie zainstalowana przy następnym wczytaniu strony w tle. Jeśli chcesz, aby została zainstalowana wcześniej, możesz wywołać funkcję chrome.runtime.reload(). Jeśli Twoje rozszerzenie korzysta z trwałej strony w tle, strona w tle nigdy nie zostanie wczytana, więc jeśli nie wywołasz funkcji chrome.runtime.reload() ręcznie w odpowiedzi na to zdarzenie, aktualizacja zostanie zainstalowana dopiero przy następnym ponownym uruchomieniu Chrome. Jeśli nie ma żadnych obsługiwanych zdarzeń i rozszerzenie ma trwałą stronę w tle, zachowuje się tak, jakby w odpowiedzi na to zdarzenie została wywołana funkcja chrome.runtime.reload().

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    (details: object) => void

    • szczegóły

      Obiekt

      • wersja

        ciąg znaków

        Numer wersji dostępnej aktualizacji.

onUserScriptConnect

Chrome 115 lub nowszy MV3+ 
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

Wywoływane, gdy połączenie zostanie utworzone z poziomu skryptu użytkownika z tego rozszerzenia.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    (port: Port) => void

onUserScriptMessage

Chrome 115 lub nowszy MV3+ 
chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

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

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

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

    • wiadomość

      każdy

    • nadawca

      MessageSender

    • sendResponse

      funkcja

      Parametr sendResponse ma postać:

      () => void

    • returns

      wartość logiczna | nieokreślona