хром.за кадром

Описание

Разрешения

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

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

Доступность

Концепции и использование

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

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

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

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

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

chrome.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 = 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;
  }
}

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

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

  // Send message to offscreen document
  chrome.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 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>