Menu

类：Menu

¥Class: Menu

创建原生应用菜单和上下文菜单。

¥Create native application menus and context menus.

进程：主进程

¥Process: Main

new Menu()

创建一个新菜单。

¥Creates a new menu.

静态方法

¥Static Methods

Menu 类具有以下静态方法：

¥The Menu class has the following static methods:

Menu.setApplicationMenu(menu)

• menu Menu | null

将 menu 设置为 macOS 上的应用菜单。在 Windows 和 Linux 上，menu 将被设置为每个窗口的顶部菜单。

¥Sets menu as the application menu on macOS. On Windows and Linux, the menu will be set as each window's top menu.

此外，在 Windows 和 Linux 上，你可以在顶层项目名称中使用 & 来指示哪个字母应获得生成的加速器。例如，使用 &File 作为文件菜单将生成一个打开关联菜单的 Alt-F 加速器。然后，按钮标签中指示的字符将带有下划线，并且 & 字符不会显示在按钮标签上。

¥Also on Windows and Linux, you can use a & in the top-level item name to indicate which letter should get a generated accelerator. For example, using &File for the file menu would result in a generated Alt-F accelerator that opens the associated menu. The indicated character in the button label then gets an underline, and the & character is not displayed on the button label.

为了转义项目名称中的 & 字符，请添加前面的 &。例如，&&File 将导致 &File 显示在按钮标签上。

¥In order to escape the & character in an item name, add a proceeding &. For example, &&File would result in &File displayed on the button label.

通过 null 将取消默认菜单。在 Windows 和 Linux 上，这具有从窗口中删除菜单栏的附加效果。

¥Passing null will suppress the default menu. On Windows and Linux, this has the additional effect of removing the menu bar from the window.

注意：如果应用未设置默认菜单，则会自动创建默认菜单。它包含 File、Edit、View、Window 和 Help 等标准项目。

¥Note: The default menu will be created automatically if the app does not set one. It contains standard items such as File, Edit, View, Window and Help.

Menu.getApplicationMenu()

返回 Menu | null - 应用菜单（如果已设置）或 null（如果未设置）。

¥Returns Menu | null - The application menu, if set, or null, if not set.

注意：返回的 Menu 实例不支持动态添加或删除菜单项。实例属性 仍然可以动态修改。

¥Note: The returned Menu instance doesn't support dynamic addition or removal of menu items. Instance properties can still be dynamically modified.

Menu.sendActionToFirstResponder(action) macOS

• action 字符串

  ¥action string

将 action 发送给应用的第一响应者。这用于模拟默认的 macOS 菜单行为。通常你会使用 MenuItem 的 role 属性。

¥Sends the action to the first responder of application. This is used for emulating default macOS menu behaviors. Usually you would use the role property of a MenuItem.

有关 macOS 原生操作的更多信息，请参阅 macOS Cocoa 事件处理指南。

¥See the macOS Cocoa Event Handling Guide for more information on macOS' native actions.

Menu.buildFromTemplate(template)

• template（菜单项构造选项 | 菜单项）[]

  ¥template (MenuItemConstructorOptions | MenuItem)[]

返回 Menu

¥Returns Menu

一般情况下，template 是 options 的数组，用于构造 MenuItem。用法可以参考上面。

¥Generally, the template is an array of options for constructing a MenuItem. The usage can be referenced above.

你还可以将其他字段附加到 template 的元素，它们将成为构造的菜单项的属性。

¥You can also attach other fields to the element of the template and they will become properties of the constructed menu items.

实例方法

¥Instance Methods

menu 对象具有以下实例方法：

¥The menu object has the following instance methods:

menu.popup([options])

• options 对象（可选）

  ¥options Object (optional)

  • window BrowserWindow（可选） - 默认是聚焦窗口。

    ¥window BrowserWindow (optional) - Default is the focused window.

  • x 号码（可选） - 默认为当前鼠标光标位置。如果声明了 y，则必须声明。

    ¥x number (optional) - Default is the current mouse cursor position. Must be declared if y is declared.

  • y 号码（可选） - 默认为当前鼠标光标位置。如果声明了 x，则必须声明。

    ¥y number (optional) - Default is the current mouse cursor position. Must be declared if x is declared.

  • positioningItem 数字（可选）macOS - 要定位在鼠标光标下方指定坐标处的菜单项的索引。默认值为-1。

    ¥positioningItem number (optional) macOS - The index of the menu item to be positioned under the mouse cursor at the specified coordinates. Default is -1.

  • sourceType 字符串（可选） Windows Linux - 这应该映射到 context-menu 事件提供的 menuSourceType。不建议手动设置此值，仅提供从其他 API 收到的值或保留 undefined。可以是 none、mouse、keyboard、touch、touchMenu、longPress、longTap、touchHandle、stylus、adjustSelection 或 adjustSelectionReset。

    ¥sourceType string (optional) Windows Linux - This should map to the menuSourceType provided by the context-menu event. It is not recommended to set this value manually, only provide values you receive from other APIs or leave it undefined. Can be none, mouse, keyboard, touch, touchMenu, longPress, longTap, touchHandle, stylus, adjustSelection, or adjustSelectionReset.

  • callback 功能（可选） - 菜单关闭时调用。

    ¥callback Function (optional) - Called when menu is closed.

弹出此菜单作为 BrowserWindow 中的上下文菜单。

¥Pops up this menu as a context menu in the BrowserWindow.

menu.closePopup([browserWindow])

• browserWindow BrowserWindow（可选） - 默认是聚焦窗口。

  ¥browserWindow BrowserWindow (optional) - Default is the focused window.

关闭 browserWindow 中的上下文菜单。

¥Closes the context menu in the browserWindow.

menu.append(menuItem)

• menuItem MenuItem

将 menuItem 添加到菜单。

¥Appends the menuItem to the menu.

menu.getMenuItemById(id)

• id 字符串

  ¥id string

返回 MenuItem | null 具有指定 id 的项目

¥Returns MenuItem | null the item with the specified id

menu.insert(pos, menuItem)

• pos 整数

  ¥pos Integer

• menuItem MenuItem

将 menuItem 插入到菜单的 pos 位置。

¥Inserts the menuItem to the pos position of the menu.

实例事件

¥Instance Events

使用 new Menu 创建或由 Menu.buildFromTemplate 返回的对象会发出以下事件：

¥Objects created with new Menu or returned by Menu.buildFromTemplate emit the following events:

注意：某些事件仅在特定操作系统上可用并如此标记。

¥Note: Some events are only available on specific operating systems and are labeled as such.

事件：'menu-will-show'

¥Event: 'menu-will-show'

返回：

¥Returns:

• event 事件

  ¥event Event

调用 menu.popup() 时发出。

¥Emitted when menu.popup() is called.

事件：'menu-will-close'

¥Event: 'menu-will-close'

返回：

¥Returns:

• event 事件

  ¥event Event

当手动或使用 menu.closePopup() 关闭弹出窗口时发出。

¥Emitted when a popup is closed either manually or with menu.closePopup().

实例属性

¥Instance Properties

menu 对象还具有以下属性：

¥menu objects also have the following properties:

menu.items

包含菜单项的 MenuItem[] 数组。

¥A MenuItem[] array containing the menu's items.

每个 Menu 由多个 MenuItem 组成，每个 MenuItem 可以有一个子菜单。

¥Each Menu consists of multiple MenuItems and each MenuItem can have a submenu.

示例

¥Examples

使用简单模板 API 创建应用菜单的示例：

¥An example of creating the application menu with the simple template API:

const { app, Menu } = require('electron')

const isMac = process.platform === 'darwin'

const template = [
  // { role: 'appMenu' }
  ...(isMac
    ? [{
        label: app.name,
        submenu: [
          { role: 'about' },
          { type: 'separator' },
          { role: 'services' },
          { type: 'separator' },
          { role: 'hide' },
          { role: 'hideOthers' },
          { role: 'unhide' },
          { type: 'separator' },
          { role: 'quit' }
        ]
      }]
    : []),
  // { role: 'fileMenu' }
  {
    label: 'File',
    submenu: [
      isMac ? { role: 'close' } : { role: 'quit' }
    ]
  },
  // { role: 'editMenu' }
  {
    label: 'Edit',
    submenu: [
      { role: 'undo' },
      { role: 'redo' },
      { type: 'separator' },
      { role: 'cut' },
      { role: 'copy' },
      { role: 'paste' },
      ...(isMac
        ? [
            { role: 'pasteAndMatchStyle' },
            { role: 'delete' },
            { role: 'selectAll' },
            { type: 'separator' },
            {
              label: 'Speech',
              submenu: [
                { role: 'startSpeaking' },
                { role: 'stopSpeaking' }
              ]
            }
          ]
        : [
            { role: 'delete' },
            { type: 'separator' },
            { role: 'selectAll' }
          ])
    ]
  },
  // { role: 'viewMenu' }
  {
    label: 'View',
    submenu: [
      { role: 'reload' },
      { role: 'forceReload' },
      { role: 'toggleDevTools' },
      { type: 'separator' },
      { role: 'resetZoom' },
      { role: 'zoomIn' },
      { role: 'zoomOut' },
      { type: 'separator' },
      { role: 'togglefullscreen' }
    ]
  },
  // { role: 'windowMenu' }
  {
    label: 'Window',
    submenu: [
      { role: 'minimize' },
      { role: 'zoom' },
      ...(isMac
        ? [
            { type: 'separator' },
            { role: 'front' },
            { type: 'separator' },
            { role: 'window' }
          ]
        : [
            { role: 'close' }
          ])
    ]
  },
  {
    role: 'help',
    submenu: [
      {
        label: 'Learn More',
        click: async () => {
          const { shell } = require('electron')
          await shell.openExternal('https://electron.nodejs.cn')
        }
      }
    ]
  }
]

const menu = Menu.buildFromTemplate(template)
Menu.setApplicationMenu(menu)

渲染进程

¥Render process

要创建由渲染器进程启动的菜单，请使用 IPC 将所需信息发送到主进程，并让主进程代表渲染器显示菜单。

¥To create menus initiated by the renderer process, send the required information to the main process using IPC and have the main process display the menu on behalf of the renderer.

下面是用户右键单击页面时显示菜单的示例：

¥Below is an example of showing a menu when the user right clicks the page:

// renderer
window.addEventListener('contextmenu', (e) => {
  e.preventDefault()
  ipcRenderer.send('show-context-menu')
})

ipcRenderer.on('context-menu-command', (e, command) => {
  // ...
})

// main
ipcMain.on('show-context-menu', (event) => {
  const template = [
    {
      label: 'Menu Item 1',
      click: () => { event.sender.send('context-menu-command', 'menu-item-1') }
    },
    { type: 'separator' },
    { label: 'Menu Item 2', type: 'checkbox', checked: true }
  ]
  const menu = Menu.buildFromTemplate(template)
  menu.popup({ window: BrowserWindow.fromWebContents(event.sender) })
})

macOS 应用菜单注意事项

¥Notes on macOS Application Menu

macOS 的应用菜单风格与 Windows 和 Linux 完全不同。以下是一些关于使应用的菜单更加原生的注意事项。

¥macOS has a completely different style of application menu from Windows and Linux. Here are some notes on making your app's menu more native-like.

标准菜单

¥Standard Menus

在 macOS 上有许多系统定义的标准菜单，例如 Services 和 Windows 菜单。为了使你的菜单成为标准菜单，你应该将菜单的 role 设置为以下之一，Electron 将识别它们并使它们成为标准菜单：

¥On macOS there are many system-defined standard menus, like the Services and Windows menus. To make your menu a standard menu, you should set your menu's role to one of the following and Electron will recognize them and make them become standard menus:

• window

• help

• services

标准菜单项操作

¥Standard Menu Item Actions

macOS 为某些菜单项提供了标准操作，例如 About xxx、Hide xxx 和 Hide Others。要将菜单项的操作设置为标准操作，你应该设置菜单项的 role 属性。

¥macOS has provided standard actions for some menu items, like About xxx, Hide xxx, and Hide Others. To set the action of a menu item to a standard action, you should set the role attribute of the menu item.

主菜单名称

¥Main Menu's Name

在 macOS 上，应用菜单第一项的标签始终是应用的名称，无论你设置什么标签。要更改它，请修改应用包的 Info.plist 文件。请参阅 关于信息属性列表文件 了解更多信息。

¥On macOS the label of the application menu's first item is always your app's name, no matter what label you set. To change it, modify your app bundle's Info.plist file. See About Information Property List Files for more information.

特定浏览器窗口的设置菜单 (Linux Windows)

¥Setting Menu for Specific Browser Window (Linux Windows)

浏览器窗口的 setMenu 方法 可以设置某些浏览器窗口的菜单。

¥The setMenu method of browser windows can set the menu of certain browser windows.

菜单项位置

¥Menu Item Position

当使用 Menu.buildFromTemplate 构建菜单时，你可以使用 before、after、beforeGroupContaining、afterGroupContaining 和 id 来控制项目的放置方式。

¥You can make use of before, after, beforeGroupContaining, afterGroupContaining and id to control how the item will be placed when building a menu with Menu.buildFromTemplate.

• before - 将此项目插入到具有指定 id 的项目之前。如果引用的项目不存在，该项目将被插入到菜单的末尾。还意味着相关菜单项应放置在与该项目相同的“组”中。

  ¥before - Inserts this item before the item with the specified id. If the referenced item doesn't exist the item will be inserted at the end of the menu. Also implies that the menu item in question should be placed in the same “group” as the item.

• after - 将此项目插入到具有指定 id 的项目之后。如果引用的项目不存在，该项目将被插入到菜单的末尾。还意味着相关菜单项应放置在与该项目相同的“组”中。

  ¥after - Inserts this item after the item with the specified id. If the referenced item doesn't exist the item will be inserted at the end of the menu. Also implies that the menu item in question should be placed in the same “group” as the item.

• beforeGroupContaining - 为单个上下文菜单提供一种方法，以声明其包含组位于具有指定 id 的项目的包含组之前。

  ¥beforeGroupContaining - Provides a means for a single context menu to declare the placement of their containing group before the containing group of the item with the specified id.

• afterGroupContaining - 为单个上下文菜单提供一种方法，以声明其包含组在具有指定 id 的项目的包含组之后的位置。

  ¥afterGroupContaining - Provides a means for a single context menu to declare the placement of their containing group after the containing group of the item with the specified id.

默认情况下，除非使用指定的定位关键字之一，否则项目将按照它们在模板中存在的顺序插入。

¥By default, items will be inserted in the order they exist in the template unless one of the specified positioning keywords is used.

示例

¥Examples

模板：

¥Template:

[
  { id: '1', label: 'one' },
  { id: '2', label: 'two' },
  { id: '3', label: 'three' },
  { id: '4', label: 'four' }
]

菜单：

¥Menu:

- 1
- 2
- 3
- 4

模板：

¥Template:

[
  { id: '1', label: 'one' },
  { type: 'separator' },
  { id: '3', label: 'three', beforeGroupContaining: ['1'] },
  { id: '4', label: 'four', afterGroupContaining: ['2'] },
  { type: 'separator' },
  { id: '2', label: 'two' }
]

菜单：

¥Menu:

- 3
- 4
- ---
- 1
- ---
- 2

模板：

¥Template:

[
  { id: '1', label: 'one', after: ['3'] },
  { id: '2', label: 'two', before: ['1'] },
  { id: '3', label: 'three' }
]

菜单：

¥Menu:

- ---
- 3
- 2
- 1