chrome.mimeHandler

Описание

Используйте API chrome.mimeHandler для обработки потоков MIME-типов в сторонних расширениях.

Доступность

В ожидании

Манифест

Для использования этого API в манифесте необходимо указать следующие ключи.

"mime_types_handler"

Понятия и применение

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

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

Обработчики 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 до Chrome 151 расширение, объявляющее "mime_types_handler" , по-прежнему устанавливается и запускается, но не регистрируется в качестве обработчика, и chrome.mimeHandler не определен. Расширения, переходящие от перехвата сетевых запросов, могут проверять наличие API при запуске и сохранять свой существующий подход в качестве резервного варианта:

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

Примеры

Обработка потока

Следующий пример выполняется на странице обработчика, указанной в манифесте. Он получает содержимое документа и, если рендеринг не удается, переключается на встроенный в Chrome просмотрщик:

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

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

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

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

Типы

MimeHandlerOptions

Характеристики

  • включено

    логический

    Указывает, активен ли данный обработчик для заданного типа MIME.

StreamInfo

Характеристики

  • встроенный

    логический

    Возвращает true, если загружается во встроенном контексте (iframe/embed/object).

  • mimeType

    нить

    MIME-тип перехваченного контента.

  • originalUrl

    нить

    Исходный URL-адрес, на который перешёл пользователь.

  • responseHeaders

    объект

    Заголовки HTTP-ответа представлены в виде пар ключ-значение.

  • streamUrl

    нить

    URL-адрес, с которого следует получать данные потока.

  • tabId

    число

    Идентификатор вкладки, содержащей документ.

Методы

abortAndFallbackToNativeHandler()

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

Прерывает текущую обработку потока и передает контент собственному обработчику пользовательского агента. После этого вызова расширенный кадр будет закрыт; вызывающие стороны не должны ожидать дальнейшего выполнения.

Возвраты

  • Обещание<пустота>

getMimeHandlerOptions()

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

Считывает сохраненные параметры для типа MIME. Возвращает значения по умолчанию (enabled=true), если таковые не были сохранены.

Параметры

  • mimeType

    нить

    MIME-тип, параметры которого необходимо прочитать.

Возвраты

  • Promise< MimeHandlerOptions >

    Обещание выполнено с сохранением параметров для MIME-типа.

getStreamInfo()

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

Получает информацию о потоке для текущего контекста обработчика MIME. Должен вызываться из страницы расширения обработчика MIME.

Возвраты

setMimeHandlerOptions()

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

Задает параметры конфигурации для указанного типа MIME.

Параметры

  • mimeType

    нить

    Тип MIME для настройки.

  • параметры

    MimeHandlerOptions

    Новые доступные варианты использования.

Возвраты

  • Обещание<пустота>

    Обещание выполняется после установки конфигурации.