browser.userScripts

תיאור

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

הרשאות

userScripts

כדי להשתמש ב-User Scripts API,‏ browser.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 ואילך ‫browser.* ‎ מגרסה Chrome 148 ‫MV3 ואילך

מושגים ושימוש

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

הפעלת השימוש ב-userScripts API

אחרי שהתוסף מקבל הרשאה להשתמש ב-userScripts API, המשתמשים צריכים להפעיל מתג ספציפי כדי לאפשר לתוסף להשתמש ב-API. המתג הספציפי שנדרש וההתנהגות של ה-API כשהוא מושבת משתנים בהתאם לגרסת Chrome.

כדי לקבוע איזה מתג המשתמש צריך להפעיל, למשל במהלך ההצטרפות של משתמש חדש, אפשר להשתמש בבדיקה הבאה:

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

בקטעים הבאים מתוארים המתגים השונים ואיך להפעיל אותם.

גרסאות Chrome לפני 138 (מתג מצב פיתוח)

כמפתחי תוספים, מצב המפתחים כבר מופעל בהתקנה של Chrome. גם המשתמשים צריכים להפעיל את מצב הפיתוח.

אתם יכולים להעתיק את ההוראות הבאות ולהדביק אותן בתיעוד של התוסף למשתמשים:

1. עוברים לדף התוספים על ידי הזנת chrome://extensions בכרטיסייה חדשה. (כחלק מהעיצוב, אי אפשר לקשר לכתובות URL של chrome://.)

2. מפעילים את מצב הפיתוח על ידי לחיצה על המתג לצד מצב פיתוח.

   

   דף התוספים (chrome://extensions)

הערה: אם מצב פיתוח לא מופעל, תופיע הודעת שגיאה כשתיכנסו לכתובת browser.userScripts. אפשר להשתמש בשגיאה הזו כדי לבדוק את הזמינות של ה-API, כמו שמוסבר בקטע בדיקת הזמינות של ה-API.

גרסאות Chrome‏ 138 ואילך (מתג "אישור לסקריפטים של משתמשים")

המתג אישור סקריפטים של משתמשים נמצא בדף הפרטים של כל תוסף (לדוגמה, chrome://extensions/?id=YOUR_EXTENSION_ID).

אתם יכולים להעתיק ולהדביק את ההוראות הבאות במסמכי התיעוד של התוסף שלכם בשביל המשתמשים:

1. עוברים לדף התוספים על ידי הזנת chrome://extensions בכרטיסייה חדשה. (כחלק מהעיצוב, אי אפשר לקשר לכתובות URL של chrome://.)
2. לוחצים על הכפתור "פרטים" בכרטיס התוסף כדי לראות מידע מפורט על התוסף.
3. לוחצים על המתג לצד אישור סקריפטים של משתמשים.

מתג לאישור סקריפטים של משתמשים (chrome://extensions/?id=abc...)

הערה: אם המתג אישור לסקריפטים של משתמשים לא מופעל, browser.userScripts לא מוגדר. המצב הלא מוגדר הזה (בדומה לאופן שבו ממשקי API אחרים פועלים) מתאפס רק כשההקשר של סקריפט התוסף נטען מחדש. לדוגמה, אם משתמש מבטל את הגישה בזמן ש-service worker פועל, browser.userScripts נשאר מוגדר. עם זאת, בתרחיש הזה, ניסיון להפעיל כל אחת מהשיטות שלו יוביל לשגיאה.

בדיקת הזמינות של ה-API

כדי לבדוק אם userScripts API מופעל, מומלץ לבצע את הבדיקה הבאה, כי היא פועלת בכל הגרסאות של Chrome. בבדיקה הזו מתבצע ניסיון להפעיל method של browser.userScripts(), שאמור תמיד להצליח כשה-API זמין. אם הקריאה הזו מחזירה שגיאה, ה-API לא זמין:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    browser.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

עבודה בעולמות מבודדים

גם סקריפטים של משתמשים וגם סקריפטים של תוכן יכולים לפעול בעולם מבודד או בעולם הראשי. סביבה מבודדת היא סביבת הפעלה שאי אפשר לגשת אליה מדף מארח או מתוספים אחרים. כך סקריפט משתמש יכול לשנות את סביבת ה-JavaScript שלו בלי להשפיע על הדף המארח או על סקריפטים של משתמשים ותוכן של תוספים אחרים. לעומת זאת, סקריפטים של משתמשים (וסקריפטים של תוכן) לא גלויים לדף המארח או לסקריפטים של תוכן ומשתמשים של תוספים אחרים. סקריפטים שפועלים בעולם הראשי נגישים לדפי מארח ולתוספים אחרים, וגלויים לדפי מארח ולתוספים אחרים. כדי לבחור את העולם, מעבירים את "USER_SCRIPT" או את "MAIN" כשקוראים ל-userScripts.register().

כדי להגדיר מדיניות אבטחת תוכן לעולם USER_SCRIPT, צריך להפעיל את userScripts.configureWorld():

browser.userScripts.configureWorld({
  csp: "script-src 'self'"
});

העברת הודעות

בדומה לסקריפטים של תוכן ולמסמכים מחוץ למסך, סקריפטים של משתמשים מתקשרים עם חלקים אחרים של תוסף באמצעות העברת הודעות (כלומר, הם יכולים לקרוא ל-runtime.sendMessage() ול-runtime.connect() כמו כל חלק אחר של תוסף). עם זאת, הם מתקבלים באמצעות גורמים מטפלים ייעודיים באירועים (כלומר, הם לא משתמשים ב-onMessage או ב-onConnect). הגורמים המטפלים האלה נקראים runtime.onUserScriptMessage ו-runtime.onUserScriptConnect. מטפלים ייעודיים מקלים על זיהוי הודעות מסקריפטים של משתמשים, שהם הקשר פחות מהימן.

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

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

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

סקריפטים של משתמשים נמחקים כשהתוסף מתעדכן. אפשר להוסיף אותם בחזרה על ידי הפעלת קוד ב-גורם המטפל באירועים של runtime.onInstalled ב-קובץ השירות (service worker) של התוסף. מגיבים רק לסיבה "update" שמועברת לקריאה החוזרת (callback) של האירוע.

דוגמה

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

רישום סקריפט

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

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

סוגים

ExecutionWorld

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

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

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

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

InjectionResult

‫Chrome מגרסה 135 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

מאפיינים

• documentId

  מחרוזת

  המסמך שמשויך להזרקה.

• error

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

  השגיאה, אם יש כזו. אי אפשר להשתמש ב-error וב-result ביחד.

• frameId

  number

  המסגרת שמשויכת להזרקה.

• תוצאה

  any optional

  התוצאה של הרצת הסקריפט.

InjectionTarget

‫Chrome מגרסה 135 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

מאפיינים

• allFrames

  בוליאני אופציונלי

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

• documentIds

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

  המזהים של documentIds ספציפיים שרוצים להוסיף. אסור להגדיר את המדיניות הזו אם המדיניות frameIds מוגדרת.

• frameIds

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

  המזהים של מסגרות ספציפיות שצריך להוסיף אליהן.

• tabId

  number

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

RegisteredUserScript

מאפיינים

• allFrames

  בוליאני אופציונלי

  אם הערך הוא 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 ואילך ‫browser.* ‎ מ-Chrome 148

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

ScriptSource

מאפיינים

• קוד

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

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

• קובץ

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

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

UserScriptFilter

מאפיינים

• מזהים

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

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

UserScriptInjection

‫Chrome מגרסה 135 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

מאפיינים

• injectImmediately

  בוליאני אופציונלי

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

• js

  ScriptSource[]

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

• יעד

  InjectionTarget

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

• עולם

  ‫ExecutionWorld אופציונלי

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

• worldId

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

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

WorldProperties

מאפיינים

• csp

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

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

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

  בוליאני אופציונלי

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

• worldId

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

  ‫Chrome 133 ואילך ‫browser.* ‎ מ-Chrome 148

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

Methods

configureWorld()

browser.userScripts.configureWorld(
  properties: WorldProperties,
): Promise<void>

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

פרמטרים

• נכסים

  WorldProperties

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

החזרות

• Promise<void>

  אובייקט Promise שמופעל אחרי שהעולם מוגדר.

execute()

‫Chrome מגרסה 135 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

browser.userScripts.execute(
  injection: UserScriptInjection,
): Promise<InjectionResult[]>

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

פרמטרים

• הזרקה

  UserScriptInjection

החזרות

• Promise<InjectionResult[]>

getScripts()

browser.userScripts.getScripts(
  filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>

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

פרמטרים

• סינון

  UserScriptFilter אופציונלי

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

החזרות

• Promise<RegisteredUserScript[]>

  הבטחה (Promise) שמתקבלת עם הסקריפטים הרשומים. אם תתרחש שגיאה, ההבטחה תידחה.

getWorldConfigurations()

‫Chrome 133 ואילך ‫browser.* ‎ מ-Chrome 148

browser.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>

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

החזרות

• Promise<WorldProperties[]>

  Promise שמתקבל עם הגדרות העולם הרשומות.

register()

browser.userScripts.register(
  scripts: RegisteredUserScript[],
): Promise<void>

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

פרמטרים

• סקריפטים

  RegisteredUserScript[]

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

החזרות

• Promise<void>

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

resetWorldConfiguration()

‫Chrome 133 ואילך ‫browser.* ‎ מ-Chrome 148

browser.userScripts.resetWorldConfiguration(
  worldId?: string,
): Promise<void>

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

פרמטרים

• worldId

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

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

החזרות

• Promise<void>

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

unregister()

browser.userScripts.unregister(
  filter?: UserScriptFilter,
): Promise<void>

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

פרמטרים

• סינון

  UserScriptFilter אופציונלי

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

החזרות

• Promise<void>

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

update()

browser.userScripts.update(
  scripts: RegisteredUserScript[],
): Promise<void>

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

פרמטרים

• סקריפטים

  RegisteredUserScript[]

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

החזרות

• Promise<void>

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