browser.mimeHandler

Descrição

Disponibilidade

Manifesto

Conceitos e uso

Historicamente, as extensões de terceiros que processam tipos específicos de documentos (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 manipulador MIME evita várias limitações dessa abordagem:

• O URL original permanece na barra de endereço em vez de ser substituído por um URL chrome-extension://.
• Sua extensão busca a resposta que o Chrome já recebeu, em vez de fazer uma segunda solicitação de rede. Os documentos entregues por solicitações POST ou 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 manipuladores MIME se aplicam apenas a documentos que ocupam um frame inteiro: navegações de nível superior e documentos incorporados. Elas nunca se aplicam a subrecursos 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 processar também documentos incorporados em elementos <embed>, <object> ou <iframe>. Se omitido, seu gerenciador só vai receber navegações de nível superior. No Chrome 151, application/pdf é o único tipo MIME disponível para manipuladores públicos. Declarar um tipo MIME sem suporte 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á ativado novamente.

Recuperar informações do stream

Quando um usuário abre um documento de um tipo MIME registrado, o Chrome carrega a página do gerenciador no lugar do visualizador integrado. Na página do gerenciador, chame getStreamInfo() para recuperar um objeto StreamInfo. Isso inclui o originalUrl para que o usuário navegou, 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 sua extensão. Leia a resposta por completo antes de processá-la. Uma segunda busca do mesmo streamUrl falha. Use originalUrl ao mostrar 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.

Reverter para o gerenciador nativo

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

O Chrome armazena em buffer a resposta enquanto o manipulador é executado. Se a resposta tiver sido totalmente recebida quando você chamar esse método, o Chrome vai disponibilizar o visualizador integrado da cópia em buffer sem uma nova solicitação de rede. Caso contrário, o Chrome recarrega o documento da rede, o que pode falhar para documentos entregues por POST ou de URLs de uso único. Busque o fluxo por completo antes de decidir se é possível renderizá-lo. Quando a busca de streamUrl for concluída, o Chrome terá a resposta completa.

Como lidar com a disponibilidade da API

Em 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 é 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 um substituto:

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 volta para o visualizador integrado do Chrome se a renderização falhar:

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>