chrome.mimeHandler

Descrizione

Disponibilità

Manifest

Concetti e utilizzo

Storicamente, le estensioni di terze parti che gestiscono tipi di documenti specifici (ad esempio i visualizzatori PDF) si basavano sull'intercettazione delle richieste di rete per intercettare le navigazioni e reindirizzare gli utenti a una pagina di 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://.
• La tua estensione recupera la risposta già ricevuta da Chrome, anziché effettuare una seconda richiesta di rete. I documenti forniti dalle richieste POST o dagli URL monouso funzionano correttamente.
• La tua 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 "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 sottorisorse in linea (ad es. <audio>, <img>, o <video> elementi).

Registrare un gestore

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

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ù di un'estensione installata si registra per lo stesso tipo MIME, la più recente gestisce il tipo MIME. Se l'estensione viene disinstallata, il gestore installato in precedenza diventa di nuovo attivo.

Recuperare 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 navigato, le responseHeaders HTTP, se il documento è caricato in un contesto embedded e un streamUrl che può essere utilizzato per recuperare i contenuti del documento.

L'streamUrl può essere recuperato esattamente una volta e solo dall'origine dell'estensione. Leggi completamente la risposta prima di elaborarla; un secondo recupero dello stesso streamUrl non riesce. Utilizza originalUrl quando visualizzi la posizione o il titolo del documento, non per recuperare i contenuti, perché la richiesta originale potrebbe non essere ripetibile.

Tornare 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 come parte del fallback; nessun codice viene eseguito dopo questa chiamata.

Chrome memorizza nel buffer la risposta durante l'esecuzione del gestore. Se la risposta è stata ricevuta completamente quando chiami questo metodo, Chrome mostra il visualizzatore integrato dalla copia memorizzata nel buffer senza una nuova richiesta di rete. In caso contrario, Chrome ricarica il documento dalla rete, operazione che potrebbe non riuscire per i documenti forniti 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.

Gestire la disponibilità dell'API

Nelle versioni di Chrome precedenti alla 151, un'estensione che dichiara "mime_types_handler" viene comunque installata ed eseguita, ma non viene registrata come gestore e chrome.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 fallback:

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

Esempi

Gestire uno stream

L'esempio seguente viene eseguito nella pagina del gestore dichiarata nel manifest. Recupera i contenuti del documento e torna al visualizzatore integrato di Chrome se il rendering non riesce:

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

Consentire 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 questo tipo non vengono più indirizzati all'estensione.

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

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>