chrome.mimeHandler

Beschreibung

Mit der chrome.mimeHandler API können Sie MIME-Typ-Streams in Erweiterungen von Drittanbietern verarbeiten.

Verfügbarkeit

Ausstehend

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), Netzwerk-Anfragen abgefangen, um Navigations zu erfassen und Nutzer zu einer Erweiterungsseite weiterzuleiten. Wenn Sie sich als MIME-Handler registrieren, können Sie mehrere Einschränkungen dieses Ansatzes vermeiden:

  • 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 senden. Dokumente, die per POST-Anfrage oder über URLs zur einmaligen Verwendung bereitgestellt werden, funktionieren korrekt.
  • Ihre Erweiterung kann Dokumente rendern, die in den Elementen <embed>, <object>, oder <iframe> geladen wurden.
  • 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 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 "mime_types_handler" Schlüssel 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
    }
  },
  ...
}

Setzen Sie "can_embed" auf true, um auch Dokumente zu verarbeiten, die in den Elementen <embed>, <object> oder <iframe> eingebettet sind. Wenn Sie diese Option nicht angeben, 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 aktiviert.

Streaminformationen abrufen

Wenn ein Nutzer ein Dokument mit einem registrierten MIME-Typ öffnet, lädt Chrome Ihre Handler-Seite anstelle des integrierten Viewers. Rufen Sie auf der Handler-Seite getStreamInfo() auf, um ein StreamInfo-Objekt abzurufen. Dieses Objekt enthält die originalUrl, zu der der Nutzer navigiert ist, die HTTP-responseHeaders, Informationen dazu, ob das Dokument in einem embedded-Kontext geladen wurde, 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, wenn Sie den Speicherort oder Titel des Dokuments anzeigen, aber nicht, um den Inhalt abzurufen, da die ursprüngliche Anfrage möglicherweise nicht wiederholt werden kann.

Auf den nativen Handler zurückgreifen

Ihr Handler stößt möglicherweise auf Dokumente, 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 zu übergeben, anstatt den Nutzer auf einer fehlerhaften Seite zu lassen. Chrome entlädt Ihre Handler-Seite im Rahmen 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, als Sie diese Methode aufgerufen haben, 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. Das kann bei Dokumenten, die per POST oder über URLs zur einmaligen Verwendung bereitgestellt werden, fehlschlagen. 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 verarbeiten

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 chrome.mimeHandler ist nicht definiert. Erweiterungen, die von der Abfangung von Netzwerkanfragen migrieren, können beim Start nach der API suchen und ihren vorhandenen Ansatz als Fallback beibehalten:

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

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 Rendering fehlschlägt:

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

Nutzern das Umschalten der Verarbeitung ermöglichen

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

Typen

MimeHandlerOptions

Properties

  • aktiviert

    boolean

    Gibt an, ob dieser Handler für den angegebenen MIME-Typ aktiv ist.

StreamInfo

Properties

  • 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, zu der der Nutzer navigiert ist.

  • responseHeaders

    Objekt

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

  • streamUrl

    String

    Die URL, von der die Streamdaten abgerufen werden sollen.

  • tabId

    Zahl

    Die Tab-ID mit dem Dokument.

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 Erweiterungsframe entfernt. Aufrufer sollten keine weitere Ausführung erwarten.

Ausgabe

  • Promise<void>

getMimeHandlerOptions()

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

Liest die gespeicherten Optionen für einen MIME-Typ. Wenn keine Optionen gespeichert wurden, werden die Standardwerte zurückgegeben (enabled=true).

Parameter

  • mimeType

    String

    Der MIME-Typ, dessen Optionen gelesen werden sollen.

Ausgabe

  • Promise, das mit den gespeicherten Optionen für den MIME-Typ aufgelöst wurde.

getStreamInfo()

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

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

Ausgabe

setMimeHandlerOptions()

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

Legt die Konfigurationsoptionen für einen angegebenen MIME-Typ fest.

Parameter

  • mimeType

    String

    Der zu konfigurierende MIME-Typ.

  • Die neuen Optionen, die verwendet werden sollen.

Ausgabe

  • Promise<void>

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