action.setPopup()

指定用户单击浏览器操作图标时以弹窗形式打开的 HTML 文档。没有特定弹窗的标签页将继承全局弹窗,其默认值为清单中指定的 default_popup

备注: 该 API 在 Manifest V3 或更高版本中可用。

语法

js
browser.action.setPopup(
  details // 对象
)

参数

details

一个含有下列属性的对象:

tabId 可选

integer,指定要设置弹窗的标签页。当用户导航到新页面时,弹窗会被重置。

windowId 可选

integer,指定要设置弹窗的窗口。

stringnull,指定作为弹窗的 HTML 文件的 URL。

这可以指向打包在扩展中的文件(例如使用 extension.getURL 创建的文件),或远程文档(例如 https://example.org/)。

若传入空字符串(""),则禁用弹窗,扩展将接收 action.onClicked 事件。

popupnull

  • 若指定了 tabId,则移除标签页特定的弹窗,使标签页继承其所属窗口的弹窗。
  • 若指定了 windowId,则移除窗口特定的弹窗,使窗口继承全局弹窗。
  • tabIdwindowId 都被省略,则将全局弹窗恢复为默认值。
  • 若同时指定了 windowIdtabId,则函数出错且不会设置弹窗。
  • 若同时未指定 windowIdtabId,则将设置全局弹窗。

示例

这段代码添加了一对上下文菜单项,用于在两个弹窗之间切换。请注意,你需要在扩展的清单中设置“contextMenus”权限来创建上下文菜单项。

js
function onCreated() {
  if (browser.runtime.lastError) {
    console.log("创建菜单项时出错:", browser.runtime.lastError);
  } else {
    console.log("上下文菜单项已创建");
  }
}

browser.contextMenus.create(
  {
    id: "popup-1",
    type: "radio",
    title: "弹窗 1",
    contexts: ["all"],
    checked: true,
  },
  onCreated,
);

browser.contextMenus.create(
  {
    id: "popup-2",
    type: "radio",
    title: "弹窗 2",
    contexts: ["all"],
    checked: false,
  },
  onCreated,
);

browser.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === "popup-1") {
    browser.action.setPopup({ popup: "/popup/popup1.html" });
  } else if (info.menuItemId === "popup-2") {
    browser.action.setPopup({ popup: "/popup/popup2.html" });
  }
});

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Firefox for Android
Safari on iOS
setPopup
details.windowId parameter
The popup property of the details parameter can be set to null.

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support

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