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

Описание

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

Разрешения

offscreen

Для использования API Offscreen необходимо указать разрешение "offscreen" в манифесте расширения . Например:

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

Доступность

Chrome 109+ MV3+

Понятия и применение

Сервис-воркеры не имеют доступа к 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);
    });
  }
}

Типы

CreateParameters

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

  • обоснование

    нить

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

  • причины

    Причина []

    Причина(ы) создания расширения, находящимся за пределами видимой области экрана.

  • url

    нить

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

Reason

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

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

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

"IFRAME_SCRIPTING"
Указывает, что документ, находящийся вне экрана, должен встраивать и обрабатывать iframe с помощью скриптов, чтобы иметь возможность изменять его содержимое.

"DOM_SCRAPING"
Указывает, что документ, находящийся вне экрана, должен содержать в себе iframe и анализировать его DOM для извлечения информации.

"КАПЛЫШКИ"
Указывает, что документ, находящийся вне экрана, должен взаимодействовать с объектами Blob (включая URL.createObjectURL() ).

"DOM_PARSER"
Указывает, что документ, находящийся вне экрана, должен использовать API DOMParser .

"USER_MEDIA"
Указывает, что документ, находящийся вне экрана, должен взаимодействовать с медиапотоками пользователя (например, getUserMedia() ).

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

"WEB_RTC"
Указывает, что документ, находящийся вне экрана, должен использовать API WebRTC .

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

"ЛОКАЛЬНОЕ_ХРАНИЛИЩЕ"
Указывает, что документу, находящемуся вне экрана, необходим доступ к localStorage .

«Рабочие»
Указывает, что документ, находящийся вне экрана, должен запускать рабочие процессы.

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

"MATCH_MEDIA"
Указывает, что документ, находящийся за пределами видимой области экрана, должен использовать window.matchMedia .

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

Методы

closeDocument()

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

Закрывает текущий открытый документ, находящийся за пределами видимой области экрана, для данного расширения.

Возвраты

  • Обещание<пустота>

    Обещание, которое выполняется после закрытия документа, находящегося вне видимой области экрана.

createDocument()

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

Создает новый документ, находящийся за пределами видимой области экрана, для расширения.

Параметры

  • параметры

    CreateParameters

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

Возвраты

  • Обещание<пустота>

    Обещание, которое выполняется после создания документа, находящегося вне экрана, и завершения его первоначальной загрузки страницы.