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

המפתח "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 שתואמות גם לאזור הזה בעולם. נועדה לאמולציה של מילת המפתח @include Greeasemonkey.

"exclude_globs" – מערך

אופציונלי. המערכת מחילה התאמות אחרי התאמות כדי להחריג כתובות URL שתואמות לכדור הארץ הזה. נועדה לדמות את מילת המפתח @Exclude (החרגה) של Graeasemonkey.

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

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

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

גלובוסים ודוגמאות להתאמה של כתובות URL

"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. אם היא לא עומדת בדרישות לגבי כתובת ה-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 של הדף המארח. מידע נוסף זמין במאמר עבודה בעולמות מבודדים.

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

דוגמה

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