chrome.mimeHandler

Description

Utilisez l'API chrome.mimeHandler pour gérer les flux de type MIME dans les extensions tierces.

Disponibilité

En attente

Fichier manifeste

Les clés suivantes doivent être déclarées dans le fichier manifeste pour utiliser cette API.

"mime_types_handler"

Concepts et utilisation

Auparavant, les extensions tierces qui géraient des types de documents spécifiques (tels que les lecteurs PDF) s'appuyaient sur l'interception des requêtes réseau pour intercepter les navigations et rediriger les utilisateurs vers une page d'extension. L'enregistrement en tant que gestionnaire MIME évite plusieurs limites de cette approche :

  • L'URL d'origine reste dans la barre d'adresse au lieu d'être remplacée par une URL chrome-extension://.
  • Votre extension récupère la réponse que Chrome a déjà reçue, au lieu d'effectuer une deuxième requête réseau. Les documents fournis par des requêtes POST ou à partir d'URL à usage unique fonctionnent correctement.
  • Votre extension peut afficher des documents chargés dans des éléments <embed>, <object>, ou <iframe>.
  • Les fichiers locaux (URL file://) fonctionnent sans que l'utilisateur n'ait à activer manuellement "Autoriser l'accès aux URL de fichiers" dans les paramètres de l'extension.

Les gestionnaires MIME ne s'appliquent qu'aux documents qui occupent une frame entière : les navigations de premier niveau et les documents intégrés. Ils ne s'appliquent jamais aux sous-ressources intégrées (par exemple, les éléments <audio>, <img> ou <video>).

Enregistrer un gestionnaire

Pour enregistrer votre extension en tant que gestionnaire MIME, déclarez la "mime_types_handler" clé dans le fichier manifeste. Chaque entrée mappe un type MIME à la page d'extension qui l'affiche :

manifest.json:

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

Définissez "can_embed" sur true pour gérer également les documents intégrés dans des éléments <embed>, <object> ou <iframe>. Si vous omettez ce paramètre, votre gestionnaire ne reçoit que les navigations de premier niveau. À partir de Chrome 151, application/pdf est le seul type MIME disponible pour les gestionnaires publics. La déclaration d'un type MIME non compatible entraîne un avertissement d'installation.

Si plusieurs extensions installées s'enregistrent pour le même type MIME, l'extension installée le plus récemment le gère. Si cette extension est désinstallée, le gestionnaire installé précédemment redevient actif.

Récupérer des informations sur le flux

Lorsqu'un utilisateur ouvre un document d'un type MIME enregistré, Chrome charge la page de votre gestionnaire à la place de son lecteur intégré. Sur la page du gestionnaire, appelez getStreamInfo() pour récupérer un objet StreamInfo. Cela inclut l'originalUrl vers lequel l'utilisateur a navigué, les responseHeaders HTTP, si le document est chargé dans un contexte embedded et un streamUrl qui peut être utilisé pour extraire le contenu du document.

Le streamUrl ne peut être récupéré qu'une seule fois et uniquement à partir de l'origine de votre extension. Lisez la réponse entièrement avant de la traiter. Une deuxième récupération du même streamUrl échoue. Utilisez originalUrl lorsque vous affichez l'emplacement ou le titre du document, et non pour extraire le contenu, car la requête d'origine n'est peut-être pas répétable.

Revenir au gestionnaire natif

Votre gestionnaire peut rencontrer des documents qu'il ne peut pas afficher, tels que des fichiers corrompus ou protégés par un mot de passe. Appelez abortAndFallbackToNativeHandler() pour arrêter la gestion du document et le renvoyer au lecteur intégré de Chrome, plutôt que de laisser l'utilisateur sur une page défectueuse. Chrome décharge la page de votre gestionnaire dans le cadre du retour en arrière. Aucun code ne s'exécute après cet appel.

Chrome met en mémoire tampon la réponse pendant l'exécution de votre gestionnaire. Si la réponse a été entièrement reçue lorsque vous appelez cette méthode, Chrome diffuse le lecteur intégré à partir de la copie mise en mémoire tampon sans nouvelle requête réseau. Sinon, Chrome recharge le document à partir du réseau, ce qui peut échouer pour les documents fournis par POST ou à partir d'URL à usage unique. Récupérez le flux entièrement avant de décider si vous pouvez l'afficher. Une fois l'extraction de streamUrl terminée, Chrome dispose de la réponse complète.

Gérer la disponibilité de l'API

Dans les versions de Chrome antérieures à Chrome 151, une extension déclarant "mime_types_handler" s'installe et s'exécute toujours, mais n'est pas enregistrée en tant que gestionnaire et chrome.mimeHandler n'est pas défini. Les extensions qui migrent depuis l'interception des requêtes réseau peuvent vérifier l'API au démarrage et conserver leur approche existante comme solution de secours :

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

Exemples

Gérer un flux

L'exemple suivant s'exécute sur la page du gestionnaire déclarée dans le fichier manifeste. Il extrait le contenu du document et revient au lecteur intégré de Chrome si l'affichage échoue :

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

Autoriser les utilisateurs à activer/désactiver la gestion

Les options du gestionnaire sont stockées par type MIME. L'exemple suivant utilise getMimeHandlerOptions() et setMimeHandlerOptions() pour permettre aux utilisateurs de désactiver la gestion à partir de la page d'options, sans désinstaller l'extension. Lorsque la gestion est désactivée, les documents de ce type ne sont plus acheminés vers votre extension.

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

Types

MimeHandlerOptions

Propriétés

  • activé

    booléen

    Indique si ce gestionnaire est actif pour le type MIME donné.

StreamInfo

Propriétés

  • intégré

    booléen

    La valeur est "true" si le contenu est chargé dans un contexte intégré (iframe/embed/object).

  • mimeType

    chaîne

    Type MIME du contenu intercepté.

  • originalUrl

    chaîne

    URL d'origine vers laquelle l'utilisateur a navigué.

  • responseHeaders

    objet

    En-têtes de réponse HTTP sous forme de paires clé/valeur.

  • streamUrl

    chaîne

    URL à partir de laquelle extraire les données de flux.

  • tabId

    nombre

    ID de l'onglet contenant le document.

Méthodes

abortAndFallbackToNativeHandler()

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

Interrompt la gestion du flux actuel et transmet le contenu au gestionnaire natif de l'agent utilisateur. Après cet appel, le frame d'extension sera supprimé. Les appelants ne doivent pas s'attendre à une exécution supplémentaire.

Renvoie

  • Promise<void>

getMimeHandlerOptions()

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

Lit les options persistantes pour un type MIME. Renvoie les valeurs par défaut (enabled=true) si aucune n'a été stockée.

Paramètres

  • mimeType

    chaîne

    Type MIME dont les options doivent être lues.

Renvoie

  • Promesse résolue avec les options persistantes pour le type MIME.

getStreamInfo()

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

Récupère les informations de flux pour le contexte actuel du gestionnaire MIME. Doit être appelé à partir d'une page d'extension du gestionnaire MIME.

Renvoie

setMimeHandlerOptions()

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

Définit les options de configuration pour un type MIME spécifié.

Paramètres

  • mimeType

    chaîne

    Type MIME à configurer.

  • Nouvelles options à utiliser.

Renvoie

  • Promise<void>

    Promesse résolue une fois la configuration définie.