browser.mimeHandler

Description

Disponibilité

Fichier manifeste

Concepts et utilisation

Auparavant, les extensions tierces qui gèrent des types de documents spécifiques (comme les lecteurs PDF) s'appuyaient sur l'interception des requêtes réseau pour détecter les navigations et rediriger les utilisateurs vers une page d'extension. L'enregistrement en tant que gestionnaire MIME permet d'éviter 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 envoyés 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 ait à activer manuellement l'option "Autoriser l'accès aux URL de fichier" dans les paramètres de l'extension.

Les gestionnaires MIME ne s'appliquent qu'aux documents qui occupent un frame entier : navigations de premier niveau et documents intégrés. Elles 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 clé "mime_types_handler" 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 les éléments <embed>, <object> ou <iframe>. Si ce paramètre est omis, 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 précédemment installé redevient actif.

Récupérer des informations sur le flux

Lorsqu'un utilisateur ouvre un document d'un type MIME enregistré, Chrome charge votre page de gestionnaire à la place de sa visionneuse intégrée. Sur la page du gestionnaire, appelez getStreamInfo() pour récupérer un objet StreamInfo. Cela inclut l'originalUrl vers lequel l'utilisateur a accédé, l'responseHeaders HTTP, si le document est chargé dans un contexte embedded et un streamUrl qui peut être utilisé pour récupérer 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 l'intégralité de la réponse avant de la traiter. Une deuxième récupération du même streamUrl échoue. Utilisez originalUrl pour afficher l'emplacement ou le titre du document, et non pour récupérer le contenu, car la requête d'origine peut ne pas être reproductible.

Basculer vers le 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 de gérer le document et le renvoyer à la visionneuse intégrée de Chrome, plutôt que de laisser l'utilisateur sur une page défectueuse. Chrome décharge votre page de gestionnaire dans le cadre du remplacement. 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 la visionneuse intégrée à 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 envoyés par POST ou à partir d'URL à usage unique. Récupérez entièrement le flux avant de décider si vous pouvez l'afficher. Une fois la récupération 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 browser.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 (browser.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 dans la page du gestionnaire déclarée dans le fichier manifeste. Il récupère le contenu du document et utilise la visionneuse intégrée de Chrome si l'affichage échoue :

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

Laisser les utilisateurs activer/désactiver la gestion

Les options de gestionnaire sont stockées par type MIME. L'exemple suivant utilise getMimeHandlerOptions() et setMimeHandlerOptions() pour permettre aux utilisateurs de désactiver la gestion depuis la page des 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 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>