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
ionMessageExternal
. Dodatkowo rozszerzenie może przekazywać wiadomości do aplikacji natywnych na urządzeniu użytkownika za pomocą standardówconnectNative()
isendNativeMessage()
.
- 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()
igetPlatformInfo()
. - 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()
isetUninstallURL()
. - 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()
irestartAfterDelay()
`.
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()
.
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 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
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
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
Kontekstowe treści rozszerzenia hostingu.
Właściwości
-
contextId
string,
Unikalny identyfikator na potrzeby tego kontekstu
-
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 wersjeIdentyfikator UUID dokumentu, który uruchomił połączenie.
-
documentLifecycle
ciąg znaków opcjonalny
Chrome 106 i nowsze wersjeCykl ż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 nowszyNazwa 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
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
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
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
Architektura procesora komputera.
-
nacl_arch
Natywna architektura klienta. Na niektórych platformach może się różnić od tego, który dostępny jest w archiwum.
-
os
System operacyjny, w którym działa Chrome.
PlatformNaclArch
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
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 przez odłączenie, 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) => {...}
-
onMessage
Zdarzenie<functionvoidvoid>
Zdarzenie to jest wywoływane przez wywołanie metody postMessage przez drugi koniec portu.
Funkcja
onMessage.addListener
wygląda tak:(callback: function) => {...}
-
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 wersjeWiadomość do wysłania. Ten obiekt powinien obsługiwać format JSON.
-
RequestUpdateCheckStatus
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, 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, przez który wiadomości mogą być wysyłane i odbierane za pomocą aplikacji
getBackgroundPage()
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
-
Promise<Window | undefined>
Chrome 99 i nowszeObietnice 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()
chrome.runtime.getContexts(
filter: ContextFilter,
callback?: function,
)
Pobiera informacje o aktywnych kontekstach powiązanych z tym rozszerzeniem
Parametry
-
filtr
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
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()
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 wersjeObietnice 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()
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
-
Zwroty
-
Promise<PlatformInfo>
Chrome 99 i nowszeObietnice 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()
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 nowszeObietnice 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()
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 wersjeObiekt RequestUpdateCheckResult, który zawiera stan sprawdzania aktualizacji i wszelkie szczegóły wyniku, jeśli jest dostępna aktualizacja
-
status
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 wersjeObietnice 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()
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 nowszeObietnice 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()
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 nowszeParametr
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 nowszeObietnice 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()
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 nowszeParametr
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 nowszeObietnice 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()
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 wersjeParametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Chrome 99 i nowszeObietnice 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
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
).
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.
onConnectNative
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.
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
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
-
sendResponse
funkcja
Parametr
sendResponse
wygląda tak:() => void
-
returns
wartość logiczna | nieokreślona
-
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
-
sendResponse
funkcja
Parametr
sendResponse
wygląda tak:() => void
-
returns
wartość logiczna | nieokreślona
-
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
-
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.runtime.onUserScriptConnect.addListener(
callback: function,
)
Uruchamiane, gdy nawiążesz połączenie za pomocą skryptu użytkownika z tego rozszerzenia.
onUserScriptMessage
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
-
sendResponse
funkcja
Parametr
sendResponse
wygląda tak:() => void
-
returns
wartość logiczna | nieokreślona
-