chrome.mimeHandler

توضیحات

از API chrome.mimeHandler برای مدیریت جریان‌های نوع MIME در افزونه‌های شخص ثالث استفاده کنید.

در دسترس بودن

در حال بررسی

مانیفست

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

"mime_types_handler"

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

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

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

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

ثبت نام یک هندلر

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

مانیفست.json:

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

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

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

بازیابی اطلاعات جریان

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

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

به هندلر بومی برگردید

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

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

مدیریت در دسترس بودن API

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

سرویس-ورکر.js:

if (chrome.mimeHandler) {
  // Chrome routes registered MIME types to the handler page
  // declared in the manifest.
} else {
  // Fall back to network request interception.
}

مثال‌ها

مدیریت یک جریان

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

بیننده.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();

به کاربران اجازه دهید نحوه‌ی مدیریت را تغییر دهند

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

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

انواع

MimeHandlerOptions

خواص

  • فعال شده

    بولی

    آیا این کنترل‌کننده برای نوع MIME داده شده فعال است یا خیر.

StreamInfo

خواص

  • جاسازی شده

    بولی

    اگر در یک زمینه تعبیه‌شده (iframe/embed/object) بارگذاری شود، صحیح است.

  • نوع مایم

    رشته

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

  • آدرس اصلی

    رشته

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

  • هدرهای پاسخ

    شیء

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

  • آدرس اینترنتی

    رشته

    آدرس اینترنتی (URL) برای دریافت داده‌های جریان داده.

  • شناسه برگه

    شماره

    شناسه‌ی برگه‌ای که سند در آن قرار دارد.

روش‌ها

abortAndFallbackToNativeHandler()

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

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

بازگشت‌ها

  • قول<void>

getMimeHandlerOptions()

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

گزینه‌های ذخیره شده برای یک نوع MIME را می‌خواند. اگر هیچ کدام ذخیره نشده باشند، مقادیر پیش‌فرض (enabled=true) را برمی‌گرداند.

پارامترها

  • نوع مایم

    رشته

    نوع MIME که گزینه‌های آن خوانده می‌شود.

بازگشت‌ها

getStreamInfo()

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

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

بازگشت‌ها

setMimeHandlerOptions()

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

گزینه‌های پیکربندی را برای یک نوع MIME مشخص شده تنظیم می‌کند.

پارامترها

  • نوع مایم

    رشته

    نوع MIME برای پیکربندی.

  • گزینه‌های جدیدی که باید استفاده شوند.

بازگشت‌ها

  • قول<void>

    قول داده شده پس از تنظیم پیکربندی، حل شود.