chrome.runtime

Opis

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

Przegląd

Interfejs Runtime API udostępnia metody obsługujące wiele obszarów funkcjonalności, z których mogą korzystać 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 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ą funkcji connectNative() i sendNativeMessage().
Dostęp do metadanych rozszerzeń i platform
Te metody umożliwiają pobieranie kilku konkretnych 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 metaoperacji na rozszerzeniu i wyświetlanie strony opcji. Metody i wydarzenia w tej kategorii to m.in. onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() i setUninstallURL().
Narzędzia pomocnicze
Metody te zapewniają przydatne funkcje, takie 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 kiosków. Metody w tej kategorii to restart i restartAfterDelay.

Uprawnienia

Większość metod w interfejsie Runtime API nie wymaga żadnych uprawnień, z wyjątkiem metod sendNativeMessage i connectNative, które wymagają uprawnienia nativeMessaging.

Plik manifestu

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

manifest.json:

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

Przypadki użycia

Dodawanie obrazu do strony internetowej

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

W tym przykładzie rozszerzenie doda logo.png do strony, do której skrypt treści jest wstrzykiwany, używając runtime.getURL() do utworzenia pełnego adresu URL. Najpierw jednak zasób musi być 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 = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

Wysyłanie danych z procesu usługi do skryptu treści

Skrypty treści rozszerzenia często potrzebują danych zarządzanych przez inną część rozszerzenia, np. proces roboczy usługi. Podobnie jak w przypadku dwóch okien przeglądarki otwartych na tej samej stronie internetowej, te dwa 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 tych różnych kontekstach.

W tym przykładzie skrypt treści potrzebuje danych z procesu usługi rozszerzenia, aby zainicjować interfejs. Aby uzyskać te dane, wysyła do service workera wiadomość get-user-data, a ten 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);
});

background.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 lepiej służyć użytkownikom i zwiększyć ich zaangażowanie. Poniższy przykład pokazuje, 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 rozszerzeń

Więcej przykładów interfejsu Runtime API znajdziesz w demonstracji zasobów dostępnych w internecie w Manifest V3.

Typy

ContextFilter

Chrome 114 lub nowsza

Filtr dopasowujący określone konteksty rozszerzeń. Pasujące 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[] opcjonalny

  • contextTypes

    ContextType[] opcjonalnie

  • documentIds

    string[] opcjonalny

  • documentOrigins

    string[] opcjonalny

  • documentUrls

    string[] opcjonalny

  • frameIds

    number[] opcjonalny

  • incognito

    wartość logiczna opcjonalna

  • tabIds

    number[] opcjonalny

  • windowIds

    number[] opcjonalny

ContextType

Chrome 114 lub nowsza

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 nowsza

Kontekst hostujący treści rozszerzenia.

Właściwości

  • contextId

    ciąg znaków

    Unikalny identyfikator tego kontekstu

  • contextType

    ContextType

    Typ kontekstu, do którego odnosi się ten element.

  • documentId

    ciąg znaków opcjonalny

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

  • documentOrigin

    ciąg znaków opcjonalny

    Pochodzenie dokumentu powiązanego z tym kontekstem lub wartość undefined, jeśli kontekst nie jest hostowany w dokumencie.

  • documentUrl

    ciąg znaków opcjonalny

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

  • frameId

    liczba

    Identyfikator ramki w tym kontekście 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 w tym kontekście lub –1, jeśli ten kontekst nie jest hostowany na karcie.

  • windowId

    liczba

    Identyfikator okna w tym kontekście lub –1, jeśli ten 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 nowsza

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

  • documentLifecycle

    ciąg znaków opcjonalny

    Chrome 106 lub nowsza

    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 – w przypadku ramek najwyższego poziomu, dodatnia – w przypadku ramek podrzędnych. To ustawienie będzie dostępne 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 nowszy

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

  • pochodzenie

    ciąg znaków opcjonalny

    Chrome 80 lub nowsza

    Ź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 może być nieprzezroczysty (np. w przypadku piaskownicy iframe). Jest to przydatne, gdy nie możemy od razu stwierdzić na podstawie adresu URL, czy źródło jest godne zaufania.

  • tabulator

    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 i jeśli jest on 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 ramce iframe, będzie to adres URL ramki iframe, a nie adres URL strony, która ją hostuje.

OnInstalledReason

Chrome 44 lub nowszy

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

OnRestartRequiredReason

Chrome 44 lub nowszy

Przyczyna 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 konieczne, 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ż dopuszczalny czas pracy 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 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.

„riscv64”
Określa architekturę procesora jako riscv64.

PlatformInfo

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

Właściwości

  • Architektura procesora maszyny.

  • nacl_arch

    PlatformNaclArch opcjonalnie

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

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

PlatformNaclArch

Chrome 44 lub nowszy

Architektura klienta natywnego. Na niektórych platformach może się on 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 nowszy

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

    ciąg znaków

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

  • onDisconnect

    Event<functionvoidvoid>

    Uruchamiane, gdy port zostanie odłączony od drugiego końca(drugich końców). Wartość runtime.lastError może być ustawiona, jeśli port został odłączony z powodu błędu. Jeśli port zostanie zamknięty za pomocą polecenia disconnect, to zdarzenie zostanie wywołane tylko na drugim końcu. To zdarzenie jest wywoływane co najwyżej raz (zobacz też Okres istnienia portu).

    Funkcja onDisconnect.addListener wygląda tak:

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

    • callback

      funkcja

      Parametr callback wygląda tak:

      (port: Port) => void

  • onMessage

    Event<functionvoidvoid>

    To zdarzenie jest wywoływane, gdy druga strona portu wywołuje funkcję postMessage.

    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 tylko obecna w portach przekazywanych do odbiorników onConnect / onConnectExternal / onConnectNative.

  • rozłącz

    pusty,

    Natychmiast odłącz port. Wywołanie disconnect() na porcie, który jest już odłączony, nie ma żadnego efektu. Po odłączeniu portu nie będą do niego wysyłane żadne nowe zdarzenia.

    Funkcja disconnect wygląda tak:

    () => {...}

  • postMessage

    pusty,

    Wyślij wiadomość na drugi koniec portu. Jeśli port zostanie odłączony, wystąpi 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 nowszy

Wynik sprawdzenia aktualizacji.

Typ wyliczeniowy

„throttled”
Określa, że sprawdzanie 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 jest dostępna aktualizacja do zainstalowania.

Właściwości

id

Identyfikator rozszerzenia lub aplikacji.

Typ

ciąg znaków

lastError

Zawiera komunikat o błędzie, jeśli wywołanie funkcji interfejsu API nie powiedzie się. W przeciwnym razie jest niezdefiniowane. Jest ona zdefiniowana tylko w zakresie wywołania zwrotnego tej funkcji. Jeśli wystąpi błąd, ale w wywołaniu zwrotnym nie ma dostępu do runtime.lastError, w konsoli zostanie zarejestrowany komunikat z listą funkcji interfejsu API, które spowodowały 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ć odbiorców w ramach rozszerzenia (np. strony w tle) lub innych rozszerzeń/aplikacji. Jest to przydatne w przypadku skryptów treści łączących się z procesami rozszerzenia, komunikacji między aplikacjami lub rozszerzeniami oraz komunikacji w internecie. Pamiętaj, że nie łączy się to z żadnymi odbiorcami w skrypcie treści. Rozszerzenia mogą łączyć się ze skryptami treści osadzonymi w kartach za pomocą tabs.connect.

Parametry

  • extensionId

    ciąg znaków opcjonalny

    Identyfikator rozszerzenia, z którym chcesz się połączyć. Jeśli ten argument nie zostanie podany, połączenie zostanie nawiązane z Twoim rozszerzeniem. Wymagane, jeśli wysyłasz wiadomości ze strony internetowej w ramach wiadomości internetowych.

  • connectInfo

    obiekt opcjonalny

    • includeTlsChannelId

      wartość logiczna opcjonalna

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

    • nazwa

      ciąg znaków opcjonalny

      Zostanie przekazany do funkcji onConnect w przypadku procesów, które nasłuchują zdarzenia 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,
): Port

Łączy się z aplikacją natywną na komputerze hosta. Ta metoda wymaga uprawnienia "nativeMessaging". Więcej informacji znajdziesz w sekcji Komunikatory.

Parametry

  • aplikacja

    ciąg znaków

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

Zwroty

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

getBackgroundPage()

Promise Tylko na pierwszym planie Wycofane w Chrome 133
chrome.runtime.getBackgroundPage(
  callback?: function,
): Promise<Window | undefined>

W rozszerzeniach MV3 nie ma stron w tle.

Pobiera obiekt JavaScript „window” strony w tle działającej w bieżącym rozszerzeniu lub aplikacji. Jeśli strona w tle jest stroną zdarzeń, system zadba o jej wczytanie przed wywołaniem funkcji zwrotnej. Jeśli nie ma strony w tle, wystąpi błąd.

Parametry

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (backgroundPage?: Window) => void

    • backgroundPage

      Okno opcjonalne

      Obiekt JavaScript „window” strony tła.

Zwroty

  • Promise<Window | undefined>

    Chrome 99 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getManifest()

chrome.runtime.getManifest(): object

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

Zwroty

  • obiekt

    Szczegóły pliku manifestu.

getPackageDirectoryEntry()

Promise Tylko na pierwszym planie 
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
): Promise<DirectoryEntry>

Zwraca DirectoryEntry dla katalogu pakietu.

Parametry

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

Zwroty

  • Promise<DirectoryEntry>

    Chrome 122 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getPlatformInfo()

Obietnica 
chrome.runtime.getPlatformInfo(
  callback?: function,
): Promise<PlatformInfo>

Zwraca informacje o bieżącej platformie.

Parametry

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (platformInfo: PlatformInfo) => void

Zwroty

  • Promise<PlatformInfo>

    Chrome 99 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getURL()

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

Konwertuje ścieżkę względną w katalogu instalacyjnym 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 instalacyjnego.

Zwroty

  • ciąg znaków

    Pełny adres URL zasobu.

getVersion()

Oczekuje
chrome.runtime.getVersion(): string

Zwraca wersję rozszerzenia zadeklarowaną w pliku manifestu.

Zwroty

  • ciąg znaków

    Wersja rozszerzenia.

openOptionsPage()

Obietnica 
chrome.runtime.openOptionsPage(
  callback?: function,
): Promise<void>

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 albo od tego, co Chrome obsługuje w danym momencie. Na przykład strona może zostać otwarta na nowej karcie, w chrome://extensions, w aplikacji lub może po prostu skupić się na otwartej stronie opcji. Nigdy nie spowoduje ponownego załadowania strony wywołującej.

Jeśli rozszerzenie nie deklaruje strony opcji lub Chrome nie udało się jej utworzyć z innego powodu, funkcja zwrotna ustawi wartość lastError.

Parametry

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 99 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

reload()

chrome.runtime.reload(): void

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

requestUpdateCheck()

Obietnica 
chrome.runtime.requestUpdateCheck(
  callback?: function,
): Promise<object>

Wymaga natychmiastowego sprawdzenia, czy ta aplikacja lub to rozszerzenie wymaga aktualizacji.

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

Ta metoda jest odpowiednia tylko w bardzo ograniczonych okolicznościach, np. jeśli rozszerzenie komunikuje się z usługą backendową, a usługa backendowa stwierdziła, że wersja rozszerzenia klienta jest bardzo przestarzała i chcesz poprosić użytkownika o aktualizację. Większość innych zastosowań funkcji requestUpdateCheck, takich jak bezwarunkowe wywoływanie jej na podstawie powtarzającego się timera, prawdopodobnie tylko marnuje zasoby klienta, sieci i serwera.

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

Parametry

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (result: object) => void

    • wynik

      obiekt

      Chrome 109 lub nowsza

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

      • Wynik sprawdzenia aktualizacji.

      • wersja

        ciąg znaków opcjonalny

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

Zwroty

  • Promise<object>

    Chrome 109 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

restart()

chrome.runtime.restart(): void

Ponownie uruchom urządzenie z ChromeOS, gdy aplikacja działa w trybie kiosku. W przeciwnym razie nie ma to żadnego efektu.

restartAfterDelay()

Promise Chrome 53+ 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
): Promise<void>

Ponownie uruchamia urządzenie z ChromeOS, gdy aplikacja działa w trybie kiosku po upływie podanego czasu. Jeśli przed upływem tego czasu zostanie wywołana ponownie, ponowne uruchomienie zostanie opóźnione. Jeśli wywołasz tę funkcję z wartością -1, ponowne uruchomienie zostanie anulowane. W trybie innym niż kiosk ta funkcja nie działa. Może być wielokrotnie wywoływana 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ć zaplanowane ponowne uruchomienie.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 99 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

sendMessage()

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

Wysyła pojedynczą wiadomość do odbiorców zdarzeń w rozszerzeniu lub w innym rozszerzeniu/aplikacji. Działa 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 funkcji tabs.sendMessage.

Parametry

  • extensionId

    ciąg znaków opcjonalny

    Identyfikator rozszerzenia, do którego ma zostać wysłana wiadomość. Jeśli ten parametr zostanie pominięty, wiadomość zostanie wysłana do Twojego rozszerzenia lub aplikacji. Jest wymagany, jeśli wiadomości są wysyłane ze strony internetowej w przypadku wiadomości internetowych.

  • wiadomość

    każdy

    Wiadomość do wysłania. Wiadomość powinna być obiektem, który można przekształcić w JSON.

  • Opcje

    obiekt opcjonalny

    • includeTlsChannelId

      wartość logiczna opcjonalna

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

  • callback

    funkcja opcjonalna

    Chrome 99 lub nowsza

    Parametr callback wygląda tak:

    (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, wywołanie zwrotne zostanie wywołane bez argumentów, a wartość runtime.lastError zostanie ustawiona na komunikat o błędzie.

Zwroty

  • Promise<any>

    Chrome 99 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

sendNativeMessage()

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

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 wiadomości natywnych.

  • callback

    funkcja opcjonalna

    Chrome 99 lub nowsza

    Parametr callback wygląda tak:

    (response: any) => void

    • odpowiedź

      każdy

      Wiadomość odpowiedzi wysłana przez hosta natywnych aplikacji do obsługi wiadomości. Jeśli podczas łączenia z hostem wiadomości natywnych wystąpi błąd, wywołanie zwrotne zostanie wywołane bez argumentów, a wartość runtime.lastError zostanie ustawiona na komunikat o błędzie.

Zwroty

  • Promise<any>

    Chrome 99 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

setUninstallURL()

Obietnica 
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
): Promise<void>

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

Parametry

  • URL

    ciąg znaków

    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ć nowej karty.

  • callback

    funkcja opcjonalna

    Chrome 45 lub nowsza

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 99 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

Wydarzenia

onBrowserUpdateAvailable

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

Użyj runtime.onRestartRequired.

Wywoływane, gdy dostępna jest aktualizacja Chrome, ale nie jest ona instalowana od razu, ponieważ wymaga ponownego uruchomienia przeglądarki.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    () => void

onConnect

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

Wywoływane, 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

onConnectExternal

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

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

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (port: Port) => void

onConnectNative

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

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

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (port: Port) => void

onInstalled

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

Wywoływane, gdy rozszerzenie jest instalowane po raz pierwszy, gdy jest aktualizowane do nowej wersji i gdy Chrome jest aktualizowany 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. Ten element jest obecny tylko wtedy, gdy „reason” ma wartość „shared_module_update”.

      • previousVersion

        ciąg znaków opcjonalny

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

      • Przyczyna wysłania tego zdarzenia.

onMessage

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

Wysyłane, gdy wiadomość jest wysyłana z procesu rozszerzenia (przez runtime.sendMessage) lub skryptu treści (przez tabs.sendMessage).

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:

      () => void

    • returns

      wartość logiczna | nieokreślona

onMessageExternal

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

Wywoływane, 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 | undefined

    • wiadomość

      każdy

    • nadawca,

      MessageSender

    • sendResponse

      funkcja

      Parametr sendResponse wygląda tak:

      () => 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 najwygodniejszym dla siebie momencie, aby umożliwić ponowne uruchomienie. Jeśli aplikacja nie podejmie żadnych działań, po 24-godzinnym okresie prolongaty zostanie wymuszone ponowne uruchomienie. Obecnie to zdarzenie jest wywoływane tylko w przypadku aplikacji kiosku w ChromeOS.

Parametry

onStartup

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

Uruchamiane, gdy profil z zainstalowanym tym rozszerzeniem zostanie uruchomiony po raz pierwszy. To zdarzenie nie jest wywoływane po uruchomieniu profilu incognito, nawet jeśli to rozszerzenie działa w trybie incognito „podzielonym”.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    () => void

onSuspend

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

Wysyłane na stronę zdarzenia tuż przed jej zamknięciem. Dzięki temu rozszerzenie może przeprowadzić pewne działania porządkowe. Pamiętaj, że ponieważ strona jest zamykana, nie ma gwarancji, że wszystkie operacje asynchroniczne rozpoczęte podczas obsługi tego zdarzenia zostaną ukończone. Jeśli przed zwolnieniem strony wydarzenia wystąpi więcej aktywności, zostanie wysłane zdarzenie onSuspendCanceled, a strona nie zostanie zwolniona.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    () => void

onSuspendCanceled

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

Wysyłany po wywołaniu funkcji onSuspend, aby wskazać, że aplikacja nie zostanie jednak zwolniona.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    () => void

onUpdateAvailable

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

Wyzwalane, gdy dostępna jest aktualizacja, ale nie jest instalowana od razu, ponieważ aplikacja jest obecnie uruchomiona. Jeśli nic nie zrobisz, aktualizacja zostanie zainstalowana przy następnym zamknięciu strony w tle. Jeśli chcesz, aby została zainstalowana wcześniej, możesz jawnie wywołać chrome.runtime.reload(). Jeśli Twoje rozszerzenie używa trwałej strony w tle, strona ta nigdy nie jest zamykana, więc jeśli nie wywołasz ręcznie chrome.runtime.reload() w odpowiedzi na to zdarzenie, aktualizacja nie zostanie zainstalowana do czasu ponownego uruchomienia Chrome. Jeśli żadne moduły obsługi nie nasłuchują tego zdarzenia, a rozszerzenie ma trwałą stronę w tle, zachowuje się 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

        ciąg znaków

        Numer wersji dostępnej aktualizacji.