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

chrome.runtime

Opis

Użyj interfejsu chrome.runtime API, aby pobrać skrypt service worker, zwrócić szczegóły pliku manifestu oraz nasłuchiwać zdarzeń w cyklu życia rozszerzenia i na nie odpowiadać. Za pomocą tego interfejsu API możesz też konwertować względne ścieżki adresów URL na pełne i jednoznaczne adresy URL.

Większość użytkowników tego interfejsu API nie wymaga żadnych uprawnień. Te uprawnienia są potrzebne w przypadku usług connectNative(), sendNativeMessage() i onNativeConnect.

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

manifest.json:

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

Pojęcia i zastosowanie

Interfejs Runtime API udostępnia metody umożliwiające obsługę wielu obszarów, z których mogą korzystać rozszerzenia:

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

Dostęp do metadanych rozszerzenia i platformy: Te metody umożliwiają pobranie 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 dotyczących rozszerzenia i wyświetlanie strony opcji. Metody i zdarzenia w tej kategorii to onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() i setUninstallURL().
Narzędzia pomocnicze: Te metody zapewniają narzędzia, takie jak konwersja reprezentacji zasobów wewnętrznych na formaty zewnętrzne. Metody w tej kategorii obejmują getURL().
Narzędzia w trybie kiosku: Te metody są dostępne tylko w ChromeOS i reprezentują głównie wdrożenia kiosku. Metody w tej kategorii to restart() i restartAfterDelay()`.

Działanie rozszerzeń bez pakietu

Ponowne wczytywanie rozszerzenia bez pakietu jest traktowane jako aktualizacja. Oznacza to, że zdarzenie chrome.runtime.onInstalled zostanie uruchomione z przyczyną "update". Dotyczy to też ponownego ładowania rozszerzenia za pomocą metody chrome.runtime.reload().

Przykłady zastosowań

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 zasobów rozszerzenia na stronie internetowej. Różnice między tymi 2 różnicami polegają na tym, że zasoby rozszerzenia muszą być widoczne jako zasoby dostępne przez internet, a za wstrzykiwanie zasobów rozszerzenia odpowiadają zwykle skrypty treści.

W tym przykładzie rozszerzenie doda logo.png do strony, na którą wstrzykiwany jest skrypt treści, i użyje runtime.getURL(), aby utworzyć pełny adres URL. Najpierw jednak zasób musi zostać zadeklarowany w pliku manifestu jako zasób dostępny przez internet.

manifest.json:

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

content.js:

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

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

Często skrypty treści rozszerzeń wymagają danych zarządzanych przez inną część rozszerzenia, np. skrypt service worker. Podobnie jak dwa okna przeglądarki otwierające tę samą stronę internetową, te dwa konteksty nie mają bezpośredniego dostępu do swoich wartości. Zamiast tego rozszerzenie może korzystać z przekazywania wiadomości, aby koordynować działania w różnych kontekstach.

W tym przykładzie skrypt treści potrzebuje danych z skryptu service worker rozszerzenia, aby zainicjować interfejs użytkownika. Aby je pobrać, przekazuje zdefiniowaną przez dewelopera komunikat get-user-data do skryptu service worker i wysył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);
});

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 na temat odinstalowywania

Wiele rozszerzeń korzysta z ankiet po odinstalowaniu, aby dowiedzieć się, jak rozszerzenie może służyć użytkownikom i poprawić wskaźnik utrzymania użytkowników. 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 interfejsu Runtime API znajdziesz w prezentacji o zasobach dostępnych w przeglądarce (Manifest V3).

Typy

ContextFilter

Chrome 114 i nowsze wersje

Filtr dopasowania 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. Dlatego filtr „{}” będzie pasować do wszystkich dostępnych kontekstów.

Właściwości

contextIds

string[] opcjonalny
contextTypes

ContextType[] opcjonalny
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 i nowsze wersje

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 114 i nowsze wersje

Kontekstowe treści rozszerzenia hostingu.

Właściwości

contextId

string,

Unikalny identyfikator na potrzeby tego kontekstu
contextType

ContextType

Typ kontekstu, któremu odpowiada.
documentId

ciąg znaków opcjonalny

Identyfikator UUID dokumentu powiązanego z tym kontekstem lub niezdefiniowany, jeśli ten kontekst jest hostowany poza dokumentem.
documentOrigin

ciąg znaków opcjonalny

Pochodzenie 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 niezdefiniowany, jeśli kontekst nie jest hostowany w dokumencie.
frameId

Liczba

Identyfikator ramki na potrzeby tego kontekstu lub -1, jeśli kontekst nie jest hostowany w ramce.
incognito

boolean

Wskazuje, czy kontekst jest powiązany z profilem incognito.
tabId

Liczba

Identyfikator karty na potrzeby 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 i nowsze wersje

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

ciąg znaków opcjonalny

Chrome 106 i nowsze wersje

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

Liczba opcjonalnie

Ramka, która otworzyła połączenie. 0 – ramki najwyższego poziomu, dodatnie w przypadku ramek podrzędnych. To ustawienie zostanie ustawione 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 i nowszy

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

ciąg znaków opcjonalny

Chrome 80 i nowsze wersje

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

Tab opcjonalnie

tabs.Tab, który (jeśli wystąpił) uruchomił połączenie. Ta właściwość będzie widoczna tylko wtedy, gdy połączenie zostanie otwarte na karcie (w tym ze skryptami treści) oraz tylko wtedy, gdy odbiornik jest rozszerzeniem, a nie aplikacją.
tlsChannelId

ciąg znaków opcjonalny

Identyfikator kanału TLS strony lub ramki, które otworzyły połączenie, jeśli jest wymagane przez rozszerzenie i jeśli jest dostępne.
URL

ciąg znaków opcjonalny

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

OnInstalledReason

Chrome 44 i nowsze wersje

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ę modułu udostępnionego.

OnRestartRequiredReason

Chrome 44 i nowsze wersje

Powód wysyłania zdarzenia. Parametr „app_update” jest używany, gdy wymagane jest ponowne uruchomienie, ponieważ aplikacja jest aktualizowana do nowszej wersji. Parametr „os_update” jest używany, gdy wymagane jest ponowne uruchomienie, ponieważ przeglądarka lub system operacyjny zostały zaktualizowane do nowszej wersji. Wartość „okresowy” jest używana, gdy system działa przez dłuższy czas niż dozwolony w zasadach 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 i nowsze wersje

Architektura procesora komputera.

Typ wyliczeniowy

"arm"
Określa architekturę procesu przetwarzania jako gałąź.

"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

łuk

PlatformArch

Architektura procesora komputera.
nacl_arch

PlatformNaclArch

Natywna architektura klienta. Na niektórych platformach może się różnić od tego, który dostępny jest w archiwum.
os

PlatformOs

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

PlatformNaclArch

Chrome 44 i nowsze wersje

Natywna architektura klienta. Na niektórych platformach może się różnić od tego, który dostępny jest w archiwum.

Typ wyliczeniowy

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

"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 i nowsze wersje

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

Typ wyliczeniowy

"mac"
Określa system operacyjny MacOS.

"win"
Określa system operacyjny Windows.

"android"
Określa system operacyjny Android.

"cros"
Określa system operacyjny Chrome.

"linux"
Określa system operacyjny Linux.

"openbsd"
Określa system operacyjny OpenBSD.

"fuchsia"
Określa system operacyjny Fuchsia.

Port

Obiekt umożliwiający dwukierunkową komunikację z innymi stronami. Więcej informacji znajdziesz w sekcji Połączenia długotrwałe.

Właściwości

nazwa

string,

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

Zdarzenie<functionvoidvoid>

Uruchamiane, gdy port jest odłączony od innych końców. Jeśli port został rozłączony w wyniku błędu, może być ustawiony parametr runtime.lastError. Jeśli port jest zamknięty za pomocą funkcji Rozłącz, to zdarzenie jest wywoływane tylko po drugiej stronie. To zdarzenie jest uruchamiane co najwyżej raz (patrz też Czas eksploatacji 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<functionvoidvoid>

To zdarzenie jest wywoływane, gdy drugi koniec portu wywoła metodę postMessage.

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

MessageSender – opcjonalny

Ta właściwość będzie dostępna tylko w przypadku portów przekazanych do detektorów onConnect, onConnectExternal i onConnectNative.
rozłącz

void

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

Funkcja disconnect wygląda tak:
```
()=> {...}
```
postMessage

void

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

Funkcja postMessage wygląda tak:
```
(message: any)=> {...}
```
- wiadomość
  
  Dowolne
  
  Chrome 52 i nowsze wersje
  
  Wiadomość do wysłania. Ten obiekt powinien obsługiwać format JSON.

RequestUpdateCheckStatus

Chrome 44 i nowsze wersje

Wynik sprawdzania dostępności aktualizacji.

Typ wyliczeniowy

"throttled"
Określa, że kontrola stanu została ograniczona. Może się to zdarzyć po wielokrotnym sprawdzeniu konta w krótkim czasie.

"no_update"
Wskazuje, ż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

string,

lastError

Wyświetlany z komunikatem o błędzie, jeśli wywołanie funkcji interfejsu API nie powiodło się. W przeciwnym razie jest niezdefiniowane. Ta wartość jest definiowana tylko w zakresie wywołania zwrotnego tej funkcji. Jeśli wystąpi błąd, ale usługa runtime.lastError nie zostanie uzyskana w wywołaniu zwrotnym, w konsoli zostanie zarejestrowany komunikat z listą funkcji interfejsu API, która spowodowała błąd. Funkcje 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 wystąpienia błędu.

Metody

connect()

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

Próba połączenia detektorów w rozszerzeniu (np. na stronie w tle) lub w innych rozszerzeniach/aplikacjach. Przydaje się to w przypadku skryptów treści, które łączą się z procesami rozszerzeń, komunikacją między aplikacjami i rozszerzeniami oraz wiadomościami internetowymi. Pamiętaj, że nie spowoduje to połączenia z żadnymi słuchaczami w skrypcie treści. Rozszerzenia mogą łączyć się ze skryptami treści umieszczonymi na kartach przez tabs.connect.

Parametry

extensionId

ciąg znaków opcjonalny

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

obiekt opcjonalnie
- includeTlsChannelId
  
  wartość logiczna opcjonalna
  
  Określa, czy identyfikator kanału TLS jest przekazywany do onConnectExternal w przypadku procesów, które nasłuchują zdarzenia połączenia.
- nazwa
  
  ciąg znaków opcjonalny
  
  Będzie przekazywany do onConnect na potrzeby procesów, które nasłuchują zdarzenia połączenia.

Zwroty

Port

Port, przez który można wysyłać i odbierać wiadomości. Zdarzenie onDisconnect na porcie jest uruchamiane, gdy rozszerzenie nie istnieje.

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

Parametry

aplikacja

string,

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

Zwroty

Port

Port, przez który wiadomości mogą być wysyłane i odbierane za pomocą aplikacji

getBackgroundPage()

Obietnica Tylko na pierwszym planie

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

Pobiera obiekt JavaScript „window” dla strony działającej w tle w bieżącym rozszerzeniu lub aplikacji. Jeśli strona w tle jest stroną zdarzenia, system zadba o jej wczytanie przed wywołaniem zwrotnym. Jeśli nie ma strony w tle, zostaje wyświetlony komunikat o błędzie.

Parametry

wywołanie zwrotne

funkcja opcjonalnie

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

Zwroty

Obietnica<okno|undefined>

Chrome 99 i nowsze

Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getContexts()

Obietnica Chrome w wersji 116 lub nowszej MV3 lub nowsza

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

Pobiera informacje o aktywnych kontekstach powiązanych z tym rozszerzeniem

Parametry

filter

ContextFilter

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

funkcja opcjonalnie

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

Zwroty

Promise<ExtensionContext[]>

Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getManifest()

chrome.runtime.getManifest()

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

Zwroty

obiekt

Szczegóły pliku manifestu.

getPackageDirectoryEntry()

Obietnica Tylko na pierwszym planie

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

Zwraca wartość DirectoryEntry z katalogu pakietu.

Parametry

wywołanie zwrotne

funkcja opcjonalnie

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

Zwroty

Promise<DirectoryEntry>

Chrome 122 i nowsze wersje

Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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 opcjonalnie

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

Zwroty

Promise<PlatformInfo>

Chrome 99 i nowsze

Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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/rozszerzenia na pełny adres URL.

Parametry

ścieżka

string,

Ścieżka do zasobu w aplikacji lub rozszerzeniu wyrażona w odniesieniu do jej katalogu instalacyjnego.

Zwroty

string,

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

Jeśli rozszerzenie nie zadeklaruje strony opcji lub Chrome nie utworzy jej z jakiegoś innego powodu, wywołanie zwrotne ustawi wartość lastError.

Parametry

wywołanie zwrotne

funkcja opcjonalnie

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

Zwroty

Promise<void>

Chrome 99 i nowsze

Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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,
)

Prośbę o natychmiastowe sprawdzenie aktualizacji tej aplikacji lub tego rozszerzenia prosi o sprawdzenie jej dostępności.

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

Tę metodę można stosować tylko w bardzo nielicznych okolicznościach, np. gdy rozszerzenie komunikuje się z usługą backendu, a usługa backendu ustaliła, że wersja rozszerzenia klienta jest bardzo przestarzała i chcesz poprosić użytkownika o aktualizację. Większość innych zastosowań metody requestUpdateCheck, na przykład wywoływanie jej bezwarunkowo na podstawie powtarzającego się licznika czasu, prawdopodobnie służy tylko do zużywania zasobów klienta, sieci i serwera.

Uwaga: w przypadku wywołania zwrotnego zamiast zwrócenia obiektu ta funkcja zwróci 2 właściwości jako osobne argumenty przekazywane do wywołania zwrotnego.

Parametry

wywołanie zwrotne

funkcja opcjonalnie

Parametr callback wygląda tak:
```
(result: object)=>void
```
- wynik
  
  obiekt
  
  Chrome 109 i nowsze wersje
  
  Obiekt RequestUpdateCheckResult, który zawiera stan sprawdzania aktualizacji i wszelkie 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, to jest widoczna wersja dostępnej aktualizacji.

Zwroty

Promise<object>

Chrome 109 i nowsze wersje

Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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 nic nie szkodzi.

restartAfterDelay()

Obietnica Chrome w wersji 53 lub nowszej

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

Uruchom ponownie urządzenie z ChromeOS, gdy aplikacja działa w trybie kiosku po upływie określonych sekund. Ponowne uruchomienie będzie się opóźniać przed upływem limitu czasu. Jeśli zostanie wywołany z wartością -1, ponowne uruchomienie zostanie anulowane. W trybie innym niż kiosk nie działa. Pierwsze rozszerzenie może wywoływać ten interfejs API tylko wielokrotnie przez pierwsze rozszerzenie.

Parametry

s

Liczba

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

funkcja opcjonalnie

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

Zwroty

Promise<void>

Chrome 99 i nowsze

Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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 rozszerzeniu lub innym rozszerzeniu/aplikacji. Podobnie jak runtime.connect, wysyła tylko jedną wiadomość z opcjonalną odpowiedzią. Jeśli wysyłasz rozszerzenie do rozszerzenia, zdarzenie runtime.onMessage będzie wywoływane w każdej klatce (z wyjątkiem ramki nadawcy) lub runtime.onMessageExternal, jeśli jest inne. Pamiętaj, że rozszerzenia nie mogą wysyłać wiadomości do skryptów treści za pomocą tej metody. Aby wysyłać wiadomości do skryptów treści, użyj tabs.sendMessage.

Parametry

extensionId

ciąg znaków opcjonalny

Identyfikator rozszerzenia, do którego ma zostać wysłana wiadomość. Jeśli go pominiesz, wiadomość zostanie wysłana do Twojego rozszerzenia lub aplikacji. Wymagane w przypadku wysyłania wiadomości ze strony internetowej na potrzeby wiadomości internetowych.
wiadomość

Dowolne

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

obiekt opcjonalnie
- includeTlsChannelId
  
  wartość logiczna opcjonalna
  
  Określa, czy identyfikator kanału TLS jest przekazywany do onMessageExternal w przypadku procesów, które nasłuchują zdarzenia połączenia.
wywołanie zwrotne

funkcja opcjonalnie

Chrome 99 i nowsze

Parametr callback wygląda tak:
```
(response: any)=>void
```
- odpowiedź
  
  Dowolne
  
  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 wykonane bez argumentów, a dla funkcji runtime.lastError zostanie ustawiony komunikat o błędzie.

Zwroty

Obietnica<jakikolwiek>

Chrome 99 i nowsze

Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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

string,

Nazwa hosta natywnego przesyłania komunikatów.
wiadomość

obiekt

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

funkcja opcjonalnie

Chrome 99 i nowsze

Parametr callback wygląda tak:
```
(response: any)=>void
```
- odpowiedź
  
  Dowolne
  
  Wiadomość z odpowiedzią wysłana przez hosta natywnego przesyłania komunikatów. Jeśli podczas łączenia z hostem natywnego przesyłania komunikatów wystąpi błąd, wywołanie zwrotne zostanie wykonane bez argumentów, a runtime.lastError otrzyma komunikat o błędzie.

Zwroty

Obietnica<jakikolwiek>

Chrome 99 i nowsze

Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

setUninstallURL()

Obietnica

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

Określa adres URL, który ma zostać otwarty po odinstalowaniu. Można ich używać do czyszczenia danych po stronie serwera, prowadzenia analiz i wdrażania ankiet. Maksymalnie 1023 znaki.

Parametry

URL

string,

Adres URL, który zostanie 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.
wywołanie zwrotne

funkcja opcjonalnie

Chrome 45 i nowsze wersje

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

Zwroty

Promise<void>

Chrome 99 i nowsze

Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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, 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,
)

Uruchamiane, gdy połączenie jest tworzone przez proces rozszerzenia lub skrypt treści (przez 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 zostanie nawiązane z innego rozszerzenia (przez runtime.connect) lub z witryny, którą można połączyć z zewnątrz.

Parametry

wywołanie zwrotne

funkcja

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

onConnectNative

Chrome 76 i nowsze wersje

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

Uruchamiane, gdy połączenie jest nawiązywane z aplikacji natywnej. To wydarzenie wymaga uprawnienia "nativeMessaging". Jest obsługiwane 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,
)

Uruchamiany przy pierwszym zainstalowaniu rozszerzenia, po jego zaktualizowaniu do nowej wersji i aktualizowaniu 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 rozszerzenia modułu udostępnionego, które zostało zaktualizowane. Występuje tylko wtedy, gdy atrybut „reason” ma wartość „shared_module_update”.
  - previousVersion
    
    ciąg znaków opcjonalny
    
    Wskazuje poprzednią wersję rozszerzenia, która właśnie została zaktualizowana. Ta wartość występuje tylko wtedy, gdy „Przyczyna” 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ść
  
  Dowolne
- nadawca
  
  MessageSender
- sendResponse
  
  funkcja
  
  Parametr sendResponse wygląda tak:
```
()=>void
```
- returns
  boolean|undefined

onMessageExternal

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

Uruchamiane, gdy wiadomość zostanie wysłana z innego rozszerzenia (przez runtime.sendMessage). Nie można go użyć w skrypcie treści.

Parametry

wywołanie zwrotne

funkcja

Parametr callback wygląda tak:
```
(message: any,sender: MessageSender,sendResponse: function)=>boolean|undefined
```
- wiadomość
  
  Dowolne
- nadawca
  
  MessageSender
- sendResponse
  
  funkcja
  
  Parametr sendResponse wygląda tak:
```
()=>void
```
- returns
  boolean|undefined

onRestartRequired

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

Uruchamiane, gdy aplikacja lub urządzenie, na którym działa, wymaga ponownego uruchomienia. Aplikacja powinna zamknąć wszystkie okna w najkrótszym dogodnym czasie, aby umożliwić ponowne uruchomienie. Jeśli aplikacja nie zadziała, po upływie 24 godzin zostanie wymuszone jej ponowne uruchomienie. 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 z zainstalowanym tym rozszerzeniem. To zdarzenie nie jest wywoływane po uruchomieniu profilu incognito, nawet jeśli rozszerzenie działa w trybie incognito.

Parametry

wywołanie zwrotne

funkcja

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

onSuspend

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

Wysyłana na stronę wydarzenia tuż przed jego wyładowaniem. Dzięki temu rozszerzenie będzie mogło je wyczyścić. Uwaga: ponieważ strona jest wyładowywana, nie ma gwarancji, że wszystkie operacje asynchroniczne rozpoczęte podczas obsługi tego zdarzenia zostaną ukończone. Jeśli na stronie zdarzenia nastąpi więcej działań, zanim zostanie ona usunięta z pamięci, wysłane zostanie zdarzenie onsuspendedCanceled, a 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łane po wystąpieniu zawieszenia, aby wskazać, że aplikacja nie zostanie jednak wyładowana 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 nic nie zrobisz, aktualizacja zostanie zainstalowana przy następnym wczytaniu strony w tle. Jeśli chcesz, by została zainstalowana szybciej, możesz wprost wywołać chrome.runtime.reload(). Jeśli rozszerzenie używa stałej strony w tle, strona w tle oczywiście nigdy nie jest wczytywana. Jeśli więc w odpowiedzi na to zdarzenie ręcznie wywołasz chrome.runtime.reload(), 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, działa tak, jakby w odpowiedzi na to zdarzenie wywoływano funkcję chrome.runtime.reload().

Parametry

wywołanie zwrotne

funkcja

Parametr callback wygląda tak:
```
(details: object)=>void
```
- szczegóły
  
  obiekt
  - wersja
    
    string,
    
    Numer wersji dostępnej aktualizacji.

onUserScriptConnect

Chrome 115 i nowsze MV3 i nowsze

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

Uruchamiane, gdy nawiążesz połączenie za pomocą skryptu użytkownika z tego rozszerzenia.

Parametry

wywołanie zwrotne

funkcja

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

onUserScriptMessage

Chrome 115 i nowsze MV3 i nowsze

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

Uruchamiane, gdy wiadomość zostanie wysł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ść
  
  Dowolne
- nadawca
  
  MessageSender
- sendResponse
  
  funkcja
  
  Parametr sendResponse wygląda tak:
```
()=>void
```
- returns
  boolean|undefined