עדכון הקוד

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

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

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

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

ל-method executeScript() צריך:

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

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

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

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

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

בקובץ השירות של התוסף.

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

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

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

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

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

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

מניפסט מגרסה 2
chrome.tabs.insertCSS(tabId, injectDetails, () => {
  // callback code
});

בקובץ סקריפט ברקע.

מניפסט מגרסה V3
const insertPromise = await chrome.scripting.insertCSS({
  files: ["style.css"],
  target: { tabId: tab.id }
});
// Remaining code.

בקובץ השירות של התוסף.

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

פעולות דפדפן ופעולות בדף היו מושגים נפרדים במניפסט מגרסה 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" מופיע בקובץ העזר.

מניפסט מגרסה 2
{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}
מניפסט מגרסה V3
{
  ...
  "action": {
    "default_popup": "popup.html"
  }

  ...
}

החלפת ממשקי ה-API של BrowserAction ו-pageAction בממשק ה-API של הפעולה

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

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

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

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

בתאימות לאחור, יש הרבה שיטות שתומכות בקריאות חוזרות (callback) אחרי שנוספת תמיכה מובטחת. שימו לב שלא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. אם מעבירים קריאה חוזרת (callback), הפונקציה לא מחזירה אובייקט מסוג Pro, ואם רוצים להחזיר התחייבות, אין להעביר קריאה חוזרת (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 בקובץ השירות של התוסף שלך. בטווח הארוך, מומלץ להחליף את הקריאות האלה ב-postMessage() ובגורם מטפל באירועים של 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 כאשר method מחזיר הבטחות, משתמשים ב-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 (סקריפטים ברקע) אין תמיכה ב-Service Workers של תוספים. במקום זאת, יש להשתמש באירוע 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