הוספת סקריפטים לכרטיסייה הפעילה

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

סקירה כללית

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

במדריך זה נסביר כיצד לבצע את הפעולות הבאות:

• שימוש בקובץ השירות (service worker) של התוסף כמתאם אירועים.
• שמירה על פרטיות המשתמשים בעזרת ההרשאה "activeTab".
• מריצים את הקוד כשהמשתמש לוחץ על סמל סרגל הכלים של התוסף.
• הוספה והסרה של גיליון סגנונות באמצעות Scripting API.
• אפשר להשתמש במקש קיצור כדי להפעיל את הקוד.

לפני שמתחילים

המדריך הזה מבוסס על ההנחה שיש לכם ניסיון בסיסי בפיתוח אתרים. מומלץ להיכנס לאתר Hello World כדי לקבל מבוא לתהליך פיתוח התוספים.

יצירת התוסף

כדי להתחיל, צריך ליצור ספרייה חדשה בשם focus-mode שתכיל את הקבצים של התוסף. אם תרצו, תוכלו להוריד את קוד המקור המלא מ-GitHub.

שלב 1: מוסיפים את הנתונים והסמלים של התוסף

יוצרים קובץ בשם manifest.json וכוללים את הקוד הבא.

{
  "manifest_version": 3,
  "name": "Focus Mode",
  "description": "Enable focus mode on Chrome's official Extensions and Chrome Web Store documentation.",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  }
}

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

יוצרים תיקייה ב-images ומורידים את הסמלים אליה.

שלב 2: מפעילים את התוסף

תוספים יכולים לעקוב אחר אירועי דפדפן ברקע באמצעות קובץ השירות (service worker) של התוסף. קובצי שירות (service worker) הם סביבות JavaScript מיוחדות שמטפלות באירועים ומסתיימות כשאין בהם צורך.

בשלב הראשון צריך לרשום את קובץ השירות (service worker) בקובץ manifest.json:

{
  ...
  "background": {
    "service_worker": "background.js"
  },
  ...
}

יוצרים קובץ בשם background.js ומוסיפים את הקוד הבא:

chrome.runtime.onInstalled.addListener(() => {
  chrome.action.setBadgeText({
    text: "OFF",
  });
});

האירוע הראשון שה-Service Worker שלנו יאזין לו הוא runtime.onInstalled(). השיטה הזו מאפשרת לתוסף להגדיר מצב ראשוני או להשלים כמה משימות במהלך ההתקנה. לתוספים אפשר להשתמש ב-Storage API וב-IndexedDB כדי לאחסן את מצב האפליקציה. עם זאת, במקרה הזה אנחנו מטפלים רק בשני מצבים, ולכן נשתמש בטקסט של תג הפעולה עצמו כדי לבדוק אם התוסף נמצא במצב 'מופעל' או 'כבוי'.

מונח מפתח: תג הפעולה הוא באנר צבעוני שמופיע מעל פעולת התוסף (סמל סרגל הכלים).

שלב 3: מפעילים את פעולת התוסף

פעולת התוסף קובעת את סמל סרגל הכלים של התוסף. לכן בכל פעם שהמשתמש לוחץ על סמל התוסף, הוא יפעיל קוד כלשהו (כמו בדוגמה הזו) או יציג חלון קופץ. מוסיפים את הקוד הבא כדי להצהיר על פעולת התוסף בקובץ manifest.json:

{
  ...
  "action": {
    "default_icon": {
      "16": "images/icon-16.png",
      "32": "images/icon-32.png",
      "48": "images/icon-48.png",
      "128": "images/icon-128.png"
    }
  },
  ...
}

שימוש בהרשאה activeTab כדי להגן על פרטיות המשתמשים

ההרשאה activeTab מעניקה לתוסף יכולת זמנית להפעיל קוד בכרטיסייה הפעילה. היא גם מאפשרת גישה למאפיינים רגישים של הכרטיסייה הנוכחית.

ההרשאה הזו מופעלת כשהמשתמש מפעיל את התוסף. במקרה כזה, המשתמש מפעיל את התוסף על ידי לחיצה על פעולת התוסף.

💡 אילו אינטראקציות אחרות של משתמשים מפעילות את ההרשאה activeTab בתוסף שלי?

• הקשה על שילוב של מקשי קיצור.
• בחירת אפשרות בתפריט הקשר.
• מקבל הצעה מסרגל הכתובות.
• פתיחת חלון קופץ של תוסף.

ההרשאה "activeTab" מאפשרת למשתמשים לבחור במכוון להריץ את התוסף בכרטיסייה שבה מתמקדים. כך היא מגנה על פרטיות המשתמשים. יתרון נוסף הוא שהבדיקה לא גורמת להפעלה של אזהרה לגבי הרשאה.

כדי להשתמש בהרשאה "activeTab", צריך להוסיף אותה למערך ההרשאות של המניפסט:

{
  ...
  "permissions": ["activeTab"],
  ...
}

שלב 4: מעקב אחר המצב של הכרטיסייה הנוכחית

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

const extensions = 'https://developer.chrome.com/docs/extensions'
const webstore = 'https://developer.chrome.com/docs/webstore'

chrome.action.onClicked.addListener(async (tab) => {
  if (tab.url.startsWith(extensions) || tab.url.startsWith(webstore)) {
    // Retrieve the action badge to check if the extension is 'ON' or 'OFF'
    const prevState = await chrome.action.getBadgeText({ tabId: tab.id });
    // Next state will always be the opposite
    const nextState = prevState === 'ON' ? 'OFF' : 'ON'

    // Set the action badge to the next state
    await chrome.action.setBadgeText({
      tabId: tab.id,
      text: nextState,
    });
  }
});

שלב 5: הוספה או הסרה של גיליון סגנונות

זה הזמן לשנות את הפריסה של הדף. יוצרים קובץ בשם focus-mode.css וכוללים את הקוד הבא:

body > .scaffold > :is(top-nav, navigation-rail, side-nav, footer),
main > :not(:last-child),
main > :last-child > navigation-tree,
main .toc-container {
  display: none;
}

main > :last-child {
  margin-top: min(10vmax, 10rem);
  margin-bottom: min(10vmax, 10rem);
}

הוספה או הסרה של גיליון סגנונות באמצעות Scripting API. קודם כול צריך להצהיר על ההרשאה "scripting" במניפסט:

{
  ...
  "permissions": ["activeTab", "scripting"],
  ...
}

הצלחה: ה-Scripting API לא הפעיל אזהרה על הרשאה.

לסיום, צריך להוסיף ב-background.js את הקוד הבא כדי לשנות את פריסת הדף:

  ...
    if (nextState === "ON") {
      // Insert the CSS file when the user turns the extension on
      await chrome.scripting.insertCSS({
        files: ["focus-mode.css"],
        target: { tabId: tab.id },
      });
    } else if (nextState === "OFF") {
      // Remove the CSS file when the user turns the extension off
      await chrome.scripting.removeCSS({
        files: ["focus-mode.css"],
        target: { tabId: tab.id },
      });
    }
  }
});

💡 האם אפשר להשתמש ב-Scripting API כדי להוסיף קוד במקום גיליון סגנונות?

כן. השימוש ב-scripting.executeScript() מאפשר להחדיר את JavaScript.

אופציונלי: מקצים מקש קיצור

בשביל הכיף, אפשר להוסיף קיצור דרך כדי להפעיל או להשבית את מצב התמקדות בקלות. הוספת המפתח "commands" למניפסט.

{
  ...
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+B",
        "mac": "Command+B"
      }
    }
  }
}

המפתח "_execute_action" מריץ את אותו קוד כמו האירוע action.onClicked(), כך שאין צורך בקוד נוסף.

בדיקה שזה עובד

ודאו שמבנה הקובץ של הפרויקט נראה כך:

טעינת התוסף באופן מקומי

כדי לטעון תוסף לא ארוז במצב פיתוח, יש לפעול לפי השלבים ב-Hello World (שלום עולם).

בדיקת התוסף בדף התיעוד

תחילה, פותחים את הדפים הבאים:

• ברוכים הבאים לתיעוד התוספים ל-Chrome
• פרסום בחנות האינטרנט של Chrome
• Scripting API

לאחר מכן לוחצים על פעולת התוסף. אם הגדרתם מקש קיצור, תוכלו לבדוק אותו על ידי הקשה על Ctrl + B או על Cmd + B.

הוא אמור להיראות כך:

התוסף 'מצב ריכוז' מושבת

לשם כך:

תוסף 'מצב ריכוז' פועל

🎯 שיפורים אפשריים

בהתבסס על מה שלמדת היום, נסה להשיג אחת מהפעולות הבאות:

• שפר את גיליון הסגנונות של CSS.
• אפשר להקצות מקש קיצור אחר.
• לשנות את הפריסה של הבלוג או אתר התיעוד המועדפים עליך.

ממשיכים לבנות.

כל הכבוד על סיום המדריך 🎉. אפשר להשלים מדריכים אחרים בסדרה כדי להתקדם לרמה הבאה:

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

המשך בדיקה

אנחנו מקווים שנהניתם לבנות את התוסף הזה ל-Chrome ושמחים להמשיך בתהליך הלמידה של פיתוח התוסף. אלה מסלולי הלימוד המומלצים:

• במדריך למפתחים יש עשרות קישורים נוספים לקטעי תיעוד שרלוונטיים ליצירת תוספים מתקדמים.
• לתוספים יש גישה לממשקי API מתקדמים, מעבר לאלה שזמינים באינטרנט הפתוח. התיעוד של ממשקי ה-API של Chrome מכיל הסברים מפורטים לגבי כל ממשק API.