chrome.offscreen

Opis

Do tworzenia dokumentów poza ekranem i zarządzania nimi służy interfejs offscreen API.

Uprawnienia

offscreen

Aby korzystać z interfejsu Offscreen API, zadeklaruj uprawnienie "offscreen" w pliku manifestu rozszerzenia. Na przykład:

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

Dostępność

Chrome 109 lub nowszy MV3 lub nowszy

Pojęcia i zastosowanie

Service workerzy nie mają dostępu do DOM, a wiele witryn ma zasady bezpieczeństwa treści, które ograniczają funkcjonalność skryptów treści. Interfejs Offscreen API umożliwia rozszerzeniu korzystanie z interfejsów DOM API w ukrytym dokumencie bez przerywania pracy użytkownika przez otwieranie nowych okien lub kart. Interfejs runtime API jest jedynym interfejsem API rozszerzeń obsługiwanym przez dokumenty poza ekranem.

Strony wczytywane jako dokumenty poza ekranem są obsługiwane inaczej niż inne typy stron rozszerzeń. Uprawnienia rozszerzenia są przenoszone do dokumentów poza ekranem, ale z ograniczeniami dostępu do interfejsu API rozszerzenia. Na przykład interfejs chrome.runtime API jest jedynym interfejsem API rozszerzeń obsługiwanym przez dokumenty poza ekranem, więc przesyłanie wiadomości musi być obsługiwane za pomocą elementów tego interfejsu API.

Dokumenty poza ekranem różnią się od zwykłych stron w tych aspektach:

  • Adres URL dokumentu poza ekranem musi być statycznym plikiem HTML dołączonym do rozszerzenia.
  • Nie można ustawić ostrości na dokumentach poza ekranem.
  • Dokument poza ekranem to instancja window, ale wartość jego właściwości opener jest zawsze null.
  • Pakiet rozszerzenia może zawierać wiele dokumentów poza ekranem, ale zainstalowane rozszerzenie może mieć otwarty tylko jeden dokument naraz. Jeśli rozszerzenie działa w trybie podzielonym z aktywnym profilem incognito, profile normalny i incognito mogą mieć po jednym dokumencie poza ekranem.

Użyj chrome.offscreen.createDocument() i chrome.offscreen.closeDocument(), aby utworzyć i zamknąć dokument poza ekranem. W przypadku createDocument() wymagane są url dokumentu, powód i uzasadnienie:

chrome.offscreen.createDocument({   url: 'off_screen.html',   reasons: ['CLIPBOARD'],   justification: 'reason for needing the document', });

Przyczyny

Listę prawidłowych powodów znajdziesz w sekcji Powody. Przyczyny są ustawiane podczas tworzenia dokumentu, aby określić jego okres ważności. AUDIO_PLAYBACK przyczyna powoduje zamknięcie dokumentu po 30 sekundach bez odtwarzania dźwięku. W przypadku pozostałych powodów nie są ustawiane limity okresowe.

Przykłady

Utrzymywanie cyklu życia dokumentu poza ekranem

Poniższy przykład pokazuje, jak sprawdzić, czy dokument poza ekranem istnieje. Funkcja setupOffscreenDocument() wywołuje funkcję runtime.getContexts(), aby znaleźć istniejący dokument poza ekranem, lub tworzy dokument, jeśli jeszcze nie istnieje.

let creating; // A global promise to avoid concurrency issues async function setupOffscreenDocument(path) {   // Check all windows controlled by the service worker to see if one   // of them is the offscreen document with the given path   const offscreenUrl = chrome.runtime.getURL(path);   const existingContexts = await chrome.runtime.getContexts({     contextTypes: ['OFFSCREEN_DOCUMENT'],     documentUrls: [offscreenUrl]   });    if (existingContexts.length > 0) {     return;   }    // create offscreen document   if (creating) {     await creating;   } else {     creating = chrome.offscreen.createDocument({       url: path,       reasons: ['CLIPBOARD'],       justification: 'reason for needing the document',     });     await creating;     creating = null;   } }

Zanim wyślesz wiadomość do dokumentu poza ekranem, wywołaj funkcję setupOffscreenDocument(), aby upewnić się, że dokument istnieje, jak pokazano w tym przykładzie.

chrome.action.onClicked.addListener(async () => {   await setupOffscreenDocument('off_screen.html');    // Send message to offscreen document   chrome.runtime.sendMessage({     type: '...',     target: 'offscreen',     data: '...'   }); });

Pełne przykłady znajdziesz w wersjach demonstracyjnych offscreen-clipboard i offscreen-dom w GitHubie.

Przed wersją Chrome 116: sprawdzanie, czy otwarty jest dokument poza ekranem

runtime.getContexts() zostało dodane w Chrome 116. W starszych wersjach Chrome użyj clients.matchAll(), aby sprawdzić, czy istnieje już dokument poza ekranem:

async function hasOffscreenDocument() {   if ('getContexts' in chrome.runtime) {     const contexts = await chrome.runtime.getContexts({       contextTypes: ['OFFSCREEN_DOCUMENT'],       documentUrls: [OFFSCREEN_DOCUMENT_PATH]     });     return Boolean(contexts.length);   } else {     const matchedClients = await clients.matchAll();     return matchedClients.some(client => {       return client.url.includes(chrome.runtime.id);     });   } }

Typy

CreateParameters

Właściwości

  • uzasadnienie,

    ciąg znaków

    Ciąg znaków podany przez dewelopera, który bardziej szczegółowo wyjaśnia potrzebę kontekstu w tle. Klient użytkownika _może_ użyć tej wartości do wyświetlenia jej użytkownikowi.

  • przyczyn(y)

    Reason[]

    Przyczyny, dla których rozszerzenie tworzy dokument poza ekranem.

  • URL

    ciąg znaków

    (Względny) adres URL do załadowania w dokumencie.

Reason

Typ wyliczeniowy

„TESTING”
Powód używany tylko do celów testowych.

„AUDIO_PLAYBACK”
Określa, że za odtwarzanie dźwięku odpowiada dokument poza ekranem.

„IFRAME_SCRIPTING”
Określa, że dokument poza ekranem musi osadzić element iframe i wykonać w nim skrypt, aby zmodyfikować jego zawartość.

„DOM_SCRAPING”
Określa, że dokument poza ekranem musi umieścić element iframe i przeanalizować jego DOM, aby wyodrębnić informacje.

„BLOBS”
Określa, że dokument poza ekranem musi wchodzić w interakcję z obiektami Blob (w tym URL.createObjectURL()).

„DOM_PARSER”
Określa, że dokument poza ekranem musi korzystać z interfejsu DOMParser API.

„USER_MEDIA”
Określa, że dokument poza ekranem musi wchodzić w interakcję ze strumieniami multimediów z multimediów użytkownika (np. getUserMedia()).

„DISPLAY_MEDIA”
Określa, że dokument poza ekranem musi wchodzić w interakcję ze strumieniami multimediów z mediów displayowych (np. getDisplayMedia()).

„WEB_RTC”
Określa, że dokument poza ekranem musi korzystać z interfejsów WebRTC API.

„CLIPBOARD”
Określa, że dokument poza ekranem musi wchodzić w interakcję z interfejsem Clipboard API.

"LOCAL_STORAGE"
Określa, że dokument poza ekranem potrzebuje dostępu do localStorage.

„WORKERS”
Określa, że dokument poza ekranem musi tworzyć procesy robocze.

„BATTERY_STATUS”
Określa, że dokument poza ekranem musi używać interfejsu navigator.getBattery.

„MATCH_MEDIA”
Określa, że dokument poza ekranem musi używać funkcji window.matchMedia.

„GEOLOCATION”
Określa, że dokument poza ekranem musi używać interfejsu navigator.geolocation.

Metody

closeDocument()

chrome.offscreen.closeDocument(): Promise<void>

Zamyka aktualnie otwarty dokument poza ekranem dla rozszerzenia.

Zwroty

  • Promise<void>

createDocument()

chrome.offscreen.createDocument(
  parameters: CreateParameters,
): Promise<void>

Tworzy nowy dokument poza ekranem dla rozszerzenia.

Parametry

  • parametry

    CreateParameters

    Parametry opisujące dokument poza ekranem, który ma zostać utworzony.

Zwroty

  • Promise<void>