browser.mimeHandler

Opis

Dostępność

Plik manifestu

Pojęcia i zastosowanie

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

• Oryginalny adres URL pozostaje na pasku adresu i nie jest zastępowany adresem URL chrome-extension://.
• Rozszerzenie pobiera odpowiedź, którą Chrome już otrzymał, zamiast wysyłać drugie żądanie sieciowe. Dokumenty dostarczane za pomocą żądań POST lub z adresów URL jednorazowego użytku działają prawidłowo.
• Rozszerzenie może renderować dokumenty załadowane w elementach <embed>, <object> lub <iframe>.
• Pliki lokalne (file:// adresy URL) działają bez ręcznego włączania przez użytkownika opcji „Zezwalaj na dostęp do adresów URL plików” w ustawieniach rozszerzenia.

Obsługa MIME dotyczy tylko dokumentów, które zajmują całą ramkę: nawigacji najwyższego poziomu i dokumentów osadzonych. 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 wartość "can_embed" na true, aby obsługiwać też dokumenty umieszczone w elementach <embed>, <object> lub <iframe>. Jeśli ten parametr zostanie pominięty, moduł obsługi będzie otrzymywać tylko nawigacje najwyższego poziomu. Od wersji Chrome 151 typ MIME application/pdf jest jedynym typem MIME dostępnym dla publicznych programów obsługi. Zadeklarowanie nieobsługiwanego typu MIME powoduje wyświetlenie ostrzeżenia o instalacji.

Jeśli więcej niż 1 zainstalowane rozszerzenie zarejestruje się w tym samym typie MIME, będzie go obsługiwać rozszerzenie zainstalowane jako ostatnie. Jeśli to rozszerzenie zostanie odinstalowane, wcześniej zainstalowany program obsługi ponownie stanie się aktywny.

Pobieranie informacji o strumieniu

Gdy użytkownik otworzy dokument zarejestrowanego typu MIME, Chrome wczyta stronę obsługi zamiast wbudowanej przeglądarki. Na stronie obsługi wywołaj funkcję 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.

Dane streamUrl można pobrać dokładnie raz i tylko z domeny rozszerzenia. Przed przetworzeniem odpowiedzi przeczytaj ją w całości. Druga próba pobrania tego samego streamUrl zakończy się niepowodzeniem. Używaj originalUrl do wyświetlania lokalizacji lub tytułu dokumentu, a nie do pobierania treści, ponieważ oryginalne żądanie może nie być powtarzalne.

Wróć do natywnego modułu obsługi

Program obsługi może napotkać dokumenty, których nie może renderować, 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 zwalnia stronę obsługi jako część rezerwy. Po tym wywołaniu nie jest wykonywany żaden kod.

Chrome buforuje odpowiedź podczas działania modułu obsługi. Jeśli w momencie wywołania tej metody odpowiedź została w pełni odebrana, Chrome wyświetli wbudowaną przeglądarkę z kopii w buforze bez wysyłania nowego żądania sieciowego. W przeciwnym razie Chrome ponownie wczytuje dokument z sieci, co może się nie udać w przypadku dokumentów dostarczanych metodą POST lub z użyciem adresów URL jednorazowego użytku. Przed podjęciem decyzji o tym, czy można renderować strumień, pobierz go w całości. Po zakończeniu pobierania streamUrl Chrome ma pełną odpowiedź.

Obsługa dostępności interfejsu API

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

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 obsługi zadeklarowanej w pliku manifestu. Pobiera zawartość dokumentu i w razie niepowodzenia renderowania przełącza się na wbudowaną przeglądarkę 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();

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

Opcje 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 Twojego 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>