chrome.userScripts

תיאור

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

הרשאות

userScripts

כדי להשתמש ב-API chrome.userScripts, מוסיפים את ההרשאה "userScripts" לקובץ manifest.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 בכרטיסייה חדשה. (כתוצאה מהתכנון, לא ניתן לקשר לכתובות URL מסוג 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). פונקציות הטיפול האלה נקראות runtime.onUserScriptMessage ו-runtime.onUserScriptConnect. קל יותר לזהות הודעות מסקריפטים של משתמשים בעזרת בוררים ייעודיים, כי הם הקשר פחות מהימן.

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

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

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

תסריטים של משתמשים נמחקים כשמתבצע עדכון של תוסף. אפשר להוסיף אותם חזרה על ידי הפעלת קוד בבורר האירועים runtime.onInstalled ב-service worker של התוסף. יש להשיב רק לסיבה "update" שהועברה ל-call back של האירוע.

דוגמה

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

רישום סקריפט

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

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

סוגים

ExecutionWorld

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

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

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

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

RegisteredUserScript

מאפיינים

  • allFrames

    boolean אופציונלי

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

  • excludeGlobs

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

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

  • excludeMatches

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

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

  • id [מזהה]

    מחרוזת

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

  • includeGlobs

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

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

  • js

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

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

  • תואם את:

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

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

  • runAt

    RunAt אופציונלי

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

  • עולם

    ExecutionWorld אופציונלי

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

  • worldId

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

    בהמתנה

    אם מצוין, מזהה ספציפי של עולם סקריפט של משתמש שבו צריך לבצע את הפעולה. תקף רק אם השדה world מושמט או שהוא USER_SCRIPT. אם השדה הזה לא יצוין, הסקריפט יבוצע בעולם ברירת המחדל של סקריפט המשתמש. ערכים עם קו תחתון מוביל (_) שמורים.

ScriptSource

מאפיינים

  • קוד

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

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

  • קובץ

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

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

UserScriptFilter

מאפיינים

  • ids

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

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

WorldProperties

מאפיינים

  • csp

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

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

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

    boolean אופציונלי

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

  • worldId

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

    בהמתנה

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

Methods

configureWorld()

Promise 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

הגדרת סביבת ההפעלה של `USER_SCRIPT`.

פרמטרים

  • נכסים

    WorldProperties

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

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

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

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

    () => void

החזרות

  • Promise<void>

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

getScripts()

Promise 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

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

פרמטרים

  • סינון

    UserScriptFilter אופציונלי

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

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

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

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

    (scripts: RegisteredUserScript[]) => void

החזרות

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

getWorldConfigurations()

Promise בהמתנה
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

אחזור של כל הגדרות העולם הרשומים.

פרמטרים

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

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

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

    (worlds: WorldProperties[]) => void

החזרות

  • Promise<WorldProperties[]>

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

register()

Promise 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

פרמטרים

  • סקריפטים

    RegisteredUserScript[]

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

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

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

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

    () => void

החזרות

  • Promise<void>

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

resetWorldConfiguration()

Promise בהמתנה
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

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

פרמטרים

  • worldId

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

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

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

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

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

    () => void

החזרות

  • Promise<void>

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

unregister()

Promise 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

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

פרמטרים

  • סינון

    UserScriptFilter אופציונלי

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

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

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

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

    () => void

החזרות

  • Promise<void>

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

update()

Promise 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

פרמטרים

  • סקריפטים

    RegisteredUserScript[]

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

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

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

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

    () => void

החזרות

  • Promise<void>

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