chrome.devtools.panels

תיאור

משתמשים ב-chrome.devtools.panels API כדי לשלב את התוסף בממשק המשתמש של חלון הכלים למפתחים: יוצרים חלוניות משלכם, ניגשים לחלוניות קיימות ומוסיפים סרגלי צד.

מניפסט

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

"devtools_page"

במאמר סיכום של ממשקי DevTools API יש מבוא כללי לשימוש בממשקי Developer Tools API.

סקירה כללית

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

אפשר להשתמש בשיטה devtools.panels.setOpenResourceHandler כדי להתקין פונקציית קריאה חוזרת שמטפלת בבקשות של משתמשים לפתוח משאב (בדרך כלל, לחיצה על קישור למשאב בחלון כלי הפיתוח). לכל היותר, אחד מהמטפלים המותקנים יקבל קריאה. המשתמשים יכולים לציין (באמצעות תיבת הדו-שיח של ההגדרות של כלי הפיתוח) את התנהגות ברירת המחדל או תוסף לטיפול בבקשות לפתיחת משאבים. אם תוסף קורא ל-setOpenResourceHandler() כמה פעמים, רק ה-handler האחרון נשמר.

דוגמאות

הקוד הבא מוסיף חלונית שנמצאת ב-Panel.html, שמיוצגת על ידי FontPicker.png בסרגל הכלים של הכלים למפתחים ומסומנת בתווית Font Picker:

chrome.devtools.panels.create("Font Picker",
                              "FontPicker.png",
                              "Panel.html",
                              function(panel) { ... });

הקוד הבא מוסיף לחלונית Elements (רכיבים) חלונית צדדית שנמצאת ב-Sidebar.html ונקראת Font Properties, ואז מגדיר את הגובה שלה ל-8ex:

chrome.devtools.panels.elements.createSidebarPane("Font Properties",
  function(sidebar) {
    sidebar.setPage("Sidebar.html");
    sidebar.setHeight("8ex");
  }
);

צילום המסך הזה מדגים את ההשפעה של הדוגמאות שלמעלה על חלון הכלים למפתחים:

חלונית סמלי התוספים בסרגל הכלים של כלי הפיתוח

כדי לנסות את ה-API הזה, צריך להתקין את הדוגמה ל-API של חלוניות כלי הפיתוח ממאגר chrome-extension-samples.

סוגים

Button

כפתור שנוצר על ידי התוסף.

מאפיינים

  • onClicked

    Event<functionvoidvoid>

    מופעל כשלוחצים על הלחצן.

    הפונקציה onClicked.addListener נראית כך: 

    (callback: function) => {...}

    • callback

      פונקציה

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

      () => void

  • עדכון

    void

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

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

    (iconPath?: string, tooltipText?: string, disabled?: boolean) => {...}

    • iconPath

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

      הנתיב לסמל החדש של הלחצן.

    • tooltipText

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

      הטקסט שמוצג כהסבר קצר כשמשתמש מעביר את העכבר מעל הכפתור.

    • הושבת

      ‫boolean אופציונלי

      האם הכפתור מושבת.

ElementsPanel

מייצג את חלונית הרכיבים.

מאפיינים

  • onSelectionChanged

    Event<functionvoidvoid>

    האירוע מופעל כשבוחרים אובייקט בחלונית.

    הפונקציה onSelectionChanged.addListener נראית כך: 

    (callback: function) => {...}

    • callback

      פונקציה

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

      () => void

  • createSidebarPane

    void

    Promise

    יוצרת חלונית בסרגל הצד של החלונית.

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

    (title: string, callback?: function) => {...}

    • title

      מחרוזת

      הטקסט שמוצג בכיתוב בסרגל הצד.

    • callback

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

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

      (result: ExtensionSidebarPane) => void

      • אובייקט ExtensionSidebarPane של חלונית סרגל הצד שנוצרה.

    • החזרות

      Promise<ExtensionSidebarPane>

      בהמתנה

      קריאה חוזרת (callback) שמופעלת כשסרגל הצד נוצר.

      התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

ExtensionPanel

מייצג חלונית שנוצרה על ידי תוסף.

מאפיינים

  • onHidden

    Event<functionvoidvoid>

    האירוע מופעל כשהמשתמש עובר מחלונית אחת לחלונית אחרת.

    הפונקציה onHidden.addListener נראית כך: 

    (callback: function) => {...}

    • callback

      פונקציה

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

      () => void

  • onSearch

    Event<functionvoidvoid>

    האירוע מופעל כשמתבצעת פעולת חיפוש (התחלה של חיפוש חדש, ניווט בתוצאות החיפוש או ביטול החיפוש).

    הפונקציה onSearch.addListener נראית כך: 

    (callback: function) => {...}

    • callback

      פונקציה

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

      (action: string, queryString?: string) => void

      • פעולה

        מחרוזת

      • queryString

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

  • onShown

    Event<functionvoidvoid>

    מופעל כשמשתמש עובר לחלונית.

    הפונקציה onShown.addListener נראית כך: 

    (callback: function) => {...}

    • callback

      פונקציה

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

      (window: Window) => void

      • חלון

        חלון

  • createStatusBarButton

    void

    מוסיף כפתור לשורת המצב של החלונית.

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

    (iconPath: string, tooltipText: string, disabled: boolean) => {...}

    • iconPath

      מחרוזת

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

    • tooltipText

      מחרוזת

      הטקסט שמוצג כהסבר קצר כשמשתמש מעביר את העכבר מעל הכפתור.

    • הושבת

      בוליאני

      האם הכפתור מושבת.

  • הצג

    void

    ‫Chrome 140+‎

    החלונית מוצגת על ידי הפעלת הכרטיסייה המתאימה.

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

    () => {...}

ExtensionSidebarPane

סרגל צד שנוצר על ידי התוסף.

מאפיינים

  • onHidden

    Event<functionvoidvoid>

    האירוע מופעל כשחלונית סרגל הצד מוסתרת כתוצאה מכך שהמשתמש עובר מהחלונית שמארחת את חלונית סרגל הצד.

    הפונקציה onHidden.addListener נראית כך: 

    (callback: function) => {...}

    • callback

      פונקציה

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

      () => void

  • onShown

    Event<functionvoidvoid>

    האירוע מופעל כשחלונית סרגל הצד הופכת לגלוי כתוצאה מכך שהמשתמש עובר לחלונית שמארחת אותה.

    הפונקציה onShown.addListener נראית כך: 

    (callback: function) => {...}

    • callback

      פונקציה

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

      (window: Window) => void

      • חלון

        חלון

  • setExpression

    void

    Promise

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

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

    (expression: string, rootTitle?: string, callback?: function) => {...}

    • ביטוי

      מחרוזת

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

    • rootTitle

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

      כותרת אופציונלית לשורש של עץ הביטוי.

    • callback

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

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

      () => void

    • החזרות

      Promise<void>

      בהמתנה

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

      התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

  • setHeight

    void

    הגדרת הגובה של סרגל הצד.

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

    (height: string) => {...}

    • גובה

      מחרוזת

      ציון גודל בסגנון CSS, כמו '100px' או '12ex'.

  • setObject

    void

    Promise

    מגדירה אובייקט תואם JSON שיוצג בחלונית של סרגל הצד.

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

    (jsonObject: string, rootTitle?: string, callback?: function) => {...}

    • jsonObject

      מחרוזת

      אובייקט שיוצג בהקשר של הדף שנבדק. ההערכה מתבצעת בהקשר של המתקשר (לקוח ה-API).

    • rootTitle

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

      כותרת אופציונלית לשורש של עץ הביטוי.

    • callback

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

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

      () => void

    • החזרות

      Promise<void>

      בהמתנה

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

      התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

  • setPage

    void

    הגדרה של דף HTML שיוצג בחלונית הצדדית.

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

    (path: string) => {...}

    • נתיב

      מחרוזת

      הנתיב היחסי של דף תוסף שיוצג בסרגל הצדדי.

SourcesPanel

מייצג את חלונית המקורות.

מאפיינים

  • onSelectionChanged

    Event<functionvoidvoid>

    האירוע מופעל כשבוחרים אובייקט בחלונית.

    הפונקציה onSelectionChanged.addListener נראית כך: 

    (callback: function) => {...}

    • callback

      פונקציה

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

      () => void

  • createSidebarPane

    void

    Promise

    יוצרת חלונית בסרגל הצד של החלונית.

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

    (title: string, callback?: function) => {...}

    • title

      מחרוזת

      הטקסט שמוצג בכיתוב בסרגל הצד.

    • callback

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

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

      (result: ExtensionSidebarPane) => void

      • אובייקט ExtensionSidebarPane של חלונית סרגל הצד שנוצרה.

    • החזרות

      Promise<ExtensionSidebarPane>

      בהמתנה

      קריאה חוזרת (callback) שמופעלת כשסרגל הצד נוצר.

      התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

Theme

‫Chrome 99 ואילך

העיצוב שבו משתמשים בכלי הפיתוח.

Enum

‫"default"
העיצוב שמוגדר כברירת מחדל בכלי הפיתוח. העיצוב תמיד יהיה בהיר.

‫'dark'
עיצוב כהה.

מאפיינים

elements

חלונית הרכיבים.

סוג

ElementsPanel

sources

חלונית המקורות.

סוג

SourcesPanel

themeName

‫Chrome 59+‎

השם של ערכת הצבעים שהוגדרה בהגדרות של כלי הפיתוח של המשתמש. הערכים האפשריים: default (ברירת המחדל) ו-dark.

סוג

מחרוזת

Methods

create()

Promise 
chrome.devtools.panels.create(
  title: string,
  iconPath: string,
  pagePath: string,
  callback?: function,
): Promise<ExtensionPanel>

יוצר לוח הרחבה.

פרמטרים

  • title

    מחרוזת

    הכותרת שמוצגת לצד סמל התוסף בסרגל הכלים של כלי הפיתוח.

  • iconPath

    מחרוזת

    הנתיב של סמל החלונית ביחס לספריית התוסף.

  • pagePath

    מחרוזת

    הנתיב של דף ה-HTML של החלונית ביחס לספריית התוסף.

  • callback

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

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

    (panel: ExtensionPanel) => void

    • חלונית

      ExtensionPanel

      אובייקט ExtensionPanel שמייצג את החלונית שנוצרה.

החזרות

  • Promise<ExtensionPanel>

    בהמתנה

    פונקציה שמופעלת כשהחלונית נוצרת.

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

openResource()

Promise 
chrome.devtools.panels.openResource(
  url: string,
  lineNumber: number,
  columnNumber?: number,
  callback?: function,
): Promise<void>

הפונקציה שולחת בקשה לכלים למפתחים לפתוח כתובת URL בחלונית של הכלים למפתחים.

פרמטרים

  • כתובת אתר

    מחרוזת

    כתובת ה-URL של המשאב שרוצים לפתוח.

  • lineNumber

    number

    מציין את מספר השורה שאליה יתבצע גלילה כשהמשאב נטען.

  • columnNumber

    מספר אופציונלי

    ‫Chrome 114 ואילך

    מציין את מספר העמודה שאליה יתבצע גלילה כשהמשאב נטען.

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    בהמתנה

    פונקציה שמופעלת כשהמשאב נטען בהצלחה.

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

setOpenResourceHandler()

chrome.devtools.panels.setOpenResourceHandler(
  callback?: function,
): void

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

פרמטרים

  • callback

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

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

    (resource: Resource, lineNumber: number) => void

setThemeChangeHandler()

‫Chrome 99 ואילך 
chrome.devtools.panels.setThemeChangeHandler(
  callback?: function,
): void

מציינים את הפונקציה שתופעל כשהעיצוב הנוכחי משתנה בכלי הפיתוח. כדי לבטל את ההגדרה של ה-handler, קוראים ל-method ללא פרמטרים או מעבירים את null כפרמטר.

פרמטרים

  • callback

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

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

    (theme: Theme) => void

    • עיצוב

      עיצוב

      העיצוב הנוכחי בכלי הפיתוח.