adding-tauri-system-tray

Tauri 系统托盘实现

本技能介绍如何在 Tauri v2 应用中实现系统托盘（通知区域）功能。

配置

在 src-tauri/Cargo.toml 中启用 tray-icon 功能：

[dependencies]
tauri = { version = "2", features = ["tray-icon"] }

基本托盘设置

在 src-tauri/src/lib.rs 中创建托盘图标：

use tauri::tray::TrayIconBuilder;

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .setup(|app| {
            // Use TrayIconBuilder::with_id() to reference the tray later
            let tray = TrayIconBuilder::with_id(app, "main-tray")
                .icon(app.default_window_icon().unwrap().clone())
                .tooltip("My Tauri App")
                .build(app)?;
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

托盘菜单

带菜单项的基本菜单

use tauri::{
    menu::{Menu, MenuItem},
    tray::TrayIconBuilder,
};

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .setup(|app| {
            let show_item = MenuItem::with_id(app, "show", "Show Window", true, None::<&str>)?;
            let hide_item = MenuItem::with_id(app, "hide", "Hide Window", true, None::<&str>)?;
            let quit_item = MenuItem::with_id(app, "quit", "Quit", true, None::<&str>)?;

            let menu = Menu::with_items(app, &[&show_item, &hide_item, &quit_item])?;

            let tray = TrayIconBuilder::new()
                .icon(app.default_window_icon().unwrap().clone())
                .menu(&menu)
                .menu_on_left_click(false)  // Only show menu on right-click
                .build(app)?;

            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

带分隔符和子菜单的菜单

use tauri::{
    menu::{Menu, MenuItem, PredefinedMenuItem, Submenu},
    tray::TrayIconBuilder,
};

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .setup(|app| {
            let option1 = MenuItem::with_id(app, "option1", "Option 1", true, None::<&str>)?;
            let option2 = MenuItem::with_id(app, "option2", "Option 2", true, None::<&str>)?;
            let options_submenu = Submenu::with_items(app, "Options", true, &[&option1, &option2])?;

            let show_item = MenuItem::with_id(app, "show", "Show Window", true, None::<&str>)?;
            let separator = PredefinedMenuItem::separator(app)?;
            let quit_item = MenuItem::with_id(app, "quit", "Quit", true, None::<&str>)?;

            let menu = Menu::with_items(
                app,
                &[&show_item, &options_submenu, &separator, &quit_item],
            )?;

            let tray = TrayIconBuilder::new()
                .icon(app.default_window_icon().unwrap().clone())
                .menu(&menu)
                .build(app)?;

            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

处理托盘事件

菜单项事件

use tauri::{
    menu::{Menu, MenuItem},
    tray::TrayIconBuilder,
    Manager,
};

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .setup(|app| {
            let show_item = MenuItem::with_id(app, "show", "Show Window", true, None::<&str>)?;
            let hide_item = MenuItem::with_id(app, "hide", "Hide Window", true, None::<&str>)?;
            let quit_item = MenuItem::with_id(app, "quit", "Quit", true, None::<&str>)?;
            let menu = Menu::with_items(app, &[&show_item, &hide_item, &quit_item])?;

            let tray = TrayIconBuilder::new()
                .icon(app.default_window_icon().unwrap().clone())
                .menu(&menu)
                .on_menu_event(|app, event| {
                    match event.id.as_ref() {
                        "show" => {
                            if let Some(window) = app.get_webview_window("main") {
                                let _ = window.show();
                                let _ = window.set_focus();
                            }
                        }
                        "hide" => {
                            if let Some(window) = app.get_webview_window("main") {
                                let _ = window.hide();
                            }
                        }
                        "quit" => app.exit(0),
                        _ => println!("Unhandled menu item: {:?}", event.id),
                    }
                })
                .build(app)?;

            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

托盘图标鼠标事件

use tauri::{
    tray::{MouseButton, MouseButtonState, TrayIconBuilder, TrayIconEvent},
    Manager,
};

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .setup(|app| {
            let tray = TrayIconBuilder::new()
                .icon(app.default_window_icon().unwrap().clone())
                .on_tray_icon_event(|tray, event| {
                    match event {
                        TrayIconEvent::Click {
                            button: MouseButton::Left,
                            button_state: MouseButtonState::Up,
                            ..
                        } => {
                            let app = tray.app_handle();
                            if let Some(window) = app.get_webview_window("main") {
                                let _ = window.unminimize();
                                let _ = window.show();
                                let _ = window.set_focus();
                            }
                        }
                        TrayIconEvent::DoubleClick { button: MouseButton::Left, .. } => {
                            let app = tray.app_handle();
                            if let Some(window) = app.get_webview_window("main") {
                                if window.is_visible().unwrap_or(false) {
                                    let _ = window.hide();
                                } else {
                                    let _ = window.show();
                                    let _ = window.set_focus();
                                }
                            }
                        }
                        TrayIconEvent::Enter { .. } => println!("Mouse entered tray"),
                        TrayIconEvent::Leave { .. } => println!("Mouse left tray"),
                        _ => {}
                    }
                })
                .build(app)?;

            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

注意：Linux 不支持 Enter、Move 和 Leave 事件。

在运行时更新托盘

更新图标和工具提示

use tauri::{image::Image, tray::TrayIconBuilder, Manager};

#[tauri::command]
fn update_tray_icon(app: tauri::AppHandle, icon_path: String) -> Result<(), String> {
    if let Some(tray) = app.tray_by_id("main-tray") {
        let icon = Image::from_path(&icon_path).map_err(|e| e.to_string())?;
        tray.set_icon(Some(icon)).map_err(|e| e.to_string())?;
    }
    Ok(())
}

#[tauri::command]
fn update_tray_tooltip(app: tauri::AppHandle, tooltip: String) -> Result<(), String> {
    if let Some(tray) = app.tray_by_id("main-tray") {
        tray.set_tooltip(Some(&tooltip)).map_err(|e| e.to_string())?;
    }
    Ok(())
}

动态更新菜单项

use std::sync::Mutex;
use tauri::{
    menu::{Menu, MenuItem, MenuItemKind},
    tray::TrayIconBuilder,
    Manager,
};

struct AppState {
    menu: Mutex<Option<Menu<tauri::Wry>>>,
}

#[tauri::command]
fn toggle_menu_item(app: tauri::AppHandle, item_id: String, enabled: bool) -> Result<(), String> {
    let state = app.state::<AppState>();
    if let Some(menu) = state.menu.lock().unwrap().as_ref() {
        if let Some(MenuItemKind::MenuItem(item)) = menu.get(&item_id) {
            item.set_enabled(enabled).map_err(|e| e.to_string())?;
        }
    }
    Ok(())
}

#[tauri::command]
fn update_menu_text(app: tauri::AppHandle, item_id: String, text: String) -> Result<(), String> {
    let state = app.state::<AppState>();
    if let Some(menu) = state.menu.lock().unwrap().as_ref() {
        if let Some(MenuItemKind::MenuItem(item)) = menu.get(&item_id) {
            item.set_text(&text).map_err(|e| e.to_string())?;
        }
    }
    Ok(())
}

替换整个菜单

use tauri::{menu::{Menu, MenuItem}, Manager};

#[tauri::command]
fn set_connected_menu(app: tauri::AppHandle) -> Result<(), String> {
    if let Some(tray) = app.tray_by_id("main-tray") {
        let disconnect = MenuItem::with_id(&app, "disconnect", "Disconnect", true, None::<&str>)
            .map_err(|e| e.to_string())?;
        let status = MenuItem::with_id(&app, "status", "Connected", false, None::<&str>)
            .map_err(|e| e.to_string())?;
        let quit = MenuItem::with_id(&app, "quit", "Quit", true, None::<&str>)
            .map_err(|e| e.to_string())?;

        let menu = Menu::with_items(&app, &[&status, &disconnect, &quit])
            .map_err(|e| e.to_string())?;
        tray.set_menu(Some(menu)).map_err(|e| e.to_string())?;
    }
    Ok(())
}

完整示例

use std::sync::Mutex;
use tauri::{
    menu::{Menu, MenuItem, PredefinedMenuItem},
    tray::{MouseButton, MouseButtonState, TrayIconBuilder, TrayIconEvent},
    Manager,
};

struct TrayState {
    is_paused: Mutex<bool>,
}

#[tauri::command]
fn get_tray_status(state: tauri::State<TrayState>) -> bool {
    *state.is_paused.lock().unwrap()
}

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .manage(TrayState { is_paused: Mutex::new(false) })
        .setup(|app| {
            let show = MenuItem::with_id(app, "show", "Show Window", true, None::<&str>)?;
            let hide = MenuItem::with_id(app, "hide", "Hide Window", true, None::<&str>)?;
            let sep = PredefinedMenuItem::separator(app)?;
            let pause = MenuItem::with_id(app, "pause", "Pause", true, None::<&str>)?;
            let quit = MenuItem::with_id(app, "quit", "Quit", true, None::<&str>)?;

            let menu = Menu::with_items(app, &[&show, &hide, &sep, &pause, &quit])?;

            let _tray = TrayIconBuilder::with_id(app, "main-tray")
                .icon(app.default_window_icon().unwrap().clone())
                .tooltip("My Tauri App - Running")
                .menu(&menu)
                .menu_on_left_click(false)
                .on_menu_event(|app, event| {
                    match event.id.as_ref() {
                        "show" => {
                            if let Some(w) = app.get_webview_window("main") {
                                let _ = w.show();
                                let _ = w.set_focus();
                            }
                        }
                        "hide" => {
                            if let Some(w) = app.get_webview_window("main") {
                                let _ = w.hide();
                            }
                        }
                        "pause" => {
                            let state = app.state::<TrayState>();
                            let mut paused = state.is_paused.lock().unwrap();
                            *paused = !*paused;
                            if let Some(tray) = app.tray_by_id("main-tray") {
                                let tip = if *paused { "Paused" } else { "Running" };
                                let _ = tray.set_tooltip(Some(tip));
                            }
                        }
                        "quit" => app.exit(0),
                        _ => {}
                    }
                })
                .on_tray_icon_event(|tray, event| {
                    if let TrayIconEvent::Click {
                        button: MouseButton::Left,
                        button_state: MouseButtonState::Up, ..
                    } = event {
                        let app = tray.app_handle();
                        if let Some(w) = app.get_webview_window("main") {
                            if w.is_visible().unwrap_or(false) {
                                let _ = w.hide();
                            } else {
                                let _ = w.show();
                                let _ = w.set_focus();
                            }
                        }
                    }
                })
                .build(app)?;

            Ok(())
        })
        .invoke_handler(tauri::generate_handler![get_tray_status])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

平台说明

平台	支持情况
Windows	完全支持所有托盘事件
macOS	完全支持所有托盘事件
Linux	不支持 Enter、Move、Leave 事件

故障排除

托盘图标未显示：

• 确保已在 Cargo.toml 中启用 tray-icon 功能
• 确认图标有效且可访问
• 检查是否调用了 build() 并保存了结果

菜单未显示：

• 确认菜单已通过 .menu(&menu) 附加
• 检查 menu_on_left_click 设置
• 确认菜单项已正确创建

事件未触发：

• 确保在调用 build() 之前已附加事件处理器
• 检查事件处理器中的模式匹配
• 使用 tray_by_id() 时，确认托盘 ID 匹配