תיאור
שימוש ב-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"));
קוד שהוחדר
תוספים יכולים לציין את הקוד להחדרה באמצעות קובץ חיצוני או במשתנה זמן ריצה.
קבצים
הקבצים מצוינים כמחרוזות שהן נתיבים ביחס לשורש של התוסף.
הקוד הבא יוסיף את הקובץ 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
מאפיינים
-
מזהים
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
number
Chrome מגרסה 90 ואילךהמסגרת שמשויכת להזרקה.
-
תוצאה
כל אופציונלי
התוצאה של הפעלת הסקריפט.
InjectionTarget
מאפיינים
-
allFrames
ערך בוליאני אופציונלי
אם הסקריפט צריך להחדיר אותו לכל הפריימים בכרטיסייה. ברירת המחדל היא False. הערך הזה לא יכול להיות נכון אם צוין
frameIds
. -
documentIds
string[] אופציונלי
Chrome 106+המזהים של מזהי documentId הספציפיים שצריך להזין. אין להגדיר את הערך הזה אם השדה
frameIds
מוגדר. -
frameIds
מספר[] אופציונלי
המזהים של פריימים ספציפיים שרוצים להזריק אליהם.
-
tabId
number
המזהה של הכרטיסייה שאליה יש להחדיר.
RegisteredContentScript
מאפיינים
-
allFrames
ערך בוליאני אופציונלי
אם צוין True, תתבצע החדרה לכל הפריימים, גם אם הפריים הוא לא הפריים העליון בכרטיסייה. כל מסגרת נבדקת בנפרד לגבי הדרישות לגבי כתובות URL. אם כתובת ה-URL לא עומדת בדרישות של כתובת ה-URL, היא לא תחדר למסגרות צאצא. ערך ברירת המחדל הוא False. כלומר, מתבצעת התאמה רק לפריים העליון.
-
css
string[] אופציונלי
רשימת קובצי ה-CSS שיש להחדיר לדפים תואמים. ה-DOM הזה מוחדר לפי הסדר שבו הן מופיעות במערך, לפני בניית ה-DOM או הצגתו עבור הדף.
-
excludeMatches
string[] אופציונלי
מחריגה דפים שסקריפט התוכן הזה היה מוחדר אליהם אחרת. ניתן למצוא פרטים נוספים על התחביר של מחרוזות אלה בקטע תבניות התאמה.
-
id [מזהה]
מחרוזת
המזהה של סקריפט התוכן, שצוין בקריאה ל-API. לא יכול להתחיל ב-'_' כי הוא שמור כקידומת למזהי סקריפטים שנוצרו.
-
JavaScript
string[] אופציונלי
רשימת קובצי JavaScript שיש להחדיר לדפים תואמים. המחרוזות האלה מועברות לפי הסדר שבו הן מופיעות במערך הזה.
-
matchOriginAsFallback
ערך בוליאני אופציונלי
Chrome 119 ואילךמציינת אם ניתן להחדיר את הסקריפט למסגרות שבהן כתובת ה-URL מכילה סכמה שאינה נתמכת. ספציפית: על:, נתונים:, blob: או מערכת קבצים:. במקרים כאלה, מקור כתובת ה-URL נבדק כדי לקבוע אם צריך להחדיר את הסקריפט. אם המקור הוא
null
(כמו במקרה של נתונים: כתובות URL), אז המקור שבו נעשה שימוש הוא המסגרת שיצרה את המסגרת הנוכחית או המסגרת שיזמה את המעבר למסגרת הזו. לתשומת ליבכם: יכול להיות שזו לא מסגרת ההורה. -
תואם את:
string[] אופציונלי
מציין לאילו דפים סקריפט התוכן הזה יוחדר. ניתן למצוא פרטים נוספים על התחביר של מחרוזות אלה בקטע תבניות התאמה. יש לציין את הערך בשדה
registerContentScripts
. -
persistAcrossSessions
ערך בוליאני אופציונלי
המדיניות מציינת אם סקריפט התוכן הזה יישמר בסשנים עתידיים. ברירת המחדל היא True.
-
runAt
RunAt אופציונלי
המדיניות הזו מציינת מתי קובצי JavaScript מוחדרים לדף האינטרנט. הערך המועדף וערך ברירת המחדל הוא
document_idle
. -
עולם
ExecutionWorld אופציונלי
Chrome 102+"עולם" JavaScript כדי להריץ את הסקריפט ברירת המחדל היא
ISOLATED
.
ScriptInjection
מאפיינים
-
ארגומנטים
כל[] אופציונלי
Chrome מגרסה 92 ואילךהארגומנטים שצריך להעביר לפונקציה הנתונה. ההצעה הזו תקפה רק אם מציינים את הפרמטר
func
. הארגומנטים האלה צריכים להיות ניתנים סריאליזציה ל-JSON. -
קבצים
string[] אופציונלי
הנתיב של קובצי ה-JS או ה-CSS להחדרה, ביחס לספריית השורש של התוסף. יש לציין בדיוק אחד מתוך
files
אוfunc
. -
injectImmediately
ערך בוליאני אופציונלי
Chrome 102+האם ההזרקה צריכה להיות מופעלת ביעד בהקדם האפשרי. חשוב לשים לב שזו לא ערובה לכך שהחדרה תתבצע לפני שהדף נטען, כי יכול להיות שהדף כבר נטען לפני שהסקריפט יגיע ליעד.
-
יעד
פרטים שמציינים את היעד שאליו צריך להחדיר את הסקריפט.
-
עולם
ExecutionWorld אופציונלי
Chrome מגרסה 95 ואילך"עולם" JavaScript כדי להריץ את הסקריפט ברירת המחדל היא
ISOLATED
. -
func
ביטול אופציונלי
Chrome מגרסה 92 ואילךפונקציית JavaScript להחדרה. הפונקציה הזו תעבור סריאליזציה ולאחר מכן יעבור תהליך deserialize לצורך הזרקה. פירוש הדבר הוא שכל הפרמטרים המקושרים והקשר הביצוע יאבדו. יש לציין בדיוק אחד מתוך
files
אוfunc
.הפונקציה
func
נראית כך:() => {...}
StyleOrigin
המקור של שינוי הסגנון. מידע נוסף זמין במאמר מקורות סגנון.
Enum
"AUTHOR"
"משתמש"
שיטות
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
החזרות
-
הבטחה<Empty>
Chrome מגרסה 90 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
registerContentScripts()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
רושם סקריפט תוכן אחד או יותר עבור תוסף זה.
פרמטרים
-
סקריפטים
מכיל רשימת סקריפטים להרשמה. אם יש שגיאות במהלך ניתוח הסקריפט או אימות הקבצים, או אם המזהים שצוינו כבר קיימים, לא רשומים סקריפטים.
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:() => void
החזרות
-
הבטחה<Empty>
הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
removeCSS()
chrome.scripting.removeCSS(
injection: CSSInjection,
callback?: function,
)
הסרה של גיליון סגנונות של CSS שנוסף בעבר על ידי התוסף הזה מההקשר של היעד.
פרמטרים
-
הזרקה
פרטי הסגנונות להסרה. לתשומת ליבכם: המאפיינים
css
,files
ו-origin
חייבים להתאים בדיוק לגיליון הסגנון שמוסיפים באמצעותinsertCSS
. ניסיון להסיר גיליון סגנונות שלא קיים נחשב ללא פעולה. -
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:() => void
החזרות
-
הבטחה<Empty>
הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
unregisterContentScripts()
chrome.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
ביטול הרישום של סקריפטים של תוכן לתוסף הזה.
פרמטרים
-
סינון
ContentScriptFilter אופציונלי
אם צוין, המערכת מבטלת את הרישום רק של סקריפטים של תוכן דינמי שתואמים למסנן. אחרת, כל הסקריפטים של התוכן הדינמי של התוסף לא יירשמו.
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:() => void
החזרות
-
הבטחה<Empty>
הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
updateContentScripts()
chrome.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
מעדכנים סקריפט תוכן אחד או יותר עבור התוסף הזה.
פרמטרים
-
סקריפטים
רשימת סקריפטים לעדכון. מאפיין מתעדכן עבור הסקריפט הקיים רק אם הוא מצוין באובייקט הזה. אם יש שגיאות במהלך ניתוח הסקריפט או אימות הקובץ, או אם המזהים שצוינו לא תואמים לסקריפט שרשום במלואו, לא יתבצע עדכון של הסקריפטים.
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:() => void
החזרות
-
הבטחה<Empty>
הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.