تعديل الرمز

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

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

استبدِل 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();

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

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

chrome.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() هو نفسه.

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

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

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

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

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

استبدال "browser_action" و"page_action" بكلمة "إجراء"

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

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

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

  ...
}

استبدل واجهات برمجة التطبيقات browserAction وpageAction API بـ Action API.

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

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

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

استبدال عمليات الاستدعاء بـ promises

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

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

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

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

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

استبدال الدوال التي تتوقع الحصول على سياق خلفية Manifest V2 فيها

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

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

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

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

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