【11】Tauri 应用篇 - 系统托盘

[lencx]

以 macOS 为例

系统托盘允许用户通过系统状态栏中的托盘图标便捷访问应用或其特定菜单项。

基本配置

编辑 src-tauri/tauri.conf.json 文件

iconAsTemplate 是一个布尔值，用于确定图像是否表示 macOS 上的模板图像（为 true 时图像应仅包含黑色和清晰的颜色，为 false 时图片显示原色）。在 Linux 上，则需要安装软件包对其进行支持，从官方文档了解 Linux 设置。

{
  "tauri": {
    "systemTray": {
      "iconPath": "icons/icon.png", // 托盘图标，默认根路径为 `src-tauri/`
      "iconAsTemplate": true
    }
  }
}

编辑 src-tauri/src/main.rs 文件

#![cfg_attr(
    all(not(debug_assertions), target_os = "windows"),
    windows_subsystem = "windows"
)]

fn main() {
    let context = tauri::generate_context!();
    tauri::Builder::default()
        .system_tray(tauri::SystemTray::default()) // ✅ 将 `tauri.conf.json` 上配置的图标添加到系统托盘
        .run(context)
        .expect("error while running OhMyBox application");
}

注意：点击托盘图标无响应，是因为并未对其添加菜单和事件。

托盘菜单 & 事件

菜单 API

• SystemTrayMenu - 创建一个新菜单
• SystemTraySubmenu - 使用给定的标题和菜单项创建一个新的子菜单
• CustomMenuItem - 自定义菜单项，与 Menu 中的 CustomMenuItem 用法一致
• SystemTrayMenuItem - 原生菜单项，目前仅支持菜单分割符 SystemTrayMenuItem::Separator

注意：虽然应用菜单和托盘菜单都是菜单，但除 CustomMenuItem 与 Menu 共用外，其他 API 不可以混用。

托盘菜单项

SystemTrayMenu::new()

• add_item - 将自定义菜单项添加到系统托盘菜单

  use tauri::{SystemTrayMenu, CustomMenuItem};
  
  SystemTrayMenu::new()
    .add_item(CustomMenuItem::new("quit".to_string(), "Quit"))
    .add_item(CustomMenuItem::new("close".to_string(), "Close"));

• add_native_item - 将原生菜单项添加到系统托盘菜单

  use tauri::{SystemTrayMenu, SystemTrayMenuItem, CustomMenuItem};
  
  SystemTrayMenu::new()
    .add_item(CustomMenuItem::new("quit".to_string(), "Quit"))
    .add_native_item(SystemTrayMenuItem::Separator) // ✅ 菜单分割线
    .add_item(CustomMenuItem::new("close".to_string(), "Close"));

• add_submenu - 添加一个带有子菜单的条目

  use tauri::{SystemTrayMenu, SystemTraySubmenu, SystemTrayMenuItem, CustomMenuItem};
  
  SystemTrayMenu::new()
    .add_submenu(SystemTraySubmenu::new(
      "File",
      SystemTrayMenu::new()
        .add_item(CustomMenuItem::new("new_file".to_string(), "New File"))
        .add_item(CustomMenuItem::new("edit_file".to_string(), "Edit File")),
    ))
    .add_native_item(SystemTrayMenuItem::Separator)
    .add_item(CustomMenuItem::new("hide".to_string(), "Hide"))
    .add_item(CustomMenuItem::new("show".to_string(), "Show"))
    .add_native_item(SystemTrayMenuItem::Separator)
    .add_item(CustomMenuItem::new("quit".to_string(), "Quit"));

创建托盘菜单

新建 src-tauri/src/tray.rs 文件

use tauri::{AppHandle, SystemTrayEvent, SystemTray, CustomMenuItem, SystemTrayMenu, SystemTrayMenuItem, SystemTraySubmenu};

// 托盘菜单
pub fn menu() -> SystemTray {
    let tray_menu = SystemTrayMenu::new()
        .add_submenu(SystemTraySubmenu::new( // 子菜单
            "File", // 子菜单名称
            SystemTrayMenu::new()
                .add_item(CustomMenuItem::new("new_file".to_string(), "New File")) // 子菜单项（新增）
                .add_item(CustomMenuItem::new("edit_file".to_string(), "Edit File")), // 子菜单项（编辑）
        ))
        .add_native_item(SystemTrayMenuItem::Separator) // 分割线
        .add_item(CustomMenuItem::new("hide".to_string(), "Hide")) // 隐藏应用窗口
        .add_item(CustomMenuItem::new("show".to_string(), "Show")) // 显示应用窗口
        .add_native_item(SystemTrayMenuItem::Separator) // 分割线
        .add_item(CustomMenuItem::new("quit".to_string(), "Quit")); // 退出

    // 设置在右键单击系统托盘时显示菜单
    SystemTray::new().with_menu(tray_menu)
}

// 菜单事件
pub fn handler(app: &AppHandle, event: SystemTrayEvent) {
    // 获取应用窗口
    let window = app.get_window("main").unwrap();
    let parent_window = Some(&window);
    // 匹配点击事件
    match event {
        // 左键点击
        SystemTrayEvent::LeftClick {
            position: _,
            size: _,
            ..
        } => {
            println!("system tray received a left click");
        }
        // 右键点击
        SystemTrayEvent::RightClick {
            position: _,
            size: _,
            ..
        } => {
            println!("system tray received a right click");
        }
        // 双击，macOS / Linux 不支持
        SystemTrayEvent::DoubleClick {
            position: _,
            size: _,
            ..
        } => {
            println!("system tray received a double click");
        }
        // 根据菜单 id 进行事件匹配
        SystemTrayEvent::MenuItemClick { id, .. } => match id.as_str() {
            "edit_file" => {
                message(parent_window, "Eidt File", "TODO");
            }
            "new_file" => {
                message(parent_window, "New File", "TODO");
            }
            "quit" => {
                std::process::exit(0);
            }
            "show" => {
                window.show().unwrap();
            }
            "hide" => {
                window.hide().unwrap();
            }
            _ => {}
        },
        _ => {}
    }
}

编辑 src-tauri/src/main.rs 文件

#![cfg_attr(
    all(not(debug_assertions), target_os = "windows"),
    windows_subsystem = "windows"
)]

mod tray;

fn main() {
    let context = tauri::generate_context!();
    tauri::Builder::default()
        .menu(tauri::Menu::os_default(&context.package_info().name))
        .system_tray(tray::menu())  // ✅ 将 `tauri.conf.json` 上配置的图标添加到系统托盘
        .on_system_tray_event(tray::handler) // ✅ 注册系统托盘事件处理程序
        .run(context)
        .expect("error while running OhMyBox application");
}

注意：只创建菜单项，而不添加事件处理，点击菜单依然会无响应。

更新系统托盘

AppHandle 上有一个 tray_handle 方法，用于返回系统托盘的句柄，可以用来更新托盘图标和上下文菜单项。

更新 src-tauri/src/tray.rs 文件

use tauri::{AppHandle, CustomMenuItem, SystemTray, SystemTrayEvent, SystemTrayMenu, SystemTrayMenuItem, SystemTraySubmenu};

// 托盘菜单
pub fn menu() -> SystemTray {
    let quit = CustomMenuItem::new("quit".to_string(), "Quit");
    let show = CustomMenuItem::new("show".to_string(), "Show");
    let hide = CustomMenuItem::new("hide".to_string(), "Hide");
    let change_ico = CustomMenuItem::new("change_ico".to_string(), "Change Icon");
    let tray_menu = SystemTrayMenu::new()
        .add_submenu(SystemTraySubmenu::new(
            "Language", // 语言菜单
            SystemTrayMenu::new()
                .add_item(CustomMenuItem::new("lang_english".to_string(), "English"))
                .add_item(CustomMenuItem::new("lang_zh_CN".to_string(), "简体中文"))
                .add_item(CustomMenuItem::new("lang_zh_HK".to_string(), "繁体中文")),
        ))
        .add_native_item(SystemTrayMenuItem::Separator) // 分割线
        .add_item(change_ico)
        .add_native_item(SystemTrayMenuItem::Separator)
        .add_item(hide)
        .add_item(show)
        .add_native_item(SystemTrayMenuItem::Separator)
        .add_item(quit);

    SystemTray::new().with_menu(tray_menu)
}

// 托盘事件
pub fn handler(app: &AppHandle, event: SystemTrayEvent) {
    match event {
        SystemTrayEvent::MenuItemClick { id, .. } => match id.as_str() {
            "change_ico" => { // 更新托盘图标
                app.tray_handle()
                    .set_icon(tauri::Icon::Raw(
                        include_bytes!("../icons/toolbox.png").to_vec(),
                    ))
                    .unwrap();
            }
            lang if lang.contains("lang_") => { // 选择语言，匹配 id 前缀包含 `lang_` 的事件
                Lang::new(
                    app,
                    id, // 点击菜单的 id
                    vec![
                        Lang {
                            name: "English",
                            id: "lang_english",
                        },
                        Lang {
                            name: "繁体中文",
                            id: "lang_zh_HK",
                        },
                        Lang {
                            name: "简体中文",
                            id: "lang_zh_CN",
                        },
                    ],
                );
            }
            _ => {}
        },
        _ => {}
    }
}

struct Lang<'a> {
    name: &'a str,
    id: &'a str,
}

impl Lang<'static> {
    fn new(app: &AppHandle, id: String, langs: Vec<Lang>) {
        // 获取点击的菜单项的句柄
        // 注意 `tray_handle` 可以在任何地方调用，只需在 setup 钩子上使用 `app.handle()` 获取 `AppHandle` 实例，将其移动到另一个函数或线程
        langs.iter().for_each(|lang| {
            let handle = app.tray_handle().get_item(lang.id);
            if lang.id.to_string() == id.as_str() {
                // 设置菜单名称
                handle.set_title(format!("🥳 {}", lang.name)).unwrap();
                // 还可以使用 `set_selected`、`set_enabled` 和 `set_native_image`（仅限 macOS）
                handle.set_selected(true).unwrap();
            } else {
                handle.set_title(lang.name).unwrap();
                handle.set_selected(false).unwrap();
            }
        });
    }
}

编辑 src-tauri/Cargo.toml 文件，tauri 新增 icon-png，直接使用 tauri::Icon API 设置托盘图标会报错，具体原因可以查看此 issues Path variant of tauri::Icon cannot be found, despite being a documented variant

[dependencies]
tauri = { version = "1.0.5", features = ["api-all", "icon-png", "macos-private-api", "system-tray"] }