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

Описание

Используйте offscreen API для создания закадровых документов и управления ими.

Разрешения

offscreen

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

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

Доступность

Хром 109+ МВ3+

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

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

Страницы, загруженные как закадровые документы, обрабатываются иначе, чем другие типы страниц расширений. Разрешения расширения передаются и на закадровые документы, но с ограничениями на доступ к 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 await matchedClients.some(client => {
        client.url.includes(chrome.runtime.id);
    });
  }
}

Типы

CreateParameters

Характеристики

  • оправдание

    нить

    Строка, предоставленная разработчиком, которая более подробно объясняет необходимость фонового контекста. Пользовательский агент _может_ использовать это для отображения пользователю.

  • причины

    Причина []

    Причина(ы), по которой расширение создает закадровый документ.

  • URL

    нить

    (Относительный) URL-адрес для загрузки в документ.

Reason

Перечисление

"ТЕСТИРОВАНИЕ"
Причина используется только в целях тестирования.

"АУДИО_ВОСПРОИЗВЕДЕНИЕ"
Указывает, что закадровый документ отвечает за воспроизведение звука.

"IFRAME_SCRIPTING"
Указывает, что в закадровый документ необходимо внедрить и создать сценарий iframe, чтобы изменить содержимое iframe.

"ДОМ_СКРАПИНГ"
Указывает, что в закадровый документ необходимо внедрить iframe и очистить его DOM для извлечения информации.

"БЛОБС"
Указывает, что документ за кадром должен взаимодействовать с объектами Blob (включая URL.createObjectURL() ).

"ДОМ_ПАРСЕР"
Указывает, что закадровый документ должен использовать API DOMParser .

"ПОЛЬЗОВАТЕЛЬ_МЕДИА"
Указывает, что закадровый документ должен взаимодействовать с медиапотоками пользовательского мультимедиа (например, getUserMedia() ).

"DISPLAY_MEDIA"
Указывает, что закадровый документ должен взаимодействовать с медиапотоками отображаемого мультимедиа (например, getDisplayMedia() ).

"ВЕБ_RTC"
Указывает, что закадровый документ должен использовать API WebRTC .

"БУФЕР БУФЕРА"
Указывает, что закадровый документ должен взаимодействовать с API буфера обмена .

"LOCAL_STORAGE"
Указывает, что документу за кадром требуется доступ к localStorage .

"РАБОЧИЕ"
Указывает, что закадровый документ должен порождать рабочие процессы.

"БАТАРЕЯ_СТАТУС"
Указывает, что закадровый документ должен использовать navigator.getBattery .

"МАТЧ_МЕДИА"
Указывает, что закадровый документ должен использовать window.matchMedia .

"ГЕОЛОКАЦИЯ"
Указывает, что закадровый документ должен использовать navigator.geolocation .

Методы

closeDocument()

Обещать
chrome.offscreen.closeDocument(
  callback?: function,
)

Закрывает открытый в данный момент закадровый документ для расширения.

Параметры

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    () => void

Возврат

  • Обещание<void>

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

createDocument()

Обещать
chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)

Создает новый закадровый документ для расширения.

Параметры

  • Параметры, описывающие создаваемый закадровый документ.

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    () => void

Возврат

  • Обещание<void>

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.