browser.userScripts

תיאור

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

הרשאות

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+ MV3+

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

סקריפט משתמש הוא קטע קוד שמוזרק לדף אינטרנט כדי לשנות את המראה או את ההתנהגות שלו. בניגוד לתכונות אחרות של תוספים, כמו סקריפטים של תוכן ו-browser.scripting API, ‏ User Scripts 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 ואילך (המתג 'אישור לסקריפטים של משתמשים')

המתג Allow User Scripts מופיע בדף הפרטים של כל תוסף (לדוגמה, chrome://extensions/?id=YOUR_EXTENSION_ID).

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

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

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

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

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

מומלץ לבצע את הבדיקה הבאה כדי לדעת אם userScripts API מופעל, כי הוא פועל בכל גרסאות Chrome. בבדיקה הזו נעשה ניסיון לקרוא לשיטה 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"סיבה שמועברת לקריאה החוזרת של האירוע.

דוגמה

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

רישום סקריפט

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

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

סוגים

ExecutionWorld

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

ספירה

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

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

InjectionResult

‫Chrome 135 ואילך

מאפיינים

• documentId

  מחרוזת

  המסמך שמשויך להחדרה.

• error

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

  השגיאה, אם יש כזו. error ו-result הם ערכים בלעדיים.

• frameId

  number

  המסגרת שמשויכת להחדרה.

• תוצאה

  כל אופציונלי

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

InjectionTarget

‫Chrome 135 ואילך

מאפיינים

• allFrames

  ‫boolean אופציונלי

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

• documentIds

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

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

• frameIds

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

  המזהים של מסגרות ספציפיות להוספה.

• tabId

  number

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

RegisteredUserScript

מאפיינים

• allFrames

  ‫boolean אופציונלי

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

• excludeGlobs

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

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

• excludeMatches

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

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

• id [מזהה]

  מחרוזת

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

• includeGlobs

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

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

• js

  ‫ScriptSource[] optional

  רשימה של אובייקטים מסוג 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

מאפיינים

• מזהים

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

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

UserScriptInjection

‫Chrome 135 ואילך

מאפיינים

• injectImmediately

  ‫boolean אופציונלי

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

• js

  ScriptSource[]

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

• יעד

  InjectionTarget

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

• עולם

  ‫ExecutionWorld אופציונלי

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

• worldId

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

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

WorldProperties

מאפיינים

• csp

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

  מציין את ספק ה-CSP העולמי. ברירת המחדל היא `ISOLATED` world csp.

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

  ‫boolean אופציונלי

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

• worldId

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

  ‫Chrome 133 ואילך

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

Methods

configureWorld()

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

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

פרמטרים

• נכסים

  WorldProperties

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

החזרות

• Promise<void>

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

execute()

‫Chrome 135 ואילך

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

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

פרמטרים

• החדרה

  UserScriptInjection

החזרות

• Promise<InjectionResult[]>

getScripts()

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

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

פרמטרים

• סינון

  ‫UserScriptFilter אופציונלי

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

החזרות

• Promise<RegisteredUserScript[]>

  ‫Promise שמוחזר עם הסקריפטים הרשומים. ההבטחה תידחה אם תתרחש שגיאה.

getWorldConfigurations()

‫Chrome 133 ואילך

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

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

החזרות

• Promise<WorldProperties[]>

  ‫Promise שמוחזר עם ההגדרות הרשומות של העולם.

register()

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

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

פרמטרים

• סקריפטים

  RegisteredUserScript[]

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

החזרות

• Promise<void>

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

resetWorldConfiguration()

‫Chrome 133 ואילך

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

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

פרמטרים

• worldId

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

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

החזרות

• Promise<void>

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

unregister()

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

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

פרמטרים

• סינון

  ‫UserScriptFilter אופציונלי

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

החזרות

• Promise<void>

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

update()

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

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

פרמטרים

• סקריפטים

  RegisteredUserScript[]

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

החזרות

• Promise<void>

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