browser.mimeHandler

Beschrijving

Beschikbaarheid

Manifest

Concepten en gebruik

In het verleden vertrouwden extensies van derden die specifieke documenttypen verwerken (zoals pdf-viewers) op onderschepping van netwerkverzoeken om navigaties vast te leggen en gebruikers om te leiden naar een extensiepagina. Als je je registreert als MIME-handler, vermijd je verschillende beperkingen van die aanpak:

• De oorspronkelijke URL blijft in de adresbalk staan in plaats van te worden vervangen door een chrome-extension://-URL.
• Je extensie haalt de reactie op die Chrome al heeft gekregen, in plaats van een 2e netwerkverzoek te doen. Documenten die worden geleverd via POST-verzoeken of via URL's voor eenmalig gebruik, werken correct.
• Je extensie kan documenten weergeven die zijn geladen in <embed>-, <object>- of <iframe>-elementen.
• Lokale bestanden (file://-URL's) werken zonder dat de gebruiker handmatig Toegang tot bestands-URL's toestaan aanzet in de instellingen van de extensie.

MIME-handlers zijn alleen van toepassing op documenten die een heel frame in beslag nemen: navigatie op het hoogste niveau en ingesloten documenten. Ze zijn nooit van toepassing op inline subbronnen (bijvoorbeeld <audio>-, <img>- of <video>-elementen).

Een handler registreren

Als je je extensie wilt registreren als MIME-handler, definieer je de sleutel "mime_types_handler" in het manifest. Elke invoer wijst een MIME-type toe aan de extensiepagina die het weergeeft:

manifest.json:

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

Stel "can_embed" in op true om ook documenten te verwerken die zijn ingesloten in <embed>-, <object>- of <iframe>-elementen. Als je dit weglaat, krijgt je handler alleen navigaties op het hoogste niveau. Vanaf Chrome 151 is application/pdf het enige MIME-type dat beschikbaar is voor openbare handlers. Als je een niet-ondersteund MIME-type declareert, krijg je een installatiewaarschuwing.

Als meer dan één geïnstalleerde extensie zich registreert voor hetzelfde MIME-type, wordt dit verwerkt door de meest recent geïnstalleerde extensie. Als die extensie wordt verwijderd, wordt de eerder geïnstalleerde handler weer actief.

Streaminformatie ophalen

Als een gebruiker een document van een geregistreerd MIME-type opent, laadt Chrome je handlerpagina in plaats van de ingebouwde viewer. Roep op de handlerpagina getStreamInfo() aan om een StreamInfo-object op te halen. Dit omvat de originalUrl waarnaar de gebruiker is genavigeerd, de HTTP responseHeaders, of het document is geladen in een embedded-context en een streamUrl die kan worden gebruikt om de content van het document op te halen.

De streamUrl kan precies één keer worden opgehaald en alleen vanuit de oorsprong van je extensie. Lees de reactie volledig voordat je deze verwerkt. Een 2e ophaalpoging van dezelfde streamUrl mislukt. Gebruik originalUrl als je de locatie of titel van het document wilt tonen, niet om de content op te halen, omdat het oorspronkelijke verzoek misschien niet kan worden herhaald.

Terugvallen op de systeemeigen handler

Uw handler kan documenten tegenkomen die niet kunnen worden gerenderd, zoals beschadigde bestanden of bestanden die met een wachtwoord zijn beveiligd. Roep abortAndFallbackToNativeHandler() aan om de verwerking van het document te stoppen en het terug te geven aan de ingebouwde viewer van Chrome, in plaats van de gebruiker op een niet-werkende pagina achter te laten. Chrome verwijdert je handlerpagina als onderdeel van de fallback. Na deze aanroep wordt er geen code meer uitgevoerd.

Chrome buffert de reactie terwijl je handler wordt uitgevoerd. Als de reactie volledig is ontvangen wanneer je deze methode aanroept, levert Chrome de ingebouwde viewer vanuit de gebufferde kopie zonder een nieuw netwerkverzoek. Anders laadt Chrome het document opnieuw vanuit het netwerk. Dit kan mislukken voor documenten die worden geleverd via POST of via URL's voor eenmalig gebruik. Haal de stream volledig op voordat je beslist of je deze kunt renderen. Nadat het ophalen van streamUrl is afgerond, heeft Chrome de volledige reactie.

API-beschikbaarheid verwerken

In Chrome-versies vóór Chrome 151 wordt een extensie die "mime_types_handler" declareert nog steeds geïnstalleerd en uitgevoerd, maar wordt deze niet geregistreerd als handler en is browser.mimeHandler niet gedefinieerd. Extensies die migreren van onderschepping van netwerkverzoeken, kunnen bij het opstarten controleren of de API aanwezig is en hun bestaande aanpak als fallback behouden:

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

Voorbeelden

Een stream verwerken

Het volgende voorbeeld wordt uitgevoerd op de handlerpagina die in het manifest is gedefinieerd. De extensie haalt de content van het document op en valt terug op de ingebouwde viewer van Chrome als de weergave mislukt:

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

Gebruikers toestaan de verwerking aan of uit te zetten

Handleropties worden per MIME-type opgeslagen. In het volgende voorbeeld worden getMimeHandlerOptions() en setMimeHandlerOptions() gebruikt om gebruikers de mogelijkheid te geven de verwerking uit te zetten op de optiepagina, zonder de extensie te verwijderen. Als de verwerking is uitgezet, worden documenten van dat type niet meer naar je extensie geleid.

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>