browser.scripting

תיאור

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

הרשאות

scripting

זמינות

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

מניפסט

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

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

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

אפשר להשתמש ב-browser.scripting API כדי להחדיר JavaScript ו-CSS לאתרים. זה דומה למה שאפשר לעשות עם סקריפטים של תוכן. אבל באמצעות מרחב השמות browser.scripting, תוספים יכולים לקבל החלטות בזמן הריצה.

יעדים להזרקה

אפשר להשתמש בפרמטר target כדי לציין יעד להוספת JavaScript או CSS.

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

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected"));

כדי להפעיל את התוסף בכל המסגרות של הכרטיסייה שצוינה, אפשר להגדיר את הערך של allFrames boolean ל-true.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected in all frames"));

אפשר גם להחדיר לפריימים ספציפיים בכרטיסייה על ידי ציון מזהי פריימים ספציפיים. מידע נוסף על מזהי מסגרות זמין במאמר בנושא browser.webNavigation API.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected on target frames"));

קוד מוחדר

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

קבצים

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

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("injected script file"));

פונקציות של זמן ריצה

כשמזריקים JavaScript באמצעות scripting.executeScript(), אפשר לציין פונקציה שתופעל במקום קובץ. הפונקציה הזו צריכה להיות משתנה פונקציה שזמין בהקשר הנוכחי של התוסף.

function getTabId() { ... }
function getTitle() { return document.title; }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : getTitle,
    })
    .then(() => console.log("injected a function"));

function getTabId() { ... }
function getUserColor() { ... }

function changeBackgroundColor() {
  document.body.style.backgroundColor = getUserColor();
}

browser.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;
}

browser.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; }";

browser.scripting
    .insertCSS({
      target : {tabId : getTabId()},
      css : css,
    })
    .then(() => console.log("CSS injected"));

טיפול בתוצאות

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

function getTabId() { ... }
function getTitle() { return document.title; }

browser.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;
}

browser.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 browser.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return browser.scripting.unregisterContentScripts({ ids: scriptIds });
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

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

סוגים

ContentScriptFilter

‫Chrome 96 ואילך

מאפיינים

  • מזהים

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

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

CSSInjection

מאפיינים

  • css

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

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

  • קבצים

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

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

  • origin

    ‫StyleOrigin אופציונלי

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

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

ExecutionWorld

‫Chrome 95 ואילך

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

ספירה

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

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

InjectionResult

מאפיינים

  • documentId

    מחרוזת

    ‫Chrome 106 ואילך

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

  • frameId

    number

    ‫Chrome 90 ואילך

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

  • תוצאה

    כל אופציונלי

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

InjectionTarget

מאפיינים

  • allFrames

    ‫boolean אופציונלי

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

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

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

  • עולם

    ‫ExecutionWorld אופציונלי

    ‫Chrome 95 ואילך

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

  • func

    ‫void optional

    ‫Chrome 92 ואילך

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

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

    () => {...}

StyleOrigin

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

ספירה

"AUTHOR"

"USER"

Methods

executeScript()

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

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

פרמטרים

החזרות

  • Promise<InjectionResult[]>

    ‫Chrome 90 ואילך

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

getRegisteredContentScripts()

‫Chrome 96 ואילך 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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

פרמטרים

  • סינון

    ‫ContentScriptFilter אופציונלי

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

החזרות

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