chrome.offscreen

Opis

Uprawnienia

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

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

Dostępność

Pojęcia i wykorzystanie

Skrypty service worker nie mają dostępu DOM, a wiele witryn ma politykę zabezpieczeń treści, ograniczają funkcjonalność skryptów treści. Interfejs Offscreen API umożliwia rozszerzeniu korzystanie z modelu DOM interfejsów API w ukrytym dokumencie bez zakłócania pracy użytkowników przez otwieranie nowych okien lub . Interfejs API runtime to jedyny interfejs API rozszerzeń obsługiwane przez dokumenty poza ekranem.

Strony wczytywane jako dokumenty poza ekranem są obsługiwane inaczej niż w przypadku innych typów stron rozszerzeń. Uprawnienia rozszerzenia są przenoszone do dokumentów poza ekranem, ale z ograniczeniami dotyczącymi interfejsu API rozszerzenia dostęp. Jako że interfejs API chrome.runtime jest jedynym interfejsu API rozszerzeń obsługiwanego przez dokumenty poza ekranem, wiadomości muszą być obsługiwane za pomocą elementów tego interfejsu API.

Dokumenty poza ekranem działają inaczej niż zwykłe strony na następujące sposoby:

• Adres URL dokumentu poza ekranem musi być statycznym plikiem HTML dołączonym do rozszerzenia.
• Nie można zaznaczyć dokumentów poza ekranem.
• Dokument poza ekranem to wystąpienie elementu window, ale wartość jego właściwości opener zawsze wynosi null.
• Chociaż pakiet rozszerzeń może zawierać wiele dokumentów poza ekranem, zainstalowane rozszerzenie może a potem otworzyć tylko jedną z nich. Jeśli rozszerzenie jest uruchomione w trybie podzielonego z aktywnym profilem incognito można jeden dokument poza ekranem.

Używaj chrome.offscreen.createDocument() oraz chrome.offscreen.closeDocument(), aby utworzyć i zamknąć ekran poza ekranem dokument. Funkcja createDocument() wymaga właściwości url dokumentu oraz przyczyny i uzasadnienia:

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

Przyczyny

Listę prawidłowych powodów znajdziesz w sekcji Przyczyny. Powody są określane w czasie tworzenia dokumentu, aby określić jego okres ważności. Przyczyna: AUDIO_PLAYBACK ustawia dokument zostanie zamknięty po 30 sekundach bez odtwarzania dźwięku. Żadne inne powody nie powodują nałożenia limitów bezterminowych.

Przykłady

Zachować cykl życia dokumentu poza ekranem

Z przykładu poniżej dowiesz się, jak sprawdzić, czy dokument poza ekranem istnieje. Funkcja setupOffscreenDocument() wywołuje funkcję runtime.getContexts(), aby znaleźć istniejącego dokumentu poza ekranem, albo 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 setupOffscreenDocument(), aby upewnić się, dokument istnieje, co pokazano w przykładzie poniżej.

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 artykułach na temat offscreen-clipboard i wersji demonstracyjne offscreen-dom na GitHubie.

Do wersji Chrome 116: sprawdzanie, czy dokument poza ekranem jest otwarty

Aplikacja runtime.getContexts() została dodana w Chrome 116. We wcześniejszych wersjach Chrome – użyj clients.matchAll() aby sprawdzić istniejący 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 await matchedClients.some(client => {
        client.url.includes(chrome.runtime.id);
    });
  }
}

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

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