Descripción
Usa la API de offscreen
para crear y administrar documentos fuera de pantalla.
Permisos
offscreen
Para usar la API de Offscreen, declara el permiso "offscreen"
en el manifiesto de extensión. Por ejemplo:
{
"name": "My extension",
...
"permissions": [
"offscreen"
],
...
}
Disponibilidad
Conceptos y uso
Los service workers no tienen acceso al DOM, y muchos sitios web tienen políticas de seguridad del contenido que limitan la funcionalidad de las secuencias de comandos de contenido. La API de Offscreen permite que la extensión use las APIs de DOM en un documento oculto sin interrumpir la experiencia del usuario, ya que abre ventanas o pestañas nuevas. La API de runtime
es la única API de extensiones compatible con los documentos fuera de pantalla.
Las páginas cargadas como documentos fuera de pantalla se manejan de manera diferente a otros tipos de páginas de extensiones.
Los permisos de la extensión se transfieren a los documentos fuera de pantalla, pero con límites en el acceso a la API de extensiones. Por ejemplo, debido a que la API de chrome.runtime
es la única
API de extensiones compatible con los documentos fuera de pantalla, los mensajes se deben controlar
con miembros de esa API.
A continuación, se muestran otras formas en que los documentos fuera de pantalla se comportan de manera diferente que las páginas normales:
- La URL de un documento fuera de pantalla debe ser un archivo HTML estático empaquetado con la extensión.
- No se pueden enfocar los documentos fuera de pantalla.
- Un documento fuera de pantalla es una instancia de
window
, pero el valor de su propiedadopener
siempre esnull
. - Si bien un paquete de extensión puede contener varios documentos fuera de pantalla, una extensión instalada solo puede tener una abierta a la vez. Si la extensión se ejecuta en modo dividido con un perfil de incógnito activo, los perfiles normal y de incógnito pueden tener un documento fuera de pantalla cada uno.
Usa chrome.offscreen.createDocument()
y chrome.offscreen.closeDocument()
para crear y cerrar un documento fuera de pantalla. createDocument()
requiere la url
del documento, un motivo y una justificación:
chrome.offscreen.createDocument({
url: 'off_screen.html',
reasons: ['CLIPBOARD'],
justification: 'reason for needing the document',
});
Motivos
Para obtener una lista de los motivos válidos, consulta la sección Motivos. Los motivos se establecen durante la creación del documento para determinar su vida útil. El motivo AUDIO_PLAYBACK
establece que el documento se cierra después de 30 segundos sin que se reproduzca audio. Todos los demás motivos no establecen límites de duración.
Ejemplos
Mantén el ciclo de vida de un documento fuera de pantalla
En el siguiente ejemplo, se muestra cómo garantizar que exista un documento fuera de pantalla. La función setupOffscreenDocument()
llama a runtime.getContexts()
para encontrar un documento fuera de pantalla existente o lo crea si aún no existe.
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 un mensaje a un documento fuera de pantalla, llama a setupOffscreenDocument()
para asegurarte de que
el documento exista, como se muestra en el siguiente ejemplo.
chrome.action.onClicked.addListener(async () => {
await setupOffscreenDocument('off_screen.html');
// Send message to offscreen document
chrome.runtime.sendMessage({
type: '...',
target: 'offscreen',
data: '...'
});
});
Para ver ejemplos completos, consulta las demostraciones offscreen-clipboard y offscreen-dom en GitHub.
Antes de Chrome 116: verifica si un documento fuera de pantalla está abierto
Se agregó runtime.getContexts()
en Chrome 116. En versiones anteriores de Chrome, usa clients.matchAll()
para verificar un documento fuera de pantalla existente:
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
Propiedades
-
justificación
cadena
Es una cadena proporcionada por el desarrollador que explica con más detalle la necesidad de un contexto en segundo plano. El usuario-agente _puede_ usar esto en pantalla para el usuario.
-
motivos
Motivo[]
Los motivos por los que la extensión crea el documento fuera de pantalla.
-
url
cadena
La URL (relativa) que se cargará en el documento.
Reason
Enum
"PRUEBA"
Es un motivo que se usa solo para realizar pruebas.
"AUDIO_PLAYBACK"
Especifica que el documento fuera de pantalla es responsable de la reproducción de audio.
"Iframe_SCRIPTING"
Especifica que el documento fuera de pantalla debe incorporar y crear una secuencia de comandos de un iframe para modificar su contenido.
"DOM_SCRAPING"
Especifica que el documento fuera de pantalla debe incorporar un iframe y copiar su DOM para extraer información.
"BLOBS"
Especifica que el documento fuera de pantalla debe interactuar con objetos Blob (incluido URL.createObjectURL()
).
"DOM_PARSER"
Especifica que el documento fuera de pantalla debe usar la API de DOMParser.
"USER_MEDIA"
Especifica que el documento fuera de pantalla debe interactuar con transmisiones multimedia del contenido multimedia del usuario (p.ej., getUserMedia()
).
"DISPLAY_MEDIA"
Especifica que el documento fuera de pantalla debe interactuar con flujos de contenido multimedia de la pantalla (p.ej., getDisplayMedia()
).
"WEB_RTC"
Especifica que el documento fuera de pantalla debe usar APIs de WebRTC.
"CLIPBOARD"
Especifica que el documento fuera de pantalla debe interactuar con la API de portapapeles.
"LOCAL_STORAGE"
Especifica que el documento fuera de pantalla necesita acceso a localStorage.
"WORKERS"
Especifica que el documento fuera de pantalla debe generar trabajadores.
"BATTERY_STATUS"
Especifica que el documento fuera de pantalla debe usar navigator.getBattery.
"MATCH_MEDIA"
Especifica que el documento fuera de pantalla debe usar window.matchMedia.
"GEOLOCATION"
Especifica que el documento fuera de pantalla debe usar navigator.geolocation.
Métodos
closeDocument()
chrome.offscreen.closeDocument(
callback?: function,
)
Cierra el documento fuera de pantalla que se encuentra abierto actualmente de la extensión.
Parámetros
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
createDocument()
chrome.offscreen.createDocument(
parameters: CreateParameters,
callback?: function,
)
Crea un documento fuera de pantalla nuevo para la extensión.
Parámetros
-
Parámetros
Son los parámetros que describen el documento fuera de pantalla que se creará.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.