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

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

סקירה כללית

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

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

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

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

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

בניית התוסף

כדי להתחיל, צריך ליצור ספרייה חדשה בשם 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" ב- דף הסקירה הכללית של המניפסט.

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

• הוא צריך להיות ברמה הבסיסית (root) של הפרויקט.
• המפתחות הנדרשים היחידים הם "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.

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

שלב 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 למאפיין רמת הרכיב.
• שרשור אופציונלי המשמש לגישה למאפיין אובייקט שעשוי להיות לא מוגדר או ריק.
• Nullish coalescing מחזירה את הערך <heading> אם <date> הוא null או undefined.

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

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

טעינה מקומית של התוסף

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

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

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

• פרסום בחנות האינטרנט של Chrome
• הבנת סקריפטים של תוכן

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

🎯 שיפורים פוטנציאליים

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

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

להמשיך לפתח

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

מידע נוסף על היעדים

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

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