chrome.mimeHandler

Descrição

Use a API chrome.mimeHandler para processar fluxos de tipo MIME em extensões de terceiros.

Disponibilidade

Pendente

Manifesto

As chaves a seguir precisam ser declaradas no manifesto para usar essa API.

"mime_types_handler"

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 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 processar também documentos incorporados em elementos <embed>, <object> ou <iframe>. Se omitido, seu manipulador 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 manipulador 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 manipulador em vez do visualizador integrado. Na página do manipulador, 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 vai falhar. 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.

Voltar ao manipulador nativo

Seu manipulador 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 manipulador, e chrome.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 um substituto:

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

Exemplos

Processar um stream

O exemplo a seguir é executado na página do manipulador 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 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();

Permitir que os usuários alternem o processamento

As opções de manipulador 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 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();

Tipos

MimeHandlerOptions

Propriedades

  • ativado

    booleano

    Indica se o gerenciador está ativo para o tipo MIME especificado.

StreamInfo

Propriedades

  • incorporado

    booleano

    Verdadeiro se carregado em um contexto incorporado (iframe/embed/object).

  • mimeType

    string

    O tipo MIME do conteúdo interceptado.

  • originalUrl

    string

    O URL original para que o usuário navegou.

  • responseHeaders

    objeto

    Cabeçalhos de resposta HTTP como pares de chave-valor.

  • streamUrl

    string

    O URL para buscar os dados de stream.

  • tabId

    número

    O ID da guia que contém o documento.

Métodos

abortAndFallbackToNativeHandler()

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

Interrompe o processamento de stream atual e entrega o conteúdo ao manipulador nativo do user agent. Depois dessa chamada, o frame da extensão será desativado. Os chamadores não devem esperar mais execuções.

Retorna

  • Promessa<void>

getMimeHandlerOptions()

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

Lê as opções persistentes de um tipo MIME. Retorna os padrões (enabled=true) se nenhum tiver sido armazenado.

Parâmetros

  • mimeType

    string

    O tipo MIME cujas opções serão lidas.

Retorna

  • Promessa resolvida com as opções persistentes para o tipo MIME.

getStreamInfo()

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

Recupera informações de stream para o contexto do manipulador MIME atual. Precisa ser chamado em uma página de extensão do gerenciador de MIME.

Retorna

setMimeHandlerOptions()

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

Define as opções de configuração para um tipo MIME especificado.

Parâmetros

  • mimeType

    string

    O tipo MIME a ser configurado.

  • As novas opções de uso.

Retorna

  • Promessa<void>

    A promessa é resolvida quando a configuração é definida.