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" שהועברה ל-callbak של האירוע.

דוגמה

הדוגמה הזו היא מהדוגמה של 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

  • סקריפטים

    RegisteredUserScript[]

החזרות

• Promise<RegisteredUserScript[]>

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

getWorldConfigurations()

Promise בהמתנה

chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

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

פרמטרים

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

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

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

  (worlds: WorldProperties[]) => void

  • עולמות

    WorldProperties[]

החזרות

• 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.