Ta strona została przetłumaczona przez Cloud Translation API.

chrome.runtime

Opis

Interfejs API chrome.runtime umożliwia pobieranie skryptu service worker, zwracanie szczegółów pliku manifestu oraz nasłuchiwanie zdarzeń w cyklu życia rozszerzenia i odpowiadanie na nie. Za pomocą tego interfejsu API można również konwertować ścieżki względne adresów URL na pełne adresy URL.

Omówienie

Interfejs Runtime API udostępnia metody obsługi różnych obszarów funkcji, z których korzystają rozszerzenia możesz używać:

Wiadomość zaliczona: Twoje 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ą metod connectNative() i sendNativeMessage().

Dostęp do metadanych rozszerzeń i platform: Te metody pozwalają pobrać kilka 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 pozwalają wykonać niektóre metaoperacje na rozszerzeniu i wyświetlić stronę opcji. Metody i zdarzenia w tej kategorii to onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() i setUninstallURL().
Narzędzia pomocnicze: Te metody są przydatne, na przykład konwertowanie reprezentacji zasobów wewnętrznych na: z formatami zewnętrznymi. Metody w tej kategorii obejmują getURL().
Narzędzia w trybie 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

Ten 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 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 komponenty rozszerzenia muszą być wyświetlane jako sieć dostępnych zasobów, i że za wstrzykiwanie kodu odpowiadają zazwyczaj skrypty komponentów.

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 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 skryptu service worker do skryptu treści

Skrypty treści rozszerzenia często potrzebują danych zarządzanych przez inną część rozszerzenia, np. przez usługę w tle. Podobnie jak w przypadku dwóch okien przeglądarki otwierających się na tej samej stronie internetowej, 2 konteksty nie mają bezpośredniego dostępu do wzajemnych wartości. 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 je pobrać, przekazuje komunikat get-user-data do skryptu service worker, przesyła w odpowiedzi 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 może lepiej służyć użytkownikom i zatrzymać 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 rozszerzeń

Więcej przykładów środowiska wykonawczego API znajdziesz w wersji demonstracyjnej Manifest V3 – zasoby dostępne w internecie.

Typy

ContextFilter

Chrome w wersji 114 lub nowszej

Filtr dopasowujący do określonych kontekstów rozszerzeń. Dopasowane konteksty muszą być zgodne ze wszystkimi określonymi filtrami. Filtr, który nie jest określony, pasuje do wszystkich dostępnych kontekstów. W ten sposób 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

Wartość logiczna opcjonalna
tabIds

number[] opcjonalny
windowIds

liczba[] opcjonalnie

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 w wersji 114 lub nowszej

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 pasuje ten element.
documentId

ciąg znaków opcjonalny

Identyfikator UUID dokumentu powiązanego z tym kontekstem lub niezdefiniowany, 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 w danym kontekście lub -1, jeśli ten kontekst nie jest hostowany w ramce.
incognito

wartość logiczna

Czy kontekst jest powiązany z profilem w trybie 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 w przypadku klatek najwyższego poziomu, plus w przypadku ramek podrzędnych. To ustawienie zostanie ustawione tylko wtedy, gdy tab ma wartość .
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, z której nastąpiło 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. 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

Element tabs.Tab, który otworzył połączenie (jeśli taki istnieje). Ta właściwość będzie widoczna tylko wtedy, gdy połączenie zostało otwarte na karcie (w tym w skryptach 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, na której zostało otwarte połączenie, jeśli rozszerzenie tego zażądało i jeśli jest dostępne.
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 w wersji 44 lub nowszej

Przyczyna wysłania zdarzenia. Wartość „app_update” jest używana, gdy konieczne jest ponowne uruchomienie, ponieważ aplikacja została zaktualizowana do nowszej wersji. „os_update” jest używane, gdy potrzebne jest ponowne uruchomienie, ponieważ przeglądarka lub system operacyjny jest aktualizowany do nowszej wersji. „okresowe” jest używana, gdy system działa dłużej niż dozwolony czas działania ustawiony w zasadzie przedsiębiorstwa.

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.

PlatformInfo

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

Właściwości

arch

PlatformArch

Architektura procesora maszyny.
nacl_arch

PlatformNaclArch

Architektura klienta natywnego. Może się różnić od łuku na niektórych platformach.
os

PlatformOs

System operacyjny 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 architekturę klienta natywnego jako x86-32.

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

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

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

PlatformOs

Chrome w wersji 44 lub nowszej

System operacyjny 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 sekcji 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<functionvoid>

Uruchamiane, gdy port jest odłączony od innych końców. Wartość runtime.lastError może zostać ustawiona, jeśli port został odłączony w wyniku błędu. Jeśli port jest zamknięty za pomocą metody disconnect, zdarzenie jest wywoływane tylko po drugiej stronie. To zdarzenie jest wywoływane maksymalnie raz (patrz też Lifetime (żywotność) portu).

Funkcja onDisconnect.addListener wygląda tak:
```
(callback: function) => {...}
```
- wywołanie zwrotne
  
  funkcja
  
  Parametr callback wygląda tak:
```
(port: Port) => void
```
  - port
    
    Port
onMessage

Zdarzenie<functionvoid>

To zdarzenie jest wywoływane po wywołaniu funkcji postMessage przez drugi koniec portu.

Funkcja onMessage.addListener wygląda tak:
```
(callback: function) => {...}
```
- wywołanie zwrotne
  
  funkcja
  
  Parametr callback wygląda tak:
```
(message: any, port: Port) => void
```
  - wiadomość
    
    każdy
  - port
    
    Port
nadawca

Opcjonalny MessageSender

Ta właściwość będzie tylko obecna na portach przekazywanych odbiorcom 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 wygląda tak:
```
() => {...}
```
postMessage

nieważne

Wyślij wiadomość do drugiego końca portu. Jeśli port zostanie odłączony, wystąpi błąd.

Funkcja postMessage ma postać:
```
(message: any) => {...}
```
- wiadomość
  
  każdy
  
  Chrome w wersji 52 lub nowszej
  
  Wiadomość do wysłania. Ten obiekt powinien być w formacie JSON.

RequestUpdateCheckStatus

Chrome w wersji 44 lub nowszej

Wynik sprawdzania dostępności 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 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 wywołanie zwrotne nie umożliwi dostępu do runtime.lastError, w konsoli zostanie zarejestrowany komunikat z listą 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 detektorów w obrębie rozszerzenia (np. ze stroną w tle) lub z innymi rozszerzeniami lub aplikacjami. Jest to przydatne w przypadku skryptów treści łączących się z procesami rozszerzeń, komunikacją między aplikacjami/rozszerzeniami oraz wiadomościami na stronie. Pamiętaj, że nie łączy się to z żadnymi słuchaczami w skrypcie treści. Rozszerzenia mogą łączyć się ze skryptami treści umieszczonymi w kartach przez tabs.connect.

Parametry

extensionId

ciąg znaków opcjonalny

Identyfikator rozszerzenia, z którym ma zostać nawiązane połączenie. Jeśli go pominiesz, spróbujemy nawiązać połączenie z Twoim własnym rozszerzeniem. Wymagane, jeśli wysyłasz wiadomości ze strony internetowej w ramach wiadomości internetowych.
connectInfo

object opcjonalne
- includeTlsChannelId
  
  Wartość 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
  
  Będzie przekazywana do onConnect w przypadku procesów, które nasłuchują zdarzenia połączenia.

Zwroty

Port

Port, za pomocą którego 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,
)

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

Parametry

aplikacja

ciąg znaków

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

Zwroty

Port

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

getBackgroundPage()

Obietnica Tylko pierwszy plan

chrome.runtime.getBackgroundPage(
  callback?: function,
)

Pobiera obiekt „window” JavaScriptu 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 opcjonalnie
  
  „Okno” JavaScriptu dla strony w tle.

Zwroty

Obietkwarzeczenia<Window | undefined>

Chrome w wersji 99 lub nowszej

Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

getContexts()

Obietnica Chrome w wersji 116 lub nowszej MV3 lub nowszy

chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

Pobiera informacje o aktywnych kontekstach powiązanych z tym rozszerzeniem

Parametry

filtr

ContextFilter

Filtr do znajdowania pasujących kontekstów. Kontekst jest dopasowywany, jeśli pasuje do wszystkich pól określonych w filtrze. Każde niewyspecyfikowane pole w filtrze pasuje do wszystkich kontekstów.
wywołanie zwrotne

function opcjonalny

Parametr callback wygląda tak:
```
(contexts: ExtensionContext[]) => void
```
- konteksty
  
  ExtensionContext[]
  
  Pasujące konteksty (jeśli występują).

Zwroty

Promise<ExtensionContext[]>

Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

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 wartość DirectoryEntry dla katalogu pakietów.

Parametry

wywołanie zwrotne

function opcjonalny

Parametr callback ma postać:
```
(directoryEntry: DirectoryEntry) => void
```
- directoryEntry
  
  DirectoryEntry

Zwroty

Obietnica<katalogu>

Chrome w wersji 122 lub nowszej

Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

getPlatformInfo()

Obietnica

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

Zwraca informacje o bieżącej platformie.

Parametry

wywołanie zwrotne

function opcjonalny

Parametr callback wygląda tak:
```
(platformInfo: PlatformInfo) => void
```
- platformInfo
  
  PlatformInfo

Zwroty

Obietnice<PlatformInfo>

Chrome w wersji 99 lub nowszej

Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

getURL()

chrome.runtime.getURL(
  path: string,
)

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

Parametry

ścieżka

ciąg znaków

Ścieżka do zasobu w aplikacji lub rozszerzeniu wyrażona w stosunku do katalogu instalacji.

Zwroty

ciąg znaków

Pełny adres URL zasobu.

openOptionsPage()

Obietnica

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

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

Dokładne działanie może zależeć od klucza [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options) lub [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page) w pliku manifestu oraz od obsługi przez Chrome w danym momencie. Na przykład strona może się otworzyć w nowej karcie, na chrome://extensions, w aplikacji lub po prostu wybrać otwartą stronę z opcjami. 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 w wersji 99 lub nowszej

Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

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

Aplikacja lub rozszerzenie wymaga natychmiastowego sprawdzenia dostępności aktualizacji.

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ń metody requestUpdateCheck, takich jak jej bezwarunkowe wywoływanie z powodu powtarzającego się licznika, prawdopodobnie służy jedynie do zużywania zasobów klienta, sieci i serwera.

Uwaga: po wywołaniu z wywołaniem zwrotnym ta funkcja nie zwraca obiektu, ale zwraca 2 właściwości jako osobne argumenty przekazywane 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 szczegóły wyniku, jeśli dostępna jest aktualizacja.
  - status
    
    RequestUpdateCheckStatus
    
    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 tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

restart()

chrome.runtime.restart()

Uruchom ponownie urządzenie z ChromeOS, gdy aplikacja działa w trybie kiosku. W przeciwnym razie jest to działanie bezobsługowe.

restartAfterDelay()

Obietnica Chrome w wersji 53 lub nowszej

chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

Ponownie uruchom urządzenie z ChromeOS, gdy aplikacja działa w trybie kiosku po upływie podanych sekund. Jeśli zostanie ponownie wywołany 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ż kiosk nie ma to sensu. Może być wywoływany 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 w wersji 99 lub nowszej

Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

sendMessage()

Obietnice

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

Wysyła pojedynczą wiadomość do detektorów zdarzeń w Twoim rozszerzeniu lub innym rozszerzeniu/aplikacji. Podobnie jak runtime.connect, wysyła tylko jedną wiadomość z opcjonalną odpowiedzią. Jeśli wysyłasz wiadomość do rozszerzenia, zdarzenie runtime.onMessage zostanie uruchomione w każdej klatce rozszerzenia (oprócz ramki nadawcy) lub runtime.onMessageExternal w przypadku innego rozszerzenia. 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. Wymagany, jeśli wysyłasz wiadomości ze strony internetowej jako komunikator internetowy.
wiadomość

każdy

Wiadomość do wysłania. Ta wiadomość powinna być obiektem obsługującym format JSON.
Opcje

object opcjonalne
- includeTlsChannelId
  
  logiczna opcjonalna
  
  Określa, czy identyfikator kanału TLS ma być przekazywany do onMessageExternal w przypadku procesów nasłuchujących 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 się z rozszerzeniem wystąpi błąd, wywołanie zwrotne zostanie wywołane bez argumentów, a funkcja runtime.lastError zostanie ustawiona na komunikat o błędzie.

Zwroty

Promise<any>

Chrome w wersji 99 lub nowszej

Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

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 w wersji 99 lub nowszej

Parametr callback wygląda tak:
```
(response: any) => void
```
- odpowiedź
  
  każdy
  
  Odpowiedź wysłana przez hosta natywnego przesyłania komunikatów. Jeśli podczas nawiązywania połączenia z hostem natywnego przesyłania komunikatów wystąpi błąd, wywołanie zwrotne zostanie wywołane bez argumentów, a funkcja runtime.lastError zostanie ustawiona na komunikat o błędzie.

Zwroty

Promise<any>

Chrome 99+

Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

setUninstallURL()

Obietnica

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

Ustawia adres URL, który ma być odwiedzany po odinstalowaniu. Możesz go używać 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:. Aby nie otwierać nowej karty po odinstalowaniu, ustaw pusty ciąg znaków.
wywołanie zwrotne

function opcjonalny

Chrome w wersji 45 lub nowszej

Parametr callback wygląda tak:
```
() => void
```

Zwroty

Obietnica<void>

Chrome w wersji 99 lub nowszej

Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

Wydarzenia

onBrowserUpdateAvailable

Wycofane

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

Użyj adresu 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 wygląda tak:
```
() => 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 wygląda tak:
```
(port: Port) => void
```
- port
  
  Port

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 wygląda tak:
```
(port: Port) => void
```
- port
  
  Port

onConnectNative

Chrome w wersji 76 lub nowszej

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 wygląda tak:
```
(port: Port) => void
```
- port
  
  Port

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 wygląda tak:
```
(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. Dzieje się tak tylko wtedy, gdy „powód” to „shared_module_update”.
  - previousVersion
    
    ciąg znaków opcjonalny
    
    Wskazuje poprzednią wersję rozszerzenia, która została właśnie zaktualizowana. Dzieje się tak tylko wtedy, gdy „powód” to „aktualizacja”.
  - reason
    
    OnInstalledReason
    
    Powód wysył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 wygląda tak:
```
(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 wygląda tak:
```
(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
```
- wiadomość
  
  każdy
- nadawca
  
  MessageSender
- sendResponse
  
  funkcja
  
  Parametr sendResponse ma postać:
```
() => void
```
- returns
  boolean | nie zdefiniowano

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 najwcześniejszym dogodnym czasie, by 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

wywołanie zwrotne

funkcja

Parametr callback ma postać:
```
(reason: OnRestartRequiredReason) => void
```
- powód
  
  OnRestartRequiredReason

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 po uruchomieniu profilu incognito, nawet jeśli rozszerzenie działa w trybie „podziału” trybu incognito.

Parametry

wywołanie zwrotne

funkcja

Parametr callback wygląda tak:
```
() => void
```

onSuspend

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

Wysyłana na stronę zdarzenia tuż przed jego wyłączeniem z pamięci. W ten sposób rozszerzenie będzie mogło trochę posprzątać. Pamiętaj, że skoro strona jest wyładowywana, 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 wygląda tak:
```
() => void
```

onSuspendCanceled

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

Wysyłana po zawieszeniu, aby wskazać, że aplikacja nie zostanie w ogóle usunięta z pamięci.

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 nie podejmiesz żadnych działań, aktualizacja zostanie zainstalowana przy następnym usunięciu strony w tle. Jeśli chcesz zainstalować ją wcześniej, możesz jawnie wywołać funkcję chrome.runtime.reload(). Jeśli rozszerzenie używa trwałej strony w tle, strona działająca w tle nigdy nie jest wyładowywana z pamięci, więc chyba że w odpowiedzi na to zdarzenie ręcznie wywołasz funkcję chrome.runtime.reload(), aktualizacja zostanie zainstalowana dopiero przy następnym uruchomieniu Chrome. Jeśli nie ma żadnych obsługiwanych zdarzeń i Twoje rozszerzenie ma trwałą stronę w tle, zachowuje się tak, jakby w odpowiedzi na to zdarzenie wywołano funkcję chrome.runtime.reload().

Parametry

wywołanie zwrotne

funkcja

Parametr callback wygląda tak:
```
(details: object) => void
```
- szczegóły
  
  Obiekt
  - wersja
    
    ciąg znaków
    
    Numer wersji dostępnej aktualizacji.

onUserScriptConnect

Chrome w wersji 115 lub nowszej MV3 lub nowszy

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

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

Parametry

wywołanie zwrotne

funkcja

Parametr callback wygląda tak:
```
(port: Port) => void
```
- port
  
  Port

onUserScriptMessage

Chrome w wersji 115 lub nowszej MV3 lub nowszy

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 wygląda tak:
```
(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
```
- wiadomość
  
  każdy
- nadawca
  
  MessageSender
- sendResponse
  
  funkcja
  
  Parametr sendResponse ma postać:
```
() => void
```
- returns
  boolean | nie zdefiniowano