chrome.devtools.panels

说明

使用 chrome.devtools.panels API 将您的扩展程序集成到开发者工具窗口界面中：创建您自己的面板、访问现有面板以及添加边栏。

每个扩展程序面板和边栏都会显示为单独的 HTML 页面。开发者工具窗口中显示的所有扩展程序页面都可以访问 chrome.devtools API 的所有部分以及所有其他扩展程序 API。

您可以使用 devtools.panels.setOpenResourceHandler 方法安装回调函数，以处理用户打开资源的请求（通常是点击“开发者工具”窗口中的资源链接）。最多只能调用一个已安装的处理程序；用户可以指定（使用开发者工具设置对话框）默认行为或扩展程序来处理资源打开请求。如果扩展程序多次调用 setOpenResourceHandler()，则仅保留最后一个处理程序。

如需简要了解如何使用开发者工具 API，请参阅开发者工具 API 摘要。

清单

必须在清单中声明以下键，才能使用此 API。

"devtools_page"

示例

以下代码会添加一个包含在 Panel.html 中的面板，该面板由开发者工具工具栏上的 FontPicker.png 表示，并标记为字体选择器：

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 代码库中安装开发者工具面板 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

  在面板的边栏中创建一个窗格。

  createSidebarPane 函数如下所示：

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

  • title

    字符串

    在边栏字幕中显示的文本。

  • 返回

    Promise<ExtensionSidebarPane>

    Chrome 152 及更高版本

    创建边栏时调用的回调。

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

    • action

      字符串

    • 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

    字符串

    当用户将鼠标悬停在按钮上时，系统会以提示的形式显示此文本。

  • 已停用

    布尔值

    按钮是否已停用。

  • 返回

    Button

• 显示

  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 节点会显示在可展开的树中，类似于控制台/监视。

  • rootTitle

    字符串 可选

    表达式树根节点的可选标题。

  • 返回

    承诺<void>

    Chrome 152 及更高版本

    在边栏窗格更新为表达式求值结果后调用的回调。

• setHeight

  void

  设置边栏的高度。

  setHeight 函数如下所示：

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

  • 高度

    字符串

    类似 CSS 的尺寸规范，例如 '100px' 或 '12ex'。

• setObject

  void

  设置要在边栏窗格中显示的符合 JSON 规范的对象。

  setObject 函数如下所示：

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

  • jsonObject

    字符串

    要在所检查页面的上下文中显示的对象。在调用方（API 客户端）的上下文中进行评估。

  • rootTitle

    字符串 可选

    表达式树根节点的可选标题。

  • 返回

    承诺<void>

    Chrome 152 及更高版本

    在边栏更新为显示对象后调用的回调函数。

• 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 及更高版本

    创建边栏时调用的回调。

Theme

Chrome 99 及更高版本 browser.*（自 Chrome 152 起）

开发者工具使用的主题。

枚举

"default"
默认开发者工具主题。此主题始终为浅色主题。

"dark"
深色主题。

属性

elements

“元素”面板。

类型

ElementsPanel

sources

“来源”面板。

类型

SourcesPanel

themeName

Chrome 59+ browser.*（自 Chrome 152 起）

用户开发者工具设置中设置的色彩主题名称。可能的值：default（默认值）和 dark。

类型

字符串

方法

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

  字符串

  要打开的资源的网址。

• lineNumber

  数值

  指定加载资源时要滚动到的行号。

• columnNumber

  number 可选

  Chrome 114 及更高版本 browser.*（自 Chrome 152 起）

  指定加载资源时要滚动到的列号。

返回

• 承诺<void>

  Chrome 152 及更高版本

  在资源成功加载时调用的函数。

setOpenResourceHandler()

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

指定当用户点击“开发者工具”窗口中的资源链接时要调用的函数。如需取消设置处理程序，请调用不带参数的方法，或将 null 作为参数传递。

参数

• callback

  函数可选

  callback 参数如下所示：

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

  • 资源

    资源

    所点击资源的 devtools.inspectedWindow.Resource 对象。

  • lineNumber

    数值

    指定所点击资源中的行号。

setThemeChangeHandler()

Chrome 99 及更高版本 browser.*（自 Chrome 152 起）

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

指定在开发者工具中当前主题发生更改时要调用的函数。如需取消设置处理程序，请调用不带参数的方法，或将 null 作为参数传递。

参数

• callback

  函数可选

  callback 参数如下所示：

  (theme: Theme) => void

  • 主题

    主题

    开发者工具中的当前主题。