تعديل الرمز

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

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

استبدل Tab.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']
});

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

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

• إذن "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. 

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

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

إنّ الإجراءات في إصدار 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.

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

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

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

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

في الإصدار Manifest V3، تعرض العديد من طرق واجهة برمجة التطبيقات الخاصة بالإضافات وعودًا. الوعد هو خادم وكيل أو عنصر نائب لقيمة يتم عرضها بواسطة طريقة غير متزامنة. إذا لم يسبق لك استخدام تطبيق 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.