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

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>