תיאור
משתמשים ב-userScripts
API כדי להריץ סקריפטים של משתמשים בהקשר של סקריפטים של משתמשים.
הרשאות
userScripts
כדי להשתמש ב-User Scripts 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.scripting
API, User Scripts API מאפשר להריץ קוד שרירותי. ה-API הזה נדרש לתוספים שמפעילים סקריפטים שהמשתמש סיפק ולא ניתן לשלוח אותם כחלק מחבילת התוסף.
מצב פיתוח למשתמשים בתוספים
מפתחי תוספים כבר הפעילו את מצב הפיתוח בהתקנה של Chrome. בתוספים של סקריפטים של משתמשים, המשתמשים יצטרכו גם להפעיל את מצב הפיתוח. ריכזנו כאן הוראות שתוכלו להעתיק ולהדביק במסמכי התיעוד שלכם.
- כדי לעבור לדף התוספים, מזינים
chrome://extensions
בכרטיסייה חדשה. (כתוצאה מהתכנון, לא ניתן לקשר לכתובות URL מסוגchrome://
). מפעילים את מצב הפיתוח בלחיצה על המתג לצד מצב פיתוח.
דף התוספים (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 של הדף.
InjectionResult
מאפיינים
-
documentId
מחרוזת
המסמך שמשויך להזרקה.
-
error
מחרוזת אופציונלי
השגיאה, אם יש כזו. הערכים
error
ו-result
הם בלעדיים זה לזה. -
frameId
number
המסגרת שמשויכת להזרקה.
-
תוצאה
כל אופציונלי
התוצאה של ביצוע הסקריפט.
InjectionTarget
מאפיינים
-
allFrames
boolean אופציונלי
האם הסקריפט צריך להחדיר את עצמו לכל המסגרות בכרטיסייה. ברירת המחדל היא false. אסור שהערך יהיה נכון אם צוין
frameIds
. -
documentIds
string[] אופציונלי
המזהים של מזהי מסמכים ספציפיים שרוצים להחדיר. אסור להגדיר את הערך הזה אם הערך
frameIds
מוגדר. -
frameIds
number[] אופציונלי
המזהים של הפריימים הספציפיים שרוצים להחדיר אליהם.
-
tabId
number
המזהה של הכרטיסייה שבה רוצים להחדיר את הקוד.
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
מחרוזת אופציונלי
Chrome מגרסה 133 ואילךמזהה העולם שבו יתבצע הסקריפט של המשתמש. אם השדה הזה לא יצוין, הסקריפט יבוצע בעולם ברירת המחדל של סקריפט המשתמש. תקף רק אם השדה
world
מושמט או שהואUSER_SCRIPT
. ערכים עם קו תחתון מוביל (_
) שמורים.
ScriptSource
מאפיינים
-
קוד
מחרוזת אופציונלי
מחרוזת שמכילה את קוד ה-JavaScript שרוצים להחדיר. צריך לציין בדיוק אחד מהערכים
file
אוcode
. -
קובץ
מחרוזת אופציונלי
הנתיב של קובץ ה-JavaScript שרוצים להחדיר ביחס לתיקיית השורש של התוסף. צריך לציין בדיוק אחד מהערכים
file
אוcode
.
UserScriptFilter
מאפיינים
-
ids
string[] אופציונלי
הפונקציה
getScripts
מחזירה רק סקריפטים עם המזהים שצוינו ברשימה הזו.
UserScriptInjection
מאפיינים
-
injectImmediately
boolean אופציונלי
האם ההזרקה צריכה להתבצע ביעד בהקדם האפשרי. חשוב לזכור שזה לא מבטיח שההזרקה תתרחש לפני טעינת הדף, כי יכול להיות שהדף כבר נטען עד שהסקריפט מגיע ליעד.
-
js
רשימת האובייקטים מסוג ScriptSource שמגדירים מקורות של סקריפטים שרוצים להחדיר ליעד.
-
יעד
פרטים שמציינים את היעד שאליו רוצים להחדיר את הסקריפט.
-
עולם
ExecutionWorld אופציונלי
'העולם' של JavaScript שבו מריצים את הסקריפט. ערך ברירת המחדל הוא
USER_SCRIPT
. -
worldId
מחרוזת אופציונלי
מזהה העולם שבו יתבצע הסקריפט של המשתמש. אם השדה הזה לא יצוין, הסקריפט יבוצע בעולם ברירת המחדל של סקריפט המשתמש. תקף רק אם השדה
world
מושמט או שהואUSER_SCRIPT
. ערכים עם קו תחתון מוביל (_
) שמורים.
WorldProperties
מאפיינים
-
csp
מחרוזת אופציונלי
מציין את ה-CSP של העולם. ברירת המחדל היא ה-CSP של העולם
`ISOLATED`
. -
העברת הודעות
boolean אופציונלי
ההגדרה הזו קובעת אם ממשקי ה-API של הודעות נחשפים. ערך ברירת המחדל הוא
false
. -
worldId
מחרוזת אופציונלי
Chrome מגרסה 133 ואילךמזהה העולם הספציפי של סקריפט המשתמש שרוצים לעדכן. אם לא מציינים שם, המערכת מעדכנת את המאפיינים של העולם שמוגדר כברירת מחדל בסקריפט המשתמש. ערכים עם קו תחתון מוביל (
_
) שמורים.
Methods
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
הגדרת סביבת ההפעלה של `USER_SCRIPT`
.
פרמטרים
-
נכסים
מכיל את הגדרת העולם של סקריפט המשתמש.
-
callback
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.
execute()
chrome.userScripts.execute(
injection: UserScriptInjection,
callback?: function,
)
הוספה של סקריפט להקשר יעד. כברירת מחדל, הסקריפט ירוץ ב-document_idle
, או באופן מיידי אם הדף כבר נטען. אם המאפיין injectImmediately
מוגדר, ההזרקה של הסקריפט תתבצע בלי המתנה, גם אם הטעינה של הדף לא הסתיימה. אם הסקריפט מקבל ערך של הבטחה, הדפדפן ימתין עד שההבטחה תתבצע ויחזיר את הערך שנוצר.
פרמטרים
-
הזרקה
-
callback
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(result: InjectionResult[]) => void
-
תוצאה
-
החזרות
-
Promise<InjectionResult[]>
יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
הפונקציה מחזירה את כל הסקריפטים של המשתמשים שנרשמו באופן דינמי עבור התוסף הזה.
פרמטרים
-
סינון
UserScriptFilter אופציונלי
אם יצוין, השיטה הזו תחזיר רק את סקריפטים של המשתמשים שתואמים לו.
-
callback
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(scripts: RegisteredUserScript[]) => void
-
סקריפטים
-
החזרות
-
Promise<RegisteredUserScript[]>
יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.
getWorldConfigurations()
chrome.userScripts.getWorldConfigurations(
callback?: function,
)
אחזור של כל הגדרות העולם הרשומים.
פרמטרים
-
callback
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(worlds: WorldProperties[]) => void
-
עולמות
-
החזרות
-
Promise<WorldProperties[]>
יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
הרשמה של סקריפט משתמש אחד או יותר לתוסף הזה.
פרמטרים
-
סקריפטים
מכיל רשימה של סקריפטים של משתמשים שרוצים לרשום.
-
callback
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.
resetWorldConfiguration()
chrome.userScripts.resetWorldConfiguration(
worldId?: string,
callback?: function,
)
איפוס ההגדרות של עולם של סקריפט משתמש. כל סקריפט שמחדיר לעולם עם המזהה שצוין ישתמש בתצורת ברירת המחדל של העולם.
פרמטרים
-
worldId
מחרוזת אופציונלי
המזהה של עולם הסקריפט של המשתמש שרוצים לאפס. אם לא יצוין, תתבצע איפוס של הגדרות ברירת המחדל של העולם.
-
callback
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
ביטול הרישום של כל סקריפטים של משתמשים שרשומים באופן דינמי עבור התוסף הזה.
פרמטרים
-
סינון
UserScriptFilter אופציונלי
אם יצוין, השיטה הזו תבטל את הרישום של סקריפטים של משתמשים שתואמים לו בלבד.
-
callback
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
עדכון של סקריפט משתמש אחד או יותר של התוסף הזה.
פרמטרים
-
סקריפטים
מכיל רשימה של סקריפטים של משתמשים שצריך לעדכן. נכס מתעדכן בסקריפט הקיים רק אם הוא צוין באובייקט הזה. אם יש שגיאות במהלך ניתוח הסקריפט או אימות הקובץ, או אם המזהים שצוינו לא תואמים לסקריפט שרשום במלואו, לא מתבצע עדכון של סקריפטים.
-
callback
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.