browser.mimeHandler

شرح

از chrome.mimeHandler API برای مدیریت جاری‌سازی‌های نوع MIME در افزونه‌های طرف سوم استفاده کنید.

دردسترس بودن

Chrome نسخه ۱۵۱ و بالاتر

مانیفست

برای استفاده از این میانای برنامه‌سازی کاربردی، کلیدهای زیر باید در مانیفست اعلام شوند.

"mime_types_handler"

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

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

توجه: getStreamInfo() فقط در صفحه گرداننده‌ای موفق می‌شود که Chrome برای سند بار کرده باشد. فراخوانی آن از بافت افزونه دیگر، مانند کارگر سرویس یا صفحه گزینه‌ها، ناموفق است زیرا هیچ جاری‌سازی مرتبطی وجود ندارد.

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

گرداننده شما ممکن است با اسنادی مواجه شود که نمی‌تواند آن‌ها را ارائه کند، مانند فایل‌های خراب یا محافظت‌شده با گذرواژه. 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();

انواع

MimeHandlerOptions

مشخصات

• canEmbed

  بولی اختیاری

  Chrome نسخه ۱۵۷ و بالاتر

  اینکه آیا این کنترل‌کننده می‌تواند برای بارهای جاسازی‌شده (iframe، جاسازی، شیء) استفاده شود یا نه. به‌طور پیش‌فرض روی مقدار can_embed ورودی مانیفست تنظیم شده است. وقتی enabled نادرست باشد، تأثیری ندارد.

• فعال شد

  بولی اختیاری

  اینکه این گرداننده فعال است یا نه. به‌طور پیش‌فرض روی مقدار enabled ورودی مانیفست تنظیم شده است.

StreamInfo

مشخصات

• جاسازی‌شده

  بولی

  اگر در بافت جاسازی‌شده (iframe/embed/object) بار شده باشد، درست است.

• mimeType

  رشته

  نوع MIME محتوای رهگیری‌شده.

• originalUrl

  رشته

  نشانی وب اصلی که کاربر به آن پیمایش کرده است.

• responseHeaders

  شیء

  سرصفحه‌های پاسخ اچ‌تی‌تی‌پی به‌عنوان جفت‌های کلید-مقدار.

• streamUrl

  رشته

  نشانی وبی که داده‌های جاری‌سازی از آن واکشی می‌شود.

• tabId

  شماره

  شناسه زبانه‌ای که حاوی سند است.

روش‌ها

abortAndFallbackToNativeHandler()

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

مدیریت جاری جاری را لغو می‌کند و محتوا را به مدیر بومی نماینده کاربر تحویل می‌دهد. پس‌از این فراخوانی، قاب افزونه ازبین خواهد رفت؛ فراخوانندگان نباید انتظار اجرای بیشتری داشته باشند.

بازگشتی‌ها

• Promise<void>

getMimeHandlerOptions()

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

گزینه‌های نوع MIME را می‌خواند. هر عضو مقداری است که افزونه تنظیم کرده است، یا مقدار ورودی مانیفست است اگر افزونه آن را تنظیم نکرده باشد.

پارامترها

• mimeType

  رشته

  نوع MIME که گزینه‌های آن خوانده می‌شود. باید نوع MIME باشد که افزونه ازطریق mime_types_handler مدیریت می‌کند.

بازگشتی‌ها

• Promise<MimeHandlerOptions>

  Promise resolved with the options for the MIME type.

getStreamInfo()

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

اطلاعات جاری را برای زمینه کنترل‌کننده MIME فعلی بازیابی می‌کند. باید از داخل صفحه افزونه رسیدگی‌کننده MIME فراخوانی شود.

بازگشتی‌ها

• Promise<StreamInfo>

setMimeHandlerOptions()

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

گزینه‌های پیکربندی را برای نوع MIME مشخص‌شده تنظیم می‌کند. اگر افزونه در حالت ناشناس تقسیم‌شده اجرا شود، گزینه‌های تنظیم‌شده از حالت ناشناس فقط برای حالت ناشناس اعمال می‌شوند و تا پایان جلسه ناشناس باقی می‌مانند. گزینه‌هایی که از حالت ناشناس تنظیم نشده‌اند از مقادیر تنظیم‌شده در خارج از حالت ناشناس پیروی می‌کنند.

پارامترها

• mimeType

  رشته

  نوع MIME برای پیکربندی. باید نوع MIME باشد که افزونه ازطریق mime_types_handler مدیریت می‌کند.

• گزینه‌ها

  MimeHandlerOptions

  گزینه‌هایی که باید تغییر کند.

بازگشتی‌ها

• Promise<void>

  وقتی پیکربندی تنظیم شد، Promise حل شد.