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

Описание

Разрешения

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

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

Доступность

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

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

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

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

Описание

Разрешения

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

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

Доступность

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

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

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

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