تعديل الرمز

التحديثات غير المرتبطة بمشاكل أخرى

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

استبدِل tabs.executeScript() بـ scripting.executeScript()

في Manifest V3، يتم نقل executeScript() من واجهة برمجة التطبيقات tabs إلى واجهة برمجة التطبيقات scripting. يتطلّب ذلك إجراء تغييرات على الأذونات في ملف البيان، بالإضافة إلى تغييرات فعلية في الرمز البرمجي.

لاستخدام طريقة executeScript()، يجب استيفاء الشروط التالية:

• إذن "scripting"
• إما أذونات المضيف أو إذن "activeTab"

تشبه طريقة عمل الدالة scripting.executeScript() طريقة عملها مع tabs.executeScript(). هناك بعض الاختلافات.

• في حين أنّ الطريقة القديمة كانت تقبل ملفًا واحدًا فقط، يمكن للطريقة الجديدة قبول مجموعة من الملفات.
• يمكنك أيضًا تمرير العنصر ScriptInjection بدلاً من InjectDetails. هناك اختلافات متعددة بينهما. على سبيل المثال، يتم الآن تمرير tabId كعنصر من ScriptInjection.target بدلاً من تمريره كمعلَمة طريقة.

يوضّح المثال كيفية إجراء ذلك.

async function getCurrentTab() {/* ... */}
let tab = await getCurrentTab();

browser.tabs.executeScript(
  tab.id,
  {
    file: 'content-script.js'
  }
);

async function getCurrentTab()
let tab = await getCurrentTab();

browser.scripting.executeScript({
  target: {tabId: tab.id},
  files: ['content-script.js']
});

استبدال tabs.insertCSS() وtabs.removeCSS() بـ scripting.insertCSS() وscripting.removeCSS()

في الإصدار 3 من Manifest، يتم نقل insertCSS() وremoveCSS() من واجهة برمجة التطبيقات tabs إلى واجهة برمجة التطبيقات scripting. يتطلّب ذلك إجراء تغييرات على الأذونات في ملف البيان بالإضافة إلى تغييرات في الرمز البرمجي:

• إذن "scripting"
• إما أذونات المضيف أو إذن "activeTab"

تتشابه الدوال في واجهة برمجة التطبيقات scripting مع الدوال في tabs. هناك بعض الاختلافات.

• عند استدعاء هذه الطرق، عليك تمرير عنصر CSSInjection بدلاً من InjectDetails.
• يتم الآن تمرير tabId كعنصر من CSSInjection.target بدلاً من تمريره كوسيطة للدالة.

يوضّح المثال كيفية إجراء ذلك بالنسبة إلى insertCSS(). ويكون الإجراء نفسه في ما يخصّ removeCSS().

browser.tabs.insertCSS(tabId, injectDetails, () => {
  // callback code
});

const insertPromise = await browser.scripting.insertCSS({
  files: ["style.css"],
  target: { tabId: tab.id }
});
// Remaining code. 

استبدال "إجراءات المتصفّح" و"إجراءات الصفحة" بـ "الإجراءات"

كانت إجراءات المتصفّح وإجراءات الصفحة مفهومَين منفصلَين في Manifest V2. وعلى الرغم من أنّها بدأت بأدوار مختلفة، إلا أنّ الاختلافات بينها تقلّصت بمرور الوقت. في الإصدار Manifest V3، تم دمج هذه المفاهيم في واجهة برمجة التطبيقات Action. يتطلّب ذلك إجراء تغييرات في manifest.json ورمز الإضافة تختلف عن تلك التي كنت ستضعها في نص الخلفية Manifest V2.

تشبه الإجراءات في Manifest V3 إجراءات المتصفّح إلى حدّ كبير، ولكنّ واجهة برمجة التطبيقات action لا توفّر hide() وshow() كما كانت تفعل pageAction. إذا كنت لا تزال بحاجة إلى إجراءات الصفحة، يمكنك إما محاكاتها باستخدام المحتوى التعريفي أو طلب enable() أو disable() باستخدام رقم تعريف علامة التبويب.

استبدال "browser_action" و "page_action" بـ "action"

في manifest.json، استبدِل الحقلَين "browser_action" و"page_action" بالحقل "action". راجِع المرجع للحصول على معلومات حول الحقل "action".

{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}

{
  ...
  "action": {
    "default_popup": "popup.html"
  }

  ...
}

استبدال واجهتَي برمجة التطبيقات browserAction وpageAction بواجهة برمجة التطبيقات action

في حال كان الإصدار Manifest V2 يستخدم واجهتَي برمجة التطبيقات browserAction وpageAction، عليك الآن استخدام واجهة برمجة التطبيقات action.

browser.browserAction.onClicked.addListener(tab => { ... });
browser.pageAction.onClicked.addListener(tab => { ... });

browser.action.onClicked.addListener(tab => { ... });

استبدال عمليات معاودة الاتصال بالوعود

في الإصدار Manifest V3، تعرض العديد من طرق واجهة برمجة التطبيقات للإضافات وعودًا. Promise هو وكيل أو عنصر نائب لقيمة يتم عرضها بواسطة طريقة غير متزامنة. إذا لم يسبق لك استخدام Promises، يمكنك الاطّلاع على مزيد من المعلومات عنها على MDN. توضّح هذه الصفحة المعلومات التي تحتاج إلى معرفتها لاستخدامها في إضافة Chrome.

لضمان التوافق مع الإصدارات القديمة، تواصل العديد من الطرق إتاحة عمليات رد الاتصال بعد إضافة ميزة التوافق مع الوعود. يُرجى العِلم أنّه لا يمكنك استخدام كليهما في طلب الوظيفة نفسه. إذا مرّرت دالة ردّ اتصال، لن تعرض الدالة وعدًا، وإذا أردت عرض وعد، لا تمرّر دالة ردّ اتصال. ستظل بعض ميزات واجهة برمجة التطبيقات، مثل أدوات معالجة الأحداث، تتطلّب عمليات ردّ الاتصال. لمعرفة ما إذا كانت إحدى الطرق تتيح استخدام الوعود، ابحث عن التصنيف "Promise" في مرجع واجهة برمجة التطبيقات الخاص بها.

لتحويل عملية ردّ الاتصال إلى وعد، عليك إزالة عملية ردّ الاتصال والتعامل مع الوعد الذي تم إرجاعه. تم أخذ المثال أدناه من نموذج الأذونات الاختيارية، وتحديدًا newtab.js. يعرض إصدار رد الاتصال الشكل الذي سيبدو عليه طلب العيّنة إلى request() مع رد اتصال. يُرجى العِلم أنّه يمكن إعادة كتابة إصدار الوعد باستخدام async وawait.

browser.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

const newPerms = { permissions: ['topSites'] };
browser.permissions.request(newPerms)
.then((granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

استبدال الدوال التي تتوقّع سياق خلفية الإصدار 2 من البيان

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

• browser.runtime.getBackgroundPage()
• browser.extension.getBackgroundPage()
• browser.extension.getExtensionTabs()

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

استبدال واجهات برمجة التطبيقات غير المتوافقة

يجب تغيير الطرق والسمات المدرَجة أدناه في الإصدار Manifest V3.