chrome.offscreen

Descripción

Permisos

Para usar la API de Offscreen, declara el permiso "offscreen" en el manifiesto de la 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 del DOM en un documento oculto sin interrumpir la experiencia del usuario abriendo 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 controlan de manera diferente a otros tipos de páginas de extensión. 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, la mensajería debe controlarse con miembros de esa API.

A continuación, se indican otras formas en que los documentos fuera de pantalla se comportan de manera diferente a las páginas normales:

• La URL de un documento fuera de pantalla debe ser un archivo HTML estático incluido en la extensión.
• No se pueden enfocar los documentos fuera de la pantalla.
• Un documento fuera de pantalla es una instancia de window, pero el valor de su propiedad opener siempre es null.
• Si bien un paquete de extensión puede contener varios documentos fuera de pantalla, una extensión instalada solo puede tener uno abierto a la vez. Si la extensión se ejecuta en modo dividido con un perfil de Incógnito activo, cada perfil (normal y de Incógnito) puede tener un documento fuera de pantalla.

Usa chrome.offscreen.createDocument() y chrome.offscreen.closeDocument() para crear y cerrar un documento fuera de la pantalla. createDocument() requiere el 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 ciclo de vida. El motivo AUDIO_PLAYBACK establece que el documento se cierre después de 30 segundos sin que se reproduzca audio. Todos los demás motivos no establecen límites de duración.

Ejemplos

Cómo mantener 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 la pantalla. La función setupOffscreenDocument() llama a runtime.getContexts() para encontrar un documento fuera de la pantalla existente o crear el documento 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 la 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 de offscreen-clipboard y offscreen-dom en GitHub.

Antes de Chrome 116: Comprueba si hay un documento fuera de pantalla abierto

Se agregó runtime.getContexts() en Chrome 116. En versiones anteriores de Chrome, usa clients.matchAll() para verificar si existe un documento fuera de pantalla:

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>