chrome.scripting

תיאור

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

הרשאות

scripting

זמינות

‫Chrome 88 ואילך MV3 ואילך

מניפסט

כדי להשתמש ב-chrome.scripting API, צריך להצהיר על ההרשאה "scripting" במניפסט, וגם על הרשאות המארח לדפים שבהם רוצים להחדיר סקריפטים. משתמשים במקש "host_permissions" או בהרשאה "activeTab", שמעניקים הרשאות זמניות למארח. בדוגמה הבאה נעשה שימוש בהרשאה activeTab.

{
  "name": "Scripting Extension",
  "manifest_version": 3,
  "permissions": ["scripting", "activeTab"],
  ...
}

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

אפשר להשתמש ב-chrome.scripting API כדי להחדיר 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 boolean ל-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".

קוד מוחדר

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

קבצים

הקבצים מצוינים כמחרוזות שהן נתיבים יחסיים לתיקיית השורש של התוסף. הקוד הבא יחדיר את הקובץ 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({ ids: scriptIds });
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

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

כדי לנסות את chrome.scripting API, צריך להתקין את דוגמת הסקריפט ממאגר דוגמאות התוספים ל-Chrome.

סוגים

ContentScriptFilter

‫Chrome 96 ואילך

מאפיינים

• מזהים

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

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

CSSInjection

מאפיינים

• css

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

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

• קבצים

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

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

• origin

  ‫StyleOrigin אופציונלי

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

• יעד

  InjectionTarget

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

ExecutionWorld

‫Chrome 95 ואילך

עולם ה-JavaScript שבו הסקריפט יפעל.

Enum

‫"ISOLATED"
מציין את העולם המבודד, שהוא סביבת ההפעלה הייחודית לתוסף הזה.

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

InjectionResult

מאפיינים

• documentId

  מחרוזת

  ‫Chrome 106 ואילך

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

• frameId

  number

  ‫Chrome 90 ואילך

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

• תוצאה

  כל מאפיין אופציונלי

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

InjectionTarget

מאפיינים

• allFrames

  boolean אופציונלי

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

• documentIds

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

  ‫Chrome 106 ואילך

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

• frameIds

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

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

• tabId

  number

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

RegisteredContentScript

‫Chrome 96 ואילך

מאפיינים

• allFrames

  boolean אופציונלי

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

• css

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

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

• excludeMatches

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

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

• id [מזהה]

  מחרוזת

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

• js

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

  רשימת קובצי JavaScript שיוזרקו לדפים תואמים. הם מוזרקים לפי הסדר שבו הם מופיעים במערך הזה.

• matchOriginAsFallback

  boolean אופציונלי

  ‫Chrome 119 ואילך

  המדיניות הזו מציינת אם אפשר להחדיר את הסקריפט למסגרות שבהן כתובת ה-URL מכילה סכמה לא נתמכת, כלומר: about:, data:, blob:, או filesystem:. במקרים כאלה, המערכת בודקת את המקור של כתובת ה-URL כדי לקבוע אם להוסיף את הסקריפט. אם המקור הוא null (כמו במקרה של כתובות URL של נתונים), המקור שנעשה בו שימוש הוא הפריים שיצר את הפריים הנוכחי או הפריים שהפעיל את הניווט לפריים הזה. הערה: יכול להיות שזו לא מסגרת ההורה.

• תואם את:

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

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

• persistAcrossSessions

  boolean אופציונלי

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

• runAt

  ‫RunAt אופציונלי

  מציין מתי קובצי JavaScript מוזרקים לדף האינטרנט. הערך המועדף וערך ברירת המחדל הוא document_idle.

• עולם

  ‫ExecutionWorld אופציונלי

  ‫Chrome 102 ואילך

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

ScriptInjection

מאפיינים

• args

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

  ‫Chrome 92 ואילך

  הארגומנטים שיועברו לפונקציה שצוינה. הפרמטר הזה תקף רק אם מציינים את הפרמטר func. הארגומנטים האלה צריכים להיות ניתנים לסריאליזציה ב-JSON.

• קבצים

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

  הנתיב של קובצי ה-JS או ה-CSS להזרקה, ביחס לספריית הבסיס של התוסף. צריך לציין בדיוק אחד מהמאפיינים files או func.

• injectImmediately

  boolean אופציונלי

  ‫Chrome 102 ואילך

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

• יעד

  InjectionTarget

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

• עולם

  ‫ExecutionWorld אופציונלי

  ‫Chrome 95 ואילך

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

• func

  ‫void אופציונלי

  ‫Chrome 92 ואילך

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

  הפונקציה func נראית כך:

  () => {...}

StyleOrigin

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

Enum

"AUTHOR"

"USER"

Methods

executeScript()

chrome.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

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

פרמטרים

• החדרה

  ScriptInjection

  פרטי הסקריפט שרוצים להוסיף.

החזרות

• Promise<InjectionResult[]>

  ‫Chrome 90 ואילך

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

getRegisteredContentScripts()

‫Chrome 96 ואילך

chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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

פרמטרים

• סינון

  ‫ContentScriptFilter אופציונלי

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

החזרות

• Promise<RegisteredContentScript[]>

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

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

פרמטרים

• הזרקה

  CSSInjection

  הפרטים של הסגנונות שרוצים להוסיף.

החזרות

• Promise<void>

  ‫Chrome 90 ואילך

  הפונקציה מחזירה Promise שמושלם בסיום ההוספה.

registerContentScripts()

‫Chrome 96 ואילך

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

פרמטרים

• סקריפטים

  RegisteredContentScript[]

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

החזרות

• Promise<void>

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

removeCSS()

‫Chrome 90 ואילך

chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

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

פרמטרים

• הזרקה

  CSSInjection

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

החזרות

• Promise<void>

  הפונקציה מחזירה Promise שמושלם בסיום ההסרה.

unregisterContentScripts()

‫Chrome 96 ואילך

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

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

פרמטרים

• סינון

  ‫ContentScriptFilter אופציונלי

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

החזרות

• Promise<void>

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

updateContentScripts()

‫Chrome 96 ואילך

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

פרמטרים

• סקריפטים

  RegisteredContentScript[]

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

החזרות

• Promise<void>

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