تعديل الرمز

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

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

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

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

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

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

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

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

يعرض المثال كيفية إجراء ذلك.

إصدار Manifest V2
async function getCurrentTab() {/* ... */}
let tab = await getCurrentTab();

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

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

إصدار Manifest V3
async function getCurrentTab()
let tab = await getCurrentTab();

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

في مشغّل خدمات الإضافات.

استبدل tabs.insertCSS() وtab.removeCSS() بالبرمجة النصية.insertCSS() والبرمجة النصية.removeCSS()

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

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

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

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

يعرض المثال كيفية إجراء ذلك لـ insertCSS(). إجراءات removeCSS() هي نفسها.

إصدار Manifest V2
chrome.tabs.insertCSS(tabId, injectDetails, () => {
  // callback code
});

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

إصدار Manifest V3
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 API الترميزَين 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"
  }

  ...
}

استبدال واجهات برمجة التطبيقات searchAction وpageAction بواجهة برمجة التطبيقات للإجراء

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

إصدار Manifest V2
chrome.browserAction.onClicked.addListener(tab => { ... });
chrome.pageAction.onClicked.addListener(tab => { ... });
إصدار Manifest V3
chrome.action.onClicked.addListener(tab => { ... });

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

في إصدار 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 من ملف البيان.

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