Descrição
Use a API offscreen para criar e gerenciar documentos fora da tela.
Permissões
offscreenPara 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 ao abrir novas janelas ou
guias. A API runtime é a única API de extensões
com suporte para 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
da extensão. Por exemplo, como a API browser.runtime é a única
compatível com documentos fora da tela, as mensagens precisam ser processadas
usando membros dessa API.
Veja outras maneiras como os documentos fora da tela se comportam de forma diferente das páginas normais:
- O URL de um documento fora da tela precisa ser um arquivo HTML estático incluído na 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 propriedadeopeneré semprenull. - 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 de divisão com um perfil de navegação anônima ativo, os perfis normal e de navegação anônima poderão ter um documento fora da tela cada.
Use browser.offscreen.createDocument() e
browser.offscreen.closeDocument() para criar e fechar um documento
fora da tela. createDocument() requer o url do documento, um motivo e uma justificativa:
browser.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
a criação do documento para determinar o ciclo de vida 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 ciclo de vida.
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
chamada de função setupOffscreenDocument() chama runtime.getContexts() para encontrar
um documento fora da tela 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 = browser.runtime.getURL(path);
const existingContexts = await browser.runtime.getContexts({
contextTypes: ['OFFSCREEN_DOCUMENT'],
documentUrls: [offscreenUrl]
});
if (existingContexts.length > 0) {
return;
}
// create offscreen document
if (creating) {
await creating;
} else {
creating = browser.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.
browser.action.onClicked.addListener(async () => {
await setupOffscreenDocument('off_screen.html');
// Send message to offscreen document
browser.runtime.sendMessage({
type: '...',
target: 'offscreen',
data: '...'
});
});
Para ver 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 browser.runtime) {
const contexts = await browser.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(browser.runtime.id);
});
}
}
Tipos
CreateParameters
Propriedades
-
justificativa
string
Uma string fornecida pelo desenvolvedor que explica, em mais detalhes, a necessidade do contexto em segundo plano. O user agent _pode_ usar isso na exibição para o 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
"TESTING"
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 para um iframe para modificar o conteúdo dele.
"DOM_SCRAPING"
Especifica que o documento fora da tela precisa incorporar um iframe e extrair o 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 de 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 exibição (por exemplo, getDisplayMedia()).
"WEB_RTC"
Especifica que o documento fora da tela precisa usar as 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 ao 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()
browser.offscreen.closeDocument(): Promise<void>
Fecha o documento fora da tela aberto para a extensão.
Retorna
-
Promessa<void>
Promessa que é resolvida quando o documento fora da tela é fechado.
createDocument()
browser.offscreen.createDocument(
parameters: CreateParameters,
): Promise<void>
Cria um novo documento fora da tela para a extensão.
Parâmetros
-
parâmetros
Os parâmetros que descrevem o documento fora da tela a ser criado.
Retorna
-
Promessa<void>
Promessa que é resolvida quando o documento fora da tela é criado e conclui o carregamento de página inicial.
hasDocument()
browser.offscreen.hasDocument(): Promise<boolean>
Determina se a extensão tem um documento ativo.
Retorna
-
Promise<boolean>
Promessa que é resolvida com o resultado de se a extensão tem um documento fora da tela ativo.