browser.scripting

תיאור

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

הרשאות

scripting

זמינות

‫Chrome 88 ואילך ‫browser.* ‎ מגרסה Chrome 148 ‫MV3 ואילך

מניפסט

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

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

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

אתם יכולים להשתמש ב-API של browser.scripting כדי להוסיף 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 ל-true.

function getTabId() { ... }

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

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

function getTabId() { ... }

browser.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() { ... }

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

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

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

סוגים

ContentScriptFilter

‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

מאפיינים

• מזהים

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

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

CSSInjection

מאפיינים

• css

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

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

• קבצים

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

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

• origin

  ‫StyleOrigin אופציונלי

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

• יעד

  InjectionTarget

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

ExecutionWorld

‫Chrome 95 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

טיפוסים בני מנייה (enum)

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

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

InjectionResult

מאפיינים

• documentId

  מחרוזת

  ‫Chrome 106 ואילך browser.* ‎ מגרסה 148 של Chrome

  המסמך שמשויך להזרקה.

• frameId

  number

  ‫Chrome 90 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

  המסגרת שמשויכת להזרקה.

• תוצאה

  any optional

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

InjectionTarget

מאפיינים

• allFrames

  בוליאני אופציונלי

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

• documentIds

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

  ‫Chrome 106 ואילך browser.* ‎ מגרסה 148 של Chrome

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

• frameIds

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

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

• tabId

  number

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

RegisteredContentScript

‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

מאפיינים

• allFrames

  בוליאני אופציונלי

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

• css

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

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

• excludeMatches

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

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

• id [מזהה]

  מחרוזת

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

• js

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

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

• matchOriginAsFallback

  בוליאני אופציונלי

  ‫Chrome 119 ואילך ‫browser.* ‎ מ-Chrome 148

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

• תואם את:

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

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

• persistAcrossSessions

  בוליאני אופציונלי

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

• runAt

  ‫RunAt אופציונלי

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

• עולם

  ‫ExecutionWorld אופציונלי

  ‫Chrome 102 ואילך ‫‎browser.* ‎ מגרסת Chrome 148

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

ScriptInjection

מאפיינים

• args

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

  ‫Chrome 92 ואילך ‫browser.* ‎ מגרסה Chrome 148

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

• קבצים

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

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

• injectImmediately

  בוליאני אופציונלי

  ‫Chrome 102 ואילך ‫‎browser.* ‎ מגרסת Chrome 148

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

• יעד

  InjectionTarget

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

• עולם

  ‫ExecutionWorld אופציונלי

  ‫Chrome 95 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

• func

  void אופציונלי

  ‫Chrome 92 ואילך ‫browser.* ‎ מגרסה Chrome 148

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

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

  () => {...}

StyleOrigin

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

טיפוסים בני מנייה (enum)

"AUTHOR"

"USER"

Methods

executeScript()

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

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

פרמטרים

• הזרקה

  ScriptInjection

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

החזרות

• Promise<InjectionResult[]>

  ‫Chrome 90 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

getRegisteredContentScripts()

‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

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

פרמטרים

• סינון

  ContentScriptFilter אופציונלי

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

החזרות

• Promise<RegisteredContentScript[]>

insertCSS()

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

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

פרמטרים

• הזרקה

  CSSInjection

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

החזרות

• Promise<void>

  ‫Chrome 90 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

registerContentScripts()

‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

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

פרמטרים

• סקריפטים

  RegisteredContentScript[]

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

החזרות

• Promise<void>

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

removeCSS()

‫Chrome 90 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

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

פרמטרים

• הזרקה

  CSSInjection

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

החזרות

• Promise<void>

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

unregisterContentScripts()

‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

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

פרמטרים

• סינון

  ContentScriptFilter אופציונלי

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

החזרות

• Promise<void>

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

updateContentScripts()

‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

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

פרמטרים

• סקריפטים

  RegisteredContentScript[]

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

החזרות

• Promise<void>

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