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"));

קוד שהוחדר

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

קבצים

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

מאפיינים

  • מזהים

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

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

CSSInjection

מאפיינים

  • css

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

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

  • קבצים

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

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

  • מקור

    StyleOrigin אופציונלי

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

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

ExecutionWorld

Chrome מגרסה 95 ואילך

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

Chrome מגרסה 96 ואילך

מאפיינים

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

פרמטרים

  • הזרקה

    ScriptInjection

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

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

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

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

    (results: InjectionResult[]) => void

החזרות

  • Promise<InjectionResult[]>

    Chrome מגרסה 90 ואילך

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

getRegisteredContentScripts()

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

פרמטרים

  • הזרקה

    CSSInjection

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome מגרסה 90 ואילך

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

registerContentScripts()

הבטחה Chrome מגרסה 96 ואילך 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

פרמטרים

  • סקריפטים

    RegisteredContentScript[]

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

removeCSS()

הבטחה Chrome מגרסה 90 ואילך 
chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

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

פרמטרים

  • הזרקה

    CSSInjection

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

unregisterContentScripts()

הבטחה Chrome מגרסה 96 ואילך 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

פרמטרים

  • סינון

    ContentScriptFilter אופציונלי

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

updateContentScripts()

הבטחה Chrome מגרסה 96 ואילך 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

פרמטרים

  • סקריפטים

    RegisteredContentScript[]

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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