chrome.mimeHandler

Opis

Użyj interfejsu chrome.mimeHandler API, aby obsługiwać strumienie typów MIME w rozszerzeniach innych firm.

Dostępność

Oczekujące

Plik manifestu

Aby korzystać z tego interfejsu API, w pliku manifestu musisz zadeklarować te klucze.

"mime_types_handler"

Pojęcia i użycie

W przeszłości rozszerzenia innych firm, które obsługiwały określone typy dokumentów (np. przeglądarki PDF), polegały na przechwytywaniu żądań sieciowych, aby przechwytywać 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 zamiast zostać zastąpiony adresem chrome-extension://.
  • Rozszerzenie pobiera odpowiedź, którą Chrome już otrzymał, zamiast wysyłać drugie żądanie sieciowe. Dokumenty dostarczane przez żądania POST lub z adresów URL jednorazowego użytku działają prawidłowo.
  • Rozszerzenie może renderować dokumenty wczytywane 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 osadzonych. Nigdy nie mają zastosowania do zasobów podrzędnych w tekście (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 osadzone w elementach <embed>, <object>, lub <iframe>. Jeśli pominiesz ten klucz, moduł obsługi będzie otrzymywać tylko nawigacje najwyższego poziomu. W Chrome w wersji 151 i nowszych application/pdf jest jedynym typem MIME dostępnym dla publicznych modułów obsługi. Zadeklarowanie nieobsługiwanego typu MIME spowoduje wyświetlenie ostrzeżenia podczas 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, ponownie stanie się aktywny wcześniej zainstalowany moduł obsługi.

Pobieranie informacji o strumieniu

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

Adres streamUrl można pobrać tylko raz i tylko z domeny rozszerzenia. Przed przetworzeniem w pełni odczytaj odpowiedź. Drugie pobranie tego samego adresu streamUrl nie powiedzie się. 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.

Powrót do natywnego modułu obsługi

Moduł obsługi może napotkać dokumenty, których nie może renderować, np. uszkodzone lub chronione hasłem pliki. Aby zatrzymać obsługę dokumentu i przekazać go z powrotem do wbudowanej przeglądarki Chrome, a nie pozostawiać użytkownika na uszkodzonej stronie, wywołaj funkcję abortAndFallbackToNativeHandler(). Chrome zwalnia stronę modułu obsługi w ramach powrotu. Po tym wywołaniu nie jest wykonywany żaden kod.

Chrome buforuje odpowiedź podczas działania modułu obsługi. Jeśli odpowiedź została w pełni odebrana, gdy wywołasz tę metodę, Chrome wyświetli wbudowaną przeglądarkę z buforowanej kopii bez wysyłania nowego żądania sieciowego. W przeciwnym razie Chrome ponownie wczyta dokument z sieci, co może się nie udać w przypadku dokumentów dostarczanych przez żądania POST lub z adresów URL jednorazowego użytku. Przed podjęciem decyzji, czy możesz renderować strumień, pobierz go w całości. Gdy pobieranie streamUrl się zakończy, Chrome będzie mieć pełną odpowiedź.

Obsługa dostępności interfejsu API

W wersjach Chrome wcześniejszych niż Chrome 151 rozszerzenie deklarujące "mime_types_handler" nadal się instaluje i działa, ale nie jest rejestrowane jako moduł obsługi, a chrome.mimeHandler jest niezdefiniowane. Rozszerzenia migrujące z przechwytywania żądań sieciowych mogą sprawdzić interfejs API podczas uruchamiania i zachować dotychczasowe podejście jako rezerwowe:

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

Przykłady

Obsługa strumienia

Poniższy przykład działa na stronie modułu obsługi zadeklarowanej w pliku manifestu. Pobiera on treść dokumentu i w razie niepowodzenia renderowania wraca do wbudowanej przeglądarki 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();

Umożliwianie użytkownikom przełączania obsługi

Opcje modułu obsługi są przechowywane według typu MIME. Poniższy przykład używa funkcji getMimeHandlerOptions() i setMimeHandlerOptions(), aby umożliwić użytkownikom wyłączanie 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 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();

Typy

MimeHandlerOptions

Właściwości

  • enabled

    Wartość logiczna

    Określa, czy ten moduł obsługi jest aktywny w przypadku danego typu MIME.

StreamInfo

Właściwości

  • embedded

    Wartość logiczna

    Wartość true, jeśli wczytano w kontekście osadzonym (iframe/embed/object).

  • mimeType

    ciąg znaków

    Typ MIME przechwyconej treści.

  • originalUrl

    ciąg znaków

    Oryginalny adres URL, do którego użytkownik przeszedł.

  • responseHeaders

    obiekt

    Nagłówki odpowiedzi HTTP jako pary klucz-wartość.

  • streamUrl

    ciąg znaków

    Adres URL, z którego można pobrać dane strumienia.

  • tabId

    liczba

    Identyfikator karty zawierającej dokument.

Metody

abortAndFallbackToNativeHandler()

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

Przerywa bieżącą obsługę strumienia i przekazuje treść do natywnego modułu obsługi agenta użytkownika. Po tym wywołaniu ramka rozszerzenia zostanie zamknięta. Wywołujący nie powinni oczekiwać dalszego wykonania.

Zwroty

  • Promise<void>

getMimeHandlerOptions()

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

Odczytuje utrwalone opcje typu MIME. Jeśli nie zostały zapisane żadne opcje, zwraca wartości domyślne (enabled=true).

Parametry

  • mimeType

    ciąg znaków

    Typ MIME, którego opcje mają zostać odczytane.

Zwroty

  • Obietnica, która zostanie rozwiązana z utrwalonymi opcjami typu MIME.

getStreamInfo()

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

Pobiera informacje o strumieniu w bieżącym kontekście modułu obsługi MIME. Musi być wywoływana ze strony rozszerzenia modułu obsługi MIME.

Zwroty

setMimeHandlerOptions()

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

Ustawia opcje konfiguracji dla określonego typu MIME.

Parametry

  • mimeType

    ciąg znaków

    Typ MIME do skonfigurowania.

  • Nowe opcje do użycia.

Zwroty

  • Promise<void>

    Obietnica, która zostanie rozwiązana po ustawieniu konfiguracji.