מניפסט – סקריפטים של תוכן

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

מניפסט

אלה המקשים הנתמכים ב-"content_scripts". צריך רק את המפתח "matches" ואת "js" או "css".

manifest.json

{
 "name": "My extension",
 ...
 "content_scripts": [
   {
     "matches": ["https://*.example.com/*"],
     "css": ["my-styles.css"],
     "js": ["content-script.js"],
     "exclude_matches": ["*://*/*foo*"],
     "include_globs": ["*example.com/???s/*"],
     "exclude_globs": ["*bar*"],     
     "all_frames": false,
     "match_origin_as_fallback": false,
     "match_about_blank": false,
     "run_at": "document_idle",
     "world": "ISOLATED",
   }
 ],
 ...
}

קבצים

כל קובץ צריך להכיל נתיב יחסי למשאב בתיקיית השורש של התוסף. לוכסנים בתחילת הנתיב (/) נחתכים באופן אוטומטי. המפתח "run_at" מציין מתי כל קובץ יוזרק.

‫"css" – מערך
אופציונלי. מערך של נתיבי קובצי CSS, שמוזרקים לפי הסדר של המערך הזה, ולפני שמתרחשים בניית DOM או עיבוד דף.
‫"js" – מערך,
אופציונלי. מערך של נתיבי קובצי JavaScript, שמוזרקים לפי הסדר שבו הם מופיעים במערך הזה, אחרי שמוזרקים קובצי CSS. כל מחרוזת במערך חייבת להיות נתיב יחסי למשאב בתיקיית השורש של התוסף. תווי לוכסן ('/') בתחילת המחרוזת נחתכים באופן אוטומטי.

התאמה לכתובות URL

רק המאפיין "matches" נדרש. אחר כך אפשר להשתמש ב-"exclude_matches", ב-"include_globs" וב-"exclude_globs" כדי להתאים אישית את כתובות ה-URL שבהן רוצים להוסיף קוד. המפתח "matches" יפעיל אזהרה.

‫"matches" – מערך
חובה. מציינת לאילו תבניות של כתובות URL להוסיף את הסקריפטים של התוכן. התחביר מפורט בקטע תבניות התאמה.
‫"exclude_matches" – מערך
אופציונלי. החרגה של תבניות ה-URL שאליהן מוזרקים הסקריפטים של התוכן. התחביר מפורט בקטע תבניות התאמה.
‫"include_globs" – מערך
אופציונלי. מוחל אחרי ההתאמות כדי לכלול רק את כתובות ה-URL שתואמות גם ל-glob הזה. נועד לחקות את מילת המפתח ‎@include של Greasemonkey.
‫"exclude_globs" – מערך
אופציונלי. ההחרגה חלה אחרי ההתאמות, כדי להחריג כתובות URL שתואמות ל-glob הזה. נועד לחקות את מילת המפתח ‎@exclude של Greasemonkey.

כתובות URL מסוג Glob הן כתובות שמכילות "תווים כלליים לחיפוש" * וסימני שאלה. התו הכללי לחיפוש * תואם לכל מחרוזת בכל אורך, כולל מחרוזת ריקה, וסימן השאלה ? תואם לכל תו בודד.

סקריפט התוכן מוזרק לדף אם:

  • כתובת ה-URL שלו תואמת לתבניות "matches" ו-"include_globs".
  • וכתובת ה-URL לא תואמת לתבניות "exclude_matches" או "exclude_globs".

דוגמאות להתאמה של כתובות URL ו-glob

"include_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["https://???.example.com/foo/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
התאמות
https://www.example.com/foo/bar
https://the.example.com/foo/
לא תואם
https://my.example.com/foo/bar
https://example.com/foo/*
https://www.example.com/foo

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["*example.com/???s/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
התאמות
https://www.example.com/arts/index.html
https://www.example.com/jobs/index.html
לא תואם
https://www.example.com/sports/index.html
https://www.example.com/music/index.html

"exclude_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
התאמות
https://history.example.com
https://.example.com/music
לא תואם
https://science.example.com
https://www.example.com/science

דוגמה להתאמה אישית מתקדמת

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "include_globs": ["*example.com/???s/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
התאמות
https://www.example.com/arts/index.html
https://.example.com/jobs/index.html
לא תואם
https://science.example.com
https://www.example.com/jobs/business
https://www.example.com/science

פריימים

המפתח "all_frames" מציין אם צריך להחדיר את הסקריפט של התוכן לכל המסגרות שתואמות לדרישות לגבי כתובות URL שצוינו. אם המדיניות מוגדרת כ-false, ההזרקה תתבצע רק למסגרת העליונה. אפשר להשתמש בו יחד עם "match_about_blank" כדי להחדיר אותו למסגרת about:blank.

כדי להחדיר למסגרות אחרות כמו data:,‏ blob: ו-filesystem:, צריך להגדיר את "match_origin_as_fallback" ל-true. פרטים נוספים זמינים במאמר הזרקה למסגרות קשורות

"all_frames" ערך בוליאני
אופציונלי. ברירת המחדל היא false, כלומר רק הפריים העליון תואם. אם הערך הוא True, ההזרקה תתבצע לכל הפריימים, גם אם הפריים הוא לא הפריים העליון בכרטיסייה. כל מסגרת נבדקת בנפרד כדי לוודא שהיא עומדת בדרישות לגבי כתובות URL. אם המסגרת לא עומדת בדרישות, לא תתבצע הזרקה למסגרות הצאצא.
"match_about_blank" – ערך בוליאני
אופציונלי. ברירת המחדל היא false. אם הסקריפט צריך להזריק לתוך מסגרת about:blank שבה כתובת ה-URL של ההורה תואמת לאחת מהתבניות שהוצהרו ב-"matches".
"match_origin_as_fallback" – ערך בוליאני
אופציונלי. ברירת המחדל היא false. אם הסקריפט צריך להזריק למסגרות שנוצרו על ידי מקור תואם, אבל יכול להיות שכתובת ה-URL או המקור שלהן לא תואמים ישירות לתבנית. הם כוללים מסגרות עם סכימות שונות, כמו about:,‏ data:,‏ blob: ו-filesystem:.

זמן ריצה וסביבת הפעלה

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

"run_at" – document_start | document_end | document_idle
אופציונלי. מציינת מתי להוסיף את הסקריפט לדף. הוא תואם למצבי הטעינה של Document.readyState:
  • ‫"document_start": ה-DOM עדיין נטען.
  • ‫"document_end": המשאבים של הדף עדיין נטענים
  • ‫"document_idle": טעינת ה-DOM והמשאבים הסתיימה. זוהי אפשרות ברירת המחדל.
"world" – ISOLATED | MAIN
אופציונלי. העולם של JavaScript שבו הסקריפט יפעל. ערך ברירת המחדל הוא "ISOLATED", שהיא סביבת ההפעלה הייחודית לסקריפט התוכן. אם בוחרים בסביבה "MAIN", הסקריפט ישתף את סביבת ההפעלה עם ה-JavaScript של דף המארח. מידע נוסף זמין במאמר עבודה בעולמות מבודדים.

דוגמה

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