تعديل الرمز

التعديلات التي لا تتعلّق بمشاكل أخرى

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

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

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

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

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

تشبه الدوالّ في scripting API الدوالّ في 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 من ملف البيان. على الرغم من أنها بدأت بأدوار مختلفة، إلا أن الاختلافات بينها انخفضت بمرور الوقت. في الإصدار 3 من ملف البيان، يتم دمج هذه المفاهيم في واجهة برمجة التطبيقات Action. يتطلّب هذا الإجراء إجراء تغييرات في "manifest.json" ورمز الإضافة مختلفَين عن الرمز الذي كنت ستدرجه في النص البرمجي Manifest V2 للخلفية.

تُشبه الإجراءات في إصدار Manifest V3 إلى حد كبير إجراءات المتصفّح، ومع ذلك، لا توفّر واجهة برمجة التطبيقات action API 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"
  }

  ...
}

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

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

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

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

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

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

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

لتحويل المكالمة من معاودة الاتصال إلى وعد، عليك إزالتها والتعامل مع الوعد الذي تم إرجاعه. المثال أدناه مأخوذ من نموذج الأذونات الاختيارية، وهي 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() ومعالج أحداث الرسائل لدى مشغّل الخدمات.

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

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