עדכון הקוד

עדכונים שלא קשורים לבעיות אחרות

זהו הקטע הראשון מתוך שלושה שמתארים את השינויים שצריך לבצע בקוד שלא שייך ל-service worker של התוסף. בקטע הזה מפורטים שינויים נדרשים בקוד שלא קשורים לבעיות אחרות. בקטעים הבאים מוסבר על החלפת חסימה של בקשות אינטרנט ועל שיפור האבטחה.

החלפת tabs.executeScript()‎ ב-scripting.executeScript()‎

ב-Manifest V3, ‏ executeScript() עובר מ-API של tabs ל-API של scripting. כדי להשתמש ב-API הזה, צריך לבצע שינויים בהרשאות בקובץ המניפסט, בנוסף לשינויים בקוד עצמו.

כדי להשתמש בשיטה executeScript(), צריך:

• ההרשאה "scripting".
• הרשאות מארח או הרשאת "activeTab".

השיטה scripting.executeScript() דומה לאופן שבו היא פעלה עם tabs.executeScript(). יש כמה הבדלים.

• בשיטה הישנה אפשר היה להעלות רק קובץ אחד, אבל בשיטה החדשה אפשר להעלות מערך של קבצים.
• בנוסף, מעבירים אובייקט ScriptInjection במקום InjectDetails. יש כמה הבדלים בין השניים. לדוגמה, הערך tabId מועבר עכשיו כחבר ב-ScriptInjection.target במקום כארגומנט של שיטה.

בדוגמה הבאה אפשר לראות איך עושים את זה.

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

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

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. כדי להשתמש ב-API הזה, צריך לשנות את ההרשאות בקובץ המניפסט, בנוסף לשינויים בקוד:

• ההרשאה "scripting".
• הרשאות מארח או הרשאת "activeTab".

הפונקציות ב-API‏ scripting דומות לפונקציות ב-tabs. יש כמה הבדלים.

• כשמפעילים את ה-methods האלה, מעבירים אובייקט CSSInjection במקום InjectDetails.
• המאפיין tabId מועבר עכשיו כחבר של CSSInjection.target במקום כארגומנט של שיטה.

בדוגמה אפשר לראות איך עושים את זה עבור insertCSS(). ההליך עבור removeCSS() זהה.

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

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

החלפת פעולות בדפדפן ופעולות בדף בפעולות

פעולות בדפדפן ופעולות בדף היו מושגים נפרדים ב-Manifest V2. למרות שהם התחילו עם תפקידים שונים, ההבדלים ביניהם הצטמצמו עם הזמן. ב-Manifest V3, המושגים האלה מאוחדים ב-API של 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"
  }

  ...
}

החלפת ממשקי ה-API של browserAction ו-pageAction בממשק ה-API של action

במקום להשתמש בממשקי ה-API‏ browserAction ו-pageAction ב-Manifest V2, עכשיו צריך להשתמש ב-API‏ action.

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

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

החלפת קריאות חוזרות (callback) בהבטחות (promise)

ב-Manifest V3, הרבה שיטות של Extension API מחזירות הבטחות. ‫Promise הוא proxy או placeholder לערך שמוחזר על ידי שיטה אסינכרונית. אם אף פעם לא השתמשתם ב-Promises, תוכלו לקרוא עליהם ב-MDN. בדף הזה מתואר מה צריך לדעת כדי להשתמש בהם בתוסף ל-Chrome.

כדי לשמור על תאימות לאחור, הרבה שיטות ממשיכות לתמוך בפונקציות קריאה חוזרת אחרי הוספת התמיכה בהבטחות. חשוב לדעת שאי אפשר להשתמש בשניהם באותה קריאה לפונקציה. אם מעבירים קריאה חוזרת, הפונקציה לא תחזיר הבטחה. אם רוצים שהפונקציה תחזיר הבטחה, לא מעבירים קריאה חוזרת. חלק מהתכונות של ה-API, כמו event listeners, ימשיכו לדרוש קריאות חוזרות (callbacks). כדי לבדוק אם שיטה מסוימת תומכת באובייקטים מסוג promise, מחפשים את התווית Promise (אובייקט promise) במאמרי העזרה של ה-API שלה.

כדי להמיר מקריאה חוזרת (callback) לאובייקט promise, מסירים את הקריאה החוזרת ומטפלים באובייקט promise שמוחזר. הדוגמה שלמטה לקוחה מדוגמת ההרשאות האופציונליות, במיוחד newtab.js. בגרסת הקריאה החוזרת (callback) אפשר לראות איך הקריאה של הדוגמה ל-request() תיראה עם קריאה חוזרת. שימו לב שאפשר לכתוב מחדש את גרסת ההבטחה באמצעות 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()

סקריפטים של תוספים צריכים להשתמש בהעברת הודעות כדי לתקשר בין Service Worker לבין חלקים אחרים של התוסף. בשלב הזה, אפשר לעשות את זה באמצעות sendMessage() והטמעה של browser.runtime.onMessage ב-service worker של התוסף. בטווח הארוך, מומלץ לתכנן להחליף את הקריאות האלה ב-postMessage() ובגורם מטפל באירועים של הודעות של קובץ שירות (service worker).

החלפת ממשקי API שלא נתמכים

צריך לשנות את השיטות והמאפיינים שמפורטים בהמשך ב-Manifest V3.