chrome.mimeHandler

الوصف

استخدِم واجهة برمجة التطبيقات chrome.mimeHandler لمعالجة مصادر بيانات أنواع MIME في إضافات الجهات الخارجية.

مدى التوفّر

في انتظار المراجعة

البيان

يجب تعريف المفاتيح التالية في البيان لاستخدام واجهة برمجة التطبيقات هذه.

"mime_types_handler"

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

في السابق، كانت إضافات الجهات الخارجية التي تعالج أنواع مستندات معيّنة (مثل عارضات ملفات 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> أيضًا. إذا تم حذف هذا المفتاح، لن يتلقّى المعالج سوى عمليات التنقّل على المستوى الأعلى. اعتبارًا من 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 أو من عناوين URL ذات الاستخدام الواحد. عليك جلب مصدر البيانات بالكامل قبل تحديد ما إذا كان بإمكانك عرضه. بعد اكتمال عملية جلب streamUrl، سيحصل Chrome على الردّ الكامل.

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

في إصدارات 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();

الأنواع

MimeHandlerOptions

الخصائص

  • مفعّلة

    قيمة منطقية

    ما إذا كان هذا المعالج مفعّلاً لنوع MIME المحدّد.

StreamInfo

الخصائص

  • مضمّنة

    قيمة منطقية

    صحيح إذا تم التحميل في سياق مضمّن (iframe/embed/object)

  • mimeType

    سلسلة

    نوع MIME للمحتوى الذي تم اعتراضه

  • originalUrl

    سلسلة

    عنوان URL الأصلي الذي انتقل إليه المستخدم

  • responseHeaders

    عنصر

    عناوين استجابة HTTP كأزواج مفتاح/قيمة

  • streamUrl

    سلسلة

    عنوان URL الذي يتم منه جلب بيانات مصدر البيانات

  • tabId

    الرقم

    رقم تعريف علامة التبويب التي تحتوي على المستند

الطُرق

abortAndFallbackToNativeHandler()

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

توقف معالجة مصدر البيانات الحالي وتعيد المحتوى إلى المعالج الأصلي لوكيل المستخدم. بعد هذا الاستدعاء، سيتم إيقاف إطار الإضافة، لذا يجب ألا يتوقع المتصلون تنفيذًا إضافيًا.

المرتجعات

  • ‫Promise<void>

getMimeHandlerOptions()

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

تقرأ الخيارات المحفوظة لنوع MIME. تعرض هذه الدالة الإعدادات التلقائية (enabled=true) إذا لم يتم تخزين أي خيارات.

المعلمات

  • mimeType

    سلسلة

    نوع MIME الذي تريد قراءة خياراته

المرتجعات

  • ‫Promise<MimeHandlerOptions>

    وعد يتم تنفيذه باستخدام الخيارات المحفوظة لنوع MIME

getStreamInfo()

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

تسترد هذه الدالة معلومات مصدر البيانات لسياق معالج MIME الحالي. يجب استدعاؤها من داخل صفحة إضافة معالج MIME.

المرتجعات

setMimeHandlerOptions()

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

تضبط هذه الدالة خيارات الإعداد لنوع MIME محدّد.

المعلمات

  • mimeType

    سلسلة

    نوع MIME الذي تريد ضبطه

  • الخيارات الجديدة التي تريد استخدامها

المرتجعات

  • ‫Promise<void>

    وعد يتم تنفيذه عند ضبط الإعداد