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
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
do 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
compatível com 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 documentos fora da tela, mas com limites de acesso à API de extensão. Por exemplo, como a API chrome.runtime
é a única
API de extensões com suporte em documentos fora da tela, as mensagens precisam ser processadas
usando membros dessa API.
Veja a seguir 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 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 sendo executada no modo de divisão 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()
requer 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 a criação do documento para determinar a vida útil dele. O motivo AUDIO_PLAYBACK
define o
documento para ser fechado após 30 segundos sem tocar o áudio. Todos os outros motivos não definem limites para a vida útil.
Exemplos
Manter o ciclo de vida de um documento fora da tela
O exemplo a seguir mostra como garantir que existe um documento fora da tela. A
função setupOffscreenDocument()
chama runtime.getContexts()
para encontrar
um documento existente 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 = 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 existe, 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 ver exemplos completos, consulte as demonstrações offscreen-clipboard e offscreen-dom no GitHub (links em inglês).
Antes do Chrome 116: verificar se um documento fora da tela está aberto
A extensão runtime.getContexts()
foi adicionada 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 essa informação na exibição para o usuário.
-
motivos
Motivo[]
São os motivos pelos quais a extensão está criando o documento fora da tela.
-
url
string
O URL (relativo) que será carregado no documento.
Reason
Tipo enumerado
"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 para um iframe para modificar o conteúdo do iframe.
"DOM_SCRAPING"
Especifica que o documento fora da tela precisa incorporar um iframe e copiar 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 os 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ídias de exibição (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()
chrome.offscreen.closeDocument(
callback?: function,
)
Fecha o documento fora da tela aberto para a extensão no momento.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
createDocument()
chrome.offscreen.createDocument(
parameters: CreateParameters,
callback?: function,
)
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 que será criado.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.