chrome.offscreen

Descrição

Use a API offscreen para criar e gerenciar documentos fora da tela.

Permissões

offscreen

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

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

Disponibilidade

Chrome 109 ou versões mais recentes MV3+

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 o DOM APIs 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 suportado por documentos fora da tela.

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

Confira abaixo 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 empacotado com a extensão.
  • Não é possível focar em 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 anônimo ativo, os perfis normal e anônimo podem ter um documento fora da tela.

Use chrome.offscreen.createDocument() e chrome.offscreen.closeDocument() para criar e fechar uma janela fora da tela documento. 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 ver uma lista de motivos válidos, consulte a seção Motivos. Os motivos são definidos durante criação de documento para determinar a vida útil do documento. O motivo AUDIO_PLAYBACK define documento seja fechado depois de 30 segundos sem a reprodução de áudio. Todos os outros motivos não definem limites de ciclo de vida.

Exemplos

Manter o ciclo de vida de um documento fora da tela

O exemplo a seguir mostra como garantir que exista um documento fora da tela. A A função setupOffscreenDocument() chama runtime.getContexts() para encontrar um documento fora da tela ou o cria, 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 se certificar de que o documento existe, como 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 exemplos completos, consulte a área de transferência fora da tela e demonstrações fora da tela (link em inglês) no GitHub.

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

O 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 await matchedClients.some(client => {
        client.url.includes(chrome.runtime.id);
    });
  }
}

Tipos

CreateParameters

Propriedades

  • justificativa

    string

    Uma string fornecida pelo desenvolvedor que explica, com mais detalhes, a necessidade do contexto em segundo plano. O user agent _pode_ usar isso para mostrar ao usuário.

  • motivos

    Motivo[]

    Os motivos pelos quais a extensão está criando o documento fora da tela.

  • url

    string

    O URL (relativo) a ser carregado no documento.

Reason

Enumeração

"TESTE"
Um motivo usado apenas para fins de teste.

"AUDIO_PLAYBACK"
Especifica que o documento fora da tela é responsável por reproduzir áudio.

"IFRAME_SCRIPTING"
Especifica que o documento fora da tela precisa incorporar e criar um script de iframe para modificar o conteúdo do iframe.

"DOM_SCRAPING"
Especifica que o documento fora da tela precisa incorporar um iframe e raspar seu DOM para extrair informações.

"BLOBS"
Especifica que o documento fora da tela precisa interagir com objetos Blob (incluindo URL.createObjectURL()).

"DOM_PARSER"
Especifica que o documento fora da tela precisa usar a API DOMParser.

"USER_MEDIA"
Especifica que o documento fora da tela precisa interagir com streams da mídia do usuário (por exemplo, getUserMedia()).

"DISPLAY_MEDIA"
Especifica que o documento fora da tela precisa interagir com streams de mídia de display (por exemplo, getDisplayMedia()).

"WEB_RTC"
Especifica que o documento fora da tela precisa usar APIs WebRTC.

"CLIPBOARD"
Especifica que o documento fora da tela precisa interagir com a API Clipboard.

"LOCAL_STORAGE"
Especifica que o documento fora da tela precisa de acesso a localStorage.

"WORKERS"
Especifica que o documento fora da tela precisa gerar workers.

"BATTERY_STATUS"
Especifica que o documento fora da tela precisa usar navigator.getBattery.

"MATCH_MEDIA"
Especifica que o documento fora da tela precisa usar window.matchMedia.

"GEOLOCATION"
Especifica que o documento fora da tela precisa usar navigator.geolocation.

Métodos

closeDocument()

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

Fecha o documento fora da tela aberto no momento para a extensão.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

createDocument()

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

Cria um novo documento fora da tela para a extensão.

Parâmetros

  • parâmetros

    CreateParameters

    Os parâmetros que descrevem o documento fora da tela a ser criado.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.