chrome.mimeHandler

Deskripsi

Ketersediaan

Manifes

Konsep dan penggunaan

Sebelumnya, ekstensi pihak ketiga yang menangani jenis dokumen tertentu (seperti penampil PDF) mengandalkan pencegatan permintaan jaringan untuk menangkap navigasi dan mengalihkan pengguna ke halaman ekstensi. Mendaftarkan diri sebagai handler MIME menghindari beberapa batasan pendekatan tersebut:

• URL asli tetap ada di kolom alamat, 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.

Handler MIME hanya berlaku untuk dokumen yang menempati seluruh frame: navigasi tingkat teratas dan dokumen sematan. Aturan ini tidak pernah berlaku untuk subresource inline (misalnya, elemen <audio>, <img>, atau <video>).

Mendaftarkan pengendali

Untuk mendaftarkan ekstensi 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, handler Anda hanya menerima navigasi tingkat atas. Mulai Chrome 151, application/pdf adalah satu-satunya jenis MIME yang tersedia untuk handler 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 baru diinstal akan menanganinya. Jika ekstensi tersebut di-uninstal, handler yang sebelumnya diinstal akan aktif kembali.

Mengambil informasi streaming

Saat pengguna membuka dokumen dengan jenis MIME terdaftar, Chrome akan memuat halaman handler Anda sebagai pengganti penampil bawaannya. Dari halaman handler, 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.

Beralih kembali ke handler native

Handler 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, bukan membiarkan pengguna berada di halaman yang rusak. Chrome menghapus muatan halaman pengendali Anda sebagai bagian dari penggantian; tidak ada kode yang berjalan setelah panggilan ini.

Chrome akan melakukan buffering respons saat handler 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 penuh.

Menangani ketersediaan API

Pada versi Chrome sebelum Chrome 151, ekstensi yang mendeklarasikan "mime_types_handler" masih diinstal dan berjalan, tetapi tidak terdaftar sebagai handler dan chrome.mimeHandler tidak ditentukan. Ekstensi yang bermigrasi dari penyadapan permintaan jaringan dapat memeriksa API saat startup dan mempertahankan pendekatan yang ada sebagai penggantian:

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 handler yang dideklarasikan dalam manifes. Mengambil konten dokumen dan kembali 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();

Menangani tombol alih pengguna

Opsi handler 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 diarahkan 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>