browser.offscreen

Описание

Разрешения

Чтобы использовать Offscreen API, объявите разрешение "offscreen" в манифесте расширения. Пример:

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

Доступность

Основные понятия и использование

У сервис-воркеров нет доступа к DOM, а многие сайты используют Content Security Policy, ограничивающие функциональность скриптов контента. Offscreen API позволяет расширению использовать DOM API в скрытом документе, не прерывая работу пользователя открытием новых окон или вкладок. runtime API – единственный API расширений, поддерживаемый невидимыми документами.

Страницы, загруженные как фоновые документы, обрабатываются иначе, чем другие типы страниц расширений. Разрешения расширения распространяются на невидимые документы, но с ограничениями на доступ к API расширения. Например, поскольку browser.runtime API – единственный API расширений, поддерживаемый офскрин-документами, обмен сообщениями должен осуществляться с помощью членов этого API.

Ниже перечислены другие отличия офлайн-документов от обычных страниц.

• URL документа за пределами экрана должен быть статичным HTML-файлом, входящим в состав расширения.
• Нельзя выбрать документ, который не виден на экране.
• Документ вне экрана – это экземпляр window, но значение его свойства opener всегда равно null.
• Хотя пакет расширения может содержать несколько документов, находящихся за пределами экрана, в установленном расширении может быть открыт только один такой документ. Если расширение работает в разделенном режиме с активным профилем инкогнито, в обычном и режиме инкогнито может быть по одному документу вне экрана.

Используйте browser.offscreen.createDocument() и browser.offscreen.closeDocument(), чтобы создать и закрыть закадровый документ. Для createDocument() требуется url документа, причина и обоснование:

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

Причины

Список допустимых причин приведен в разделе Причины. Причины указываются при создании документа, чтобы определить срок его хранения. Причина AUDIO_PLAYBACK задает закрытие документа через 30 секунд без воспроизведения аудио. Для всех остальных причин ограничения по времени жизни не задаются.

Примеры

Как поддерживать жизненный цикл документа, который не виден на экране

В следующем примере показано, как убедиться, что документ за пределами экрана существует. Функция setupOffscreenDocument() вызывает runtime.getContexts(), чтобы найти существующий документ за пределами экрана или создать его, если он ещё не существует.

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 = browser.runtime.getURL(path);
  const existingContexts = await browser.runtime.getContexts({
    contextTypes: ['OFFSCREEN_DOCUMENT'],
    documentUrls: [offscreenUrl]
  });

  if (existingContexts.length > 0) {
    return;
  }

  // create offscreen document
  if (creating) {
    await creating;
  } else {
    creating = browser.offscreen.createDocument({
      url: path,
      reasons: ['CLIPBOARD'],
      justification: 'reason for needing the document',
    });
    await creating;
    creating = null;
  }
}

Прежде чем отправлять сообщение в документ, который не отображается на экране, вызовите setupOffscreenDocument(), чтобы убедиться, что документ существует, как показано в следующем примере.

browser.action.onClicked.addListener(async () => {
  await setupOffscreenDocument('off_screen.html');

  // Send message to offscreen document
  browser.runtime.sendMessage({
    type: '...',
    target: 'offscreen',
    data: '...'
  });
});

Полные примеры можно найти в демонстрационных версиях offscreen-clipboard и offscreen-dom на GitHub.

До версии Chrome 116: как проверить, открыт ли документ вне экрана

runtime.getContexts() был добавлен в Chrome 116. В более ранних версиях Chrome для проверки наличия существующего документа вне экрана используйте clients.matchAll():

async function hasOffscreenDocument() {
  if ('getContexts' in browser.runtime) {
    const contexts = await browser.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(browser.runtime.id);
    });
  }
}

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

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

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