تعديل الرمز

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

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

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

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

بالنسبة إلى طريقة executeScript()، ستحتاج إلى ما يلي:

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

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

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

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

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

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

في ملف نص برمجي في الخلفية

Manifest V3
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().

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

في ملف نص برمجي في الخلفية

Manifest V3
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".

Manifest V2
{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}
Manifest V3
{
  ...
  "action": {
    "default_popup": "popup.html"
  }

  ...
}

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

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

Manifest V2
browser.browserAction.onClicked.addListener(tab => { ... });
browser.pageAction.onClicked.addListener(tab => { ... });
Manifest V3
browser.action.onClicked.addListener(tab => { ... });

استبدال عمليات الاستدعاء بوعود

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

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

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

معاودة الاتصال
browser.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});
Promise
const newPerms = { permissions: ['topSites'] };
browser.permissions.request(newPerms)
.then((granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

استبدال الدوال التي تتطلّب سياقًا في الخلفية للإصدار Manifest V2

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

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

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

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

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

طريقة أو سمة Manifest V2 الاستبدال بـ
browser.extension.connect() browser.runtime.connect()
browser.extension.connectNative() browser.runtime.connectNative()
browser.extension.getExtensionTabs() browser.extension.getViews()
browser.extension.getURL() browser.runtime.getURL()
browser.extension.lastError عندما تعرض الطرق وعودًا، استخدِم promise.catch()
browser.extension.onConnect browser.runtime.onConnect
browser.extension.onConnectExternal browser.runtime.onConnectExternal
browser.extension.onMessage browser.runtime.onMessage
browser.extension.onRequest browser.runtime.onMessage
browser.extension.onRequestExternal browser.runtime.onMessageExternal
browser.extension.sendMessage() browser.runtime.sendMessage()
browser.extension.sendNativeMessage() browser.runtime.sendNativeMessage()
browser.extension.sendRequest() browser.runtime.sendMessage()
‫browser.runtime.onSuspend (نصوص برمجية في الخلفية) غير متاحة في مشغّلي خدمات الإضافات. استخدِم حدث المستند beforeunload بدلاً من ذلك.
browser.tabs.getAllInWindow() browser.tabs.query()
browser.tabs.getSelected() browser.tabs.query()
browser.tabs.onActiveChanged browser.tabs.onActivated
browser.tabs.onHighlightChanged browser.tabs.onHighlighted
browser.tabs.onSelectionChanged browser.tabs.onActivated
browser.tabs.sendRequest() browser.runtime.sendMessage()
browser.tabs.Tab.selected browser.tabs.Tab.highlighted