איך מתחילים?

תוספים מורכבים מרכיבים שונים אבל אחידים. הרכיבים יכולים לכלול רקע סקריפטים, סקריפטים של תוכן, דף אפשרויות, רכיבי ממשק משתמש וקובצי לוגיקה שונים. רכיבי תוספים נוצרים באמצעות טכנולוגיות לפיתוח אתרים: 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. לוחצים על הלחצן LOAD UNPACKED ובוחרים את ספריית התוספים.

טעינת תוסף

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

הוספת הוראה

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

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

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

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

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

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

רוב ממשקי ה-API, כולל ממשק ה-API storage, חייבים להיות רשומים בשדה "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 בתוך אירוע האזנה 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
}

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

בדיקת תצוגות

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

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

השלב האחרון הוא להוסיף את לוגיקת האפשרויות. יוצרים קובץ בשם 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);

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

עבור לשלב הבא

מעולה! בספרייה יש עכשיו תוסף ל-Chrome שפועל באופן מלא, אבל גם פשוט.

מה השלב הבא?