תיאור
שימוש ב-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. במקרה של תוספי סקריפטים של משתמשים, המשתמשים שלך יצטרכו גם להפעיל את מצב המפתח. לפניכם הוראות שתוכלו להעתיק ולהדביק במסמכים שלכם.
- כדי לעבור לדף התוספים, מזינים
chrome://extensions
בכרטיסייה חדשה. (מעוצב,chrome://
כתובות אתרים אינן ניתנות לקישור.) מפעילים את מצב הפיתוח על ידי לחיצה על מתג החלפת המצב לצד מצב פיתוח.
אפשר לקבוע אם מצב פיתוח מופעל על ידי בדיקה אם מופיעה הודעת שגיאה ב-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[] אופציונלי
מציין תבניות של תווים כלליים לחיפוש לדפים שהסקריפט של המשתמש יוכנס אליהם.
-
js
רשימת האובייקטים של 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`
.
פרמטרים
-
נכסים
מכיל את התצורה של עולם הסקריפט של המשתמש.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
מחזירה את כל הסקריפטים של המשתמשים הרשומים באופן דינמי עבור תוסף זה.
פרמטרים
-
סינון
UserScriptFilter אופציונלי
אם היא מוגדרת, השיטה הזו מחזירה רק את הסקריפטים של המשתמש שתואמים לה.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(scripts: RegisteredUserScript[]) => void
-
סקריפטים
-
החזרות
-
Promise<RegisteredUserScript[]>
יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
רושם לפחות סקריפט משתמש אחד לתוסף הזה.
פרמטרים
-
סקריפטים
מכילה רשימה של סקריפטים של משתמש לרישום.
-
קריאה חוזרת (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,
)
מתבצע עדכון של סקריפט משתמש אחד או יותר עבור התוסף הזה.
פרמטרים
-
סקריפטים
מכילה רשימה של סקריפטים של משתמש לעדכון. מאפיין מתעדכן עבור הסקריפט הקיים רק אם הוא מצוין באובייקט הזה. אם מתרחשות שגיאות במהלך ניתוח סקריפט או אימות קובץ, או אם המזהים שצוינו לא תואמים לסקריפט שרשום במלואו, הסקריפטים לא מתעדכנים.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.