الانتقال إلى مساحة اسم المتصفّح

اعتبارًا من الإصدار 148 من Chrome، تتوفّر جميع واجهات برمجة التطبيقات لإضافات Chrome ضمن مساحة الاسم browser بالإضافة إلى مساحة الاسم الحالية chrome. على سبيل المثال، browser.tabs.create({}) وchrome.tabs.create({}) متماثلتان.

تتوفّر مساحة الاسم في أي مكان يمكنك فيه استدعاء واجهات برمجة التطبيقات للإضافات، بما في ذلك النصوص البرمجية للمحتوى و"العاملون في الخدمة" والمستندات خارج الشاشة. تشير مساحة الاسم إلى كائنات واجهة برمجة التطبيقات نفسها التي تشير إليها ، لذا فإنّ chromechrome.tabs === browser.tabs.

تنتج مساحة الاسم browser عن العمل في WebExtensions Community Group (WECG), وهي مجموعة منتدى W3C يتعاون فيها مورّدو المتصفّحات بشأن معايير الإضافات المشترَكة. لن يتم إيقاف مساحة الاسم chrome، وسيستمر عمل مساحتَي الاسم.

تحديد ما إذا كنت ستستخدم مساحة الاسم browser

إذا كنت تستخدم webextension-polyfill، انتقِل إلى ملاحظة لمستخدمي polyfill قبل تغيير أي شيء آخر، لأنّ الإجابة مختلفة بالنسبة إليك.

إذا كنت بصدد إنشاء إضافة جديدة، اضبط minimum_chrome_version على "148" واستخدِم browser بدون شروط، ويمكنك التوقف عن القراءة هنا. بقية هذا القسم مخصّصة للإضافات الحالية التي تحدّد كيفية استخدام مساحة الاسم.

التحقّق من إصدارات Chrome التي يستخدمها المستخدمون

إذا كانت لديك إضافة حالية، تحقَّق من إصدارات Chrome التي يستخدمها المستخدمون قبل التبديل. يتم تحديث Chrome تلقائيًا، ولكن بعض المستخدمين يوقفون التحديثات ويستخدم آخرون أجهزة قديمة لا يمكنها تشغيل أحدث إصدار. أكِّد ذلك باستخدام بيانات "إحصاءات Google" الخاصة بك. إذا لم تكن قد أعددت "إحصاءات Google" بعد، يمكنك الاطّلاع على مقالة تتبُّع أداء إضافتك باستخدام "إحصاءات Google‏ 4" للبدء.

من هنا، اختَر مسارًا:

استخدام مساحة الاسم بدون شروط

اضبط minimum_chrome_version في ملف البيان واستخدِم browser بدون شروط، ولا حاجة إلى أداة الحماية في وقت التشغيل:

{
  "minimum_chrome_version": "148"
}

استخدِم طرحًا على مراحل عند رفع minimum_chrome_version. إذا حدث خطأ ما، يمكنك التراجع عن إضافتك في "سوق Chrome الإلكتروني".

استخدام أداة الحماية في وقت التشغيل

أضِف المقتطف البرمجي التالي في بداية رمز بدء تشغيل إضافتك قبل الإشارة إلى browser في أي مكان آخر:

if (!globalThis.browser) {
  globalThis.browser = chrome;
  // Consider firing an analytics event here to measure how often
  // your users hit this fallback path.
}

يؤدي هذا إلى جعل browser اسمًا مستعارًا لـ chrome في الإصدارات السابقة، لذا يمكن لبقية الرمز البرمجي استخدام browser بدون شروط.

ملاحظة لمستخدمي polyfill

إذا كانت إضافتك تستخدم webextension-polyfill، ستصبح بلا تأثير في الإصدار 148 من Chrome والإصدارات الأحدث. تخطّى polyfill عملية التغليف عندما تم تحديد browser من قبل، على افتراض أنّ المتصفّح المضيف قد سبق له توفير واجهة برمجة التطبيقات.

تم التراجع عن محاولة سابقة لشحن مساحة الاسم في الإصدار 136 من Chrome لـ هذا السبب: مع تحديد browser حديثًا، توقّف polyfill عن التغليف، ولكن browser.runtime.onMessage في Chrome لم يكن بعد يتيح للمستمعين عرض الوعود، وهو ما كان يوفّره polyfill. توقّفت الإضافات التي تعتمد على هذا النمط عن العمل. يشحن الإصدار 148 من Chrome مساحة الاسم والمستمعين الأصليين الذين يعرضون الوعود onMessage معًا لتجنُّب هذه الفجوة.

يمكنك إزالة تبعية polyfill بعد أن ينتقل قاعدة المستخدمين إلى الإصدار 148 من Chrome.

ميزات أخرى

الردود غير المتزامنة في runtime.sendMessage

في الإصدار 148 من Chrome، يمكن للمستمعين runtime.onMessage عرض Promise مباشرةً لإرسال رد غير متزامن. يعمل هذا الإجراء سواء استدعيته باستخدام chrome.* أو browser.*.

في السابق، كانت الطريقة الوحيدة للرد بشكل غير متزامن هي عرض true حرفيًا من المستمع واستدعاء sendResponse لاحقًا:

// Old pattern - requires returning true to keep the channel open
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  fetch('https://example.com')
    .then(response => sendResponse({ statusCode: response.status }));

  return true; // keeps the message channel open for the async response
});

يمكنك الآن عرض Promise (أو استخدام دالة async) مباشرةً:

// New pattern - return a promise or use async/await
browser.runtime.onMessage.addListener(async (message, sender) => {
  const response = await fetch('https://example.com');
  return { statusCode: response.status };
});

سيستمر نمط return true في العمل، لذا ليس عليك تغيير الرمز البرمجي الحالي.