עדכון הקוד

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

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

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

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

ב-Service Worker של התוסף.

החלפת כרטיסיות.insertCSS() ו-tab.removeCSS() ב-scripting.insertCSS() ו-scripting.removeCSS()

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

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

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

  • כשמפעילים את השיטות האלה, מעבירים אובייקט CSSInjection במקום InjectDetails.
  • 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.

ב-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 בממשק ה-API של הפעולה

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

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

החלפת שיחות חוזרות בהבטחות

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

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

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

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

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

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

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

שיטה או מאפיין של מניפסט 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