chrome.offscreen

Opis

Uprawnienia

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

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

Dostępność

Pojęcia i zastosowanie

Skrypty service worker nie mają dostępu do modelu DOM, a wiele witryn stosuje zasady bezpieczeństwa treści, które ograniczają ich funkcjonalność. Interfejs Offscreen API umożliwia rozszerzeniu korzystanie z interfejsów DOM API w ukrytym dokumencie bez zakłócania wrażeń 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 dotyczącymi dostępu przez interfejs API. Na przykład interfejs API chrome.runtime jest jedynym interfejsem API rozszerzeń obsługiwanym przez dokumenty poza ekranem, dlatego przesyłanie wiadomości musi być obsługiwane przez użytkowników tego interfejsu API.

Oto inne powody, dla których dokumenty poza ekranem zachowują się inaczej niż zwykłe strony:

• Adres URL dokumentu poza ekranem musi być statycznym plikiem HTML dołączonym do rozszerzenia.
• Nie udało się zaznaczyć dokumentów poza ekranem.
• Dokument poza ekranem to wystąpienie elementu window, ale jego wartość opener to zawsze null.
• Pakiet rozszerzeń może zawierać wiele dokumentów poza ekranem, ale zainstalowane rozszerzenie może być otwarte tylko raz. Jeśli rozszerzenie działa w trybie podziału z aktywnym profilem incognito, oba profile mogą zawierać jeden dokument poza ekranem.

Użyj narzędzi chrome.offscreen.createDocument() i chrome.offscreen.closeDocument(), aby utworzyć i zamknąć dokument poza ekranem. Funkcja createDocument() wymaga atrybutu url dokumentu, przyczyny i uzasadnienia:

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

Przyczyny

Listę uzasadnionych przyczyn znajdziesz w sekcji Przyczyny. Przyczyny są określane podczas tworzenia dokumentu w celu określenia jego okresu ważności. Przyczyna AUDIO_PLAYBACK powoduje zamknięcie dokumentu po 30 sekundach bez odtwarzania dźwięku. Żadne inne przyczyny nie powodują powstawania limitów czasu życia.

Przykłady

Opiekuj się cyklem życia dokumentu poza ekranem

Z przykładu poniżej dowiesz się, jak sprawdzić, czy dokument istnieje poza ekranem. Funkcja setupOffscreenDocument() wywołuje funkcję runtime.getContexts(), aby znaleźć istniejący dokument poza ekranem lub utworzyć taki 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(), by sprawdzić, czy 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: '...'
  });
});

Szczegółowe przykłady znajdziesz w prezentacjach offscreen-clipboard i offscreen-dom w serwisie GitHub.

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

Narzędzie runtime.getContexts() zostało dodane w Chrome 116. We wcześniejszych wersjach Chrome możesz za pomocą narzędzia clients.matchAll() sprawdzić, czy istnieje już dokument niewidoczny na ekranie:

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 await matchedClients.some(client => {
        client.url.includes(chrome.runtime.id);
    });
  }
}

chrome.offscreen.closeDocument(
  callback?: function,
)

chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)