chrome.scripting

תיאור

שימוש ב-API chrome.scripting כדי להפעיל סקריפט בהקשרים שונים.

הרשאות

scripting

זמינות

Chrome 88 ומעלה MV3+

מניפסט

כדי להשתמש ב-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"));

הערה: אי אפשר לציין גם את המאפיין "frameIds" וגם את המאפיין "allFrames".

קוד שהוחדר

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

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

Chrome 96 ומעלה

תכונות

• ids

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

  אם צוין, getRegisteredContentScripts יחזיר רק סקריפטים עם המזהה שצוין ברשימה זו.

CSSInjection

תכונות

• css

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

  מחרוזת שמכילה את ה-CSS שיש להחדיר. יש לציין בדיוק אחד מהערכים files ו-css.

• קבצים

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

  הנתיב של קובצי ה-CSS שיש להחדיר, ביחס לספריית השורש של התוסף. יש לציין בדיוק אחד מהערכים files ו-css.

• מקור

  StyleOrigin אופציונלי

  מקור הסגנון של ההזרקה. ברירת המחדל היא 'AUTHOR'.

• יעד

  InjectionTarget

  פרטים שמציינים את היעד שאליו יש להוסיף את ה-CSS.

ExecutionWorld

Chrome 95 ומעלה

עולם ה-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

Chrome 96 ומעלה

תכונות

• 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 ומעלה

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

• יעד

  InjectionTarget

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

• עולם

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

פרמטרים

• הזרקה

  ScriptInjection

  הפרטים של הסקריפט שיש להחדיר.

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

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

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

  (results: InjectionResult[])=>void

  • תוצאות

    InjectionResult[]

החזרות

• Promise<InjectionResult[]>

  Chrome 90 ומעלה

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

getRegisteredContentScripts()

Promise Chrome 96 ואילך

chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

פרמטרים

• סינון

  ContentScriptFilter אופציונלי

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

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

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

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

  (scripts: RegisteredContentScript[])=>void

  • סקריפטים

    RegisteredContentScript[]

החזרות

• Promise<RegisteredContentScript[]>

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

insertCSS()

הבטחה

chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

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

פרמטרים

• הזרקה

  CSSInjection

  פרטי הסגנונות להוספה.

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

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

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

  ()=>void

החזרות

• Promise<void>

  Chrome 90 ומעלה

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

registerContentScripts()

Promise Chrome 96 ואילך

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

פרמטרים

• סקריפטים

  RegisteredContentScript[]

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

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

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

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

  ()=>void

החזרות

• Promise<void>

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

removeCSS()

Promise Chrome 90+

chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

מסיר גיליון סגנונות CSS שהוכנס בעבר על ידי התוסף הזה מהקשר של יעד.

פרמטרים

• הזרקה

  CSSInjection

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

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

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

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

  ()=>void

החזרות

• Promise<void>

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

unregisterContentScripts()

Promise Chrome 96 ואילך

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

פרמטרים

• סינון

  ContentScriptFilter אופציונלי

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

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

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

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

  ()=>void

החזרות

• Promise<void>

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

updateContentScripts()

Promise Chrome 96 ואילך

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

פרמטרים

• סקריפטים

  RegisteredContentScript[]

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

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

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

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

  ()=>void

החזרות

• Promise<void>

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