action

用于读取和修改使用 action 清单键定义的浏览器工具栏按钮的属性,以及监听按钮的点击事件。

备注: 该 API 在 Manifest V3 或更高版本中可用。它替代了 Manifest V2 API browserAction,以及在 Chrome、Safari 中的 pageAction

浏览器操作是浏览器工具栏中的一个按钮。

你可以将弹窗与按钮关联。与网页一样,弹窗使用 HTML、CSS 和 JavaScript 指定。在弹窗中运行的 JavaScript 可以访问与后台脚本相同的 WebExtension API,但其全局上下文是弹窗,而不是浏览器中显示的当前页面。要影响网页,你需要通过消息与网页进行通信。

如果指定了弹窗,当用户点击图标时,它会显示并加载内容。如果没有指定弹窗,当用户点击图标时,会向你的扩展发送一个事件。

按钮还有一个上下文菜单。你可以利用 menus API 中 actionmenus.ContextType 添加上下文菜单项。

使用 action API,你可以:

  • 使用 action.onClicked 监听图标的点击事件。
  • 获取和设置图标的属性(图标、标题、弹窗等)。你可以获取和设置这些属性的全局值(针对所有标签页),也可以通过传递标签页 id 作为额外参数来对某个标签页单独获取和设置这些属性。

类型

action.ColorArray

四个范围在 0-255 间的整型组成的数组,表示一个 RGBA 颜色。

action.ImageDataType

图片的像素数据,必须是一个 ImageData 对象(如来源于一个 <canvas> 元素)。

函数

action.setTitle()

设置浏览器操作的标题。这会在工具提示中显示出来。

action.getTitle()

获取浏览器操作的标题。

action.setIcon()

设置浏览器操作的图标。

action.setPopup()

设置用户单击浏览器操作图标时打开的弹窗所用的 HTML 文档。

action.getPopup()

设置用户单击浏览器操作图标时打开的弹窗所用的 HTML 文档。

action.openPopup()

打开浏览器操作的弹窗。

action.setBadgeText()

设置浏览器操作的徽标文本(徽标将显示在图标上方)。

action.getBadgeText()

获取浏览器操作的徽标文本。

action.setBadgeBackgroundColor()

设置徽标的背景颜色。

action.getBadgeBackgroundColor()

获取徽标的背景颜色。

action.setBadgeTextColor()

设置徽标的文本颜色。

action.getBadgeTextColor()

获取徽标的文本颜色。

action.getUserSettings()

获取浏览器操作的用户设置。

action.enable()

启用某一个标签页的浏览器操作。默认情况下,所有标签页的浏览器操作都是启用的。

action.disable()

禁用某一个标签页的浏览器操作,意味着当该标签页处于活动状态时浏览器操作将无法被点击。

action.isEnabled()

检查浏览器操作是否被启用。

事件

action.onClicked

当浏览器操作图标被点击时触发。当浏览器操作有弹窗时该事件不会触发。

浏览器兼容性

BCD tables only load in the browser

备注: 该 API 基于 Chromium 的 chrome.action API。该文档衍生自 Chromium 代码中的 action.json