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

קוד מוחדר

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

קבצים

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

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

ExecutionWorld

‫Chrome 95 ואילך

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

Enum

‫"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 אופציונלי

    ‫Chrome 92 ואילך

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

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

    () => {...}

StyleOrigin

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

Enum

"AUTHOR"

"USER"

Methods

executeScript()

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

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

פרמטרים

החזרות

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 ואילך

registerContentScripts()

‫Chrome 96 ואילך 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

פרמטרים

  • סקריפטים

    RegisteredContentScript[]

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

החזרות

  • Promise<void>

removeCSS()

‫Chrome 90 ואילך 
chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

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

פרמטרים

  • החדרה

    CSSInjection

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

החזרות

  • Promise<void>

unregisterContentScripts()

‫Chrome 96 ואילך 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

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

פרמטרים

  • סינון

    ‫ContentScriptFilter אופציונלי

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

החזרות

  • Promise<void>

updateContentScripts()

‫Chrome 96 ואילך 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

פרמטרים

  • סקריפטים

    RegisteredContentScript[]

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

החזרות

  • Promise<void>