browser.mimeHandler

Descrizione

Disponibilità

Manifest

Concetti e utilizzo

In passato, le estensioni di terze parti che gestiscono tipi di documenti specifici (come i visualizzatori di PDF) si basavano sull'intercettazione delle richieste di rete per rilevare le navigazioni e reindirizzare gli utenti a una pagina dell'estensione. La registrazione come gestore MIME evita diverse limitazioni di questo approccio:

• L'URL originale rimane nella barra degli indirizzi anziché essere sostituito da un URL chrome-extension://.
• L'estensione recupera la risposta già ricevuta da Chrome, anziché effettuare una seconda richiesta di rete. I documenti inviati tramite richieste POST o da URL monouso funzionano correttamente.
• L'estensione può eseguire il rendering dei documenti caricati all'interno degli elementi <embed>, <object> o <iframe>.
• I file locali (URL file://) funzionano senza che l'utente debba attivare manualmente l'opzione "Consenti l'accesso agli URL dei file" nelle impostazioni dell'estensione.

I gestori MIME si applicano solo ai documenti che occupano un intero frame: navigazioni di primo livello e documenti incorporati. Non si applicano mai alle risorse secondarie incorporate (ad es. elementi <audio>, <img> o <video>).

Registra un gestore

Per registrare l'estensione come gestore MIME, dichiara la chiave "mime_types_handler" nel manifest. Ogni voce mappa un tipo MIME alla pagina dell'estensione che lo visualizza:

manifest.json:

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

Imposta "can_embed" su true per gestire anche i documenti incorporati negli elementi <embed>, <object> o <iframe>. Se omesso, il gestore riceve solo le navigazioni di primo livello. A partire da Chrome 151, application/pdf è l'unico tipo MIME disponibile per i gestori pubblici; la dichiarazione di un tipo MIME non supportato causa un avviso di installazione.

Se più estensioni installate si registrano per lo stesso tipo MIME, l'estensione installata più di recente lo gestisce. Se l'estensione viene disinstallata, il gestore installato in precedenza torna attivo.

Recupera le informazioni sullo stream

Quando un utente apre un documento di un tipo MIME registrato, Chrome carica la pagina del gestore al posto del visualizzatore integrato. Dalla pagina del gestore, chiama getStreamInfo() per recuperare un oggetto StreamInfo. Sono inclusi l'originalUrl a cui l'utente ha eseguito la navigazione, l'responseHeaders HTTP, se il documento è caricato in un contesto embedded e un streamUrl che può essere utilizzato per recuperare i contenuti del documento.

streamUrl può essere recuperato una sola volta e solo dall'origine dell'estensione. Leggi l'intera risposta prima di elaborarla; un secondo recupero dello stesso streamUrl non va a buon fine. Utilizza originalUrl quando mostri la posizione o il titolo del documento, non per recuperare i contenuti, perché la richiesta originale potrebbe non essere ripetibile.

Torna al gestore nativo

Il gestore potrebbe incontrare documenti di cui non è possibile eseguire il rendering, ad esempio file danneggiati o protetti da password. Chiama abortAndFallbackToNativeHandler() per interrompere la gestione del documento e restituirlo al visualizzatore integrato di Chrome, anziché lasciare l'utente su una pagina non funzionante. Chrome scarica la pagina del gestore nell'ambito del fallback; nessun codice viene eseguito dopo questa chiamata.

Chrome memorizza nel buffer la risposta mentre il gestore è in esecuzione. Se la risposta è stata ricevuta completamente quando chiami questo metodo, Chrome fornisce il visualizzatore integrato dalla copia memorizzata nel buffer senza una nuova richiesta di rete. In caso contrario, Chrome ricarica il documento dalla rete, il che potrebbe non riuscire per i documenti inviati tramite POST o da URL monouso. Recupera completamente lo stream prima di decidere se puoi eseguirne il rendering; una volta completato il recupero di streamUrl, Chrome ha la risposta completa.

Gestisci la disponibilità dell'API

Nelle versioni di Chrome precedenti a Chrome 151, un'estensione che dichiara "mime_types_handler" viene comunque installata ed eseguita, ma non viene registrata come gestore e browser.mimeHandler non è definita. Le estensioni che eseguono la migrazione dall'intercettazione delle richieste di rete possono verificare la presenza dell'API all'avvio e mantenere l'approccio esistente come opzione di riserva:

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.
}

Esempi

Gestisci uno stream

L'esempio seguente viene eseguito nella pagina del gestore dichiarata nel manifest. Recupera i contenuti del documento e, se il rendering non va a buon fine, utilizza il visualizzatore integrato di Chrome:

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

Consenti agli utenti di attivare/disattivare la gestione

Le opzioni del gestore vengono memorizzate per tipo MIME. L'esempio seguente utilizza getMimeHandlerOptions() e setMimeHandlerOptions() per consentire agli utenti di disattivare la gestione dalla pagina delle opzioni, senza disinstallare l'estensione. Quando la gestione è disattivata, i documenti di quel tipo non vengono più indirizzati alla tua estensione.

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

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

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

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

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