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 בכרטיסייה חדשה. (לא ניתן לקשר כתובות 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). רכיבי ה-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 לא עומדת בדרישות של כתובת ה-URL, היא לא תחדר למסגרות צאצא. ערך ברירת המחדל הוא False. כלומר, מתבצעת התאמה רק לפריים העליון.

  • excludeGlobs

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

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

  • excludeMatches

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

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

  • id [מזהה]

    מחרוזת

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

  • includeGlobs

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

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

  • JavaScript

    ScriptSource[]

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

  • תואם את:

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

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

  • runAt

    RunAt אופציונלי

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

  • עולם

    ExecutionWorld אופציונלי

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

ScriptSource

מאפיינים

  • קוד

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

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

  • קובץ

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

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

UserScriptFilter

מאפיינים

  • מזהים

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

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

WorldProperties

מאפיינים

  • CSP

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

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

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

    ערך בוליאני אופציונלי

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

שיטות

configureWorld()

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

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

פרמטרים

  • נכסים

    WorldProperties

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

getScripts()

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

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

פרמטרים

  • סינון

    UserScriptFilter אופציונלי

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

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

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

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

    (scripts: RegisteredUserScript[]) => void

החזרות

  • Promise&lt;RegisteredUserScript[]&gt;

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

register()

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

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

פרמטרים

  • סקריפטים

    RegisteredUserScript[]

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

unregister()

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

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

פרמטרים

  • סינון

    UserScriptFilter אופציונלי

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

update()

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

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

פרמטרים

  • סקריפטים

    RegisteredUserScript[]

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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