browser.mimeHandler

Descrição

Disponibilidade

Manifesto

Conceitos e uso

Historicamente, as extensões de terceiros que processam tipos de documentos específicos (como leitores de PDF) dependiam da interceptação de solicitações de rede para capturar navegações e redirecionar os usuários para uma página de extensão. O registro como um gerenciador de MIME evita várias limitações dessa abordagem:

• O URL de origem permanece na barra de endereço em vez de ser substituído por um URL do chrome-extension://.
• A extensão busca a resposta que o Chrome já recebeu, em vez de fazer uma segunda solicitação de rede. Os documentos enviados por solicitações POST ou de URLs de uso único funcionam corretamente.
• Sua extensão pode renderizar documentos carregados em elementos <embed>, <object> ou <iframe>.
• Os arquivos locais (URLs file://) funcionam sem que o usuário precise ativar manualmente a opção "Permitir acesso a URLs de arquivo" nas configurações da extensão.

Os gerenciadores de MIME se aplicam apenas a documentos que ocupam um frame inteiro: navegações de nível superior e documentos incorporados. Eles nunca se aplicam a sub-recursos inline (por exemplo, elementos <audio>, <img> ou <video>).

Registrar um gerenciador

Para registrar sua extensão como um gerenciador de MIME, declare a chave "mime_types_handler" no manifesto. Cada entrada mapeia um tipo MIME para a página de extensão que o renderiza:

manifest.json:

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

Defina "can_embed" como true para também processar documentos incorporados em elementos <embed>, <object> ou <iframe>. Se omitido, o gerenciador só vai receber navegações de nível superior. A partir do Chrome 151, application/pdf é o único tipo MIME disponível para gerenciadores públicos. Declarar um tipo MIME não compatível causa um aviso de instalação.

Se mais de uma extensão instalada se registrar para o mesmo tipo MIME, a extensão instalada mais recentemente vai processá-lo. Se essa extensão for desinstalada, o gerenciador instalado anteriormente será reativado.

Recuperar informações do stream

Quando um usuário abre um documento de um tipo MIME registrado, o Chrome carrega sua página de gerenciador no lugar do visualizador integrado. Na página do gerenciador, chame getStreamInfo() para recuperar um objeto StreamInfo. Isso inclui o originalUrl acessado pelo usuário, o responseHeaders HTTP, se o documento é carregado em um contexto embedded e um streamUrl que pode ser usado para buscar o conteúdo do documento.

O streamUrl pode ser buscado exatamente uma vez e apenas na origem da extensão. Leia a resposta completa antes de processá-la. Uma segunda busca do mesmo streamUrl vai falhar. Use originalUrl ao exibir o local ou o título do documento, não para buscar o conteúdo, porque a solicitação original pode não ser repetível.

Voltar para o gerenciador nativo

O gerenciador pode encontrar documentos que não podem ser renderizados, como arquivos corrompidos ou protegidos por senha. Chame abortAndFallbackToNativeHandler() para interromper o processamento do documento e devolvê-lo ao visualizador integrado do Chrome, em vez de deixar o usuário em uma página corrompida. O Chrome descarrega a página do gerenciador como parte do substituto. Nenhum código é executado após essa chamada.

O Chrome armazena a resposta em buffer enquanto o gerenciador é executado. Se a resposta tiver sido totalmente recebida quando você chamar esse método, o Chrome vai exibir o visualizador integrado da cópia em buffer sem uma nova solicitação de rede. Caso contrário, o Chrome vai recarregar o documento da rede, o que pode falhar para documentos enviados por POST ou de URLs de uso único. Busque o stream completamente antes de decidir se ele pode ser renderizado. Quando a busca de streamUrl for concluída, o Chrome terá a resposta completa.

Processar a disponibilidade da API

Nas versões do Chrome anteriores à 151, uma extensão que declara "mime_types_handler" ainda é instalada e executada, mas não é registrada como um gerenciador, e browser.mimeHandler fica indefinido. As extensões que estão migrando da interceptação de solicitações de rede podem verificar a API na inicialização e manter a abordagem atual como substituta:

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

Exemplos

Processar um stream

O exemplo a seguir é executado na página do gerenciador declarada no manifesto. Ele busca o conteúdo do documento e, se a renderização falhar, usa o visualizador integrado do Chrome:

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

Permitir que os usuários alternem o processamento

As opções de gerenciador são armazenadas por tipo MIME. O exemplo a seguir usa getMimeHandlerOptions() e setMimeHandlerOptions() para permitir que os usuários desativem o processamento na página de opções, sem desinstalar a extensão. Enquanto o processamento estiver desativado, os documentos desse tipo não serão mais encaminhados para sua extensão.

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>