chrome.mimeHandler

Descrizione

Disponibilità

Manifest

Concetti e utilizzo

In passato, le estensioni di terze parti che gestiscono tipi di documenti specifici (come i visualizzatori PDF) si basavano sull'intercettazione delle richieste di rete per rilevare gli spostamenti 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://.
• 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 attivi 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 risorse secondarie inline (ad es. elementi <audio>, <img> o <video>).

Registrare 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 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 viene registrata per lo stesso tipo MIME, la gestione viene eseguita dall'estensione installata più di recente. Se l'estensione viene disinstallata, il gestore installato in precedenza torna 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 eseguito la navigazione, l'responseHeaders HTTP, se il documento viene caricato in un contesto embedded e un streamUrl che può essere utilizzato per recuperare i contenuti del documento.

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

Ripristinare il gestore nativo

Il gestore potrebbe riscontrare documenti che non può 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 danneggiata. Chrome scarica la pagina del gestore nell'ambito del fallback; dopo questa chiamata non viene eseguito alcun codice.

Chrome memorizza nella cache 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, 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.

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 è indefinito. 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 va a buon fine:

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 quel tipo non vengono più indirizzati alla tua 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>