chrome.devtools.panels

refresh date: 2026-09-25 robots: noindex

說明

使用 chrome.devtools.panels API 將擴充功能整合至開發人員工具視窗 UI：建立自己的面板、存取現有面板，以及新增側欄。

資訊清單

您必須在資訊清單中宣告下列金鑰，才能使用這個 API。

"devtools_page"

如需開發人員工具 API 的一般使用簡介，請參閱「開發人員工具 API 摘要」。

總覽

每個擴充功能面板和側欄都會顯示為獨立的 HTML 網頁。開發人員工具視窗中顯示的所有擴充功能頁面，都能存取 chrome.devtools API 中的所有模組，以及 chrome.extension API。開發人員工具視窗中的頁面無法使用其他擴充功能 API，但您可以傳送要求至擴充功能的背景頁面來叫用這些 API，方法與內容指令碼類似。

您可以使用 devtools.panels.setOpenResourceHandler 方法安裝回呼函式，處理使用者開啟資源的要求 (通常是點選開發人員工具視窗中的資源連結)。最多只會呼叫一個已安裝的處理常式；使用者可以透過開發人員工具設定對話方塊，指定預設行為或擴充功能來處理資源開啟要求。如果擴充功能多次呼叫 setOpenResourceHandler()，系統只會保留最後一個處理常式。

範例

下列程式碼會新增 Panel.html 包含的面板，由開發人員工具工具列上的 FontPicker.png 表示，並標示為「Font Picker」：

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

下列程式碼會將 Sidebar.html 包含的側欄窗格 (標題為「Font Properties」) 新增至「Elements」面板，然後將高度設為 8ex：

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

這張螢幕截圖顯示上述範例對開發人員工具視窗的效果：

如要試用這個 API，請從 chrome-extension-samples 存放區安裝 devtools panels API 範例。

類型

Button

由擴充功能建立的按鈕。

屬性

• onClicked

  Event<functionvoidvoid>

  使用者點選按鈕時觸發。

  onClicked.addListener 函式如下所示：

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

  • callback

    函式

    callback 參數如下：

    () => void

• update

  void

  更新按鈕的屬性。如果省略部分引數或引數為 null，則不會更新對應的屬性。

  update 函式如下所示：

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

  • iconPath

    字串 選填

    按鈕新圖示的路徑。

  • tooltipText

    字串 選填

    使用者將滑鼠游標懸停在按鈕上時，會顯示工具提示文字。

  • 已停用

    布林值 選填

    按鈕是否已停用。

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

      已建立側欄窗格的 ExtensionSidebarPane 物件。

  • returns

    Promise<ExtensionSidebarPane>

    Chrome 152 以上版本

    建立側欄時叫用的回呼。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

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

    字串

    使用者將滑鼠游標懸停在按鈕上時，會顯示工具提示文字。

  • 已停用

    布林值

    按鈕是否已停用。

  • returns

    按鈕

• 顯示

  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 節點會顯示在可展開的樹狀結構中，類似控制台/監控。

  • rootTitle

    字串 選填

    運算式樹狀結構根節點的選用標題。

  • callback

    函式 選填

    callback 參數如下：

    () => void

  • returns

    承諾<void>

    Chrome 152 以上版本

    在側欄窗格更新運算式評估結果後，叫用的回呼。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

• 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

  • returns

    承諾<void>

    Chrome 152 以上版本

    在側欄更新物件後叫用的回呼。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

• 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

      已建立側欄窗格的 ExtensionSidebarPane 物件。

  • returns

    Promise<ExtensionSidebarPane>

    Chrome 152 以上版本

    建立側欄時叫用的回呼。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

Theme

Chrome 99 以上版本

開發人員工具使用的主題。

列舉

"default"
預設開發人員工具主題。一律使用淺色主題。

"dark"
深色主題。

屬性

elements

「元素」面板。

類型

ElementsPanel

sources

「來源」面板。

類型

SourcesPanel

themeName

Chrome 59 以上版本

使用者在開發人員工具設定中設定的色彩主題名稱。可能的值：default (預設) 和 dark。

類型

字串

方法

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>

  Chrome 152 以上版本

  建立面板時呼叫的函式。

  Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

openResource()

Promise

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

要求開發人員工具在開發人員工具面板中開啟網址。

參數

• 網址

  字串

  要開啟的資源網址。

• lineNumber

  數字

  指定資源載入時要捲動至的行號。

• columnNumber

  數字 選填

  Chrome 114 以上版本

  指定資源載入時要捲動至的資料欄編號。

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 152 以上版本

  成功載入資源時呼叫的函式。

  Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

setOpenResourceHandler()

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

指定使用者在開發人員工具視窗中點選資源連結時，要呼叫的函式。如要取消設定處理常式，請呼叫不含參數的方法，或傳遞空值做為參數。

參數

• callback

  函式 選填

  callback 參數如下：

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

  • 資源

    資源

    所點擊資源的 devtools.inspectedWindow.Resource 物件。

  • lineNumber

    數字

    指定所點擊資源中的行號。

setThemeChangeHandler()

Chrome 99 以上版本

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

指定開發人員工具中目前主題變更時要呼叫的函式。如要取消設定處理常式，請呼叫不含參數的方法，或傳遞 null 做為參數。

參數

• callback

  函式 選填

  callback 參數如下：

  (theme: Theme) => void

  • 主題

    主題

    開發人員工具目前的主題。