chrome.devtools.panels

תיאור

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

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

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

במאמר סיכום ממשקי ה-API של כלי הפיתוח יש מבוא כללי לשימוש בממשקי ה-API של כלי הפיתוח.

מניפסט

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

"devtools_page"

דוגמה

הקוד הבא מוסיף חלונית שכלולה ב-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 של חלוניות devtools ממאגר 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

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

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

    • הושבת

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

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

ElementsPanel

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

מאפיינים

  • onSelectionChanged

    Event<functionvoidvoid>

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

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

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

    • callback

      פונקציה

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

      () => void

  • createSidebarPane

    void

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

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

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

    • title

      מחרוזת

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

    • החזרות

      Promise<ExtensionSidebarPane>

      ‫Chrome מגרסה 152 ואילך

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

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 ואילך ‫‎browser.* ‎ החל מ-Chrome 152

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

    הפונקציה 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

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

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

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

    • ביטוי

      מחרוזת

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

    • rootTitle

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

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

    • החזרות

      Promise<void>

      ‫Chrome מגרסה 152 ואילך

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

  • setHeight

    void

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

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

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

    • גובה

      מחרוזת

      מפרט גודל כמו ב-CSS, למשל '100px' או '12ex'.

  • setObject

    void

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

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

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

    • jsonObject

      מחרוזת

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

    • rootTitle

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

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

    • החזרות

      Promise<void>

      ‫Chrome מגרסה 152 ואילך

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

  • setPage

    void

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

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

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

    • נתיב

      מחרוזת

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

SourcesPanel

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

מאפיינים

  • onSelectionChanged

    Event<functionvoidvoid>

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

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

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

    • callback

      פונקציה

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

      () => void

  • createSidebarPane

    void

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

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

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

    • title

      מחרוזת

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

    • החזרות

      Promise<ExtensionSidebarPane>

      ‫Chrome מגרסה 152 ואילך

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

Theme

‫Chrome 99 ואילך ‫browser.* ‎ מ-Chrome 152

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

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

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

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

מאפיינים

elements

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

סוג

ElementsPanel

sources

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

סוג

SourcesPanel

themeName

Chrome 59 ואילך browser.* ‎ מ-Chrome 152 ואילך

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

סוג

מחרוזת

Methods

create()

browser.devtools.panels.create(
  title: string,
  iconPath: string,
  pagePath: string,
): Promise<ExtensionPanel>

יוצרת חלונית של תוסף.

פרמטרים

  • title

    מחרוזת

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

  • iconPath

    מחרוזת

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

  • pagePath

    מחרוזת

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

החזרות

  • Promise<ExtensionPanel>

    ‫Chrome מגרסה 152 ואילך

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

openResource()

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

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

פרמטרים

  • url

    מחרוזת

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

  • lineNumber

    number

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

  • columnNumber

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

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

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

החזרות

  • Promise<void>

    ‫Chrome מגרסה 152 ואילך

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

setOpenResourceHandler()

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

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

פרמטרים

  • callback

    function optional

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

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

setThemeChangeHandler()

‫Chrome 99 ואילך ‫browser.* ‎ מ-Chrome 152 
browser.devtools.panels.setThemeChangeHandler(
  callback?: function,
): void

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

פרמטרים

  • callback

    function optional

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

    (theme: Theme) => void

    • עיצוב

      עיצוב

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