browser.mimeHandler

Deskripsi

Gunakan chrome.mimeHandler API untuk menangani streaming jenis MIME di ekstensi pihak ketiga.

Ketersediaan

Chrome 151+

Manifes

Kunci berikut harus dideklarasikan dalam manifes untuk menggunakan API ini.

"mime_types_handler"

Konsep dan penggunaan

Secara historis, ekstensi pihak ketiga yang menangani jenis dokumen tertentu (seperti penampil PDF) mengandalkan intersepsi permintaan jaringan untuk menangkap navigasi dan mengalihkan pengguna ke halaman ekstensi. Mendaftarkan sebagai pengendali MIME akan menghindari beberapa batasan pendekatan tersebut:

  • URL asli tetap berada di kolom URL, bukan diganti dengan URL chrome-extension://.
  • Ekstensi Anda mengambil respons yang telah diterima Chrome, bukan membuat permintaan jaringan kedua. Dokumen yang dikirimkan oleh permintaan POST atau dari URL sekali pakai berfungsi dengan benar.
  • Ekstensi Anda dapat merender dokumen yang dimuat dalam elemen <embed>, <object>, atau <iframe>.
  • File lokal (URL file://) berfungsi tanpa pengguna mengaktifkan "Izinkan akses ke URL file" secara manual di setelan ekstensi.

Pengendali MIME hanya berlaku untuk dokumen yang menempati seluruh frame: navigasi tingkat atas dan dokumen tersemat. Kebijakan ini tidak pernah berlaku untuk subresource inline (misalnya, elemen <audio>, <img>, atau <video>).

Mendaftarkan pengendali

Untuk mendaftarkan ekstensi Anda sebagai pengendali MIME, deklarasikan kunci "mime_types_handler" di manifes. Setiap entri memetakan jenis MIME ke halaman ekstensi yang merendernya:

manifest.json:

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

Tetapkan "can_embed" ke true untuk juga menangani dokumen yang disematkan dalam elemen <embed>, <object>, atau <iframe>. Jika dihilangkan, pengendali Anda hanya akan menerima navigasi tingkat teratas. Mulai Chrome 151, application/pdf adalah satu-satunya jenis MIME yang tersedia untuk pengendali publik; mendeklarasikan jenis MIME yang tidak didukung akan menyebabkan peringatan penginstalan.

Jika lebih dari satu ekstensi yang diinstal mendaftar untuk jenis MIME yang sama, ekstensi yang terakhir diinstal akan menanganinya. Jika ekstensi tersebut di-uninstal, pengendali yang diinstal sebelumnya akan aktif kembali.

Mengambil informasi streaming

Saat pengguna membuka dokumen dengan jenis MIME terdaftar, Chrome akan memuat halaman pengendali Anda, bukan penampil bawaannya. Dari halaman pengendali, panggil getStreamInfo() untuk mengambil objek StreamInfo. Hal ini mencakup originalUrl yang dibuka pengguna, responseHeaders HTTP, apakah dokumen dimuat dalam konteks embedded, dan streamUrl yang dapat digunakan untuk mengambil konten dokumen.

streamUrl dapat diambil tepat satu kali, dan hanya dari origin ekstensi Anda. Baca respons sepenuhnya sebelum memprosesnya; pengambilan kedua dari streamUrl yang sama akan gagal. Gunakan originalUrl saat menampilkan lokasi atau judul dokumen, bukan untuk mengambil konten, karena permintaan asli mungkin tidak dapat diulang.

Kembali ke pengendali native

Pengendali Anda mungkin menemukan dokumen yang tidak dapat dirender, seperti file yang rusak atau dilindungi sandi. Panggil abortAndFallbackToNativeHandler() untuk berhenti menangani dokumen dan mengembalikannya ke penampil bawaan Chrome, daripada membiarkan pengguna berada di halaman yang rusak. Chrome akan menghapus halaman pengendali Anda sebagai bagian dari penggantian; tidak ada kode yang berjalan setelah panggilan ini.

Chrome akan menyangga respons saat pengendali Anda berjalan. Jika respons telah diterima sepenuhnya saat Anda memanggil metode ini, Chrome akan menyajikan penampil bawaan dari salinan yang di-buffer tanpa permintaan jaringan baru. Jika tidak, Chrome akan memuat ulang dokumen dari jaringan, yang mungkin gagal untuk dokumen yang dikirim oleh POST atau dari URL sekali pakai. Ambil streaming sepenuhnya sebelum memutuskan apakah Anda dapat merendernya; setelah pengambilan streamUrl selesai, Chrome akan memiliki respons lengkap.

Menangani ketersediaan API

Di Chrome versi sebelum Chrome 151, ekstensi yang mendeklarasikan "mime_types_handler" masih diinstal dan dijalankan, tetapi tidak terdaftar sebagai pengendali dan browser.mimeHandler tidak ditentukan. Ekstensi yang bermigrasi dari intersepsi permintaan jaringan dapat memeriksa API saat memulai dan mempertahankan pendekatan yang ada sebagai pengganti:

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

Contoh

Menangani streaming

Contoh berikut berjalan di halaman pengendali yang dideklarasikan dalam manifes. Fungsi ini mengambil konten dokumen dan beralih ke penampil bawaan Chrome jika rendering gagal:

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

Mengizinkan pengguna mengaktifkan/menonaktifkan penanganan

Opsi pengendali disimpan per jenis MIME. Contoh berikut menggunakan getMimeHandlerOptions() dan setMimeHandlerOptions() untuk memungkinkan pengguna menonaktifkan penanganan dari halaman opsi, tanpa meng-uninstal ekstensi. Saat penanganan dinonaktifkan, dokumen jenis tersebut tidak lagi dirutekan ke ekstensi Anda.

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

Jenis

MimeHandlerOptions

Properti

  • canEmbed

    boolean opsional

    Chrome 157+

    Apakah pengendali ini dapat digunakan untuk pemuatan tersemat (iframe, sematan, objek). Setelan default-nya adalah nilai can_embed entri manifes. Tidak berpengaruh jika enabled bernilai salah (false).

  • aktif

    boolean opsional

    Apakah pengendali ini diaktifkan. Setelan default-nya adalah nilai enabled entri manifes.

StreamInfo

Properti

  • tersemat

    boolean

    Benar jika dimuat dalam konteks tersemat (iframe/embed/object).

  • mimeType

    string

    Jenis MIME dari konten yang dicegat.

  • originalUrl

    string

    URL asli yang dibuka pengguna.

  • responseHeaders

    objek

    Header respons HTTP sebagai key-value pair.

  • streamUrl

    string

    URL untuk mengambil data streaming.

  • tabId

    angka

    ID tab yang berisi dokumen.

Metode

abortAndFallbackToNativeHandler()

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

Membatalkan penanganan streaming saat ini dan menyerahkan konten ke pengendali native agen pengguna. Setelah panggilan ini, frame ekstensi akan dihentikan; pemanggil tidak boleh mengharapkan eksekusi lebih lanjut.

Hasil

  • Promise<void>

getMimeHandlerOptions()

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

Membaca opsi untuk jenis MIME. Setiap anggota adalah nilai yang ditetapkan ekstensi, atau nilai entri manifes jika ekstensi belum menetapkannya.

Parameter

  • mimeType

    string

    Jenis MIME yang opsinya akan dibaca. Jenis MIME harus ditangani ekstensi melalui mime_types_handler.

Hasil

getStreamInfo()

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

Mengambil informasi streaming untuk konteks pengendali MIME saat ini. Harus dipanggil dari dalam halaman ekstensi pengendali MIME.

Hasil

setMimeHandlerOptions()

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

Menetapkan opsi konfigurasi untuk jenis MIME yang ditentukan. Jika ekstensi berjalan dalam mode samaran terpisah, opsi yang ditetapkan dari mode samaran hanya berlaku untuk mode samaran dan berlangsung hingga sesi samaran berakhir. Opsi yang tidak ditetapkan dari mode samaran akan mengikuti nilai yang ditetapkan di luar mode samaran.

Parameter

  • mimeType

    string

    Jenis MIME yang akan dikonfigurasi. Jenis MIME harus ditangani ekstensi melalui mime_types_handler.

  • Opsi yang dapat diubah.

Hasil

  • Promise<void>

    Promise diselesaikan saat konfigurasi telah ditetapkan.