browser.mimeHandler

الوصف

مدى التوفّر

البيان

المفاهيم والاستخدام

في السابق، كانت الإضافات التابعة لجهات خارجية والتي تتعامل مع أنواع مستندات معيّنة (مثل برامج عرض ملفات PDF) تعتمد على اعتراض طلبات الشبكة لرصد عمليات التنقّل وإعادة توجيه المستخدمين إلى صفحة الإضافة. يؤدي التسجيل كمعالج MIME إلى تجنُّب العديد من القيود المفروضة على هذا الأسلوب:

• يبقى عنوان URL الأصلي في شريط العناوين بدلاً من استبداله بعنوان URL من chrome-extension://.
• تجلب الإضافة الردّ الذي تلقّاه Chrome، بدلاً من إرسال طلب شبكة ثانٍ. تعمل المستندات التي يتم تسليمها من خلال طلبات POST أو من عناوين URL للاستخدام الواحد بشكل صحيح.
• يمكن لإضافتك عرض المستندات التي تم تحميلها ضمن العناصر <embed> أو <object> أو <iframe>.
• تعمل الملفات المحلية (عناوين URL في المسار file://) بدون أن يفعّل المستخدم يدويًا خيار "السماح بالوصول إلى عناوين URL للملفات" في إعدادات الإضافة.

لا تنطبق معالِجات 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> أيضًا. في حال حذفها، سيتلقّى المعالج عمليات التنقّل ذات المستوى الأعلى فقط. اعتبارًا من الإصدار 151 من Chrome، أصبح application/pdf هو نوع MIME الوحيد المتاح للمعالِجات المتاحة للجميع، ويؤدي الإعلان عن نوع MIME غير متوافق إلى ظهور تحذير أثناء التثبيت.

إذا تم تسجيل أكثر من إضافة مثبّتة لنوع MIME نفسه، ستتعامل معها الإضافة التي تم تثبيتها مؤخرًا. وفي حال إلغاء تثبيت هذه الإضافة، سيصبح المعالج المثبَّت سابقًا نشطًا مرة أخرى.

استرداد معلومات البث

عندما يفتح مستخدم مستندًا من نوع MIME مسجَّل، يحمّل Chrome صفحة المعالج بدلاً من العارض المدمج. من صفحة المعالج، يمكنك استدعاء getStreamInfo() لاسترداد عنصر StreamInfo. ويشمل ذلك originalUrl الذي انتقل إليه المستخدم، وresponseHeaders لبروتوكول HTTP، وما إذا تم تحميل المستند في سياق embedded، وstreamUrl يمكن استخدامه لجلب محتوى المستند.

يمكن جلب streamUrl مرة واحدة فقط، ومن مصدر الإضافة فقط. يجب قراءة الردّ بالكامل قبل معالجته، لأنّ عملية الجلب الثانية لـ streamUrl نفسه ستفشل. استخدِم originalUrl عند عرض موقع المستند أو عنوانه، وليس لجلب المحتوى، لأنّ الطلب الأصلي قد لا يكون قابلاً للتكرار.

الرجوع إلى المعالج الأصلي

قد يواجه المعالج مستندات لا يمكنه عرضها، مثل الملفات التالفة أو المحمية بكلمة مرور. يمكنك استدعاء abortAndFallbackToNativeHandler() لإيقاف معالجة المستند وإعادته إلى عارض Chrome المضمّن، بدلاً من ترك المستخدم على صفحة معطّلة. يزيل Chrome صفحة المعالج كجزء من الإجراء الاحتياطي، ولا يتم تشغيل أي رمز برمجي بعد هذا الطلب.

يخزّن Chrome الردّ مؤقتًا أثناء تشغيل المعالج. إذا تم تلقّي الردّ بالكامل عند طلب هذه الطريقة، يعرض Chrome العارض المضمّن من النسخة المخزّنة مؤقتًا بدون طلب شبكة جديد. وإلا، سيعيد Chrome تحميل المستند من الشبكة، وقد يتعذّر ذلك في المستندات التي يتم تسليمها من خلال POST أو من عناوين URL للاستخدام الواحد. يمكنك جلب البث بالكامل قبل تحديد ما إذا كان بإمكانك عرضه. بعد اكتمال جلب streamUrl، سيحصل Chrome على الاستجابة الكاملة.

التعامل مع مدى توفّر واجهة برمجة التطبيقات

في إصدارات Chrome السابقة للإصدار 151، سيظل بإمكانك تثبيت وتشغيل الإضافة التي تصرّح عن "mime_types_handler"، ولكن لن يتم تسجيلها كمعالج، ولن يتم تحديد browser.mimeHandler. يمكن للإضافات التي يتم نقلها من اعتراض طلبات الشبكة التحقّق من واجهة برمجة التطبيقات عند بدء التشغيل والاحتفاظ بنهجها الحالي كحل احتياطي:

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>