chrome.userScripts

תיאור

שימוש ב-API userScripts כדי להפעיל סקריפטים של משתמשים בהקשר של סקריפטים של משתמשים.

הרשאות

userScripts

כדי להשתמש ב-API chrome.userScripts, צריך להוסיף את ההרשאה "userScripts" ל-מניפסט.json ול-"host_permissions" באתרים שבהם רוצים להריץ סקריפטים.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

זמינות

Chrome 120+ MV3+

מושגים ושימוש

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

מצב פיתוח למשתמשי תוסף

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

  1. כדי לעבור לדף התוספים, מזינים chrome://extensions בכרטיסייה חדשה. (מעוצב, chrome:// כתובות אתרים אינן ניתנות לקישור.)

  2. מפעילים את מצב הפיתוח על ידי לחיצה על מתג החלפת המצב לצד מצב פיתוח.

    דרך דף התוספים

    דף התוספים (chrome://extensions)

אפשר לקבוע אם מצב פיתוח מופעל על ידי בדיקה אם מופיעה הודעת שגיאה ב-chrome.userScripts. למשל:

function isUserScriptsAvailable() {
  try {
    // Property access which throws if developer mode is not enabled.
    chrome.userScripts;
    return true;
  } catch {
    // Not available.
    return false;
  }
}

עבודה בעולמות מבודדים

סקריפטים של משתמשים וגם סקריפטים של תוכן יכולים לפעול בעולם מבודד או בעולם הראשי. עולם מבודד הוא סביבת הפעלה שאינה נגישה לדף מארח או לתוספים אחרים. כך סקריפט של משתמש יכול לשנות את סביבת ה-JavaScript שלו בלי להשפיע על הדף המארח או על הסקריפטים של התוכן והמשתמש בתוספים אחרים. לעומת זאת, סקריפטים של משתמש (וסקריפטים של תוכן) אינם גלויים לדף המארח או למשתמש ולסקריפטים של התוכן של תוספים אחרים. סקריפטים שרצים בעולם הראשי נגישים לדפים מארחים ולתוספים אחרים, והם גלויים לדפים מארחים ולתוספים אחרים. כדי לבחור את העולם, צריך להעביר את הערך "USER_SCRIPT" או "MAIN" בשיחה userScripts.register().

כדי להגדיר מדיניות אבטחת תוכן לעולם USER_SCRIPT, צריך לקרוא ל-userScripts.configureWorld():

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

העברת הודעות

בדומה לסקריפטים של תוכן ומסמכים שאינם במסך, סקריפטים של משתמשים מתקשרים עם חלקים אחרים של התוסף באמצעות העברת הודעות (כלומר, הם יכולים לקרוא ל-runtime.sendMessage() ול-runtime.connect() כמו כל חלק אחר של תוסף). עם זאת, הם מתקבלים באמצעות גורמים ייעודיים לטיפול באירועים (כלומר, הם לא משתמשים ב-onMessage או ב-onConnect). רכיבי ה-handler האלה נקראים runtime.onUserScriptMessage ו-runtime.onUserScriptConnect. רכיבי handler ייעודיים מאפשרים לזהות בקלות יותר הודעות מסקריפטים של משתמשים, שהם הקשר פחות מהימן.

לפני שליחת הודעה, עליך להפעיל את configureWorld() כאשר הארגומנט messaging מוגדר ל-true. הערה: ניתן להעביר את הארגומנטים csp וגם את הארגומנטים messaging בו-זמנית.

chrome.userScripts.configureWorld({
  messaging: true
});

עדכונים בתוספים

הסקריפטים של המשתמש נמחקים כשתוסף מתעדכן. כדי להוסיף אותם מחדש, מריצים את הקוד ב-handler של האירועים runtime.onInstalled ב-Service Worker של התוסף. צריך להשיב רק לסיבה אחת ("update") שהועברה לקריאה החוזרת של האירוע.

דוגמה

הדוגמה הזו לקוחה מדוגמה של userScript במאגר הדוגמאות שלנו.

רישום סקריפט

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

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

סוגים

ExecutionWorld

עולם ה-JavaScript שבו סקריפט של משתמש יופעל.

טיפוסים בני מנייה (enum)

"MAIN"
מציין את סביבת הביצוע של ה-DOM, שהיא סביבת הביצוע המשותפת עם ה-JavaScript של הדף המארח.

"USER_SCRIPT"
מפרטת את סביבת הביצוע שהיא ספציפית לסקריפטים של משתמשים ושפטורה מה-CSP של הדף.

RegisteredUserScript

תכונות

  • allFrames

    בוליאני אופציונלי

    אם היא מוגדרת כ-True, היא תוחדר לכל הפריימים, גם אם המסגרת היא לא המסגרת העליונה בכרטיסייה. כל מסגרת נבדקת בנפרד כדי לראות את הדרישות לגבי כתובות ה-URL. היא לא תוחדר למסגרות צאצא אם הן לא עומדות בדרישות לגבי כתובות ה-URL. ערך ברירת המחדל הוא False, כלומר רק המסגרת העליונה מתאימה.

  • excludeGlobs

    string[] אופציונלי

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

  • excludeMatches

    string[] אופציונלי

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

  • id

    מחרוזת

    המזהה של סקריפט המשתמש שצוין בקריאה ל-API. המאפיין לא יכול להתחיל ב-'_' כי הוא שמור כקידומת למזהי סקריפטים שנוצרו.

  • includeGlobs

    string[] אופציונלי

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

  • רשימת האובייקטים של ScriptSource להגדרת מקורות של סקריפטים שיש להחדיר לדפים תואמים.

  • תואם את:

    string[] אופציונלי

    מציין לאילו דפים יוחדר סקריפט המשתמש הזה. למידע נוסף על התחביר של מחרוזות אלה, ראה תבניות התאמה. יש לציין את המאפיין הזה ל-${ref:register}.

  • runAt

    RunAt אופציונלי

    המדיניות הזו קובעת מתי קובצי JavaScript מוחדרים לדף האינטרנט. הערך המועדף וערך ברירת המחדל הוא document_idle.

  • עולם

    ExecutionWorld אופציונלי

    סביבת הביצוע של JavaScript שבה צריך להריץ את הסקריפט. ערך ברירת המחדל הוא `USER_SCRIPT`.

ScriptSource

תכונות

  • קוד

    מחרוזת אופציונלי

    מחרוזת שמכילה את קוד ה-JavaScript להחדרה. יש לציין בדיוק אחד מהערכים file או code.

  • קובץ

    מחרוזת אופציונלי

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

UserScriptFilter

תכונות

  • ids

    string[] אופציונלי

    הפקודה getScripts מחזירה רק סקריפטים עם המזהים שצוינו ברשימה הזו.

WorldProperties

תכונות

  • CSP

    מחרוזת אופציונלי

    מציין את ה-csp בעולם. ברירת המחדל היא `ISOLATED` csp בעולם.

  • העברת הודעות

    בוליאני אופציונלי

    ההגדרה קובעת אם ממשקי API להעברת הודעות נחשפו. ערך ברירת המחדל הוא false.

שיטות

configureWorld()

הבטחה 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

המדיניות מגדירה את סביבת הביצוע של `USER_SCRIPT`.

פרמטרים

  • נכסים

    WorldProperties

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    ()=>void

החזרות

  • Promise<void>

    יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

getScripts()

הבטחה 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

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

פרמטרים

  • סינון

    UserScriptFilter אופציונלי

    אם היא מוגדרת, השיטה הזו מחזירה רק את הסקריפטים של המשתמש שתואמים לה.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (scripts: RegisteredUserScript[])=>void

החזרות

  • יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

register()

הבטחה 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

פרמטרים

  • סקריפטים

    RegisteredUserScript[]

    מכילה רשימה של סקריפטים של משתמש לרישום.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    ()=>void

החזרות

  • Promise<void>

    יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

unregister()

הבטחה 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

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

פרמטרים

  • סינון

    UserScriptFilter אופציונלי

    אם היא מוגדרת, השיטה הזו מבטלת רק את הרישום של סקריפטים של משתמשים שתואמים לה.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    ()=>void

החזרות

  • Promise<void>

    יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

update()

הבטחה 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

פרמטרים

  • סקריפטים

    RegisteredUserScript[]

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    ()=>void

החזרות

  • Promise<void>

    יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.