chrome.mimeHandler

Deskripsi

Ketersediaan

Manifes

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. Mendaftar sebagai pengendali MIME menghindari beberapa batasan pendekatan tersebut:

• URL asli tetap berada di kolom URL, bukan diganti dengan URL chrome-extension://.
• Ekstensi Anda mengambil respons yang sudah 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 yang disematkan. Pengendali MIME tidak pernah berlaku untuk subresource inline (misalnya, <audio>, <img>, atau <video> elemen).

Mendaftarkan pengendali

Untuk mendaftarkan ekstensi Anda sebagai pengendali MIME, deklarasikan kunci "mime_types_handler" dalam 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 atas. 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 terinstal yang terdaftar untuk jenis MIME yang sama, ekstensi yang paling baru diinstal akan menanganinya. Jika ekstensi tersebut di-uninstal, pengendali yang sebelumnya diinstal akan aktif kembali.

Mengambil informasi streaming

Saat pengguna membuka dokumen 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 dinavigasi pengguna, responseHeaders HTTP, apakah dokumen dimuat dalam konteks embedded, dan streamUrl yang dapat digunakan untuk mengambil konten dokumen.

streamUrl hanya dapat diambil satu kali, dan hanya dari asal 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.

Beralih 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 menyerahkannya kembali ke penampil bawaan Chrome, bukan membiarkan pengguna berada di halaman yang rusak. Chrome akan membongkar halaman pengendali Anda sebagai bagian dari fallback; tidak ada kode yang berjalan setelah panggilan ini.

Chrome akan mem-buffer respons saat pengendali Anda berjalan. Jika respons telah diterima sepenuhnya saat Anda memanggil metode ini, Chrome akan menayangkan 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 dikirimkan 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 berjalan, tetapi tidak terdaftar sebagai pengendali dan chrome.mimeHandler tidak ditentukan. Ekstensi yang bermigrasi dari intersepsi permintaan jaringan dapat memeriksa API saat startup dan mempertahankan pendekatan yang ada sebagai fallback:

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

Contoh

Menangani streaming

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

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

Mengizinkan pengguna mengaktifkan/menonaktifkan penanganan

Opsi pengendali disimpan per jenis MIME. Contoh berikut menggunakan getMimeHandlerOptions() dan setMimeHandlerOptions() untuk mengizinkan 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 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();

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>