chrome.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" وتشغيلها، ولكن لا يتم تسجيلها كمعالج ويكون chrome.mimeHandler غير محدّد. يمكن للإضافات التي يتم نقل بياناتها من عملية اعتراض طلبات الشبكة التحقّق من توفّر واجهة برمجة التطبيقات عند بدء التشغيل، والاحتفاظ بالأسلوب الحالي كحلّ احتياطي:

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

أمثلة

التعامل مع بث

يعمل المثال التالي في صفحة المعالِج المحدّدة في البيان. يستردّ هذا الإطار محتوى المستند ويعود إلى عارض Chrome المضمّن في حال تعذّر العرض:

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

السماح للمستخدمين بتفعيل أو إيقاف المعالجة

يتم تخزين خيارات المعالج لكل نوع 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();

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>