הרצת סקריפטים בכל דף

יוצרים את התוסף הראשון שמוסיף רכיב חדש בדף.

סקירה כללית

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

תוסף זמן קריאה בדף הפתיחה של התוסף
תוסף זמן הקריאה בדף הפתיחה של התוסף.

במדריך הזה נסביר את המושגים הבאים:

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

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

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

יצירת התוסף

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

שלב 1: הוספת מידע על התוסף

קובץ המניפסט מסוג JSON הוא הקובץ הנדרש היחיד. יש בו מידע חשוב על התוסף. יוצרים קובץ manifest.json ברמה הבסיסית (root) של הפרויקט ומוסיפים את הקוד הבא:

{
  "manifest_version": 3,
  "name": "Reading time",
  "version": "1.0",
  "description": "Add the reading time to Chrome Extension documentation articles"
}

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

💡 עובדות נוספות על מניפסט התוסף

  • הוא צריך להיות ממוקם בשורש הפרויקט.
  • המפתחות היחידים הנדרשים הם "manifest_version", "name" ו-"version".
  • הוא תומך בתגובות (//) במהלך הפיתוח, אך יש להסיר אותן לפני העלאת הקוד לחנות האינטרנט של Chrome.

שלב 2: שליחת הסמלים

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

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

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

מומלץ להשתמש בקובצי PNG, אבל מותר להשתמש בפורמטים אחרים של קבצים, מלבד קובצי SVG.

💡 איפה מוצגים הסמלים בגדלים השונים?

גודל הסמל שימוש בסמלים
16x16 סמל האתר בדפים ובתפריט ההקשר של התוסף.
32x32 לרוב, מחשבים עם Windows דורשים את הגודל הזה.
48x48 מוצג בדף התוספים.
128x128 מוצג בזמן ההתקנה ובחנות האינטרנט של Chrome.

שלב 3: מצהירים על סקריפט התוכן

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

מוסיפים את הקוד הבא ל-manifest.json כדי לרשום סקריפט תוכן שנקרא content.js.

{
  "content_scripts": [
    {
      "js": ["scripts/content.js"],
      "matches": [
        "https://developer.chrome.com/docs/extensions/*",
        "https://developer.chrome.com/docs/webstore/*"
      ]
    }
  ]
}

השדה "matches" יכול להכיל דפוס התאמה אחד או יותר. הם מאפשרים לדפדפן לזהות לאילו אתרים להחדיר את הסקריפטים של התוכן. דפוסי ההתאמה מורכבים משלושה חלקים: <scheme>://<host><path>. הן יכולות להכיל תווי '*'.

💡 האם מוצגת בתוסף הזה אזהרה לגבי הרשאה?

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

בדוגמה הזו, המשתמש יראה את האזהרה הבאה לגבי הרשאה:

אזהרת הרשאה שהמשתמש יראה אחרי התקנת תוסף זמן הקריאה
אזהרה לגבי ההרשאה לזמן קריאה.

במאמר הצהרת הרשאות והזהרת משתמשים מוסבר בפירוט על הרשאות של תוספים.

שלב 4: מחשבים ומוסיפים את זמן הקריאה

סקריפטים של תוכן יכולים להשתמש ב-Document Object Model (DOM) רגיל כדי לקרוא ולשנות תוכן של דף. התוסף יבדוק קודם אם הדף מכיל את הרכיב <article>. לאחר מכן, המערכת תספור את כל המילים ברכיב הזה ותיצור פסקה שמציגה את זמן הקריאה הכולל.

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

const article = document.querySelector("article");

// `document.querySelector` may return null if the selector doesn't match anything.
if (article) {
  const text = article.textContent;
  const wordMatchRegExp = /[^\s]+/g; // Regular expression
  const words = text.matchAll(wordMatchRegExp);
  // matchAll returns an iterator, convert to array to get word count
  const wordCount = [...words].length;
  const readingTime = Math.round(wordCount / 200);
  const badge = document.createElement("p");
  // Use the same styling as the publish information in an article's header
  badge.classList.add("color-secondary-text", "type--caption");
  badge.textContent = `⏱️ ${readingTime} min read`;

  // Support for API reference docs
  const heading = article.querySelector("h1");
  // Support for article docs with date
  const date = article.querySelector("time")?.parentNode;

  (date ?? heading).insertAdjacentElement("afterend", badge);
}

💡 שימוש בקוד JavaScript מעניין בקוד הזה

  • ביטויים רגולריים המשמשים לספירה רק של המילים בתוך הרכיב <article>.
  • הפונקציה insertAdjacentElement() משמשת להכנסת הצומת של זמן הקריאה אחרי הרכיב.
  • המאפיין classList המשמש להוספת שמות מחלקות CSS למאפיין מחלקת הרכיב.
  • שרשור אופציונלי משמש לגישה למאפיין של אובייקט שעשוי להיות מוגדר כ-null או לא מוגדר.
  • איחוד גס מחזיר את <heading> אם <date> הוא ריק או לא מוגדר.

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

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

התוכן של תיקיית זמן הקריאה: Manifest.json , content.js בתיקיית הסקריפטים ותיקיית התמונות.

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

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

פתיחת תיעוד של תוסף או של חנות האינטרנט של Chrome

הנה כמה דפים שתוכלו לפתוח כדי לראות כמה זמן ייקח לקרוא כל מאמר.

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

זמן הקריאה פועל בדף הפתיחה
דף הפתיחה של התוסף עם התוסף של זמן הקריאה

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

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

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

להמשיך לבנות

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

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

המשך בדיקה

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

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