chrome.offscreen

Opis

Uprawnienia

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

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

Dostępność

Pojęcia i użycie

Service worker 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 działania użytkownika przez otwieranie nowych okien lub kart. Interfejs runtime API to jedyny interfejs API rozszerzeń obsługiwany przez dokumenty poza ekranem.

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

Oto inne sposoby, w jakie dokumenty poza ekranem różnią się od zwykłych stron:

• Adres URL dokumentu poza ekranem musi być statycznym plikiem HTML dołączonym do rozszerzenia.
• Dokumentów poza ekranem nie można ustawić jako aktywne.
• Dokument poza ekranem jest instancją 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 1 dokument naraz. Jeśli rozszerzenie działa w trybie podzielonym z aktywnym profilem incognito, profil zwykły i incognito mogą mieć po 1 dokumencie poza ekranem.

Aby utworzyć i zamknąć dokument poza ekranem, użyj funkcji chrome.offscreen.createDocument() i chrome.offscreen.closeDocument(). createDocument() wymaga podania adresu url dokumentu, przyczyny i uzasadnienia:

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

Przyczyny

Listę prawidłowych przyczyn znajdziesz w sekcji Przyczyny. Przyczyny są ustawiane podczas tworzenia dokumentu, aby określić jego okres istnienia. Przyczyna AUDIO_PLAYBACK powoduje zamknięcie dokumentu po 30 sekundach bez odtwarzania dźwięku. Wszystkie inne przyczyny nie ustawiają limitów czasu.

Przykłady

Utrzymywanie cyklu życia dokumentu poza ekranem

Poniższy przykład pokazuje, jak zapewnić istnienie dokumentu poza ekranem. Funkcja setupOffscreenDocument() wywołuje 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;
  }
}

Przed wysłaniem wiadomości do dokumentu poza ekranem wywołaj setupOffscreenDocument(), aby upewnić się, że dokument istnieje, jak pokazano w poniższym 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 GitHub.

Przed Chrome 116: sprawdź, czy dokument poza ekranem jest otwarty

runtime.getContexts() został dodany w Chrome 116. W starszych wersjach Chrome użyj clients.matchAll() , aby sprawdzić, czy istnieje 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);
    });
  }
}

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

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

chrome.offscreen.hasDocument(): Promise<boolean>