chrome.offscreen

Descrição

Permissões

Para usar a API Offscreen, declare a permissão "offscreen" no manifesto da extensão. Exemplo:

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

Disponibilidade

Conceitos e uso

Os service workers não têm acesso ao DOM, e muitos sites têm políticas de segurança de conteúdo que limitam a funcionalidade dos scripts de conteúdo. A API Offscreen permite que a extensão use APIs DOM em um documento oculto sem interromper a experiência do usuário abrindo novas janelas ou guias. A API runtime é a única API de extensões com suporte a documentos fora da tela.

As páginas carregadas como documentos fora da tela são processadas de maneira diferente de outros tipos de páginas de extensão. As permissões da extensão são transferidas para documentos fora da tela, mas com limites no acesso à API de extensão. Por exemplo, como a API chrome.runtime é a única API de extensões com suporte a documentos fora da tela, as mensagens precisam ser processadas usando membros dessa API.

A seguir, mostramos outras maneiras como os documentos fora da tela se comportam de maneira diferente das páginas normais:

• O URL de um documento fora da tela precisa ser um arquivo HTML estático agrupado com a extensão.
• Não é possível focar documentos fora da tela.
• Um documento fora da tela é uma instância de window, mas o valor da propriedade opener é sempre null.
• Embora um pacote de extensão possa conter vários documentos fora da tela, uma extensão instalada só pode ter um aberto por vez. Se a extensão estiver em execução no modo dividido com um perfil de navegação anônima ativo, os perfis normal e anônimo poderão ter um documento fora da tela.

Use chrome.offscreen.createDocument() e chrome.offscreen.closeDocument() para criar e fechar um documento fora da tela. createDocument() exige o url do documento, um motivo e uma justificativa:

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

Motivos

Para conferir uma lista de motivos válidos, consulte a seção Motivos. Os motivos são definidos durante a criação do documento para determinar a vida útil dele. O motivo AUDIO_PLAYBACK define o documento para fechar após 30 segundos sem reprodução de áudio. Todos os outros motivos não definem limites de vida útil.

Exemplos

Manter o ciclo de vida de um documento fora da tela

O exemplo a seguir mostra como garantir que um documento fora da tela exista. A função setupOffscreenDocument() chama runtime.getContexts() para encontrar um documento fora da tela existente ou cria o documento se ele ainda não existir.

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;
  }
}

Antes de enviar uma mensagem para um documento fora da tela, chame setupOffscreenDocument() para garantir que o documento exista, conforme demonstrado no exemplo a seguir.

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

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

Para conferir exemplos completos, consulte as demonstrações offscreen-clipboard e offscreen-dom no GitHub.

Antes do Chrome 116: verificar se um documento fora da tela está aberto

runtime.getContexts() foi adicionado no Chrome 116. Em versões anteriores do Chrome, use clients.matchAll() para verificar se há um documento fora da tela:

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>

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