Tauri 与 React 前端集成：通信机制与交互原理详解

2. 事件驱动：事件监听（Event）

• 定义：Rust 后端可主动发送事件，前端通过 listen 方法监听事件，实现'后端推送通知'能力。
• 特点：
  • 双向通信：后端主动通知前端（如进度更新、系统事件）；
  • 多监听器：前端可注册多个事件处理函数；
  • 无返回值：事件仅用于通知，不返回数据。

3. 通信流程

三、具体示例：React 与 Rust 交互

以下通过 '文件读取' 和 '实时进度通知' 两个场景，演示完整的交互流程。

场景 1：React 调用 Rust 命令（文件读取）

目标：React 前端提供输入框和按钮，用户输入文件路径，点击按钮后调用 Rust 后端读取文件内容并显示。

Step 1：Rust 后端定义命令

在 src-tauri/src/main.rs 中，使用 #[tauri::command] 定义 read_file 命令：

// src-tauri/src/main.rs
use tauri::Manager;
use std::fs;

// 定义命令：读取文件内容
#[tauri::command]
fn read_file(file_path: String) -> Result<String, String> {
    // 调用 Rust 标准库 fs 模块读取文件
    match fs::read_to_string(&file_path) {
        Ok(content) => Ok(content),
        Err(e) => Err(format!("文件读取失败：{}", e)),
    }
}

fn main() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![read_file]) // 注册命令
        .run(tauri::generate_context!())
        .expect("运行 Tauri 应用失败");
}

Step 2：React 前端调用命令

在 src/App.tsx 中，通过 Tauri 的 invoke 方法调用 read_file 命令：

// src/App.tsx
import { useState } from 'react';
import { invoke } from '@tauri-apps/api/core'; // Tauri 核心 API

function App() {
    const [filePath, setFilePath] = useState('');
    const [content, setContent] = useState('');
    const [error, setError] = useState('');

    // 处理文件读取按钮点击
    const handleReadFile = async () => {
        try {
            setError('');
            // 调用 Rust 后端的 read_file 命令
            const result = await invoke<string>('read_file', { filePath });
            setContent(result);
        } catch (err) {
            setError(err as string);
        }
    };

    return (
        <div className="container">
            <h1>Tauri + React 文件读取示例</h1>
            <input type="text" placeholder="输入文件路径（如 C:\\test.txt）" value={filePath} onChange={(e) => setFilePath(e.target.value)} />
            <button onClick={handleReadFile}>读取文件</button>
            {error && <p style={{ color: 'red' }}>{error}</p>}
            <pre>{content}</pre>
        </div>
    );
}
export default App;

Step 3：配置 Tauri 权限

在 src-tauri/tauri.conf.json 中，声明前端可访问的文件路径（避免安全限制）：

{
  "tauri": {
    "allowlist": {
      "all": false,
      "core": {
        "invoke": true // 允许前端调用命令
      },
      "fs": {
        "all": true, // 允许文件系统操作（生产环境需限制具体路径）
        "scope": ["$APP/*", "$DOCUMENT/*"] // 限制可访问路径
      }
    }
  }
}

场景 2：Rust 后端发送事件，React 前端监听

目标：Rust 后端模拟一个耗时任务（如文件复制），通过事件实时向前端推送进度，前端显示进度条。

Step 1：Rust 后端定义事件与命令

在 main.rs 中，使用 tauri::emit 发送事件，并定义 start_task 命令触发任务：

// src-tauri/src/main.rs
use tauri::Manager;
use std::thread;
use std::time::Duration;

// 定义事件：发送进度更新
#[tauri::command]
fn start_task(task_id: u32, on_event: tauri::Emitter) -> Result<(), String> {
    // 模拟耗时任务（如文件复制）
    for progress in 0..=100 {
        // 发送事件：事件名 "task-progress"，携带数据 { task_id, progress }
        on_event.emit("task-progress", serde_json::json!({"taskId": task_id, "progress": progress}))
            .map_err(|e| e.to_string())?;
        thread::sleep(Duration::from_millis(100)); // 模拟耗时
    }
    Ok(())
}

fn main() {
    tauri::Builder::default()
        .setup(|app| {
            // 获取应用句柄，用于发送事件
            let app_handle = app.handle();
            Ok(())
        })
        .invoke_handler(tauri::generate_handler![start_task])
        .run(tauri::generate_context!())
        .expect("运行 Tauri 应用失败");
}

Step 2：React 前端监听事件

在 App.tsx 中，通过 listen 方法监听 task-progress 事件，更新进度条：

// src/App.tsx
import { useState, useEffect, useRef } from 'react';
import { invoke } from '@tauri-apps/api/core';
import { listen } from '@tauri-apps/api/event'; // 事件监听 API

function App() {
    const [progress, setProgress] = useState(0);
    const [isTaskRunning, setIsTaskRunning] = useState(false);
    const unlistenRef = useRef<(() => void) | null>(null); // 保存取消监听函数

    // 启动任务并监听进度
    const handleStartTask = async () => {
        setIsTaskRunning(true);
        setProgress(0);
        // 监听 "task-progress" 事件
        unlistenRef.current = await listen('task-progress', (event) => {
            const data = event.payload as { taskId: number; progress: number };
            setProgress(data.progress);
            if (data.progress >= 100) {
                setIsTaskRunning(false);
                unlistenRef.current?.(); // 任务完成后取消监听
            }
        });
        // 调用 Rust 命令启动任务
        await invoke('start_task', { taskId: 1 });
    };

    // 组件卸载时取消监听
    useEffect(() => {
        return () => unlistenRef.current?.();
    }, []);

    return (
        <div className="container">
            <h1>Tauri + React 进度通知示例</h1>
            <button onClick={handleStartTask} disabled={isTaskRunning}>
                {isTaskRunning ? '任务运行中...' : '启动耗时任务'}
            </button>
            <div style={{ width: '300px', height: '20px', backgroundColor: '#eee', marginTop: '10px' }}>
                <div style={{ width: `${progress}%`, height: '100%', backgroundColor: '#007bff', transition: 'width 0.1s' }} />
            </div>
            <p>进度：{progress}%</p>
        </div>
    );
}
export default App;

四、通信原理深入

1. 命令调用（Command）的底层流程

1. 前端 invoke 调用：React 通过 invoke('read_file', { filePath }) 发送请求，Tauri 将请求序列化为 JSON 格式，通过 IPC 通道（如 Unix Domain Socket/Windows Named Pipe）发送给 Rust 后端。
2. 后端命令路由：Rust 后端的 invoke_handler 匹配命令名 read_file，调用对应的函数，传入参数（自动反序列化 JSON 为 Rust 类型）。
3. 后端处理与返回：Rust 函数执行逻辑（如读取文件），返回结果或错误，Tauri 将结果序列化为 JSON，通过 IPC 通道返回前端。
4. 前端接收结果：React 的 await invoke(...) 解析 JSON 并返回 TypeScript 类型的结果。

2. 事件监听（Event）的底层流程

1. 后端 emit 发送事件：Rust 后端通过 on_event.emit('task-progress', data) 发送事件，Tauri 将事件数据序列化并通过 IPC 推送。
2. 前端 listen 注册回调：React 前端调用 listen('task-progress', callback)，Tauri 在前端进程中注册回调函数。
3. 事件触发与回调执行：后端发送事件后，前端 IPC 接收数据并触发回调函数，更新 UI（如进度条）。

五、最佳实践与注意事项

1. 错误处理：后端命令返回 Result<T, E>，前端 invoke 需用 try-catch 捕获错误，避免崩溃。
2. 性能优化：
   • 避免在循环中频繁调用 invoke（合并请求）；
   • 事件监听需在组件卸载时取消（useEffect 清理函数），防止内存泄漏。
3. 安全性：
   • 限制前端可调用的命令（通过 tauri.conf.json 的 allowlist）；
   • 校验前端传入的参数（如文件路径合法性），避免恶意输入。

类型安全：使用 TypeScript 定义命令参数和返回值类型，并在 Rust 中用 serde 序列化（如 serde_json::json!），避免类型错误。

// 前端类型定义（types.ts）
export interface ReadFileArgs {
    filePath: string;
}
export interface ReadFileResult {
    content: string;
}

六、总结

Tauri 与 React 的集成核心是 IPC 通信：

• 命令调用（Command）：前端主动调用后端能力，适合'请求 - 响应'场景（如文件操作、API 请求）；
• 事件监听（Event）：后端主动推送通知，适合'实时更新'场景（如进度条、系统事件）。

通过这两个机制，React 前端可专注于 UI 渲染，Rust 后端处理复杂逻辑和系统交互，充分发挥两者优势。实际开发中，需结合业务场景选择合适的通信方式，并注意类型安全、错误处理和性能优化。