التعديلات التي لا تتعلّق بمشاكل أخرى
هذا هو القسم الأول من بين ثلاثة أقسام تصف التغييرات اللازمة للتعليمة البرمجية التي ليست جزءًا من مشغّل خدمات الإضافات. هذا القسم مخصّص لتغييرات الرمز المطلوبة التي لا تتعلّق بمشاكل أخرى. يتناول القسمان التاليان استبدال طلبات حظر الويب وتحسين الأمان.
استبدال tabs.executeScript() بـ scripting.executeScript()
في إصدار Manifest V3، يتم نقل executeScript()
من tabs
API إلى scripting
API. يتطلب ذلك إجراء تغييرات على الأذونات في ملف البيان بالإضافة إلى تغييرات الرمز الفعلية.
بالنسبة إلى طريقة 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() وtab.removeCSS() بالبرمجة النصية.insertCSS() والبرمجة النصية.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
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" } ... }
استبدال واجهات برمجة التطبيقات searchAction وpageAction بواجهة برمجة التطبيقات للإجراء
عند استخدام إصدار Manifest V2 الخاص بواجهة برمجة التطبيقات browserAction
وpageAction
، عليك الآن استخدام action
API.
chrome.browserAction.onClicked.addListener(tab => { ... }); chrome.pageAction.onClicked.addListener(tab => { ... });
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 |