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 de contenido que limitan la funcionalidad de las secuencias de comandos de contenido. La API de Offscreen permite que la extensión use DOM APIs en un documento oculto sin interrumpir la experiencia del usuario, ya que se abren ventanas nuevas o pestañas. La API de runtime es la única API de extensiones respaldada por documentos fuera de pantalla.

Las páginas que se cargan como documentos fuera de pantalla se manejan de forma diferente a otros tipos de páginas de extensión. Los permisos de la extensión se transfieren a los documentos que no aparecen en pantalla, pero con límites para la API de extensión el acceso a los datos. Por ejemplo, debido a que la API de chrome.runtime es la única API de extensiones compatible con documentos fuera de pantalla, se debe manejar la mensajería con miembros de esa API.

Las siguientes son otras maneras 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 con la extensión.
• Los documentos fuera de pantalla no se pueden enfocar.
• Un documento fuera de pantalla es una instancia de window, pero el valor de su propiedad opener siempre es null.
• Aunque un paquete de extensión puede contener varios documentos fuera de pantalla, una extensión instalada solo puede tengan una abierta a la vez. Si la extensión se está ejecutando en modo dividido con un perfil de incógnito activo, tanto el perfil normal como el incógnito tener un documento fuera de pantalla.

Usa chrome.offscreen.createDocument() y chrome.offscreen.closeDocument() para crear y cerrar un elemento fuera de 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 ver una lista de motivos válidos, consulta la sección Motivos. Los motivos se establecen durante la creación de documentos para determinar su vida útil. El motivo AUDIO_PLAYBACK establece la el documento se cierre después de 30 segundos sin reproducir audio. Los demás motivos no establecen límites de duración.

Ejemplos

Mantener el ciclo de vida de un documento fuera de pantalla

En el siguiente ejemplo, se muestra cómo asegurarse de que exista un documento fuera de pantalla. El La función setupOffscreenDocument() llama a runtime.getContexts() para buscar un documento existente fuera de pantalla o crea 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 pantalla, llama a setupOffscreenDocument() para asegurarte existe el documento, 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 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 buscar 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,
)