browser.mimeHandler

Opis

Dostępność

Plik manifestu

Pojęcia i użycie

W przeszłości rozszerzenia innych firm, które obsługują określone typy dokumentów (np. przeglądarki plików PDF), polegały na przechwytywaniu żądań sieciowych, aby wykrywać nawigację i przekierowywać użytkowników na stronę rozszerzenia. Zarejestrowanie jako moduł obsługi MIME pozwala uniknąć kilku ograniczeń tego podejścia:

• Pierwotny adres URL pozostaje na pasku adresu, zamiast zostać zastąpiony adresem URL chrome-extension://.
• Rozszerzenie pobiera odpowiedź, którą Chrome już otrzymał, zamiast wysyłać drugie żądanie sieciowe. Dokumenty dostarczane przez żądania POST lub z jednorazowych adresów URL działają prawidłowo.
• Rozszerzenie może renderować dokumenty wczytane w elementach <embed>, <object> lub <iframe>.
• Pliki lokalne (adresy URL file://) działają bez konieczności ręcznego włączania przez użytkownika opcji „Zezwalaj na dostęp do adresów URL plików” w ustawieniach rozszerzenia.

Moduły obsługi MIME mają zastosowanie tylko do dokumentów, które zajmują całą ramkę: nawigacji najwyższego poziomu i dokumentów umieszczonych na stronie. Nigdy nie mają zastosowania do zasobów podrzędnych wbudowanych (np. elementów <audio>, <img> lub <video>).

Rejestrowanie modułu obsługi

Aby zarejestrować rozszerzenie jako moduł obsługi MIME, zadeklaruj klucz "mime_types_handler" w pliku manifestu. Każdy wpis mapuje typ MIME na stronę rozszerzenia, która go renderuje:

manifest.json:

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

Ustaw "can_embed" na true, aby obsługiwać też dokumenty umieszczone w elementach <embed>, <object> lub <iframe>. Jeśli go pominiesz, moduł obsługi będzie otrzymywać tylko nawigacje najwyższego poziomu. Od Chrome 151 application/pdf jest jedynym typem MIME dostępnym dla modułów obsługi publicznej. Zadeklarowanie nieobsługiwanego typu MIME powoduje wyświetlenie ostrzeżenia podczas instalacji.

Jeśli więcej niż jedno zainstalowane rozszerzenie jest zarejestrowane dla tego samego typu MIME, obsługuje je ostatnio zainstalowane rozszerzenie. Jeśli to rozszerzenie zostanie odinstalowane, wcześniej zainstalowany moduł obsługi zostanie ponownie aktywowany.

Pobieranie informacji o strumieniu

Gdy użytkownik otworzy dokument o zarejestrowanym typie MIME, Chrome wczyta stronę modułu obsługi zamiast wbudowanej przeglądarki. Na stronie modułu obsługi wywołaj getStreamInfo(), aby pobrać obiekt StreamInfo. Obejmuje to originalUrl, do którego użytkownik przeszedł, responseHeaders HTTP, informację o tym, czy dokument jest wczytywany w kontekście embedded, oraz streamUrl, którego można użyć do pobrania zawartości dokumentu.

streamUrl można pobrać tylko raz i tylko ze źródła rozszerzenia. Przed przetworzeniem odpowiedzi przeczytaj ją w całości. Drugie pobranie tego samego elementu streamUrl nie powiedzie się. Używaj originalUrl podczas wyświetlania lokalizacji lub tytułu dokumentu, a nie do pobierania treści, ponieważ pierwotne żądanie może nie być powtarzalne.

Zastępcza obsługa natywna

Moduł obsługi może napotkać dokumenty, których nie może przetworzyć, np. uszkodzone lub chronione hasłem pliki. Wywołaj funkcję abortAndFallbackToNativeHandler(), aby przestać obsługiwać dokument i przekazać go z powrotem do wbudowanej przeglądarki Chrome, zamiast pozostawiać użytkownika na uszkodzonej stronie. Chrome wyładowuje stronę modułu obsługi w ramach kreacji zastępczej. Po tym wywołaniu nie jest uruchamiany żaden kod.

Chrome buforuje odpowiedź podczas działania modułu obsługi. Jeśli odpowiedź została w pełni odebrana, gdy wywołujesz tę metodę, Chrome wyświetla wbudowaną przeglądarkę z buforowanej kopii bez nowego żądania sieciowego. W przeciwnym razie Chrome ponownie załaduje dokument z sieci, co może się nie udać w przypadku dokumentów dostarczanych przez POST lub z jednorazowych adresów URL. Pobierz cały strumień, zanim zdecydujesz, czy możesz go wyrenderować. Gdy pobieranie streamUrl się zakończy, Chrome będzie mieć pełną odpowiedź.

Obsługa dostępności interfejsu API

W wersjach Chrome starszych niż Chrome 151 rozszerzenie deklarujące "mime_types_handler" nadal się instaluje i działa, ale nie jest zarejestrowane jako moduł obsługi, a browser.mimeHandler jest niezdefiniowane. Rozszerzenia, które przechodzą z przechwytywania żądań sieciowych, mogą sprawdzać interfejs API podczas uruchamiania i zachować dotychczasowe podejście jako rozwiązanie zastępcze:

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

Przykłady

Obsługa strumienia

Poniższy przykład działa na stronie modułu obsługi zadeklarowanej w pliku manifestu. Pobiera zawartość dokumentu i wraca do wbudowanej przeglądarki Chrome, jeśli renderowanie się nie powiedzie:

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

Zezwalaj użytkownikom na przełączanie obsługi

Opcje modułu obsługi są przechowywane według typu MIME. W poniższym przykładzie użyto getMimeHandlerOptions() i setMimeHandlerOptions(), aby umożliwić użytkownikom wyłączenie obsługi na stronie opcji bez odinstalowywania rozszerzenia. Gdy obsługa jest wyłączona, dokumenty tego typu nie są już kierowane do rozszerzenia.

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>