chrome.offscreen

Descripción

Permisos

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 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 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);
    });
  }
}

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

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