browser.mimeHandler

Descripción

Disponibilidad

Manifiesto

Conceptos y uso

Históricamente, las extensiones de terceros que controlan tipos de documentos específicos (como los visores de PDF) dependían de la intercepción de solicitudes de red para capturar las navegaciones y redireccionar a los usuarios a una página de extensión. Registrarse como un controlador de MIME evita varias limitaciones de ese enfoque:

• La URL de origen permanece en la barra de direcciones en lugar de reemplazarse por una URL de chrome-extension://.
• Tu extensión recupera la respuesta que Chrome ya recibió, en lugar de realizar una segunda solicitud de red. Los documentos que se entregan a través de solicitudes POST o desde URLs de un solo uso funcionan correctamente.
• Tu extensión puede renderizar documentos cargados en elementos <embed>, <object> o <iframe>.
• Los archivos locales (URLs de file://) funcionan sin que el usuario habilite manualmente la opción "Permitir acceso a las URLs de archivo" en la configuración de la extensión.

Los controladores de MIME solo se aplican a los documentos que ocupan un marco completo: navegaciones de nivel superior y documentos incorporados. Nunca se aplican a los recursos secundarios intercalados (p.ej., elementos <audio>, <img> o <video>).

Registra un controlador

Para registrar tu extensión como un controlador de MIME, declara la clave "mime_types_handler" en el manifiesto. Cada entrada asigna un tipo de MIME a la página de extensión que lo renderiza:

manifest.json:

{
  "name": "My PDF Viewer",
  ...
  "mime_types_handler": {
    "application/pdf": {
      "handler_url": "viewer.html",
      "can_embed": true
    }
  },
  ...
}

Establece "can_embed" en true para controlar también los documentos incorporados en los elementos <embed>, <object> o <iframe>. Si se omite, tu controlador solo recibirá navegaciones de nivel superior. A partir de Chrome 151, application/pdf es el único tipo de MIME disponible para los controladores públicos. Declarar un tipo de MIME no compatible genera una advertencia de instalación.

Si más de una extensión instalada se registra para el mismo tipo de MIME, la extensión instalada más recientemente lo controla. Si se desinstala esa extensión, el controlador instalado anteriormente vuelve a activarse.

Recupera información de la transmisión

Cuando un usuario abre un documento de un tipo de MIME registrado, Chrome carga tu página de controlador en lugar de su visor integrado. En la página del controlador, llama a getStreamInfo() para recuperar un objeto StreamInfo. Esto incluye la originalUrl a la que navegó el usuario, el responseHeaders HTTP, si el documento se carga en un contexto de embedded y un streamUrl que se puede usar para recuperar el contenido del documento.

El streamUrl se puede recuperar exactamente una vez y solo desde el origen de tu extensión. Lee la respuesta por completo antes de procesarla; un segundo intento de recuperar el mismo streamUrl fallará. Usa originalUrl cuando muestres la ubicación o el título del documento, no para recuperar el contenido, ya que es posible que la solicitud original no se pueda repetir.

Recurre al controlador nativo

Es posible que tu controlador encuentre documentos que no puede renderizar, como archivos dañados o protegidos con contraseña. Llama a abortAndFallbackToNativeHandler() para dejar de controlar el documento y devolverlo al visor integrado de Chrome, en lugar de dejar al usuario en una página rota. Chrome descarga tu página de controlador como parte del resguardo; no se ejecuta ningún código después de esta llamada.

Chrome almacena en búfer la respuesta mientras se ejecuta el controlador. Si la respuesta se recibió por completo cuando llamas a este método, Chrome entrega el visor integrado desde la copia almacenada en búfer sin una nueva solicitud de red. De lo contrario, Chrome vuelve a cargar el documento desde la red, lo que puede fallar en el caso de los documentos entregados por POST o desde URLs de un solo uso. Recupera el flujo por completo antes de decidir si puedes renderizarlo. Una vez que se complete la recuperación de streamUrl, Chrome tendrá la respuesta completa.

Controla la disponibilidad de la API

En las versiones de Chrome anteriores a Chrome 151, una extensión que declara "mime_types_handler" se sigue instalando y ejecutando, pero no se registra como un controlador y browser.mimeHandler no está definido. Las extensiones que migran desde la intercepción de solicitudes de red pueden verificar la API al inicio y mantener su enfoque existente como resguardo:

service-worker.js:

if (browser.mimeHandler) {
  // Chrome routes registered MIME types to the handler page
  // declared in the manifest.
} else {
  // Fall back to network request interception.
}

Ejemplos

Cómo controlar un flujo

El siguiente ejemplo se ejecuta en la página del controlador declarada en el manifiesto. Recupera el contenido del documento y recurre al visor integrado de Chrome si falla la renderización:

viewer.js:

async function loadDocument() {
  const streamInfo = await browser.mimeHandler.getStreamInfo();

  // The `embedded` property is true if the document is loaded
  // within an <embed>, <object>, or <iframe> element.
  if (streamInfo.embedded) {
    // Adjust the UI (e.g., hide the top navigation bar).
    document.body.classList.add('embedded-view');
  }

  // Fetch the content using the provided streamUrl. The stream can
  // only be consumed once, so read it fully before continuing.
  const response = await fetch(streamInfo.streamUrl);
  const data = await response.arrayBuffer();

  try {
    // Render the document (e.g., using PDF.js).
    await renderDocument(data);
  } catch (e) {
    // Can't render this document. Fall back to Chrome's built-in
    // viewer; the page unloads and no code runs after this call.
    browser.mimeHandler.abortAndFallbackToNativeHandler();
  }
}

loadDocument();

Permitir que los usuarios activen o desactiven el manejo

Las opciones de controlador se almacenan por tipo de MIME. En el siguiente ejemplo, se usan getMimeHandlerOptions() y setMimeHandlerOptions() para permitir que los usuarios desactiven el control desde la página de opciones, sin desinstalar la extensión. Mientras el control esté inhabilitado, los documentos de ese tipo ya no se enrutarán a tu extensión.

options.js:

const checkbox = document.querySelector('#handle-pdfs');

async function initOptions() {
  const options =
      await browser.mimeHandler.getMimeHandlerOptions('application/pdf');
  // Handling is enabled unless it has been explicitly disabled.
  checkbox.checked = options.enabled !== false;
}

checkbox.addEventListener('change', async () => {
  await browser.mimeHandler.setMimeHandlerOptions('application/pdf', {
    enabled: checkbox.checked
  });
});

initOptions();

browser.mimeHandler.abortAndFallbackToNativeHandler(): Promise<void>

browser.mimeHandler.getMimeHandlerOptions(
  mimeType: string,
): Promise<MimeHandlerOptions>

browser.mimeHandler.getStreamInfo(): Promise<StreamInfo>

browser.mimeHandler.setMimeHandlerOptions(
  mimeType: string,
  options: MimeHandlerOptions,
): Promise<void>