browser.mimeHandler

Beschreibung

Verfügbarkeit

Manifest

Konzepte und Nutzung

Bisher haben Drittanbietererweiterungen, die bestimmte Dokumenttypen verarbeiten (z. B. PDF-Viewer), Netzwerkabfang verwendet, um Navigationsvorgänge abzufangen und Nutzer auf eine Erweiterungsseite umzuleiten. Durch die Registrierung als MIME-Handler werden mehrere Einschränkungen dieses Ansatzes vermieden:

• Die ursprüngliche URL bleibt in der Adressleiste und wird nicht durch eine chrome-extension://-URL ersetzt.
• Ihre Erweiterung ruft die Antwort ab, die Chrome bereits erhalten hat, anstatt eine zweite Netzwerkanfrage zu senden. Dokumente, die über POST-Anfragen oder Einmal-URLs bereitgestellt werden, funktionieren ordnungsgemäß.
• Ihre Erweiterung kann Dokumente rendern, die in den Elementen <embed>, <object> oder <iframe> geladen werden.
• Lokale Dateien (file://-URLs) funktionieren, ohne dass der Nutzer in den Einstellungen der Erweiterung manuell „Zugriff auf Datei-URLs zulassen“ aktivieren muss.

MIME-Handler werden nur auf Dokumente angewendet, die einen gesamten Frame einnehmen: Navigationen auf oberster Ebene und eingebettete Dokumente. Sie gelten nie für Inline-Unterressourcen (z.B. <audio>-, <img>- oder <video>-Elemente).

Handler registrieren

Wenn Sie Ihre Erweiterung als MIME-Handler registrieren möchten, deklarieren Sie den Schlüssel "mime_types_handler" im Manifest. Jeder Eintrag ordnet einen MIME-Typ der Erweiterungsseite zu, auf der er gerendert wird:

manifest.json:

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

Legen Sie "can_embed" auf true fest, um auch Dokumente zu verarbeiten, die in <embed>-, <object>- oder <iframe>-Elemente eingebettet sind. Wird diese Option nicht angegeben, empfängt Ihr Handler nur Navigationen der obersten Ebene. Ab Chrome 151 ist application/pdf der einzige MIME-Typ, der für öffentliche Handler verfügbar ist. Wenn Sie einen nicht unterstützten MIME-Typ deklarieren, wird eine Installationswarnung angezeigt.

Wenn mehr als eine installierte Erweiterung für denselben MIME-Typ registriert ist, wird er von der zuletzt installierten Erweiterung verarbeitet. Wenn diese Erweiterung deinstalliert wird, wird der zuvor installierte Handler wieder aktiv.

Streaminformationen abrufen

Wenn ein Nutzer ein Dokument mit einem registrierten MIME-Typ öffnet, lädt Chrome anstelle des integrierten Viewers Ihre Handler-Seite. Rufen Sie auf der Handler-Seite getStreamInfo() auf, um ein StreamInfo-Objekt abzurufen. Dazu gehören die originalUrl, zu der der Nutzer navigiert hat, der HTTP-responseHeaders, ob das Dokument in einem embedded-Kontext geladen wird, und eine streamUrl, mit der der Inhalt des Dokuments abgerufen werden kann.

Die streamUrl kann genau einmal und nur vom Ursprung Ihrer Erweiterung abgerufen werden. Lesen Sie die Antwort vollständig, bevor Sie sie verarbeiten. Ein zweiter Abruf derselben streamUrl schlägt fehl. Verwenden Sie originalUrl, um den Speicherort oder Titel des Dokuments anzuzeigen, nicht um den Inhalt abzurufen, da die ursprüngliche Anfrage möglicherweise nicht wiederholt werden kann.

Auf den nativen Handler zurückgreifen

Ihr Handler kann auf Dokumente stoßen, die er nicht rendern kann, z. B. beschädigte oder passwortgeschützte Dateien. Rufen Sie abortAndFallbackToNativeHandler() auf, um die Verarbeitung des Dokuments zu beenden und es an den integrierten Viewer von Chrome zurückzugeben, anstatt den Nutzer auf einer fehlerhaften Seite zu lassen. Chrome entlädt Ihre Handlerseite als Teil des Fallbacks. Nach diesem Aufruf wird kein Code mehr ausgeführt.

Chrome puffert die Antwort, während Ihr Handler ausgeführt wird. Wenn die Antwort vollständig empfangen wurde, wenn Sie diese Methode aufrufen, stellt Chrome den integrierten Viewer aus der gepufferten Kopie ohne eine neue Netzwerkanfrage bereit. Andernfalls lädt Chrome das Dokument aus dem Netzwerk neu, was bei Dokumenten, die per POST oder über Einmal-URLs bereitgestellt werden, fehlschlagen kann. Rufen Sie den Stream vollständig ab, bevor Sie entscheiden, ob Sie ihn rendern können. Sobald der Abruf von streamUrl abgeschlossen ist, hat Chrome die vollständige Antwort.

API-Verfügbarkeit berücksichtigen

In Chrome-Versionen vor Chrome 151 wird eine Erweiterung, die "mime_types_handler" deklariert, weiterhin installiert und ausgeführt, aber nicht als Handler registriert und browser.mimeHandler ist nicht definiert. Erweiterungen, die von der Abfangung von Netzwerkanfragen migrieren, können beim Start nach der API suchen und ihren bisherigen Ansatz als Fallback beibehalten:

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

Beispiele

Stream verarbeiten

Das folgende Beispiel wird auf der Handler-Seite ausgeführt, die im Manifest deklariert ist. Es ruft den Inhalt des Dokuments ab und greift auf den integrierten Viewer von Chrome zurück, wenn das Rendern fehlschlägt:

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

Nutzern erlauben, die Verarbeitung zu aktivieren/deaktivieren

Handler-Optionen werden pro MIME-Typ gespeichert. Im folgenden Beispiel werden getMimeHandlerOptions() und setMimeHandlerOptions() verwendet, damit Nutzer die Verarbeitung auf der Optionsseite deaktivieren können, ohne die Erweiterung deinstallieren zu müssen. Wenn die Verarbeitung deaktiviert ist, werden Dokumente dieses Typs nicht mehr an Ihre Erweiterung weitergeleitet.

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>