browser.mimeHandler

شرح

دردسترس بودن

مانیفست

مفاهیم و کاربرد

در گذشته، افزونه‌های طرف سومی که انواع خاصی از سندها را مدیریت می‌کنند (مانند نمایشگرهای PDF) برای گرفتن پیمایش‌ها و هدایت کاربران به صفحه افزونه، به رهگیری درخواست شبکه متکی بودند. ثبت‌نام به‌عنوان کنترل‌کننده MIME از چندین محدودیت آن رویکرد جلوگیری می‌کند:

• نشانی وب اصلی در نوار نشانی باقی می‌ماند و با نشانی وب chrome-extension:// جایگزین نمی‌شود.
• افزونه شما به‌جای ایجاد درخواست شبکه دوم، پاسخی را که Chrome قبلاً دریافت کرده است واکشی می‌کند. اسنادی که با درخواست‌های POST یا از نشانی‌های وب یک‌بارمصرف ارسال می‌شوند به‌درستی کار می‌کنند.
• افزونه شما می‌تواند اسناد بارشده در عناصر <embed>، <object>، یا <iframe> را پردازش کند.
• فایل‌های محلی (نشانی‌های وب file://) بدون اینکه کاربر به‌طور دستی «اجازه دسترسی به نشانی‌های وب فایل» را در تنظیمات افزونه فعال کند، کار می‌کنند.

گرداننده‌های MIME فقط برای اسنادی اعمال می‌شوند که کل قاب را اشغال می‌کنند: پیمایش‌های سطح بالا و اسناد جاسازی‌شده. این خط‌مشی‌ها هرگز برای زیرمنابع درون‌خطی (مثلاً عناصر <audio>،‏ <img>، یا <video>) اعمال نمی‌شوند.

ثبت کردن رسیدگی‌کننده

برای ثبت افزونه‌تان به‌عنوان کنترل‌کننده MIME، کلید "mime_types_handler" را در مانیفست اعلام کنید. هر ورودی یک نوع MIME را به صفحه افزونه‌ای که آن را ارائه می‌دهد نگاشت می‌کند:

manifest.json:

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

"can_embed" را روی true تنظیم کنید تا اسناد جاسازی‌شده در عناصر <embed>، <object>، یا <iframe> را نیز مدیریت کند. اگر حذف شود، گرداننده شما فقط پیمایش‌های سطح بالا را دریافت می‌کند. از Chrome 151،‏ application/pdf تنها نوع MIME دردسترس برای کنترل‌کننده‌های عمومی است؛ اعلام نوع MIME پشتیبانی‌نشده باعث هشدار نصب می‌شود.

اگر بیش‌از یک افزونه نصب‌شده برای نوع MIME یکسانی ثبت شود، افزونه‌ای که اخیراً نصب شده است آن را مدیریت می‌کند. اگر آن افزونه حذف نصب شود، کنترل‌کننده قبلاً نصب‌شده دوباره فعال می‌شود.

بازیابی اطلاعات جاری‌سازی

وقتی کاربر سندی از نوع MIME ثبت‌شده را باز می‌کند، Chrome صفحه گرداننده شما را به‌جای نمایشگر داخلی خود بار می‌کند. از صفحه گرداننده، getStreamInfo() را فراخوانی کنید تا شیء StreamInfo را بازیابی کنید. این شامل originalUrl که کاربر به آن پیمایش کرده است، responseHeaders HTTP، اینکه آیا سند در بافت embedded بار شده است یا نه، و streamUrl که می‌تواند برای واکشی محتوای سند استفاده شود می‌شود.

streamUrl را می‌توان دقیقاً یک‌بار و فقط از مبدأ افزونه‌تان واکشی کرد. قبل‌از پردازش پاسخ، آن را به‌طور کامل بخوانید؛ واکشی دوم همان streamUrl ناموفق است. هنگام نمایش مکان یا عنوان سند، از originalUrl استفاده کنید، نه برای واکشی محتوا، زیرا ممکن است درخواست اصلی تکرارپذیر نباشد.

برگشتن به گرداننده بومی

گرداننده شما ممکن است با اسنادی مواجه شود که نمی‌تواند آن‌ها را ارائه کند، مانند فایل‌های خراب یا محافظت‌شده با گذرواژه. abortAndFallbackToNativeHandler() را فراخوانی کنید تا رسیدگی به سند متوقف شود و سند به نظاره‌گر داخلی Chrome برگردانده شود، نه اینکه کاربر در صفحه‌ای خراب رها شود. ‫Chrome صفحه گرداننده شما را به‌عنوان بخشی از بازگشت بارگیری می‌کند؛ هیچ کدی پس‌از این تماس اجرا نمی‌شود.

Chrome پاسخ را درحین اجرای گرداننده شما میان‌گیری می‌کند. اگر هنگام فراخوانی این روش، پاسخ به‌طور کامل دریافت شده باشد، Chrome نمایشگر داخلی را از نسخه میان‌گیرشده بدون درخواست شبکه جدید ارائه می‌دهد. درغیراین‌صورت، Chrome سند را از شبکه مجدداً بار می‌کند که ممکن است برای اسناد ارائه‌شده توسط POST یا از نشانی‌های وب یک‌بارمصرف ناموفق باشد. قبل‌از تصمیم‌گیری درباره اینکه می‌توانید آن را ارائه کنید یا نه، جریان را به‌طور کامل واکشی کنید؛ پس‌از تکمیل واکشی streamUrl، Chrome پاسخ کامل را دارد.

مدیریت دردسترس بودن میانای برنامه‌سازی کاربردی

در نسخه‌های Chrome قبل‌از Chrome 151، افزونه‌ای که "mime_types_handler" را اعلام می‌کند همچنان نصب و اجرا می‌شود، اما به‌عنوان گرداننده ثبت نمی‌شود و browser.mimeHandler تعریف‌نشده است. افزونه‌هایی که از رهگیری درخواست شبکه مهاجرت می‌کنند می‌توانند در زمان راه‌اندازی وجود API را بررسی کنند و رویکرد فعلی خود را به‌عنوان جایگزین حفظ کنند:

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

مثال‌ها

مدیریت جاری‌سازی

مثال زیر در صفحه کنترل‌کننده اعلام‌شده در مانیفست اجرا می‌شود. این برنامه محتوای سند را واکشی می‌کند و اگر پردازش ناموفق باشد، به نمایشگر داخلی 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();

به کاربران اجازه دهید رسیدگی را تغییر دهند

گزینه‌های گرداننده برای هر نوع MIME ذخیره می‌شود. مثال زیر از getMimeHandlerOptions() و setMimeHandlerOptions() استفاده می‌کند تا به کاربران اجازه دهد بدون حذف نصب افزونه، رسیدگی را از صفحه گزینه‌ها خاموش کنند. وقتی رسیدگی غیرفعال باشد، اسناد آن نوع دیگر به افزونه شما هدایت نمی‌شوند.

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

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

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

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

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