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.

Większość użytkowników tego interfejsu API nie wymaga żadnych uprawnień. Te uprawnienia są potrzebne 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 wykorzystanie

Interfejs Runtime API udostępnia metody obsługi wielu obszarów, na których rozszerzenia możesz używać:

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

Dostęp do metadanych rozszerzenia i platformy: Te metody pozwalają pobrać kilka określonych metadanych dotyczących rozszerzenia i platformy. Metody w tej kategorii obejmują getManifest() oraz getPlatformInfo()
Zarządzanie cyklem życia rozszerzeń i opcjami: Te właściwości pozwalają wykonać niektóre metaoperacje na rozszerzeniu i wyświetlić stronę opcji. Metody i zdarzenia w tej kategorii obejmują 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 wykorzystują je głównie do obsługi wdrożeń kiosku. Metody w tej kategorii obejmują restart() i restartAfterDelay()`.

Działanie rozszerzenia bez pakietu

Gdy rozpakowane rozszerzenie jest ponowne wczytywane, jest to traktowane jako aktualizacja. Oznacza to, że Zdarzenie chrome.runtime.onInstalled zostanie uruchomione z "update" przyczyną. Ten włącznie z ponownym wczytaniem rozszerzenia z rozszerzeniem chrome.runtime.reload().

Przypadki użycia

Dodawanie obrazu do strony internetowej

Aby strona internetowa mogła uzyskać dostęp do zasobu hostowanego w innej domenie, należy określić jego pełny adres URL (np. <img src="https://example.com/logo.png">). To samo dotyczy dołączenia komponentu z rozszerzeniem stronę internetową. 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, na której treść zostanie dodana skrypt jest wstrzyknięty przez użycie runtime.getURL() do utworzenia pełny adres 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łaj dane ze skryptu treści do skryptu service worker

Często skrypty treści rozszerzenia wymagają danych zarządzanych przez inną część rozszerzenia. np. skrypt service worker. 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 swoich wartości. Zamiast tego może użyć polecenia wiadomość w celu koordynacji działań w różnych kontekstach.

W tym przykładzie skrypt treści wymaga pewnych danych ze skryptu service worker rozszerzenia zainicjować jej interfejs użytkownika. Aby pobrać te dane, przekazuje zdefiniowaną przez dewelopera wiadomość w usłudze get-user-data skryptowi service worker i w odpowiedzi przesyła 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 rozszerzenia, by dowiedzieć się, jak dane rozszerzenie może użytkowników i poprawić ich utrzymanie. 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

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 dopasowywania do określonych kontekstów rozszerzeń. Pasujące konteksty muszą pasować do wszystkich określonych filtrów. każdy 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[] opcjonalny
documentIds

string[] opcjonalnie
documentOrigins

string[] opcjonalnie
documentUrls

string[] opcjonalnie
frameIds

liczba[] opcjonalnie
incognito

Wartość logiczna opcjonalna
tabIds

liczba[] opcjonalnie
windowIds

liczba[] opcjonalnie

ContextType

Chrome w wersji 114 lub nowszej

Typ wyliczeniowy

"TAB"
Określa typ kontekstu jako kartę

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

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

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

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

ExtensionContext

Chrome w wersji 114 lub nowszej

Kontekstowe hostowanie treści rozszerzenia.

Właściwości

contextId

ciąg znaków

Unikalny identyfikator tego kontekstu
contextType

ContextType

Typ kontekstu, którego to dotyczy.
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

Pochodzenie dokumentu powiązanego z tym kontekstem lub nieokreślone, jeśli kontekst nie jest przechowywany w dokumencie.
documentUrl

ciąg znaków opcjonalny

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

liczba

Identyfikator ramki w danym 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 dla tego kontekstu lub -1, jeśli ten kontekst nie jest hostowany na karcie.
windowId

liczba

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

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, w którym otworzył się połączenie, w chwili utworzenia portu. Pamiętaj, że stan cyklu życia dokumentu mógł się zmienić od czasu utworzenia portu.
frameId

liczba opcjonalnie

Ramka, która otworzyła połączenie. 0 w przypadku klatek najwyższego poziomu, plus w przypadku ramek podrzędnych. Ta opcja zostanie ustawiona tylko wtedy, gdy jest skonfigurowana zasada tab.
id

ciąg znaków opcjonalny

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

ciąg znaków opcjonalny

Chrome w wersji 74 lub nowszej

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

ciąg znaków opcjonalny

Chrome w wersji 80 lub nowszej

Źródło strony lub ramki, z której nastąpiło połączenie. Może on się różnić od właściwości adresu URL (np. about:blank) lub być nieprzezroczysty (np. elementy iframe w piaskownicy). Przydaje się to do określania, czy źródło jest wiarygodne, jeśli nie możemy od razu rozróżnić go na podstawie adresu URL.
tabulator

Tab opcjonalnie

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 nawiązano 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 elemencie iframe, będzie to URL elementu iframe, a nie URL strony, na której ten element jest przechowywany.

OnInstalledReason

Chrome w wersji 44 lub nowszej

Powód wysył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 w wersji 44 lub nowszej

Powód wysyłania zdarzenia. „app_update” jest używana, gdy wymagane jest ponowne uruchomienie, ponieważ aplikacja jest 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 w wersji 44 lub nowszej

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 z informacjami o bieżącej platformie.

Właściwości

łuk

PlatformArch

Architektura procesora maszyny.
nacl_arch

PlatformNaclArch

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

PlatformOs

System operacyjny Chrome.

PlatformNaclArch

Chrome w wersji 44 lub nowszej

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

Typ wyliczeniowy

"arm"
Określa architekturę klienta natywnej 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 natywnej w postaci 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 podana w wywołaniu runtime.connect.
onDisconnect

Zdarzenie<functionvoid>

Uruchamiane, gdy port jest odłączony od innych węzłó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 najwyżej raz (zobacz też Czas trwania 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 dostępna tylko na portach przekazywanych do detektorów onConnect / onConnectExternal / onConnectNative.
rozłącz

nieważne

Natychmiast odłącz port. Wywołanie disconnect() na już odłączonym porcie nie działa. Po odłączeniu portu nie będą do niego wysyłane żadne nowe zdarzenia.

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 wygląda tak:
```
(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 kilkukrotnych kontrolach 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/aplikacji.

Typ

ciąg znaków

lastError

w przypadku niepowodzenia wywołania funkcji interfejsu API wyświetla się komunikat o błędzie. w inny sposób niezdefiniowane. Jest to zdefiniowane tylko w zakresie wywołania zwrotnego tej funkcji. 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 dotyczące 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 wiąże 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. Wymagany, jeśli wysyłasz wiadomości ze strony internetowej w celu wiadomości internetowych.
connectInfo

obiekt opcjonalny
- includeTlsChannelId
  
  Wartość logiczna opcjonalna
  
  Określa, czy identyfikator kanału TLS ma być przekazywany do onConnectExternal w przypadku procesów nasłuchujących 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 hoście. Ta metoda wymaga uprawnienia "nativeMessaging". Więcej informacji znajdziesz w artykule Komunikaty natywne.

Parametry

aplikacja

ciąg znaków

Nazwa zarejestrowanych aplikacji, z którymi ma zostać nawiązane połączenie.

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 „okno” JavaScriptu dla strony w tle uruchomionej w bieżącym rozszerzeniu/aplikacji. Jeśli strona w tle jest stroną zdarzenia, przed wywołaniem wywołania zwrotnego system upewni się, że zostanie ona wczytana. Jeśli w tle nie ma strony w tle, oznacza to, że wystąpił błąd.

Parametry

wywołanie zwrotne

funkcja optional

Parametr callback wygląda tak:
```
(backgroundPage?: Window) => void
```
.
- backgroundPage
  
  Okno opcjonalnie
  
  „Okno” JavaScriptu dla strony w tle.

Zwroty

Promise<Window | niezdefiniowane>

Chrome w wersji 99 lub nowszej

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

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 nieokreślone pole filtra pasuje do wszystkich kontekstów.
wywołanie zwrotne

funkcja optional

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

Zwroty

Promise<ExtensionContext[]>

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

getManifest()

chrome.runtime.getManifest()

Zwraca informacje o aplikacji lub rozszerzeniu z pliku manifestu. Zwrócony obiekt to serializacja pełnego pliku manifestu.

Zwroty

Obiekt

Szczegóły pliku manifestu.

getPackageDirectoryEntry()

Obietnica Tylko pierwszy plan

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

Zwraca wartość DirectoryEntry dla katalogu pakietów.

Parametry

wywołanie zwrotne

funkcja optional

Parametr callback wygląda tak:
```
(directoryEntry: DirectoryEntry) => void
```
.
- directoryEntry
  
  DirectoryEntry

Zwroty

Promise<DirectoryEntry>

Chrome w wersji 122 lub nowszej

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

getPlatformInfo()

Obietnica

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

Zwraca informacje o bieżącej platformie.

Parametry

wywołanie zwrotne

funkcja optional

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

Zwroty

Promise<PlatformInfo>

Chrome w wersji 99 lub nowszej

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

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 w odniesieniu do jej 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 to ponownego załadowania strony wywołującego.

Jeśli rozszerzenie nie deklaruje strony opcji lub Chrome nie może jej utworzyć z jakiegoś innego powodu, wywołanie zwrotne będzie ustawione na lastError.

Parametry

wywołanie zwrotne

funkcja optional

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

Zwroty

Obietnica<void>

Chrome w wersji 99 lub nowszej

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

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

Obietnica

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

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

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

Ta metoda jest odpowiednia w przypadku bardzo rzadkich sytuacji, np. gdy rozszerzenie komunikuje się z usługą backendu, a usługa backendu wykryła, że wersja rozszerzenia klienta jest bardzo nieaktualna, i chcesz poprosić użytkownika o aktualizację. 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

funkcja optional

Parametr callback wygląda tak:
```
(result: object) => void
```
.
- wynik
  
  Obiekt
  
  Chrome 109 lub nowszy
  
  Obiekt RequestUpdateCheckResult zawierający stan sprawdzania dostępności aktualizacji i wszystkie szczegóły wyniku, jeśli jest dostępna aktualizacja
  - status
    
    RequestUpdateCheckStatus
    
    Wynik sprawdzania dostępności aktualizacji.
  - wersja
    
    ciąg znaków opcjonalny
    
    Jeśli aktualizacja jest dostępna, wyświetlana jest jej wersja.

Zwroty

Promise<object>

Chrome 109 lub nowszy

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

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 po upływie podanych sekund aplikacja będzie działać w trybie kiosku. W przypadku ponownego wywołania przed podanym czasem ponowne uruchomienie zostanie opóźnione. Jeśli zostanie wywołana z wartością -1, ponowne uruchomienie zostanie anulowane. To nic nie działa w trybie innym niż kiosk. Może być wywoływany wielokrotnie tylko przez pierwsze rozszerzenie wywołujące ten interfejs API.

Parametry

s

liczba

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

funkcja optional

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

Zwroty

Obietnica<void>

Chrome w wersji 99 lub nowszej

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

sendMessage()

Obietnica

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ą za pomocą tej metody wysyłać wiadomości do skryptów treści. Aby wysyłać wiadomości do skryptów treści, użyj narzędzia 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 w celu wiadomości internetowych.
wiadomość

każdy

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

obiekt opcjonalny
- includeTlsChannelId
  
  Wartość 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

funkcja optional

Chrome w wersji 99 lub nowszej

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

Obietnica<any>

Chrome w wersji 99 lub nowszej

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

sendNativeMessage()

Obietnica

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

Wyślij pojedynczą wiadomość 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 będzie przekazywana do hosta natywnego przesyłania komunikatów.
wywołanie zwrotne

funkcja optional

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

Obietnica<any>

Chrome w wersji 99 lub nowszej

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

setUninstallURL()

Obietnica

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

Ustawia adres URL, który ma być odwiedzany po odinstalowaniu. Można ich używać do czyszczenia 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 aplikacji nie otwierał się w nowej karcie.
wywołanie zwrotne

funkcja optional

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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

Wydarzenia

onBrowserUpdateAvailable

Wycofano

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

Użyj adresu runtime.onRestartRequired.

Uruchamiane, gdy dostępna jest aktualizacja Chrome, ale nie jest instalowana od razu, bo wymagane jest ponowne uruchomienie przeglądarki.

Parametry

wywołanie zwrotne

funkcja

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

onConnect

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

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

Parametry

wywołanie zwrotne

funkcja

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

onConnectExternal

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

Uruchamiane, gdy połączenie jest nawiązywane z innego rozszerzenia (przez runtime.connect) lub z witryny połączonej zewnętrznie.

Parametry

wywołanie zwrotne

funkcja

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

onConnectNative

Chrome w wersji 76 i nowszych

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

Uruchamiane po nawiązaniu połączenia z aplikacji natywnej. To zdarzenie wymaga uprawnienia "nativeMessaging". Jest obsługiwana tylko w systemie operacyjnym Chrome.

Parametry

wywołanie zwrotne

funkcja

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

onInstalled

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

Uruchamiane przy pierwszej instalacji rozszerzenia, zaktualizowaniu rozszerzenia do nowej wersji oraz po zaktualizowaniu Chrome 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 udostępnianego rozszerzenia 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óre zostało właśnie zaktualizowane. Dzieje się tak tylko wtedy, gdy „powód” to „aktualizacja”.
  - powód
    
    OnInstalledReason
    
    Powód wysyłania tego zdarzenia.

onMessage

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

Uruchamiane, gdy wiadomość zostanie wysłana z procesu rozszerzenia (przez runtime.sendMessage) lub skryptu treści (przez 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 wygląda tak:
```
() => void
```
  .
- returns
  boolean | nie zdefiniowano

onMessageExternal

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

Uruchamiane, gdy wiadomość zostanie wysłana z innego rozszerzenia (przez runtime.sendMessage). Nie mogą być używane 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 wygląda tak:
```
() => void
```
  .
- returns
  boolean | nie zdefiniowano

onRestartRequired

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

Uruchamiane, gdy trzeba ponownie uruchomić aplikację lub urządzenie, na którym działa. Aplikacja powinna zamknąć wszystkie okna w najwcześniejszym dogodnym czasie, by umożliwić ponowne uruchomienie. Jeśli aplikacja nie podejmie żadnych działań, ponowne uruchomienie zostanie wymuszone po upływie 24-godzinnego okresu prolongaty. Obecnie to zdarzenie jest wywoływane tylko w przypadku aplikacji kiosku Chrome OS.

Parametry

wywołanie zwrotne

funkcja

Parametr callback wygląda tak:
```
(reason: OnRestartRequiredReason) => void
```
.
- powód
  
  OnRestartRequiredReason

onStartup

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

Uruchamiane przy pierwszym uruchomieniu profilu, w 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 ponieważ strona jest wyładowywana, nie można zagwarantować zakończenia wszelkich operacji asynchronicznych uruchomionych podczas obsługi tego zdarzenia. Jeśli przed usunięciem strony zdarzenia z pamięci wystąpi więcej działań, zostanie wysłane zdarzenie onSuspensionCanceled i strona nie zostanie wyładowana z pamięci.

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

onUpdateAvailable

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

Uruchamiane, gdy aktualizacja jest dostępna, 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 żadne moduły obsługi nie nasłuchują tego zdarzenia, a rozszerzenie ma stałą 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 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,
)

Uruchamiane, gdy wiadomość zostanie wysłana za pomocą 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 wygląda tak:
```
() => void
```
  .
- returns
  boolean | nie zdefiniowano