555 lines
14 KiB
Markdown
555 lines
14 KiB
Markdown
# Tauri Event Demo
|
||
|
||
这份笔记对应当前工程里的“串口后台任务 -> Tauri event -> 前端折线图”这条链路。
|
||
|
||
目标是把一类很常见的需求拆清楚：
|
||
|
||
- 前端点一次按钮，调用 Rust command
|
||
- Rust 启动一个长期运行的后台任务
|
||
- 后台任务持续读取数据
|
||
- 每拿到一帧数据，就通过 Tauri event 推给前端
|
||
- 前端监听 event，直接刷新图表
|
||
|
||
## 0. 2026-03-25 需求更新（WebGL 点阵改用真实数据）
|
||
|
||
这次改动的目标是：
|
||
|
||
- WebGL dot matrix 不再使用虚拟 demo 数据
|
||
- 直接消费串口解析后的真实通道值
|
||
- 默认矩阵大小改为 `row=12, col=7`
|
||
|
||
### 是否需要新建 event？
|
||
|
||
不需要。继续使用现有 `hud_stream` 即可，只扩展 payload 字段：
|
||
|
||
- 原来：`{ ts, panels, summary }`
|
||
- 现在：`{ ts, panels, summary, pressureMatrix }`
|
||
|
||
这样做的好处是：
|
||
|
||
- 前后端事件通道不变，兼容原有监听逻辑
|
||
- 折线图和点阵图保持同一时间基准
|
||
- 只需在 `HudPacket` 上增量扩展，不引入额外生命周期管理
|
||
|
||
### 本次代码落地点
|
||
|
||
- 后端 `HudPacket` 新增 `pressure_matrix`（序列化为 `pressureMatrix`）：
|
||
- `src-tauri/src/serial_core/model.rs`
|
||
- 串口读循环在拿到解析值后写入 matrix 状态：
|
||
- `src-tauri/src/serial_core/serial.rs`
|
||
- 前端类型 `HudPacket` 新增 `pressureMatrix: number[] | null`：
|
||
- `src/lib/types/hud.ts`
|
||
- 页面把 `pressureMatrix` 透传到 `CenterStage -> PressureMatrixViewer`：
|
||
- `src/routes/+page.svelte`
|
||
- `PressureMatrixViewer` 去除 demo 生成逻辑；无真实数据时显示全 0：
|
||
- `src/lib/components/PressureMatrixViewer.svelte`
|
||
- 默认矩阵改为 `12 x 7`（含 reset 默认值）：
|
||
- `src/routes/+page.svelte`
|
||
- `src/lib/components/CenterStage.svelte`
|
||
- `src/lib/components/ConfigPanel.svelte`
|
||
|
||
## 1. 什么时候用 command，什么时候用 event
|
||
|
||
先记一个最实用的判断：
|
||
|
||
- `command` 适合“请求一次，返回一次”
|
||
- `event` 适合“后台持续推送”
|
||
|
||
在这个项目里：
|
||
|
||
- `serial_enum` 是 command，因为它是“一次查询串口列表”
|
||
- `serial_connect` 是 command，因为它是“一次启动连接”
|
||
- `serial_disconnect` 是 command，因为它是“一次停止连接”
|
||
- `hud_stream` 是 event，因为图表数据会持续不断地到来
|
||
|
||
如果你用 command 去不停轮询图表数据，也能做，但会有这些问题：
|
||
|
||
- 前后端耦合更重
|
||
- 轮询频率不好拿捏
|
||
- 串口数据到了也不能立刻推到前端
|
||
- 后面做 TCP、日志流、状态流时会越来越别扭
|
||
|
||
所以像串口采样、TCP telemetry、日志输出、设备状态广播，这类都更适合 event。
|
||
|
||
## 2. 当前工程里各文件的职责
|
||
|
||
### Rust
|
||
|
||
- `src-tauri/src/lib.rs`
|
||
- 注册 command
|
||
- 注册全局状态 `SerialConnectionState`
|
||
|
||
- `src-tauri/src/commands/serial.rs`
|
||
- 给前端暴露 command
|
||
- 管理串口后台任务的生命周期
|
||
- 这里尽量保持“薄”
|
||
|
||
- `src-tauri/src/serial_core/serial.rs`
|
||
- 真正的串口读循环
|
||
- 解码 frame
|
||
- 发出 `hud_stream`
|
||
|
||
- `src-tauri/src/serial_core/model.rs`
|
||
- 定义发给前端的结构
|
||
- 把原始 frame 转成前端折线图直接能吃的 `HudPacket`
|
||
|
||
- `src-tauri/src/serial_core/codecs/test.rs`
|
||
- 协议解码
|
||
|
||
### Frontend
|
||
|
||
- `src/routes/+page.svelte`
|
||
- 调用 `serial_connect` / `serial_disconnect`
|
||
- 监听 `hud_stream`
|
||
- 拿到 `HudPacket` 后刷新页面状态
|
||
|
||
- `src/lib/types/hud.ts`
|
||
- 前端使用的 HUD 类型定义
|
||
|
||
## 3. 完整数据流
|
||
|
||
当前链路可以按下面理解：
|
||
|
||
### 第一步：前端发起连接
|
||
|
||
前端点击按钮后：
|
||
|
||
```ts
|
||
await invoke("serial_connect", { port })
|
||
```
|
||
|
||
这一步只负责“启动”，不要指望它直接把流式数据返回给前端。
|
||
|
||
### 第二步：Rust command 启动后台任务
|
||
|
||
`serial_connect` 做的事应该很少：
|
||
|
||
1. 校验参数
|
||
2. 打开串口
|
||
3. 创建取消信号
|
||
4. `spawn` 后台任务
|
||
5. 把任务句柄保存到全局状态
|
||
6. 立刻返回前端
|
||
|
||
也就是说，command 只是“开机按钮”。
|
||
|
||
### 第三步：后台任务持续读串口
|
||
|
||
后台任务跑在 `serial_core/serial.rs` 里：
|
||
|
||
```rust
|
||
loop {
|
||
tokio::select! {
|
||
_ = cancel.cancelled() => break,
|
||
read_result = port.read(&mut buffer) => {
|
||
let n = read_result?;
|
||
let frames = codec.decode(&buffer[..n])?;
|
||
...
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
这里有两个关键点：
|
||
|
||
- 必须只解码 `&buffer[..n]`
|
||
- 长循环不要放在 command 里 `await` 到结束
|
||
|
||
第一点是为了避免把缓冲区后面没读到的 `0` 一起喂给解码器。
|
||
第二点是为了避免前端永远等不到 command 返回。
|
||
|
||
### 第四步：frame 转成前端友好的 packet
|
||
|
||
后台拿到 frame 后，不要把原始协议直接丢给前端，先整理成业务结构：
|
||
|
||
```rust
|
||
let packet = chart_state.apply_frame(&frame);
|
||
```
|
||
|
||
这里输出的是 `HudPacket`，它的结构是前端图表直接能渲染的形状。
|
||
|
||
### 第五步：Rust 发 event
|
||
|
||
```rust
|
||
app.emit("hud_stream", packet)?;
|
||
```
|
||
|
||
这一步就是把数据从 Rust 主动推给前端。
|
||
|
||
### 第六步：前端监听 event
|
||
|
||
前端在页面挂载时注册监听：
|
||
|
||
```ts
|
||
const unlisten = await listen<HudPacket>("hud_stream", (event) => {
|
||
applyPacket(event.payload);
|
||
});
|
||
```
|
||
|
||
拿到 payload 后直接更新 `signalPanels`，图表就会刷新。
|
||
|
||
## 4. 为什么要保存后台任务句柄
|
||
|
||
因为连接不是瞬时动作，而是一个持续运行的任务。
|
||
|
||
如果你只做：
|
||
|
||
```rust
|
||
tauri::async_runtime::spawn(async move {
|
||
...
|
||
});
|
||
```
|
||
|
||
但不保存返回的 `JoinHandle`，那你后面其实不知道该停哪个任务。
|
||
|
||
所以当前项目里 `SerialConnectionState` 的职责是：
|
||
|
||
- 保存当前连接的端口
|
||
- 保存取消信号 `CancellationToken`
|
||
- 保存后台任务句柄 `JoinHandle`
|
||
|
||
断开时：
|
||
|
||
1. 从 state 里把当前 session 取出来
|
||
2. `cancel.cancel()`
|
||
3. 等任务退出
|
||
4. 清空 session
|
||
|
||
这就是“连接生命周期管理”。
|
||
|
||
## 5. 为什么我这里用 CancellationToken，而不是只 abort
|
||
|
||
`abort()` 可以硬停，但更像“直接掐掉线程”。
|
||
|
||
`CancellationToken` 更适合做长期任务，因为它允许你在循环里优雅退出：
|
||
|
||
```rust
|
||
tokio::select! {
|
||
_ = cancel.cancelled() => break,
|
||
...
|
||
}
|
||
```
|
||
|
||
这样后面如果你需要：
|
||
|
||
- 退出前写日志
|
||
- 退出前关闭资源
|
||
- 退出前发送状态事件
|
||
|
||
都更自然。
|
||
|
||
当前代码里依然保留了 `JoinHandle`，因为它可以让你等待任务真正结束。
|
||
|
||
## 6. 这个 demo 里 model 层在做什么
|
||
|
||
`src-tauri/src/serial_core/model.rs` 里现在做了两件事：
|
||
|
||
1. 定义前端消费的数据结构
|
||
2. 提供 `HudChartState`
|
||
|
||
`HudChartState` 的作用是把“一帧 frame”逐步积累成“可滚动折线图数据”。
|
||
|
||
你可以把它理解成一个很轻量的 view-model：
|
||
|
||
- 输入：`TestFrame`
|
||
- 内部：维护每条折线的点数组
|
||
- 输出：`HudPacket`
|
||
|
||
好处是前端不用知道：
|
||
|
||
- CRC
|
||
- 包头包尾
|
||
- payload 字节意义
|
||
- 缓冲和滑动窗口怎么维护
|
||
|
||
前端只知道：我收到了一份新的图表数据。
|
||
|
||
## 7. 前端这里做了什么
|
||
|
||
前端现在分成两层：
|
||
|
||
### 控制层
|
||
|
||
通过 `invoke` 调 Rust command：
|
||
|
||
- `serial_enum`
|
||
- `serial_connect`
|
||
- `serial_disconnect`
|
||
|
||
### 数据层
|
||
|
||
通过 `listen("hud_stream")` 收 Rust 推送的数据。
|
||
|
||
也就是说：
|
||
|
||
- 控制动作走 command
|
||
- 连续数据走 event
|
||
|
||
这就是后面最好复用的模式。
|
||
|
||
## 8. 为什么页面里还保留了 mock feed
|
||
|
||
因为浏览器直接预览 UI 的时候，没有 Tauri runtime，也没有串口。
|
||
|
||
所以当前页面里做了两条分支：
|
||
|
||
- 在 Tauri 环境里：监听真实 `hud_stream`
|
||
- 在普通浏览器里：启动本地 mock feed
|
||
|
||
这样你开发样式时不用每次都连设备，效率会高很多。
|
||
|
||
## 9. 后面照着扩展时怎么套
|
||
|
||
如果你接下来做 TCP、日志流、设备状态流，基本可以照这个模板：
|
||
|
||
### TCP telemetry
|
||
|
||
- `tcp_connect` command
|
||
- `tcp_disconnect` command
|
||
- `tcp_stream` event
|
||
|
||
### 设备状态
|
||
|
||
- `device_get_status` command
|
||
- `device_status` event
|
||
|
||
### 日志输出
|
||
|
||
- `log_stream` event
|
||
|
||
只要记住一句话：
|
||
|
||
“一次性动作走 command，持续推送走 event。”
|
||
|
||
## 10. 一个最小可复用模板
|
||
|
||
### Rust command
|
||
|
||
```rust
|
||
#[tauri::command]
|
||
pub async fn start_task(app: AppHandle, state: State<'_, TaskState>) -> Result<(), TaskError> {
|
||
let cancel = CancellationToken::new();
|
||
let task_cancel = cancel.clone();
|
||
let task_app = app.clone();
|
||
|
||
let task = tauri::async_runtime::spawn(async move {
|
||
let _ = run_task(task_app, task_cancel).await;
|
||
});
|
||
|
||
*state.task.lock().unwrap() = Some(TaskSession { cancel, task });
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
### Rust 后台任务
|
||
|
||
```rust
|
||
pub async fn run_task(app: AppHandle, cancel: CancellationToken) -> anyhow::Result<()> {
|
||
loop {
|
||
tokio::select! {
|
||
_ = cancel.cancelled() => break,
|
||
data = next_data() => {
|
||
let payload = build_payload(data?);
|
||
app.emit("some_stream", payload)?;
|
||
}
|
||
}
|
||
}
|
||
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
### 前端监听
|
||
|
||
```ts
|
||
const unlisten = await listen<Payload>("some_stream", (event) => {
|
||
applyPayload(event.payload);
|
||
});
|
||
```
|
||
|
||
## 11. 这套方式最容易踩的坑
|
||
|
||
### 1. 在同步 command 里调用 async-only API
|
||
|
||
像 `open_native_async()` 这种需要 runtime 的 API，command 本身就应该写成 `async fn`。
|
||
|
||
### 2. 把长期循环直接写在 command 里
|
||
|
||
这样前端 `invoke` 会一直挂着，按钮像卡死一样。
|
||
|
||
### 3. 解码时传整个 buffer，而不是 `&buffer[..n]`
|
||
|
||
这会把未读取区域的垃圾值一并喂给解码器。
|
||
|
||
### 4. 没有保存任务句柄
|
||
|
||
这样断开时你并不知道要停哪个任务。
|
||
|
||
### 5. 原始协议直接发前端
|
||
|
||
短期快，长期维护会很痛苦。最好让 Rust 先转换成业务数据。
|
||
|
||
## 12. 你后面可以继续优化的方向
|
||
|
||
- 增加 `status_stream`，当串口异常退出时主动通知前端
|
||
- 把 `SerialConnectionState` 扩成 `HashMap<String, SerialSession>`，支持多串口
|
||
- 把 `HudChartState` 抽成更明确的 telemetry service
|
||
- 给不同协议定义不同 packet，而不是全部复用一个事件名
|
||
|
||
## 13. 现在这版如何支持动态 panel
|
||
|
||
这次我已经把 demo 从“固定四个 panel”改成了“按数据源 id 动态创建 panel”。
|
||
|
||
当前后端的行为是：
|
||
|
||
- 串口保持连接
|
||
- 收到某个 source id 的数据时，如果这个 id 还没有 panel，就新建
|
||
- 后面这个 id 持续有数据，就持续往它自己的折线里追加点
|
||
- 如果某个 id 超过一段时间没有新数据，就自动移除
|
||
- 移除后前端会走离场动画
|
||
|
||
### 当前 demo 约定的数据格式
|
||
|
||
现在 `model.rs` 里的 demo 约定是一帧 payload 可以写成多个 4 字节分组：
|
||
|
||
```text
|
||
[source_id, value1, value2, value3, source_id, value1, value2, value3, ...]
|
||
```
|
||
|
||
例如：
|
||
|
||
```text
|
||
[0x41, 180, 120, 60, 0x42, 170, 80, 30]
|
||
```
|
||
|
||
这里会被解释成：
|
||
|
||
- `0x41` -> `A`
|
||
- `0x42` -> `B`
|
||
|
||
也就是说这一帧会同时更新两个 panel：
|
||
|
||
- A panel
|
||
- B panel
|
||
|
||
如果后续几帧只有 B 和 C，没有 A，那 A 超时之后就会自动被移除。
|
||
|
||
### source id 是怎么来的
|
||
|
||
当前 demo 里：
|
||
|
||
- 如果字节是字母或数字，比如 `A`、`B`、`3`
|
||
- 就直接把它当 source id
|
||
|
||
否则会变成：
|
||
|
||
- `CH01`
|
||
- `CH0A`
|
||
- `CHFF`
|
||
|
||
这种形式。
|
||
|
||
### 超时移除在哪里控制
|
||
|
||
在 `src-tauri/src/serial_core/model.rs` 里有一个常量：
|
||
|
||
```rust
|
||
const PANEL_STALE_AFTER: Duration = Duration::from_millis(2400);
|
||
```
|
||
|
||
意思是某个 panel 2.4 秒没收到新数据，就认为它已经“消失”，会从当前 packet 里移除。
|
||
|
||
### 如果你的真实协议不是这个格式怎么办
|
||
|
||
那就只改 `expand_frame_updates(frame)` 这一层。
|
||
|
||
你真正要做的是把自己的协议，翻译成：
|
||
|
||
- source id
|
||
- 这个 source 对应的 3 个数值
|
||
|
||
例如如果你的协议里一帧只表示一个源：
|
||
|
||
```rust
|
||
fn expand_frame_updates(frame: &TestFrame) -> Vec<HudPanelUpdate> {
|
||
vec![HudPanelUpdate {
|
||
source_id: "A".to_string(),
|
||
values: [12.3, 45.6, 78.9],
|
||
}]
|
||
}
|
||
```
|
||
|
||
如果一帧里同时包含多个源：
|
||
|
||
```rust
|
||
fn expand_frame_updates(frame: &TestFrame) -> Vec<HudPanelUpdate> {
|
||
vec![
|
||
HudPanelUpdate {
|
||
source_id: "A".to_string(),
|
||
values: [12.3, 45.6, 78.9],
|
||
},
|
||
HudPanelUpdate {
|
||
source_id: "C".to_string(),
|
||
values: [33.1, 29.8, 81.4],
|
||
},
|
||
]
|
||
}
|
||
```
|
||
|
||
后面的动态创建、更新、超时移除，`HudChartState` 都会自动帮你处理掉。
|
||
|
||
## 14. TODO 提示词
|
||
|
||
如果你后面把 `handle` / 协议解析逻辑写完了，想让我把 demo 逻辑替换成真实业务逻辑，直接把下面这段话发给我就行：
|
||
|
||
```md
|
||
我已经把串口 frame 的业务含义梳理清楚了，请你把当前 tauri-demo 里的 demo 动态 panel 逻辑改成真实协议版本。
|
||
|
||
已知信息：
|
||
- frame 类型：`TestFrame`
|
||
- 数据来源文件：`src-tauri/src/serial_core/...`
|
||
- 当前 demo 映射入口：`src-tauri/src/serial_core/model.rs` 里的 `expand_frame_updates`
|
||
- 如果需要，也可以调整 `handler.on_frame(...)` 的职责
|
||
|
||
真实协议说明：
|
||
- source_id 怎么取：
|
||
- 一帧里有几路数据：
|
||
- 每一路数据对应哪些字段：
|
||
- 数值是 u8 / u16 / i16 / float：
|
||
- 字节序是大端还是小端：
|
||
- 缩放系数是多少：
|
||
- 哪些情况下表示“该路数据消失”：
|
||
- panel 标题 / 图例文案要如何显示：
|
||
|
||
请你帮我做这些事：
|
||
1. 去掉当前 demo 的 4 字节分组映射逻辑
|
||
2. 改成按真实协议生成动态 panel
|
||
3. 保留“有数据就创建，超时没数据就移除”的行为
|
||
4. 如有必要，重构 `model.rs` / `handler` / `serial.rs` 的职责边界
|
||
5. 更新 `tauri-event.md`，说明新的真实数据流
|
||
```
|
||
|
||
如果你到时候还没完全确定协议，也可以先用这个简化版提示词：
|
||
|
||
```md
|
||
我已经知道 payload 里哪些字节对应哪几个通道了，请你帮我把 `src-tauri/src/serial_core/model.rs` 里的 demo 映射改成真实映射，并告诉我还缺哪些协议信息。
|
||
```
|
||
|
||
### 到时候我最需要你提供的最小信息
|
||
|
||
- source id 怎么区分不同数据源
|
||
- 每个 source 对应几条曲线
|
||
- payload 各字段的字节位置
|
||
- 数值类型和缩放系数
|
||
- 多久没数据算“消失”
|
||
|
||
---
|
||
|
||
如果你后面要继续照这个模式扩展，最推荐的顺序是：
|
||
|
||
1. 先定义前端真正需要的 payload 结构
|
||
2. 再写 Rust 的 model/service 层
|
||
3. 最后只让 command 负责启动和停止
|
||
|
||
这样结构通常都会比较干净。
|