תיאור
שימוש ב-API chrome.scripting
כדי להפעיל סקריפט בהקשרים שונים.
הרשאות
scripting
זמינות
מניפסט
כדי להשתמש ב-API chrome.scripting
, מצהירים על ההרשאה "scripting"
במניפסט וגם על הרשאות המארח לדפים שבהם רוצים להחדיר סקריפטים. משתמשים במפתח "host_permissions"
או בהרשאה "activeTab"
, שמעניקה הרשאות מארח זמניות. הדוגמה הבאה משתמשת בהרשאה activeTab.
{
"name": "Scripting Extension",
"manifest_version": 3,
"permissions": ["scripting", "activeTab"],
...
}
מושגים ושימוש
ניתן להשתמש ב-API chrome.scripting
כדי להחדיר JavaScript ו-CSS לאתרים. זה דומה למה שאפשר לעשות עם סקריפטים של תוכן. עם זאת, באמצעות מרחב השמות chrome.scripting
, התוספים יכולים לקבל החלטות בזמן הריצה.
יעדי הזרקה
אפשר להשתמש בפרמטר target
כדי לציין יעד שאליו יוחדרו JavaScript או CSS.
שדה החובה היחיד הוא tabId
. כברירת מחדל, תתבצע הזרקה במסגרת הראשית של הכרטיסייה שצוינה.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("script injected"));
כדי לפעול בכל המסגרות של הכרטיסייה שצוינה, ניתן להגדיר את הערך הבוליאני allFrames
ל-true
.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
files : [ "script.js" ],
})
.then(() => console.log("script injected in all frames"));
אפשר גם להזריק למסגרות ספציפיות של כרטיסייה על ידי ציון מזהי פריימים ספציפיים. מידע נוסף על מזהי מסגרות זמין ב-chrome.webNavigation
API.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
files : [ "script.js" ],
})
.then(() => console.log("script injected on target frames"));
קוד שהוחדר
לתוספים אפשר להגדיר את הקוד שיוחדר באמצעות קובץ חיצוני או באמצעות משתנה של זמן ריצה.
Files
הקבצים מצוינים כמחרוזות שהן נתיבים ביחס לספריית הבסיס של התוסף. הקוד הבא יוסיף את הקובץ script.js
לפריים הראשי של הכרטיסייה.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("injected script file"));
פונקציות של זמן ריצה
כשמחדירים JavaScript עם scripting.executeScript()
, אפשר לציין פונקציה שצריך לבצע במקום קובץ. הפונקציה הזו צריכה להיות משתנה של פונקציה שזמין להקשר הנוכחי של התוסף.
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : getTitle,
})
.then(() => console.log("injected a function"));
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor() {
document.body.style.backgroundColor = getUserColor();
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
})
.then(() => console.log("injected a function"));
אפשר לעקוף את הבעיה הזו באמצעות המאפיין args
:
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
document.body.style.backgroundColor = backgroundColor;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
args : [ getUserColor() ],
})
.then(() => console.log("injected a function"));
מחרוזות זמן ריצה
במקרה שמחדירים CSS בתוך דף, אפשר גם לציין מחרוזת שתשמש במאפיין css
. האפשרות הזו זמינה רק עבור scripting.insertCSS()
. אי אפשר להריץ מחרוזת באמצעות scripting.executeScript()
.
function getTabId() { ... }
const css = "body { background-color: red; }";
chrome.scripting
.insertCSS({
target : {tabId : getTabId()},
css : css,
})
.then(() => console.log("CSS injected"));
טיפול בתוצאות
תוצאות הפעלת ה-JavaScript מועברות לתוסף. תוצאה אחת נכללת בכל פריים. המסגרת הראשית מובטחת שתהיה האינדקס הראשון במערך שיתקבל. כל שאר הפריימים יהיו בסדר לא דטרמיניסטי.
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : getTitle,
})
.then(injectionResults => {
for (const {frameId, result} of injectionResults) {
console.log(`Frame ${frameId} result:`, result);
}
});
הפונקציה scripting.insertCSS()
לא מחזירה תוצאות.
הבטחות
אם הערך שמתקבל של הפעלת הסקריפט הוא הבטחה, Chrome ימתין עד שההבטחה תיתקע ויחזיר את הערך שנוצר.
function getTabId() { ... }
async function addIframe() {
const iframe = document.createElement("iframe");
const loadComplete =
new Promise(resolve => iframe.addEventListener("load", resolve));
iframe.src = "https://example.com";
document.body.appendChild(iframe);
await loadComplete;
return iframe.contentWindow.document.title;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : addIframe,
})
.then(injectionResults => {
for (const frameResult of injectionResults) {
const {frameId, result} = frameResult;
console.log(`Frame ${frameId} result:`, result);
}
});
דוגמאות
ביטול הרישום של כל הסקריפטים של התוכן הדינמי
קטע הקוד הבא מכיל פונקציה שמבטלת את הרישום של כל סקריפטים של התוכן הדינמי שהתוסף רשם בעבר.
async function unregisterAllDynamicContentScripts() {
try {
const scripts = await chrome.scripting.getRegisteredContentScripts();
const scriptIds = scripts.map(script => script.id);
return chrome.scripting.unregisterContentScripts(scriptIds);
} catch (error) {
const message = [
"An unexpected error occurred while",
"unregistering dynamic content scripts.",
].join(" ");
throw new Error(message, {cause : error});
}
}
כדי לנסות את ה-API chrome.scripting
, צריך להתקין את דוגמת הסקריפט מהמאגר דוגמאות של תוספים ל-Chrome.
סוגים
ContentScriptFilter
תכונות
-
ids
string[] אופציונלי
אם צוין,
getRegisteredContentScripts
יחזיר רק סקריפטים עם המזהה שצוין ברשימה זו.
CSSInjection
תכונות
-
css
מחרוזת אופציונלי
מחרוזת שמכילה את ה-CSS שיש להחדיר. יש לציין בדיוק אחד מהערכים
files
ו-css
. -
קבצים
string[] אופציונלי
הנתיב של קובצי ה-CSS שיש להחדיר, ביחס לספריית השורש של התוסף. יש לציין בדיוק אחד מהערכים
files
ו-css
. -
מקור
StyleOrigin אופציונלי
מקור הסגנון של ההזרקה. ברירת המחדל היא
'AUTHOR'
. -
יעד
פרטים שמציינים את היעד שאליו יש להוסיף את ה-CSS.
ExecutionWorld
עולם ה-JavaScript שבו סקריפט יופעל.
טיפוסים בני מנייה (enum)
"ISOLATED"
מציין את העולם המבודד, שהוא סביבת הביצוע הייחודית לתוסף הזה.
"MAIN"
מציין את העולם הראשי של ה-DOM, שהוא סביבת הביצוע המשותפת עם ה-JavaScript של הדף המארח.
InjectionResult
תכונות
-
documentId
מחרוזת
Chrome 106 ומעלההמסמך המשויך להזרקה.
-
frameId
מספר
Chrome 90 ומעלההמסגרת שמשויכת להזרקה.
-
תוצאה אחת
כל אופציונלי
התוצאה של הפעלת הסקריפט.
InjectionTarget
תכונות
-
allFrames
בוליאני אופציונלי
אם הסקריפט צריך להחדיר את כל הפריימים בכרטיסייה. ברירת המחדל היא FALSE. אינו יכול להיות TRUE אם
frameIds
צוין. -
documentIds
string[] אופציונלי
Chrome 106 ומעלההמזהים של מזהי documentId ספציפיים שצריך להחדיר אליהם. אין לקבוע את ההגדרה הזו אם המדיניות
frameIds
מוגדרת. -
frameIds
number[] אופציונלי
המזהים של פריימים ספציפיים שאליהם צריך להחדר.
-
tabId
מספר
מזהה הכרטיסייה שאליה יש להחדיר.
RegisteredContentScript
תכונות
-
allFrames
בוליאני אופציונלי
אם היא מוגדרת כ-True, היא תוחדר לכל הפריימים, גם אם המסגרת היא לא המסגרת העליונה בכרטיסייה. כל מסגרת נבדקת בנפרד כדי לראות את הדרישות לגבי כתובות ה-URL. היא לא תוחדר למסגרות צאצא אם הן לא עומדות בדרישות לגבי כתובות ה-URL. ערך ברירת המחדל הוא False, כלומר רק המסגרת העליונה מתאימה.
-
css
string[] אופציונלי
הרשימה של קובצי CSS שיש להכניס לדפים תואמים. הן מוחדרות לפי הסדר שבו הן מופיעות במערך הזה, לפני ש-DOM כלשהו נבנה או מוצג עבור הדף.
-
excludeMatches
string[] אופציונלי
לא כולל דפים שסקריפט התוכן הזה היה מוחדר אליהם בדרך אחרת. למידע נוסף על התחביר של מחרוזות אלה, ראה תבניות התאמה.
-
id
מחרוזת
המזהה של סקריפט התוכן, שצוין בקריאה ל-API. אסור להתחיל ב-'_' כי הוא שמור כקידומת למזהי סקריפט שנוצרו.
-
js
string[] אופציונלי
רשימת קובצי JavaScript שיש להכניס לדפים תואמים. הערכים מוחדרים לפי הסדר שבו הם מופיעים במערך הזה.
-
matchOriginAsFallback
בוליאני אופציונלי
Chrome 119 ומעלהמציין אם ניתן להחדיר את הסקריפט למסגרות שבהן כתובת ה-URL מכילה סכימה שאינה נתמכת. בפרט: about:, data:, blob: או מערכת קבצים:. במקרים כאלה, המקור של כתובת ה-URL נבדק כדי לקבוע אם יש להחדיר את הסקריפט. אם המקור הוא
null
(כמו במקרה של נתונים: כתובות URL), המקור שנעשה בו שימוש הוא המסגרת שיצרה את המסגרת הנוכחית או המסגרת שהפעילה את הניווט למסגרת הזו. חשוב לזכור שזו לא יכולה להיות מסגרת ההורה. -
תואם את:
string[] אופציונלי
מציין לאילו דפים יוחדר סקריפט התוכן הזה. למידע נוסף על התחביר של מחרוזות אלה, ראה תבניות התאמה. חובה לציין את הערך
registerContentScripts
. -
persistAcrossSessions
בוליאני אופציונלי
המדיניות מציינת אם סקריפט התוכן הזה יישאר בסשנים עתידיים. ברירת המחדל היא True.
-
runAt
RunAt אופציונלי
המדיניות הזו קובעת מתי קובצי JavaScript מוחדרים לדף האינטרנט. הערך המועדף וערך ברירת המחדל הוא
document_idle
. -
עולם
ExecutionWorld אופציונלי
Chrome 102 ומעלה'עולם' ב-JavaScript שבו יש להריץ את הסקריפט. ברירת המחדל היא
ISOLATED
.
ScriptInjection
תכונות
-
args
כל[] אופציונלי
Chrome 92 ומעלההארגומנטים שצריך להעביר לפונקציה שסופקה. הערך הזה חוקי רק אם הפרמטר
func
צוין. הארגומנטים האלה חייבים להיות ניתנים להקראה ל-JSON. -
קבצים
string[] אופציונלי
הנתיב של קובצי ה-JS או ה-CSS שיש להחדיר, ביחס לספריית השורש של התוסף. יש לציין בדיוק אחד מהערכים
files
אוfunc
. -
injectImmediately
בוליאני אופציונלי
Chrome 102 ומעלההאם ההזרקה צריכה להיות מופעלת ביעד בהקדם האפשרי. שימו לב: אין ערובה לכך שההחדרה תתרחש לפני טעינת הדף, כי ייתכן שהדף כבר נטען כשהסקריפט מגיע ליעד.
-
יעד
פרטים שמציינים את היעד שאליו יש להחדיר את הסקריפט.
-
עולם
ExecutionWorld אופציונלי
Chrome 95 ומעלה'עולם' ב-JavaScript שבו יש להריץ את הסקריפט. ברירת המחדל היא
ISOLATED
. -
func
ביטול אופציונלי
Chrome 92 ומעלהפונקציית JavaScript להחדרה. הפונקציה הזו תעבור סריאליזציה ולאחר מכן תעבור אופטימיזציה להחדרה. פירוש הדבר הוא שכל הפרמטרים תלויים וההקשר של הביצוע יאבדו. יש לציין בדיוק אחד מהערכים
files
אוfunc
.הפונקציה
func
נראית כך:() => {...}
StyleOrigin
המקור של שינוי סגנון. מידע נוסף זמין במאמר מקורות של סגנון.
טיפוסים בני מנייה (enum)
"AUTHOR"
"USER"
שיטות
executeScript()
chrome.scripting.executeScript(
injection: ScriptInjection,
callback?: function,
)
מחדיר סקריפט להקשר יעד. כברירת מחדל, הסקריפט יפעל ב-document_idle
, או באופן מיידי אם הדף כבר נטען. אם המאפיין injectImmediately
מוגדר, הסקריפט יוכנס בלי להמתין גם אם טעינת הדף לא הסתיימה. אם הסקריפט מקבל הבטחה, הדפדפן ימתין עד שההבטחה תיתקע ויחזיר את הערך שהתקבל.
פרמטרים
-
הזרקה
הפרטים של הסקריפט שיש להחדיר.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(results: InjectionResult[]) => void
-
תוצאות
-
החזרות
-
Promise<InjectionResult[]>
Chrome 90 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
getRegisteredContentScripts()
chrome.scripting.getRegisteredContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
מחזירה את כל הסקריפטים של התוכן הרשומים באופן דינמי עבור תוסף זה, שתואמים את המסנן הנתון.
פרמטרים
-
סינון
ContentScriptFilter אופציונלי
אובייקט לסינון הסקריפטים של התוסף שנרשמו באופן דינמי.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(scripts: RegisteredContentScript[]) => void
-
סקריפטים
-
החזרות
-
Promise<RegisteredContentScript[]>
יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
insertCSS()
chrome.scripting.insertCSS(
injection: CSSInjection,
callback?: function,
)
מוסיף גיליון סגנונות CSS להקשר של יעד. אם צוינו מסגרות מרובות, המערכת תתעלם מהחדרות שנכשלו.
פרמטרים
-
הזרקה
פרטי הסגנונות להוספה.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 90 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
registerContentScripts()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
רושם לפחות סקריפט תוכן אחד של התוסף הזה.
פרמטרים
-
סקריפטים
מכילה רשימה של סקריפטים לרישום. אם מתרחשות שגיאות במהלך ניתוח סקריפט/אימות קובץ או אם המזהים שצוינו כבר קיימים, סקריפטים לא רשומים.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
removeCSS()
chrome.scripting.removeCSS(
injection: CSSInjection,
callback?: function,
)
מסיר גיליון סגנונות CSS שהוכנס בעבר על ידי התוסף הזה מהקשר של יעד.
פרמטרים
-
הזרקה
הפרטים של הסגנונות להסרה. שים לב שהמאפיינים
css
,files
ו-origin
חייבים להתאים במדויק לגיליון הסגנונות שהוכנס באמצעותinsertCSS
. הניסיון להסיר גיליון סגנונות שאינו קיים לא יהיה פעיל. -
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
unregisterContentScripts()
chrome.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
מבטל את הרישום של סקריפטים של תוכן לתוסף הזה.
פרמטרים
-
סינון
ContentScriptFilter אופציונלי
אם צוין, המערכת מבטלת את הרישום רק של סקריפטים של תוכן דינמי שתואמים למסנן. אחרת, כל הסקריפטים של התוכן הדינמי של התוסף יבוטלו.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
updateContentScripts()
chrome.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
מתבצע עדכון של סקריפט תוכן אחד או יותר עבור התוסף הזה.
פרמטרים
-
סקריפטים
מכילה רשימה של סקריפטים לעדכון. מאפיין מתעדכן עבור הסקריפט הקיים רק אם הוא מצוין באובייקט הזה. אם מתרחשות שגיאות במהלך ניתוח סקריפט או אימות קובץ, או אם המזהים שצוינו לא תואמים לסקריפט שרשום במלואו, הסקריפטים לא מתעדכנים.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.