Tauri 插件上下文菜单

这是一个用于在 Tauri v1.x 中显示原生上下文菜单的 Tauri 插件。 Tauri API 本身不支持原生上下文菜单，因此创建了这个插件来填补这一空白。

<img src="https://yellow-cdn.veclightyear.com/835a84d5/33cdc7f3-79d5-4f3a-bf71-db955e8f6a41.png" alt="image" width="400" height="auto">

官方在 Tauri v2.x 中已添加上下文菜单支持（参见这里），所以此插件仅适用于 Tauri v1.x。

支持

Windows	MacOS	Linux
✅	✅	✅

安装

Crate：https://crates.io/crates/tauri-plugin-context-menu

使用 cargo add tauri-plugin-context-menu 添加包。

或者将以下内容添加到 Cargo.toml 中以使用最新的未发布版本（不推荐）。

tauri-plugin-context-menu = { git = "https://github.com/c2r0b/tauri-plugin-context-menu", branch = "main" }

请参阅 Tauri 官方指南中的"使用插件"部分以初始化插件。

该项目提供了一个 TypeScript 工具包以简化插件的使用。运行以下命令安装 JavaScript/TypeScript 包：

npm i tauri-plugin-context-menu

示例

查看 examples 目录以获取使用示例。

examples/vanilla 中提供了一个原生 JS 示例。 在 npm install 之后，使用以下命令运行示例：

npm run examples/vanilla

examples/ts-utility 中提供了一个使用工具包的 TypeScript 示例。 你可以使用相同的命令运行它（将 examples/vanilla 替换为 examples/ts-utility）。

使用示例

不使用 JS/TS 包

import { invoke } from "@tauri-apps/api";
import { listen } from "@tauri-apps/api/event";
import { resolveResource } from "@tauri-apps/api/path";

// 监听第一个菜单项被点击时触发的事件
listen("item1clicked", (event) => {
    alert(event.payload);
});

window.addEventListener("contextmenu", async (e) => {
    e.preventDefault();
    const iconUrl = await resolveResource('assets/16x16.png');

    // 显示上下文菜单
    invoke("plugin:context_menu|show_context_menu", {
        items: [
            {
                label: "项目 1",
                disabled: false,
                event: "item1clicked",
                payload: "你好，世界！",
                shortcut: "ctrl+M",
                icon: {
                    path: iconUrl
                },
                subitems: [
                    {
                        label: "子项 1",
                        disabled: true,
                        event: "subitem1clicked",
                    },
                    {
                        is_separator: true,
                    },
                    {
                        label: "子项 2",
                        disabled: false,
                        checked: true,
                        event: "subitem2clicked",
                    }
                ]
            }
        ],
    });
});

使用 JS/TS 包

import { showMenu } from "tauri-plugin-context-menu";

showMenu({ 
    pos: {...}, // 菜单位置（选项见下文）
    theme: "light", // 菜单主题
    items: [
        ...,
        {
            ..., // 菜单项（选项见下文）
            event: () => {
                // 执行操作
            }
        }
    ]
});

你还可以使用 onEventShowMenu 函数来响应窗口事件：

import { onEventShowMenu } from "tauri-plugin-context-menu";
onEventShowMenu("contextmenu", (e) => ({ /* 菜单选项 */ }));

选项

可传递给插件的选项列表。

选项	类型	可选	描述	操作系统兼容性
items	MenuItem[]		要显示的菜单项列表。	全部
pos	Position	可选	菜单位置。默认为光标位置。	全部
theme	light | dark	可选	菜单主题。默认为系统主题。	仅 MacOS #25

菜单项

选项	类型	可选	默认值	描述	JS/TS 包
label	string			菜单项显示的文本。
disabled	boolean	可选	false	菜单项是否禁用。
event	string	可选		点击菜单项时要触发的事件名称。	你可以传递一个函数代替事件名称来执行。
payload	string	可选		传递给事件的负载。	你可以传递任何类型的数据。
checked	boolean	可选		菜单项是否被选中。
subitems	MenuItem[]	可选	[]	要显示的子菜单项列表。
shortcut	string	可选		右侧显示的键盘快捷键。
icon	MenuItemIcon	可选		左侧显示的图标。
is_separator	boolean	可选	false	菜单项是否为分隔符。

菜单项图标

选项	类型	可选	默认值	描述	JS/TS 包
path	string			图标文件的绝对路径。	你可以使用 assetToPath 将相对路径转换为绝对路径。
width	number	可选	16	图标的宽度。
height	number	可选	16	图标的高度。

位置

当 is_absolute 设置为 false 时，位置坐标必须相对于当前活动窗口。

选项	类型	可选	默认值	描述
x	number			菜单的 X 位置。
y	number			菜单的 Y 位置。
is_absolute	boolean	可选	false	位置是否相对于屏幕绝对

修饰键

修饰键可以在菜单项的 shortcut 选项中使用，以显示相应的符号（⌘、⌃、⌥、⇧）。

在 MacOS 上，当按下修饰键时，这也会使快捷键生效（因为它是由操作系统默认处理的）。

<details> <summary>按键代码列表</summary>

修饰键

• cmd
• cmd_or_ctrl（cmd 和 ctrl 的别名）
• shift
• alt
• ctrl
• opt（alt 的别名）
• altgr
• super
• win
• meta

按键

• plus
• space
• tab
• capslock
• numlock
• scrolllock
• backspace
• delete
• insert
• return
• enter
• up
• down
• left
• right
• home
• end
• pageup
• pagedown
• escape
• esc
• num0...9
• numdec
• numadd
• numsub
• nummult
• numdiv
• f1...24

</details>

事件

项目被点击

当菜单项被点击时触发。事件名称与菜单项的 event 选项相同：

import { listen } from "@tauri-apps/api/event";
import { invoke } from "@tauri-apps/api";

listen("[事件名称]", () => {
    alert("菜单项被点击");
});

invoke(...{
    items: [{
        ...
        event: "[事件名称]",
        ...
    }]
});

菜单已关闭

当菜单关闭时触发。无论菜单是通过点击菜单项还是点击菜单外部关闭，都会触发此事件。 你可以使用以下代码捕获此事件：

import { listen } from "@tauri-apps/api/event";

listen("menu-did-close", () => {
    alert("菜单已关闭");
});