browser.mimeHandler

Beschreibung

Verwenden Sie die chrome.mimeHandler API, um MIME-Typ-Streams in Drittanbietererweiterungen zu verarbeiten.

Verfügbarkeit

Chrome 151 oder höher

Manifest

Die folgenden Schlüssel müssen im Manifest deklariert werden, um diese API zu verwenden.

"mime_types_handler"

Konzepte und Verwendung

Bisher haben Erweiterungen von Drittanbietern, die bestimmte Dokumenttypen verarbeiten (z. B. PDF-Viewer), das Abfangen von Netzwerkanfragen genutzt, um Navigationen zu erfassen und Nutzer auf eine Erweiterungsseite weiterzuleiten. Durch die Registrierung als MIME-Handler werden mehrere Einschränkungen dieses Ansatzes vermieden:

  • Die ursprüngliche URL bleibt in der Adressleiste, anstatt durch eine chrome-extension://-URL ersetzt zu werden.
  • Ihre Erweiterung ruft die Antwort ab, die Chrome bereits erhalten hat, anstatt eine zweite Netzwerkanfrage zu stellen. Dokumente, die über POST-Anfragen oder Einmal-URLs bereitgestellt werden, funktionieren ordnungsgemäß.
  • Ihre Erweiterung kann Dokumente rendern, die in <embed>-, <object>- oder <iframe>-Elementen 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 gelten nur für Dokumente, die einen gesamten Frame belegen: 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, die ihn rendert:

manifest.json:

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

Setzen Sie "can_embed" auf true, um auch Dokumente zu verarbeiten, die in <embed>-, <object>- oder <iframe>-Elemente eingebettet sind. Wenn Sie ihn weglassen, empfängt Ihr Handler nur Navigationen auf oberster 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 sich mehr als eine installierte Erweiterung für denselben MIME-Typ registriert, 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 die Handler-Seite anstelle des integrierten Viewers. Rufen Sie auf der Handler-Seite getStreamInfo() auf, um ein StreamInfo-Objekt abzurufen. Dazu gehören die originalUrl, die der Nutzer aufgerufen hat, die HTTP-responseHeaders, ob das Dokument in einem embedded-Kontext geladen wird, und eine streamUrl, mit der der Inhalt des Dokuments abgerufen werden kann.

Der 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 desselben streamUrl schlägt fehl. Verwenden Sie originalUrl, wenn Sie den Speicherort oder Titel des Dokuments anzeigen, nicht um den Inhalt abzurufen, da die ursprüngliche Anfrage möglicherweise nicht wiederholt werden kann.

Fallback auf den nativen Handler

Ihr Handler kann möglicherweise 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 belassen. Chrome entlädt die Handler-Seite im Rahmen des Fallbacks. Nach diesem Aufruf wird kein Code mehr ausgeführt.

Chrome puffert die Antwort, während der 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 bereit, ohne eine neue Netzwerkanfrage zu senden. Andernfalls lädt Chrome das Dokument aus dem Netzwerk neu. Dies kann bei Dokumenten, die über POST oder von Einmal-URLs bereitgestellt werden, fehlschlagen. Rufe den Stream vollständig ab, bevor du entscheidest, ob du ihn rendern kannst. Sobald der Abruf von streamUrl abgeschlossen ist, hat Chrome die vollständige Antwort.

API-Verfügbarkeit verwalten

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 migriert werden, können beim Start nach der API suchen und ihren vorhandenen 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 im Manifest deklarierten Handler-Seite ausgeführt. Sie ruft den Inhalt des Dokuments ab und greift auf den integrierten Viewer von Chrome zurück, wenn das Rendering 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 oder zu 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 zu deinstallieren. 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();

Typen

MimeHandlerOptions

Attribute

  • canEmbed

    Boolesch optional

    Chrome 157 oder höher

    Gibt an, ob dieser Handler für eingebettete Ladevorgänge (iframe, embed, object) verwendet werden darf. Der Standardwert ist der can_embed-Wert des Manifesteintrags. Hat keine Auswirkungen, wenn enabled auf „false“ gesetzt ist.

  • aktiviert

    Boolesch optional

    Gibt an, ob dieser Handler aktiviert ist. Der Standardwert ist der enabled-Wert des Manifesteintrags.

StreamInfo

Attribute

  • eingebettet

    boolean

    „True“, wenn in einem eingebetteten Kontext (iframe/embed/object) geladen.

  • mimeType

    String

    Der MIME-Typ des abgefangenen Inhalts.

  • originalUrl

    String

    Die ursprüngliche URL, die der Nutzer aufgerufen hat.

  • responseHeaders

    Objekt

    HTTP-Antwortheader als Schlüssel/Wert-Paare.

  • streamUrl

    String

    Die URL, von der die Streamdaten abgerufen werden sollen.

  • tabId

    Zahl

    Die ID des Tabs, der das Dokument enthält.

Methoden

abortAndFallbackToNativeHandler()

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

Bricht die aktuelle Streamverarbeitung ab und übergibt den Inhalt an den nativen Handler des User-Agents. Nach diesem Aufruf wird der Erweiterungs-Frame abgebaut. Aufrufer sollten keine weitere Ausführung erwarten.

Ausgabe

  • Promise<void>

getMimeHandlerOptions()

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

Liest die Optionen für einen MIME-Typ. Jedes Mitglied ist der von der Erweiterung festgelegte Wert oder der Wert des Manifesteintrags, wenn die Erweiterung ihn nicht festgelegt hat.

Parameter

  • mimeType

    String

    Der MIME-Typ, dessen Optionen gelesen werden sollen. Es muss sich um einen MIME-Typ handeln, den die Erweiterung über „mime_types_handler“ verarbeitet.

Ausgabe

getStreamInfo()

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

Ruft Streaminformationen für den aktuellen MIME-Handler-Kontext ab. Muss von einer MIME-Handler-Erweiterungsseite aus aufgerufen werden.

Ausgabe

setMimeHandlerOptions()

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

Legt die Konfigurationsoptionen für einen angegebenen MIME-Typ fest. Wenn die Erweiterung im geteilten Inkognitomodus ausgeführt wird, gelten die im Inkognitomodus festgelegten Optionen nur für den Inkognitomodus und nur bis zum Ende der Inkognitositzung. Optionen, die nicht im Inkognitomodus festgelegt wurden, folgen den Werten, die außerhalb des Inkognitomodus festgelegt wurden.

Parameter

  • mimeType

    String

    Der zu konfigurierende MIME-Typ. Es muss sich um einen MIME-Typ handeln, den die Erweiterung über „mime_types_handler“ verarbeitet.

  • Die zu ändernden Optionen.

Ausgabe

  • Promise<void>

    Promise, das aufgelöst wird, wenn die Konfiguration festgelegt wurde.