Przejście na przestrzeń nazw przeglądarki

Od Chrome 148 wszystkie interfejsy API rozszerzeń do Chrome są dostępne w przestrzeni nazw browser oprócz dotychczasowej przestrzeni nazw chrome. Na przykład browser.tabs.create({}) i chrome.tabs.create({}) są równoważne.

Przestrzeń nazw jest dostępna wszędzie tam, gdzie można wywoływać interfejsy API rozszerzeń, w tym w skryptach treści, procesach service worker i dokumentach poza ekranem. Wskazuje te same obiekty interfejsu API co chrome, więc chrome.tabs === browser.tabs.

Przestrzeń nazw browser jest wynikiem prac grupy społecznościowej WebExtensions (WECG), grupy społecznościowej W3C, w której dostawcy przeglądarek współpracują nad wspólnymi standardami rozszerzeń. Przestrzeń nazw chrome nie zostanie usunięta. Obie przestrzenie nazw będą nadal działać.

Rozszerzenia ze stroną Narzędzi deweloperskich nie mogą używać przestrzeni nazw browser. Jeśli rozszerzenie deklaruje devtools_page, przestrzeń nazw browser jest wyłączona dla całego rozszerzenia – nie tylko dla strony Narzędzi deweloperskich, ale także dla skryptu service worker, skryptów treści, wyskakującego okienka, strony opcji i każdego innego kontekstu, w którym działają interfejsy API rozszerzenia. W tych rozszerzeniach nadal używaj symbolu chrome.*. Więcej informacji znajdziesz w artykule Przestrzeń nazw przeglądarki i rozszerzenia Narzędzi deweloperskich.

Decydowanie o przyjęciu przestrzeni nazw przeglądarki

Jeśli używasz webextension-polyfill, przed wprowadzeniem jakichkolwiek zmian przejdź do sekcji Uwaga dla użytkowników kodu polyfill – odpowiedź jest inna.

Jeśli tworzysz nowe rozszerzenie, ustaw wartość minimum_chrome_version na "148" i używaj browser bezwarunkowo. Nie musisz czytać dalej. Pozostała część tej sekcji jest przeznaczona dla dotychczasowych rozszerzeń, które decydują, jak je wdrożyć.

Sprawdzanie, z jakich wersji Chrome korzystają użytkownicy

Jeśli masz już rozszerzenie, przed przejściem na nową wersję sprawdź, z których wersji Chrome korzystają Twoi użytkownicy. Chrome aktualizuje się automatycznie, ale niektórzy użytkownicy wyłączają aktualizacje, a inni korzystają ze starszych urządzeń, na których nie można uruchomić najnowszej wersji. Potwierdź to na podstawie własnych danych analitycznych. Jeśli nie masz jeszcze skonfigurowanej analityki, zapoznaj się z artykułem Monitorowanie skuteczności rozszerzenia za pomocą Google Analytics 4, aby zacząć.

Następnie wybierz ścieżkę:

• Jeśli użytkownicy korzystają z Chrome w wersji 148 lub nowszej, zastosuj bezwarunkowo.
• Jeśli znaczna część użytkowników korzysta z Chrome 147 lub starszej wersji, użyj ochrony w czasie działania.

Przyjęcie bezwarunkowe

Ustaw w pliku manifestu wartość minimum_chrome_version i używaj browser bezwarunkowo – nie jest potrzebne żadne zabezpieczenie w czasie działania:

{
  "minimum_chrome_version": "148"
}

Ustawienie minimum_chrome_version zatrzymuje wszystkie aktualizacje dla użytkowników starszych wersji Chrome. Chrome Web Store nie będzie dostarczać użytkownikom żadnej przyszłej wersji rozszerzenia poniżej określonej przez Ciebie wersji. Pozostaną oni przy zainstalowanej wersji i nie będą otrzymywać poprawek błędów, aktualizacji zabezpieczeń ani nowych funkcji, chyba że zaktualizują Chrome. Często jest to właściwe rozwiązanie, ale traktuj je jako świadomą decyzję, a nie rutynowe ustawienie zgodności.

W przypadku zwiększania minimum_chrome_version używaj wdrażania etapowego. Jeśli coś pójdzie nie tak, możesz wycofać zmiany w rozszerzeniu w Chrome Web Store.

Korzystanie z ochrony środowiska wykonawczego

Dodaj ten fragment na początku kodu uruchamiania rozszerzenia, zanim w innych miejscach odwołasz się do browser:

if (!globalThis.browser) {
  globalThis.browser = chrome;
  // Consider firing an analytics event here to measure how often
  // your users hit this fallback path.
}

W starszych wersjach browser staje się aliasem chrome, więc reszta kodu może bezwarunkowo używać browser.

Uwaga dla użytkowników kodu polyfill

Jeśli rozszerzenie korzysta z webextension-polyfill, w Chrome w wersji 148 i nowszych nie będzie działać. Kod polyfill pominął opakowywanie, gdy zdefiniowano już browser, zakładając, że przeglądarka hosta udostępniła już interfejs API.

Wcześniejsza próba wprowadzenia przestrzeni nazw w Chrome 136 została wycofana z tego powodu: po browser nowo zdefiniowanym polyfill przestał opakowywać, ale browser.runtime.onMessage w Chrome nie obsługiwał jeszcze słuchaczy zwracających obietnice, które polyfill zapewniał. Rozszerzenia korzystające z tego wzorca przestały działać. Chrome 148 udostępnia przestrzeń nazw i natywne detektory zwracające obietniceonMessage, aby uniknąć tej luki.

Gdy Twoi użytkownicy zaczną korzystać z Chrome 148, możesz usunąć zależność od polyfill.

Inne funkcje

Odpowiedzi asynchroniczne w runtime.sendMessage

W Chrome 148 runtime.onMessage mogą zwracać Promise bezpośrednio, aby wysyłać odpowiedzi asynchroniczne. Działa to niezależnie od tego, czy wywołasz ją za pomocą chrome.* czy browser.*.

Wcześniej jedynym sposobem na asynchroniczną odpowiedź było zwrócenie literału true z funkcji nasłuchującej i późniejsze wywołanie funkcji sendResponse:

// Old pattern - requires returning true to keep the channel open
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  fetch('https://example.com')
    .then(response => sendResponse({ statusCode: response.status }));

  return true; // keeps the message channel open for the async response
});

Możesz teraz bezpośrednio zwrócić wartość Promise (lub użyć funkcji async):

// New pattern - return a promise or use async/await
browser.runtime.onMessage.addListener(async (message, sender) => {
  const response = await fetch('https://example.com');
  return { statusCode: response.status };
});

Wzorzec return true nadal działa, więc nie trzeba zmieniać istniejącego kodu.

Podobnie jak w przypadku samej przestrzeni nazw browser,runtime.onMessage odpowiedzi Promise nie są dostępne w rozszerzeniach, które deklarują devtools_page.