chrome.mimeHandler

Beschrijving

Gebruik de chrome.mimeHandler API om MIME-typestreams in extensies van derden te verwerken.

Beschikbaarheid

In behandeling

Manifest

De volgende sleutels moeten in het manifest worden gedeclareerd om deze API te kunnen gebruiken.

"mime_types_handler"

Concepten en gebruik

Historisch gezien vertrouwden extensies van derden die specifieke documenttypen verwerken (zoals PDF-viewers) op het onderscheppen van netwerkverzoeken om navigaties te vangen en gebruikers door te sturen naar een extensiepagina. Registratie als MIME-handler omzeilt een aantal beperkingen van die aanpak:

  • De oorspronkelijke URL blijft in de adresbalk staan ​​in plaats van te worden vervangen door een URL chrome-extension:// .
  • Uw extensie haalt het antwoord op dat Chrome al heeft ontvangen, in plaats van een tweede netwerkverzoek te doen. Documenten die via POST-verzoeken of via eenmalige URL's worden aangeleverd, werken correct.
  • Uw extensie kan documenten weergeven die zijn geladen binnen <embed> , <object> of <iframe> elementen.
  • Lokale bestanden ( file:// -URL's) werken zonder dat de gebruiker handmatig "Toegang tot bestands-URL's toestaan" in de extensie-instellingen hoeft in te schakelen.

MIME-handlers zijn alleen van toepassing op documenten die een volledig frame vullen: navigaties op het hoogste niveau en ingesloten documenten. Ze zijn nooit van toepassing op inline subbronnen (bijv. <audio> , <img> of <video> elementen).

Een handler registreren

Om uw extensie als MIME-handler te registreren, declareert u de sleutel "mime_types_handler" in het manifest . Elke vermelding koppelt een MIME-type 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. Indien dit wordt weggelaten, ontvangt uw handler alleen navigaties op het hoogste niveau. Vanaf Chrome 151 is application/pdf het enige MIME-type dat beschikbaar is voor openbare handlers; het declareren van een niet-ondersteund MIME-type veroorzaakt een installatiewaarschuwing.

Als meerdere geïnstalleerde extensies zich registreren voor hetzelfde MIME-type, wordt dit afgehandeld door de laatst geïnstalleerde extensie. Als die extensie wordt verwijderd, wordt de eerder geïnstalleerde handler weer actief.

Streaminformatie ophalen

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

De streamUrl kan slechts één keer worden opgehaald, en alleen vanaf de bron van uw extensie. Lees het antwoord volledig door voordat u het verwerkt; een tweede ophaalactie van dezelfde streamUrl mislukt. Gebruik originalUrl om de locatie of titel van het document weer te geven, niet om de inhoud op te halen, omdat het oorspronkelijke verzoek mogelijk niet herhaalbaar is.

Terugvallen op de native handler

Uw handler kan documenten tegenkomen die niet kunnen worden weergegeven, zoals beschadigde of met een wachtwoord beveiligde bestanden. 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 defecte pagina achter te laten. Chrome sluit uw handlerpagina af als onderdeel van de terugvalprocedure; er wordt na deze aanroep geen code meer uitgevoerd.

Chrome buffert het antwoord terwijl uw handler wordt uitgevoerd. Als het antwoord volledig is ontvangen wanneer u deze methode aanroept, serveert Chrome de ingebouwde viewer vanuit de gebufferde kopie zonder een nieuw netwerkverzoek. Anders laadt Chrome het document opnieuw vanuit het netwerk, wat kan mislukken voor documenten die via POST of via eenmalige URL's worden aangeleverd. Haal de stream volledig op voordat u besluit of u deze kunt weergeven; zodra het ophalen van streamUrl is voltooid, heeft Chrome het volledige antwoord.

Beheer de beschikbaarheid van de API

In Chrome-versies ouder dan 151 installeert en draait een extensie die "mime_types_handler" declareert nog steeds, maar wordt deze niet geregistreerd als handler en is chrome.mimeHandler niet gedefinieerd. Extensies die migreren van het onderscheppen van netwerkverzoeken kunnen bij het opstarten controleren of de API beschikbaar is en hun bestaande aanpak als terugvaloptie behouden.

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

Voorbeelden

Een stream verwerken

Het volgende voorbeeld wordt uitgevoerd op de handlerpagina die in het manifest is gedeclareerd. Het haalt de inhoud van het document op en schakelt over naar de ingebouwde viewer van Chrome als het renderen mislukt:

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

Laat gebruikers de verwerking in- of uitschakelen

Handleropties worden per MIME-type opgeslagen. Het volgende voorbeeld gebruikt getMimeHandlerOptions() en setMimeHandlerOptions() om gebruikers de mogelijkheid te geven de afhandeling uit te schakelen via de optiepagina, zonder de extensie te hoeven verwijderen. Zolang de afhandeling is uitgeschakeld, worden documenten van dat type niet langer naar uw extensie doorgestuurd.

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

Soorten

MimeHandlerOptions

Eigenschappen

  • ingeschakeld

    booleaans

    Of deze handler actief is voor het betreffende MIME-type.

StreamInfo

Eigenschappen

  • ingebed

    booleaans

    Als het geladen is in een ingebedde context (iframe/embed/object), is dit waar.

  • mimeType

    snaar

    Het MIME-type van de onderschepte inhoud.

  • origineleUrl

    snaar

    De oorspronkelijke URL waarnaar de gebruiker is doorgestuurd.

  • antwoordHeaders

    voorwerp

    HTTP-antwoordheaders als sleutel-waardeparen.

  • streamUrl

    snaar

    De URL waarvandaan de streamgegevens moeten worden opgehaald.

  • tabId

    nummer

    De tab-ID die het document bevat.

Methoden

abortAndFallbackToNativeHandler()

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

De huidige streamverwerking wordt afgebroken en de inhoud wordt overgedragen aan de native handler van de user agent. Na deze aanroep wordt het extensieframe verwijderd; bellers moeten geen verdere uitvoering verwachten.

Retourneert

  • Promise<void>

getMimeHandlerOptions()

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

Leest de opgeslagen opties voor een MIME-type. Retourneert de standaardwaarden (enabled=true) als er geen opties zijn opgeslagen.

Parameters

  • mimeType

    snaar

    Het MIME-type waarvan de opties moeten worden gelezen.

Retourneert

  • Promise< MimeHandlerOptions >

    De belofte is opgelost met de opgeslagen opties voor het MIME-type.

getStreamInfo()

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

Haalt streaminformatie op voor de huidige MIME-handlercontext. Deze functie moet worden aangeroepen vanuit een MIME-handler-extensiepagina.

Retourneert

setMimeHandlerOptions()

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

Hiermee worden de configuratieopties voor een specifiek MIME-type ingesteld.

Parameters

  • mimeType

    snaar

    Het te configureren MIME-type.

  • De nieuwe gebruiksmogelijkheden.

Retourneert

  • Promise<void>

    De belofte is vervuld zodra de configuratie is ingesteld.