به‌روزرسانی کد

به‌روزرسانی‌هایی که به مشکلات دیگر مربوط نیستند

این اولین بخش از سه بخشی است که تغییرات لازم برای کدی را که بخشی از کارگر سرویس افزونه نیست شرح می‌دهد. این بخش برای تغییرات کد الزامی است که به مشکلات دیگر مربوط نیست. دو بخش بعدی به جایگزینی درخواست‌های وب مسدودکننده و بهبود امنیت می‌پردازند.

tabs.executeScript()‎ را با scripting.executeScript()‎ جایگزین کنید

در «مانیفست نسخه ۳»، executeScript() از میانای برنامه‌سازی کاربردی tabs به میانای برنامه‌سازی کاربردی scripting منتقل می‌شود. این کار علاوه‌بر تغییرات کد واقعی، به تغییراتی در اجازه‌های فایل مانیفست نیاز دارد.

برای روش executeScript() به این موارد نیاز دارید:

  • اجازه "scripting".
  • اجازه‌های میزبان یا اجازه "activeTab".

روش scripting.executeScript() مشابه نحوه عملکرد آن با tabs.executeScript() است. چند تفاوت وجود دارد.

  • درحالی‌که روش قدیمی فقط می‌توانست یک فایل را دریافت کند، روش جدید می‌تواند آرایه‌ای از فایل‌ها را دریافت کند.
  • همچنین به‌جای InjectDetails، شیء ScriptInjection را ارسال می‌کنید. تفاوت‌های متعددی بین این دو وجود دارد. برای مثال، tabId اکنون به‌عنوان عضوی از ScriptInjection.target ارسال می‌شود، نه به‌عنوان آرگومان متد.

این مثال نحوه انجام این کار را نشان می‌دهد.

Manifest V2
async function getCurrentTab() {/* ... */}
let tab = await getCurrentTab();

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

در فایل اسکریپت پس‌زمینه.

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

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

در کارگر سرویس افزونه.

tabs.insertCSS()‎ و tabs.removeCSS()‎ را با scripting.insertCSS()‎ و scripting.removeCSS()‎ جایگزین کنید

در Manifest V3،‏ insertCSS() و removeCSS() از tabs API به scripting API منتقل می‌شوند. این کار علاوه‌بر تغییرات کد، مستلزم تغییراتی در اجازه‌های فایل مانیفست است:

  • اجازه "scripting".
  • اجازه‌های میزبان یا اجازه "activeTab".

عملکردهای scripting API مشابه عملکردهای tabs است. چند تفاوت وجود دارد.

  • هنگام فراخوانی این روش‌ها، به‌جای InjectDetails، شیء CSSInjection را ارسال می‌کنید.
  • اکنون tabId به‌عنوان عضوی از CSSInjection.target به‌جای آرگومان روش ارسال می‌شود.

این مثال نشان می‌دهد که چگونه این کار را برای insertCSS() انجام دهید. روال removeCSS() هم همین‌طور است.

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

در فایل اسکریپت پس‌زمینه.

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

در کارگر سرویس افزونه.

جایگزین کردن «کنش‌های مرورگر» و «کنش‌های صفحه» با «کنش‌ها»

کنش‌های مرورگر و کنش‌های صفحه در Manifest V2 مفاهیم جداگانه‌ای بودند. اگرچه آن‌ها با نقش‌های متمایز شروع کردند، اما تفاوت‌های بین آن‌ها با گذشت زمان کاهش یافت. در «مانیفست نسخه ۳»، این مفاهیم در میانای برنامه‌سازی کاربردی کنش ادغام شده‌اند. این کار مستلزم تغییراتی در manifest.json و کد افزونه است که با آنچه در اسکریپت پس‌زمینه «مانیفست نسخه ۲» قرار می‌دادید متفاوت است.

کنش‌ها در Manifest V3 بیشترین شباهت را به کنش‌های مرورگر دارند؛ بااین‌حال، action API برخلاف pageAction، hide() و show() را ارائه نمی‌دهد. اگر هنوز به کنش‌های صفحه نیاز دارید، می‌توانید آن‌ها را بااستفاده از محتوای اعلانی شبیه‌سازی کنید یا 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"
  }

  ...
}

جایگزین کردن میاناهای برنامه‌سازی کاربردی browserAction و pageAction با میانای برنامه‌سازی کاربردی action

جایی که Manifest V2 شما از میاناهای برنامه‌سازی کاربردی browserAction و pageAction استفاده می‌کرد، اکنون باید از میانای برنامه‌سازی کاربردی action استفاده کنید.

Manifest V2
browser.browserAction.onClicked.addListener(tab => { ... });
browser.pageAction.onClicked.addListener(tab => { ... });
Manifest V3
browser.action.onClicked.addListener(tab => { ... });

جایگزین کردن فراخوانی‌های برگشتی با وعده‌ها

در «مانیفست نسخه ۳»، بسیاری از روش‌های میانای برنامه‌سازی کاربردی افزونه، وعده برمی‌گردانند. Promise یک پراکسی یا جای‌بان برای مقداری است که توسط یک روش ناهمگام برگردانده می‌شود. اگر هرگز از Promises استفاده نکرده‌اید، می‌توانید درباره آن‌ها در MDN بخوانید. این صفحه توضیح می‌دهد که برای استفاده از آن‌ها در افزونه Chrome چه چیزهایی را باید بدانید.

برای سازگاری با نسخه قدیمی، بسیاری‌از روش‌ها پس‌از اضافه شدن پشتیبانی از Promise، همچنان از Callback پشتیبانی می‌کنند. توجه داشته باشید که نمی‌توانید از هر دو در یک فراخوانی تابع استفاده کنید. اگر یک فراخوانی را ارسال کنید، تابع یک وعده را برنمی‌گرداند و اگر می‌خواهید یک وعده برگردانده شود، فراخوانی را ارسال نکنید. برخی‌از ویژگی‌های میانای برنامه‌سازی کاربردی، مثل شنوندگان رویداد، همچنان به فراخوانی‌های برگشتی نیاز خواهند داشت. برای بررسی اینکه آیا روشی از Promise پشتیبانی می‌کند یا نه، برچسب «Promise» را در مرجع میانای برنامه‌سازی کاربردی آن جستجو کنید.

برای تبدیل از callback به promise، callback را بردارید و promise برگردانده‌شده را مدیریت کنید. نمونه زیر از نمونه اجازه‌های اختیاری، به‌طور خاص newtab.js، گرفته شده است. نسخه تماس برگشتی نشان می‌دهد که تماس نمونه با request() با تماس برگشتی چگونه خواهد بود. توجه داشته باشید که نسخه promise را می‌توان با async و await بازنویسی کرد.

پاسخ تماس
browser.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});
قول دادن
const newPerms = { permissions: ['topSites'] };
browser.permissions.request(newPerms)
.then((granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

جایگزین کردن توابعی که انتظار بافت پس‌زمینه Manifest V2 را دارند

سایر زمینه‌های افزونه فقط می‌توانند بااستفاده از انتقال پیام با کارگران سرویس افزونه تعامل داشته باشند. درنتیجه، باید فراخوانی‌هایی را که انتظار بافت پس‌زمینه دارند جایگزین کنید، به‌ویژه:

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

اسکریپت‌های افزونه شما باید از ارسال پیام برای برقراری ارتباط بین یک کارگر سرویس و سایر بخش‌های افزونه شما استفاده کنند. درحال‌حاضر این کار را می‌توان بااستفاده از sendMessage() و پیاده‌سازی browser.runtime.onMessage در کارگر سرویس افزونه انجام داد. در بلندمدت، باید برای جایگزین کردن این فراخوانی‌ها با postMessage() و گرداننده رویداد پیام سرویس‌ورکر برنامه‌ریزی کنید.

جایگزین کردن میاناهای برنامه‌سازی کاربردی پشتیبانی‌نشده

روش‌ها و ویژگی‌های فهرست‌شده در زیر باید در «مانیفست نسخه ۳» تغییر کنند.

روش یا ویژگی Manifest V2 جایگزینی با
browser.extension.connect() browser.runtime.connect()
browser.extension.connectNative() browser.runtime.connectNative()
browser.extension.getExtensionTabs() browser.extension.getViews()
browser.extension.getURL() browser.runtime.getURL()
browser.extension.lastError جایی که روش‌ها وعده‌ها را برمی‌گردانند، از promise.catch() استفاده کنید
browser.extension.onConnect browser.runtime.onConnect
browser.extension.onConnectExternal browser.runtime.onConnectExternal
browser.extension.onMessage browser.runtime.onMessage
browser.extension.onRequest browser.runtime.onMessage
browser.extension.onRequestExternal browser.runtime.onMessageExternal
browser.extension.sendMessage() browser.runtime.sendMessage()
browser.extension.sendNativeMessage() browser.runtime.sendNativeMessage()
browser.extension.sendRequest() browser.runtime.sendMessage()
browser.runtime.onSuspend (اسکریپت‌های پس‌زمینه) در کارگران سرویس افزونه پشتیبانی نمی‌شود. درعوض از رویداد سند beforeunload استفاده کنید.
browser.tabs.getAllInWindow() browser.tabs.query()
browser.tabs.getSelected() browser.tabs.query()
browser.tabs.onActiveChanged browser.tabs.onActivated
browser.tabs.onHighlightChanged browser.tabs.onHighlighted
browser.tabs.onSelectionChanged browser.tabs.onActivated
browser.tabs.sendRequest() browser.runtime.sendMessage()
browser.tabs.Tab.selected browser.tabs.Tab.highlighted