菜单

将项目添加到浏览器的菜单系统中。

此 API 模仿了 Chrome 的 "contextMenus" API，该 API 使 Chrome 扩展程序能够将项目添加到浏览器的上下文菜单中。browser.menus API 在 Chrome 的 API 中添加了一些功能。

在 Firefox 55 之前，此 API 最初也称为 contextMenus，并且该名称保留为别名，因此您可以使用 contextMenus 来编写适用于 Firefox 以及其他浏览器的代码。

要使用此 API，您需要具有 menus 权限。您也可以使用 contextMenus 别名而不是 menus，但如果您这样做，则必须以 browser.contextMenus 的形式访问 API。

除了 menus.getTargetElement() 之外，此 API 无法从内容脚本中使用。

创建菜单项

要创建菜单项，请调用 menus.create() 方法。您将传递一个包含项目选项的对象给此方法，包括项目 ID、项目类型以及应该显示项目的上下文。

在使用非持久性后台页面（事件页面）的 Firefox 扩展程序中，或者在任何 Chrome 扩展程序中，您从 runtime.onInstalled 监听器中调用 menus.create。在使用持久性后台页面的 Firefox 扩展程序中，您进行顶层调用。有关更多信息，请参阅 menus.create()。

通过向 menus.onClicked 事件添加监听器来监听菜单项的点击。此监听器将传递一个 menus.OnClickData 对象，其中包含事件的详细信息。

您可以根据在传递给 create() 的选项中提供的 type 属性的值来创建四种不同的菜单项类型。

"normal"：仅显示标签的菜单项。
"checkbox"：表示二进制状态的菜单项。它在标签旁边显示一个复选标记。点击项目将切换复选标记。点击监听器将传递两个额外的属性："checked"，表示项目当前是否选中，以及 "wasChecked"，表示项目在点击事件之前是否选中。
"radio"：表示一组选项中的一项的菜单项。与复选框一样，它也在标签旁边显示一个复选标记，其点击监听器传递 "checked" 和 "wasChecked"。但是，如果您创建了多个单选按钮项目，则这些项目将作为一组单选按钮项目：组中只有一项可以选中，点击一个项目将使其成为选中的项目。
"separator"：用于分隔一组项目的线。

如果您创建了多个上下文菜单项或多个工具菜单项，则这些项目将放置在子菜单中。子菜单的父菜单将用扩展程序的名称标记。例如，以下是一个名为 "Menu demo" 的扩展程序，它添加了两个上下文菜单项。

Context menu with two items labeled click me, and click me too!

图标

如果您已使用 "icons" 清单键为扩展程序指定了图标，则菜单项将在其标签旁边显示指定的图标。浏览器将尝试为普通显示选择一个 16x16 像素的图标，或为高密度显示选择一个 32x32 像素的图标。

Context menu with two items labeled click me, and click me too!

仅对于子菜单中的项目，您可以通过将 icons 选项传递给 menus.create() 来指定自定义图标。

Context menu with two items labeled click me, and click me too!. The click me option is labeled with a green paint can icon. The click me too option is labeled with a blue paint can icon.

示例

以下是一个包含 4 个项目的上下文菜单：一个普通项目、两个带分隔符的单选按钮项目和一个复选框。单选按钮项目被赋予了自定义图标。

Context menu with four items labeled remove me, Greenify, Bluify, and uncheck me. Greenify and Bluify are radio buttons given custom icons.

您可以使用以下代码来创建这样的子菜单。

browser.menus.create(
  {
    id: "remove-me",
    title: browser.i18n.getMessage("menuItemRemoveMe"),
    contexts: ["all"],
  },
  onCreated,
);

browser.menus.create(
  {
    id: "separator-1",
    type: "separator",
    contexts: ["all"],
  },
  onCreated,
);

browser.menus.create(
  {
    id: "greenify",
    type: "radio",
    title: browser.i18n.getMessage("menuItemGreenify"),
    contexts: ["all"],
    checked: true,
    icons: {
      16: "icons/paint-green-16.png",
      32: "icons/paint-green-32.png",
    },
  },
  onCreated,
);

browser.menus.create(
  {
    id: "bluify",
    type: "radio",
    title: browser.i18n.getMessage("menuItemBluify"),
    contexts: ["all"],
    checked: false,
    icons: {
      16: "icons/paint-blue-16.png",
      32: "icons/paint-blue-32.png",
    },
  },
  onCreated,
);

browser.menus.create(
  {
    id: "separator-2",
    type: "separator",
    contexts: ["all"],
  },
  onCreated,
);

let checkedState = true;

browser.menus.create(
  {
    id: "check-uncheck",
    type: "checkbox",
    title: browser.i18n.getMessage("menuItemUncheckMe"),
    contexts: ["all"],
    checked: checkedState,
  },
  onCreated,
);