action.setPopup()

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

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

语法

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

参数

details

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

tabId 可选

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

windowId 可选

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

string 或 null，指定作为弹窗的 HTML 文件的 URL。

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

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

若 popup 为 null：

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

示例

这段代码添加了一对上下文菜单项，用于在两个弹窗之间切换。请注意，你需要在扩展的清单中设置“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" });
  }
});

浏览器兼容性

BCD tables only load in the browser

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