chrome.mimeHandler

Descripción

Usa la API de chrome.mimeHandler para controlar los flujos de tipos de MIME en extensiones de terceros.

Disponibilidad

Pendiente

Manifiesto

Para usar esta API, se deben declarar las siguientes claves en el manifiesto.

"mime_types_handler"

Conceptos y uso

Históricamente, las extensiones de terceros que manejan tipos de documentos específicos (como los visores de PDF) se basaron en la interceptación de solicitudes de red para detectar navegaciones y redireccionar a los usuarios a una página de extensión. Registrarse como controlador de MIME evita varias limitaciones de ese enfoque:

  • La URL original permanece en la barra de direcciones en lugar de ser reemplazada 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 entregados por solicitudes POST o desde URLs de un solo uso funcionan correctamente.
  • Tu extensión puede renderizar documentos cargados dentro de elementos <embed>, <object> o <iframe>.
  • Los archivos locales (URLs file://) funcionan sin que el usuario habilite manualmente "Permitir acceso a URLs de archivos" en la configuración de la extensión.

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

Cómo registrar un controlador

Para registrar tu extensión como 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. Si se declara un tipo de MIME no compatible, se 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 previamente se vuelve a activar.

Recupera información de la transmisión

Cuando un usuario abre un documento de un tipo MIME registrado, Chrome carga la página del controlador en lugar del visor integrado. En la página del controlador, llama a getStreamInfo() para recuperar un objeto StreamInfo. Esto incluye el originalUrl al que navegó el usuario, el responseHeaders HTTP, si el documento se cargó 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. Si se realiza una segunda recuperación del mismo streamUrl, se producirá un error. 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.

Recurrir al controlador nativo

Es posible que tu controlador encuentre documentos que no pueda 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 dañada. Chrome descarga la página del controlador como parte de la resiliencia; no se ejecuta ningún código después de esta llamada.

Chrome almacena en búfer la respuesta mientras se ejecuta tu controlador. Si la respuesta se recibió por completo cuando llamas a este método, Chrome muestra 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 para los documentos que se entregan con POST o desde URLs de un solo uso. Recupera la transmisión por completo antes de decidir si puedes renderizarla. 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 la 151, una extensión que declara "mime_types_handler" se instala y ejecuta, pero no se registra como controlador y chrome.mimeHandler no está definido. Las extensiones que migran de la interceptación de solicitudes de red pueden verificar la API al inicio y mantener su enfoque existente como alternativa:

service-worker.js:

if (chrome.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 una transmisión

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 chrome.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.
    chrome.mimeHandler.abortAndFallbackToNativeHandler();
  }
}

loadDocument();

Control de alternancia para usuarios

Las opciones del 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 chrome.mimeHandler.getMimeHandlerOptions('application/pdf');
  // Handling is enabled unless it has been explicitly disabled.
  checkbox.checked = options.enabled !== false;
}

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

initOptions();

Tipos

MimeHandlerOptions

Propiedades

  • habilitado

    booleano

    Indica si este controlador está activo para el tipo de MIME determinado.

StreamInfo

Propiedades

  • Incorporado

    booleano

    Es verdadero si se carga en un contexto incorporado (iframe/incorporación/objeto).

  • mimeType

    string

    Es el tipo de MIME del contenido interceptado.

  • originalUrl

    string

    Es la URL original a la que navegó el usuario.

  • responseHeaders

    objeto

    Encabezados de respuesta HTTP como pares clave-valor.

  • streamUrl

    string

    Es la URL desde la que se recuperan los datos de transmisión.

  • tabId

    número

    Es el ID de la pestaña que contiene el documento.

Métodos

abortAndFallbackToNativeHandler()

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

Anula el control de transmisión actual y entrega el contenido al controlador nativo del agente de usuario. Después de esta llamada, se cerrará el marco de la extensión, por lo que los llamadores no deben esperar más ejecuciones.

Muestra

  • Promise<void>

getMimeHandlerOptions()

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

Lee las opciones persistentes para un tipo de MIME. Devuelve los valores predeterminados (enabled=true) si no se almacenó ninguno.

Parámetros

  • mimeType

    string

    Es el tipo de MIME cuyas opciones se leerán.

Muestra

  • Es la promesa que se resuelve con las opciones persistentes para el tipo de MIME.

getStreamInfo()

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

Recupera la información de transmisión para el contexto actual del controlador de MIME. Se debe llamar desde una página de extensión del controlador MIME.

Muestra

setMimeHandlerOptions()

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

Establece las opciones de configuración para un tipo de MIME especificado.

Parámetros

  • mimeType

    string

    Es el tipo de MIME que se configurará.

  • Las nuevas opciones para usar

Muestra

  • Promise<void>

    Promesa que se resuelve cuando se establece la configuración.