browser.mimeHandler

Описание

Доступность

Манифест

Основные понятия и использование

Ранее сторонние расширения, которые обрабатывают определенные типы документов (например, PDF), использовали перехват сетевых запросов, чтобы отслеживать переходы и перенаправлять пользователей на страницу расширения. Регистрация в качестве обработчика MIME позволяет избежать нескольких ограничений этого подхода:

• В адресной строке остается исходный URL, а не URL chrome-extension://.
• Расширение получает ответ, который уже был получен Chrome, вместо того чтобы отправлять второй сетевой запрос. Документы, доставленные с помощью запросов POST или одноразовых URL, работают корректно.
• Расширение может обрабатывать документы, загруженные в элементах <embed>, <object> или <iframe>.
• Локальные файлы (URL-адреса file://) работают без необходимости вручную включать параметр "Разрешить открывать локальные файлы по ссылкам" в настройках расширения.

Обработчики MIME применяются только к документам, которые занимают весь фрейм: навигации верхнего уровня и встроенным документам. Они никогда не применяются к встроенным подресурсам (например, элементам <audio>, <img> или <video>).

Как зарегистрировать обработчик

Чтобы зарегистрировать расширение в качестве обработчика MIME, объявите ключ "mime_types_handler" в манифесте. Каждая запись сопоставляет MIME-тип со страницей расширения, которая его обрабатывает:

manifest.json:

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

Задайте для параметра "can_embed" значение true, чтобы также обрабатывать документы, встроенные в элементы <embed>, <object> или <iframe>. Если его не указать, обработчик будет получать только переходы верхнего уровня. Начиная с Chrome 151, application/pdf – единственный MIME-тип, доступный для общедоступных обработчиков. При объявлении неподдерживаемого MIME-типа появляется предупреждение об установке.

Если для одного и того же MIME-типа зарегистрировано несколько расширений, его будет обрабатывать то, которое было установлено последним. Если расширение будет удалено, ранее установленный обработчик снова станет активным.

Как получить информацию о потоке

Когда пользователь открывает документ зарегистрированного MIME-типа, Chrome загружает страницу обработчика вместо встроенного средства просмотра. На странице обработчика вызовите getStreamInfo(), чтобы получить объект StreamInfo. В частности, это originalUrl, на который перешел пользователь, HTTP-заголовок responseHeaders, информация о том, загружен ли документ в контексте embedded, и streamUrl, который можно использовать для получения контента документа.

streamUrl можно получить только один раз и только из источника расширения. Полностью прочитайте ответ, прежде чем обрабатывать его. Повторный запрос того же streamUrl завершится ошибкой. Используйте originalUrl, чтобы показать местоположение или название документа, а не для получения контента, поскольку исходный запрос может быть неповторяемым.

Возврат к встроенному обработчику

Обработчик может столкнуться с документами, которые не удается отобразить, например с поврежденными или защищенными паролем файлами. Вызовите abortAndFallbackToNativeHandler(), чтобы прекратить обработку документа и передать его обратно встроенному средству просмотра Chrome, а не оставлять пользователя на неработающей странице. В рамках резервного варианта Chrome выгружает страницу обработчика. После этого вызова код не выполняется.

Chrome буферизует ответ во время работы обработчика. Если ответ был полностью получен при вызове этого метода, Chrome обслуживает встроенное средство просмотра из буферизованной копии без нового сетевого запроса. В противном случае Chrome перезагрузит документ из сети, что может не сработать для документов, доставленных с помощью POST или из одноразовых URL. Полностью получите поток, прежде чем решать, можете ли вы его отобразить. Как только получение streamUrl завершится, Chrome получит полный ответ.

Как обрабатывать доступность API

В версиях Chrome до 151 расширение, объявляющее "mime_types_handler", по-прежнему устанавливается и запускается, но не регистрируется как обработчик, а browser.mimeHandler не определяется. Расширения, переходящие с перехвата сетевых запросов, могут проверять наличие API при запуске и использовать существующий подход в качестве резервного:

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

Примеры

Как управлять трансляцией

Следующий пример выполняется на странице обработчика, объявленной в манифесте. Он извлекает содержимое документа и возвращается к встроенному средству просмотра 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();

Разрешить пользователям переключать обработку

Параметры обработчика хранятся для каждого MIME-типа. В следующем примере используются getMimeHandlerOptions() и setMimeHandlerOptions(), чтобы пользователи могли отключить обработку на странице параметров, не удаляя расширение. Пока обработка отключена, документы этого типа не будут направляться в ваше расширение.

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>