עדכון הקוד

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

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

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

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

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

• ההרשאה "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 דומות מאוד לפעולות בדפדפן, אבל ה-API של action לא מספק את 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

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

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

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

החלפת קריאות חוזרות (callbacks) בהבטחות (promises)

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

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

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

הקשרים אחרים של תוספים יכולים לקיים אינטראקציה עם קובצי ה-Service Worker של התוסף רק באמצעות העברת הודעות. לכן, תצטרכו להחליף קריאות שמצפות להקשר ברקע, ובמיוחד:

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

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

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

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