עדכון הקוד

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

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

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

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

ל-method executeScript() צריך:

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

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

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

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

מניפסט מגרסה 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']
});

בקובץ השירות (service worker).

מחליפים את tab.insertCSS() ו-Tab.removeCSS() ב-scripting.insertCSS() ו-scripting.removeCSS() .

במניפסט מגרסה V3, insertCSS() ו-removeCSS() עוברים מה-API של tabs ל-API של scripting. לשם כך נדרשים שינויים בהרשאות בקובץ המניפסט, בנוסף לשינויים בקוד:

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

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

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

הדוגמה מראה איך לעשות זאת עבור 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.

בקובץ השירות (service worker).

החלפת פעולות הדפדפן ופעולות בדפים ב'פעולות'

פעולות דפדפן ופעולות בדפים היו מושגים נפרדים במניפסט מגרסה V2. למרות שהם התחילו עם תפקידים נפרדים, ההבדלים ביניהם הצטמצמו עם הזמן. במניפסט מגרסה V3, המושגים האלה אוחדו ל-Action API. לשם כך נדרשים שינויים ב-manifest.json ובקוד התוסף, השונה ממה שהייתם מוסיפים בסקריפט הרקע של Manifest V2.

הפעולות במניפסט מגרסה V3 דומות ביותר לפעולות בדפדפן; עם זאת, ה-API של action לא מספק את hide() ו-show() כמו ש-pageAction סיפק. אם עדיין נדרשות פעולות בדף, אפשר לאמול אותן באמצעות תוכן הצהרתי או להפעיל את 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 ב-Action API

במקומות שבהם במניפסט מגרסה V2 נעשה שימוש בממשקי ה-API browserAction ו-pageAction, צריך להשתמש עכשיו ב-API של action.

מניפסט מגרסה V2
chrome.browserAction.onClicked.addListener(tab => { ... });
chrome.pageAction.onClicked.addListener(tab => { ... });
מניפסט מגרסה V3
chrome.action.onClicked.addListener(tab => { ... });

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

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

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

כדי לעבור מקריאה חוזרת להבטחה, צריך להסיר את הקריאה החוזרת ולטפל בהבטחה שהוחזרה. הדוגמה הבאה נלקחת מתוך דוגמה להרשאות אופציונליות, ספציפית ב-newtab.js. גרסת הקריאה החוזרת מראה איך תיראה הקריאה מהדוגמה אל request() עם קריאה חוזרת (callback). הערה: אפשר לשכתב את הגרסה המובטחת באמצעות אסינכרונית ולהמתין.

התקשרות חזרה
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');
  }
});

החלפה של פונקציות שמצפות להקשר רקע של מניפסט מגרסה V2

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

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

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

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

השיטות והמאפיינים שמפורטים בהמשך צריכים להשתנות במניפסט מגרסה V3.

שיטת או מאפיין של מניפסט מגרסה 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.onMessage
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 (סקריפטים ברקע) הפעולה הזו לא נתמכת ב-service worker. במקום זאת, צריך להשתמש באירוע של המסמך 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