8.1 前端 SDK @tauri-apps/api 核心用法

Tauri 把最常用的系统能力封装进了 @tauri-apps/api 这个 JavaScript/TypeScript 包里。前端通过它，可以安全地与 Rust 后端通信、操作窗口、读写文件、弹出系统对话框等。所有 API 都经过类型推导，使用起来就像普通的现代前端库一样自然。

安装与导入

npm install @tauri-apps/api

安装后，直接从子路径导入需要的函数，减小打包体积：

import { invoke } from '@tauri-apps/api/core';
import { open } from '@tauri-apps/plugin-dialog';
import { readTextFile } from '@tauri-apps/plugin-fs';

注意：从 Tauri v2 开始，部分功能（如 dialog、fs、shell）被拆分为插件，需要单独安装并在 Cargo.toml 和前端代码中分别引入。API 的命名空间和导入路径也做了相应调整。

调用 Rust 命令（IPC 通信）

这是最核心的功能。你在 Rust 中用 #[tauri::command] 定义的函数，前端通过 invoke 调用：

Rust 侧：

#[tauri::command]
fn greet(name: &str) -> String {
    format!("Hello, {}!", name)
}

前端侧：

import { invoke } from '@tauri-apps/api/core';
const greeting = await invoke('greet', { name: 'Tauri' });
console.log(greeting); // "Hello, Tauri!"

invoke 返回 Promise，参数以对象形式传递，Tauri 会自动完成 JSON 序列化/反序列化。如果 Rust 命令返回 Result，错误会被转为前端可捕获的异常。

窗口操作

管理当前窗口或创建新窗口：

import { getCurrentWindow } from '@tauri-apps/api/window';

const win = getCurrentWindow();
win.setTitle('新标题');
win.setSize(new LogicalSize(800, 600));
win.setAlwaysOnTop(true);

// 监听窗口事件
win.onCloseRequested((e) => {
  // 可以阻止关闭
});

文件系统访问

需要先安装插件 @tauri-apps/plugin-fs，并在 Rust 侧启用对应权限（tauri.conf.json 中配置）。然后用简洁的 API 读写文件：

import { readTextFile, writeTextFile } from '@tauri-apps/plugin-fs';

const content = await readTextFile('/path/to/file.txt');
await writeTextFile('/path/to/output.txt', 'Hello Tauri');

所有路径都基于应用的安全作用域，默认无法访问系统任意位置，需要在配置中显式声明。

对话框

安装 @tauri-apps/plugin-dialog 后，可以直接弹出原生文件选择、消息确认等：

import { open, save, message, ask } from '@tauri-apps/plugin-dialog';

const filePath = await open({ filters: [{ name: 'Markdown', extensions: ['md'] }] });
const yes = await ask('确定要保存吗？', { title: '提示' });

对话框是系统原生的，风格与操作系统完全一致。

事件系统

前后端可以互相发送自定义事件，用于解耦状态通知：

前端监听来自后端的事件：

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

const unlisten = await listen('backend-ready', (event) => {
  console.log('后端准备好了', event.payload);
});

// 取消监听
unlisten();

前端向后端发事件：

import { emit } from '@tauri-apps/api/event';
await emit('frontend-log', { message: '用户点击了按钮' });

Rust 侧使用 AppHandle 的 emit 或 emit_to 方法镜像处理。

实用技巧

类型安全：如果你的团队使用 TypeScript，建议将 Rust 命令的类型定义导出为 .ts 文件，供前端直接引用。可以用 tauri-specta 等工具自动生成类型。
错误处理：invoke 抛出的异常是 JavaScript 原生错误，你可以用 try/catch 包裹，或封装一个统一错误处理函数。
权限控制：Tauri v2 的权限系统非常精细，每个 API 调用都需要在 capabilities 中声明，初次配置感到繁琐时，可以利用 CLI 的 tauri permission add 命令交互式添加。

掌握了这些基础，你就已经可以使用 Tauri 构建一个功能完备的桌面应用了——前端负责 UI，API 负责与系统交互，代码简洁可靠。