Меню

deno desktop предоставляет два вида нативных меню: меню приложения (строка меню macOS, меню окна в Windows / Linux) и контекстные меню (всплывающие меню по щелчку правой кнопкой мыши).

В обоих случаях используется один и тот же тип Deno.MenuItem.

Структура MenuItem

MenuItem — это размеченное объединение: каждый элемент имеет одну из четырёх структур:

type MenuItem =
  // A clickable item.
  | {
    item: {
      label: string;
      id?: string; // returned in the click event
      accelerator?: string; // e.g. "CmdOrCtrl+S", "F11"
      enabled: boolean;
    };
  }
  // A nested submenu.
  | {
    submenu: {
      label: string;
      items: MenuItem[];
    };
  }
  // A divider line.
  | "separator"
  // A standard OS role (see below).
  | { role: { role: string } };

Меню верхнего уровня — это массив таких элементов. Элементы вкладываются друг в друга: для этого в submenu помещают дополнительные MenuItem в свойство items.

Меню приложения

Задайте меню, которое отображается в строке меню macOS (или в меню окна Windows / Linux):

win.setApplicationMenu([
  {
    submenu: {
      label: "File",
      items: [
        {
          item: {
            label: "New",
            id: "new",
            accelerator: "CmdOrCtrl+N",
            enabled: true,
          },
        },
        {
          item: {
            label: "Open…",
            id: "open",
            accelerator: "CmdOrCtrl+O",
            enabled: true,
          },
        },
        "separator",
        {
          item: {
            label: "Save",
            id: "save",
            accelerator: "CmdOrCtrl+S",
            enabled: true,
          },
        },
        { role: { role: "quit" } },
      ],
    },
  },
  {
    submenu: {
      label: "Edit",
      items: [
        { role: { role: "undo" } },
        { role: { role: "redo" } },
        "separator",
        { role: { role: "cut" } },
        { role: { role: "copy" } },
        { role: { role: "paste" } },
      ],
    },
  },
]);

Чтобы отслеживать щелчки, используйте событие menuclick:

win.addEventListener("menuclick", (e) => {
  switch (e.detail.id) {
    case "new":
      newDocument();
      break;
    case "open":
      openDocument();
      break;
    case "save":
      saveDocument();
      break;
  }
});

e.detail.id — это id, заданный вами для item. Элементы без id, а также элементы role (которые обрабатываются непосредственно ОС), не вызывают события menuclick.

Сочетания клавиш

Сочетания клавиш действуют глобально в активном окне. Формат строки: Modifier+Modifier+Key:

Клавиши — это буквы (A-Z), цифры (0-9), функциональные клавиши (F1-F24) или клавиши с именами (Enter, Esc, Up, Down, Left, Right, Tab, Space, Backspace, Delete).

Используйте CmdOrCtrl вместо прямого указания Cmd или Ctrl, чтобы не проверять платформу для наиболее распространённых сочетаний клавиш.

Роли

Элемент { role: { role } } соответствует стандартной команде меню ОС: платформа предоставляет для него подпись, сочетание клавиш и поведение. Используйте роли для стандартных команд, чтобы они работали нативно (а macOS связывала стандартные сочетания клавиш меню Edit):

const quit: Deno.MenuItem = { role: { role: "quit" } };
const copy: Deno.MenuItem = { role: { role: "copy" } };
const paste: Deno.MenuItem = { role: { role: "paste" } };

К распространённым ролям относятся quit, undo, redo, cut, copy, paste, selectAll, minimize и close. Элемент с ролью не требует id и никогда не вызывает событие menuclick; он обрабатывается непосредственно ОС.

Особенности строки меню macOS

В macOS первое подменю верхнего уровня является меню приложения (с названием приложения), а его подпись заменяется на название приложения. Поместите туда стандартные роли приложения (например, quit). Если вы не добавите такое меню, оно будет создано автоматически.

Стандартные элементы меню Edit (Cut, Copy, Paste, Select All, Undo, Redo) работают нативно, если добавить их как элементы role.

Контекстные меню

Покажите контекстное меню в заданной экранной позиции с помощью showContextMenu(x, y, menu):

const contextMenu: Deno.MenuItem[] = [
  { item: { label: "Copy", id: "copy", enabled: true } },
  { item: { label: "Paste", id: "paste", enabled: true } },
  "separator",
  { item: { label: "Properties…", id: "props", enabled: true } },
];

// Trigger from a right-click. The webview may not forward the browser
// `contextmenu` event, so handle the secondary mouse button on the window.
win.addEventListener("mousedown", (e) => {
  if (e.button === 2) {
    win.showContextMenu(e.clientX, e.clientY, contextMenu);
  }
});

win.addEventListener("contextmenuclick", (e) => {
  if (e.detail.id === "copy") { /* ... */ }
  if (e.detail.id === "paste") { /* ... */ }
});

Щелчки по контекстному меню поступают как события contextmenuclick, а щелчки по меню приложения — как menuclick, поэтому для различения этих событий не нужно добавлять префиксы к идентификаторам.

Динамические меню

Меню приложения можно заменить в любой момент, повторно вызвав setApplicationMenu; ОС обновит меню на месте. API для обновления отдельного элемента нет: пересоберите массив и вызовите setApplicationMenu при изменении состояния:

function rebuildEditMenu(canUndo: boolean) {
  win.setApplicationMenu([
    {
      submenu: {
        label: "Edit",
        items: [
          {
            item: {
              label: "Undo",
              id: "undo",
              accelerator: "CmdOrCtrl+Z",
              enabled: canUndo,
            },
          },
        ],
      },
    },
  ]);
}

Если меню часто обновляется (например, при каждом нажатии клавиши), объединяйте обновления вместо вызова при каждом изменении.

Отключённые и скрытые элементы

Установите enabled: false, чтобы сделать элемент неактивным:

const save: Deno.MenuItem = {
  item: { label: "Save", id: "save", enabled: false },
};

Флага visible нет. Чтобы скрыть элемент, исключите его из массива и повторно вызовите setApplicationMenu.