کد خود را به روز کنید

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

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

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

در Manifest V3، executeScript() از API tabs به API scripting حرکت می کند. این امر علاوه بر تغییرات واقعی کد، به تغییراتی در مجوزها در فایل مانیفست نیاز دارد.

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

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

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

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

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

مانیفست V2
async function getCurrentTab() {/* ... */}
let tab = await getCurrentTab();

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

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

مانیفست V3
async function getCurrentTab()
let tab = await getCurrentTab();

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

در کارگر خدمات ترویج.

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

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

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

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

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

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

مانیفست V2
chrome.tabs.insertCSS(tabId, injectDetails, () => {
  // callback code
});

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

مانیفست V3
const insertPromise = await chrome.scripting.insertCSS({
  files: ["style.css"],
  target: { tabId: tab.id }
});
// Remaining code.

در کارگر خدمات ترویج.

اقدامات مرورگر و اقدامات صفحه را با Actions جایگزین کنید

اقدامات مرورگر و اقدامات صفحه مفاهیم جداگانه ای در Manifest V2 بودند. اگرچه آنها با نقش های متمایز شروع کردند، اما تفاوت بین آنها با گذشت زمان کاهش یافت. در Manifest V3، این مفاهیم در Action API ادغام می شوند. این به تغییراتی در manifest.json و کد برنامه افزودنی شما نیاز دارد که با آنچه در اسکریپت پس‌زمینه Manifest V2 قرار می‌دادید متفاوت است.

اقدامات در Manifest V3 بیشتر شبیه اقدامات مرورگر است. با این حال، action API مانند pageAction hide() و show() ارائه نمی دهد. اگر همچنان به اقدامات صفحه نیاز دارید، می‌توانید با استفاده از محتوای اعلامی آن‌ها را شبیه‌سازی کنید یا enable() disable() .

"browser_action" و "page_action" را با "action" جایگزین کنید.

در manifest.json فیلدهای "browser_action" و "page_action" را با فیلد "action" جایگزین کنید. برای کسب اطلاعات در زمینه "action" به مرجع مراجعه کنید.

مانیفست V2
{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}
مانیفست V3
{
  ...
  "action": {
    "default_popup": "popup.html"
  }

  ...
}

API های browserAction و pageAction را با API Action جایگزین کنید

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

مانیفست V2
chrome.browserAction.onClicked.addListener(tab => { ... });
chrome.pageAction.onClicked.addListener(tab => { ... });
مانیفست V3
chrome.action.onClicked.addListener(tab => { ... });

پاسخ تماس ها را با وعده ها جایگزین کنید

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

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

برای تبدیل از callback به وعده، callback را بردارید و وعده برگشتی را مدیریت کنید. مثال زیر از نمونه مجوزهای اختیاری ، به طور خاص newtab.js گرفته شده است. نسخه callback نشان می دهد که call to request() نمونه با یک callback چگونه خواهد بود. توجه داشته باشید که نسخه وعده را می توان با async بازنویسی کرد و منتظر ماند.

پاسخ به تماس
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() و مدیریت رویداد پیام کارگر سرویس جایگزین کنید.

API های پشتیبانی نشده را جایگزین کنید

روش ها و ویژگی های ذکر شده در زیر باید در Manifest V3 تغییر کنند.

روش یا ویژگی 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