איך מתחילים?

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

במדריך הזה נבנה תוסף שמאפשר למשתמשים לשנות את צבע הרקע של כל דף באתר developer.chrome.com. הוא ישתמש ברכיבי ליבה רבים כדי להדגים את הקשרים שלהם.

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

אפשר למצוא את התוסף שהושלם כאן.

יצירת המניפסט

תוספים מתחילים במניפסט שלהם. יוצרים קובץ בשם manifest.json וכוללים את הקוד הבא:

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "manifest_version": 2
}

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

  1. כדי לפתוח את דף ניהול התוספים, יש לעבור אל chrome://extensions.
    • כדי לפתוח את הדף 'ניהול תוספים', אפשר גם ללחוץ על תפריט Chrome, להעביר את העכבר מעל כלים נוספים ולבחור באפשרות נכסים.
  2. מפעילים את 'מצב פיתוח' על ידי לחיצה על המתג שלצד מצב פיתוח.
  3. לוחצים על הלחצן טעינה לא ארוזה ובוחרים את ספריית התוספים.

טעינת התוסף

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

הוספת הוראה

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

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

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "manifest_version": 2
}

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

לתוסף הזה נדרש מידע ממשתנה קבוע מיד לאחר התקנתו. בתור התחלה, צריך לכלול בסקריפט הרקע אירוע האזנה של runtime.onInstalled. בתוך רכיב ה-listener של onInstalled, התוסף יגדיר ערך באמצעות ה-storage API. כך תוכלו למספר רכיבי תוסף לגשת לערך הזה ולעדכן אותו.

chrome.runtime.onInstalled.addListener(function() {
  chrome.storage.sync.set({color: '#3aa757'}, function() {
    console.log("The color is green.");
  });
});

כדי שהתוסף ישתמש בהם, צריך לרשום את רוב ממשקי ה-API, כולל storage API, בשדה "permissions" במניפסט.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "manifest_version": 2
}

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

בדיקת תצוגות

לחץ על הקישור כדי להציג את יומן המסוף של סקריפט הרקע, 'The color is green.'

הצגה של ממשק המשתמש

לתוספים יכולות להיות צורות רבות של ממשק משתמש, אבל זה ישתמש בחלון קופץ. יוצרים קובץ בשם popup.html ומוסיפים אותו לספרייה. התוסף הזה משתמש בלחצן לשינוי צבע הרקע.

<!DOCTYPE html>
<html>
  <head>
    <style>
      button {
        height: 30px;
        width: 30px;
        outline: none;
      }
    </style>
  </head>
  <body>
    <button id="changeColor"></button>
  </body>
</html>

בדומה לסקריפט הרקע, יש להגדיר את הקובץ הזה כחלון קופץ במניפסט בקטע page_action.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "page_action": {
    "default_popup": "popup.html"
  },
  "manifest_version": 2
}

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

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "page_action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "images/get_started16.png",
      "32": "images/get_started32.png",
      "48": "images/get_started48.png",
      "128": "images/get_started128.png"
    }
  },
  "manifest_version": 2
}

התוספים מציגים גם תמונות בדף ניהול התוספים, באזהרת ההרשאות ובסמל האתר. התמונות האלה מסומנות במניפסט בקטע icons.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "page_action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "images/get_started16.png",
      "32": "images/get_started32.png",
      "48": "images/get_started48.png",
      "128": "images/get_started128.png"
    }
  },
  "icons": {
    "16": "images/get_started16.png",
    "32": "images/get_started32.png",
    "48": "images/get_started48.png",
    "128": "images/get_started128.png"
  },
  "manifest_version": 2
}

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

מוסיפים כללים מוצהרים לסקריפט הרקע באמצעות ה-API של declarativeContent בתוך אירוע ה-listener של runtime.onInstalled.

chrome.runtime.onInstalled.addListener(function() {
  chrome.storage.sync.set({color: '#3aa757'}, function() {
    console.log('The color is green.');
  });
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([{
      conditions: [new chrome.declarativeContent.PageStateMatcher({
        pageUrl: {hostEquals: 'developer.chrome.com'},
      })
      ],
          actions: [new chrome.declarativeContent.ShowPageAction()]
    }]);
  });
});

לתוסף נדרשת הרשאה כדי לגשת ל-API declarativeContent במניפסט.

{
  "name": "Getting Started Example",
...
  "permissions": ["declarativeContent", "storage"],
...
}

פריט קופץ

מעכשיו, בדפדפן יופיע סמל פעולה בדף בצבע מלא בסרגל הכלים של הדפדפן כשמשתמשים מנווטים לכתובת URL שמכילה את "developer.chrome.com". כשהסמל בצבע מלא, המשתמשים יכולים ללחוץ עליו כדי להציג את popup.html.

בשלב האחרון של ממשק המשתמש הקופץ הוא הוספת צבע ללחצן. יוצרים ומוסיפים לספריית התוספים קובץ בשם popup.js עם הקוד הבא.

let changeColor = document.getElementById('changeColor');

chrome.storage.sync.get('color', function(data) {
  changeColor.style.backgroundColor = data.color;
  changeColor.setAttribute('value', data.color);
});

הקוד הזה לוקח את הלחצן מ-popup.html ומבקש את ערך הצבע מאחסון. לאחר מכן הוא מחיל את הצבע כרקע של הלחצן. יש לכלול תג סקריפט ב-popup.js ב-popup.html.

<!DOCTYPE html>
<html>
...
  <body>
    <button id="changeColor"></button>
    <script src="popup.js"></script>
  </body>
</html>

כדי להציג את הלחצן הירוק, יש לטעון מחדש את התוסף.

לוגיקת שכבה

עכשיו התוסף יודע שהחלון הקופץ אמור להיות זמין למשתמשים ב-developer.chrome.com ושמוצג בו לחצן צבעוני, אבל צריך להפעיל לוגיקה נוספת לאינטראקציה של המשתמשים. מעדכנים את popup.js כך שיכללו את הקוד הבא.

let changeColor = document.getElementById('changeColor');
...
changeColor.onclick = function(element) {
  let color = element.target.value;
  chrome.tabs.query({active: true, currentWindow: true}, function(tabs) {
    chrome.tabs.executeScript(
        tabs[0].id,
        {code: 'document.body.style.backgroundColor = "' + color + '";'});
  });
};

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

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

{
  "name": "Getting Started Example",
...
  "permissions": ["activeTab", "declarativeContent", "storage"],
...
}

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

מתן אפשרויות למשתמשים

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

בשלב הראשון יוצרים קובץ בספרייה בשם options.html וכוללים את הקוד הבא.

<!DOCTYPE html>
<html>
  <head>
    <style>
      button {
        height: 30px;
        width: 30px;
        outline: none;
        margin: 10px;
      }
    </style>
  </head>
  <body>
    <div id="buttonDiv">
    </div>
    <div>
      <p>Choose a different background color!</p>
    </div>
  </body>
  <script src="options.js"></script>
</html>

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

{
  "name": "Getting Started Example",
  ...
  "options_page": "options.html",
  ...
  "manifest_version": 2
}

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

בדיקת תצוגות

תוכלו לגלול למטה בדף הפרטים ולבחור באפשרות Extension options (אפשרויות תוסף) כדי לראות את דף האפשרויות, למרות שהוא ייראה ריק בשלב זה.

אפשרויות של תוספים

השלב האחרון הוא להוסיף את הלוגיקה של האפשרויות. יוצרים קובץ בשם options.js בספריית התוספים עם הקוד הבא.

let page = document.getElementById('buttonDiv');
const kButtonColors = ['#3aa757', '#e8453c', '#f9bb2d', '#4688f1'];
function constructOptions(kButtonColors) {
  for (let item of kButtonColors) {
    let button = document.createElement('button');
    button.style.backgroundColor = item;
    button.addEventListener('click', function() {
      chrome.storage.sync.set({color: item}, function() {
        console.log('color is ' + item);
      })
    });
    page.appendChild(button);
  }
}
constructOptions(kButtonColors);

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

מעבר לשלב הבא

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

מה השלב הבא?