事件系统

相关源文件

• .editorconfig
• crates/tauri-cli/src/helpers/flock.rs
• crates/tauri-cli/templates/plugin/__example-api/tauri-app/package.json
• crates/tauri-schema-worker/package.json
• crates/tauri/src/app.rs
• crates/tauri/src/event/event_name.rs
• crates/tauri/src/event/listener.rs
• crates/tauri/src/event/mod.rs
• crates/tauri/src/event/plugin.rs
• crates/tauri/src/ipc/protocol.rs
• crates/tauri/src/lib.rs
• crates/tauri/src/manager/mod.rs
• crates/tauri/src/manager/webview.rs
• crates/tauri/src/manager/window.rs
• crates/tauri/src/protocol/asset.rs
• crates/tauri/src/protocol/isolation.rs
• crates/tauri/src/protocol/tauri.rs
• crates/tauri/src/state.rs
• examples/api/package.json
• examples/api/src-tauri/tauri.conf.json
• examples/api/src/main.js
• package.json
• packages/api/CHANGELOG.md
• packages/api/package.json
• pnpm-lock.yaml

Tauri 事件系统提供了一种双向通信机制，用于 Tauri 应用程序的各个部分之间进行通信。它实现了 JavaScript 前端代码与 Rust 后端代码之间、不同 Webview 之间以及应用程序各种组件之间的通信。本文档将解释事件系统是如何构建的，事件如何在应用程序中流动，以及如何有效使用事件 API。

有关处理 JavaScript 和 Rust 之间直接函数调用的命令系统的信息，请参阅命令系统。有关在 JavaScript 和 Rust 之间流式传输数据的信息，请参阅通道 API。

核心概念

事件系统围绕几个关键抽象构建而成

EventName

一个 EventName 是事件的字符串标识符。事件名称只能包含字母数字字符、连字符（-）、正斜杠（/）、冒号（:）和下划线（_）。

来源： crates/tauri/src/event/event_name.rs1-79

EventTarget

EventTarget 枚举定义了事件被发送到或监听的源。这允许有针对性地传递事件。

来源： crates/tauri/src/event/mod.rs19-102

EventId

注册每个事件监听器时都会为其分配一个唯一的 EventId（一个 u32 值）。此 ID 用于取消监听或管理事件监听器。

事件结构

一个 Event 代表通过系统传递的消息，包含事件名称、载荷数据和目标信息。

来源： crates/tauri/src/event/mod.rs104-207

事件通信流程

事件遵循发布-订阅模式在系统中流动。

来源： crates/tauri/src/event/mod.rs104-207 crates/tauri/src/ipc/protocol.rs32-181 crates/tauri/src/event/listener.rs1-100

事件监听器注册表

事件系统维护着一个所有监听器的注册表，以便正确地路由事件。

来源： crates/tauri/src/event/listener.rs17-57

API 使用

JavaScript 事件 API

在 JavaScript 中，事件系统可以通过 @tauri-apps/api 包访问。

JavaScript API 通过事件插件在 Rust 中实现。

来源： crates/tauri/src/event/plugin.rs39-85

Rust 事件 API

在 Rust 代码中，事件系统可以通过 Manager trait 来使用。

Manager trait 提供了事件处理的方法。

来源： crates/tauri/src/lib.rs531-571 crates/tauri/src/app.rs346-443

系统事件

Tauri 定义了几个内置的系统事件，它们会自动触发。

事件	描述	目标
tauri://resize	窗口已调整大小	窗口
tauri://move	窗口已移动	窗口
tauri://close-requested	请求关闭窗口	窗口
tauri://destroyed	窗口已被销毁	窗口
tauri://focus	窗口获得焦点	窗口
tauri://blur	窗口失去焦点	窗口
tauri://scale-change	比例因子已更改	窗口
tauri://theme-changed	系统主题已更改	窗口
tauri://drag-enter	拖动进入窗口	窗口
tauri://drag-over	拖动到窗口之上	窗口
tauri://drag-drop	项目已拖放到窗口	窗口
tauri://drag-leave	拖动离开窗口	窗口

来源： crates/tauri/src/manager/window.rs26-39

事件系统架构

事件系统与 Tauri 的其他几个组件集成。

来源： crates/tauri/src/event/mod.rs1-430 crates/tauri/src/ipc/protocol.rs1-184 crates/tauri/src/manager/mod.rs1-560

组件间的事件通信

来源： crates/tauri/src/event/listener.rs126-266 crates/tauri/src/manager/mod.rs517-555

IPC 集成

事件系统与 Tauri 的 IPC（进程间通信）系统紧密集成。

与事件相关的 IPC 消息由协议处理程序处理，该处理程序将其路由到适当的事件系统函数。

来源： crates/tauri/src/ipc/protocol.rs32-250 crates/tauri/src/event/plugin.rs39-85

性能考量

事件系统旨在高效运行，但也需要注意一些事项：

1. 事件过滤：事件在传递之前会按目标进行过滤，从而最大限度地减少不必要的处理。
2. 内存管理：在 JavaScript 中使用事件监听器时，请务必在不再需要时取消监听，以防止内存泄漏。
3. 载荷大小：大型事件载荷会影响性能，特别是当发送到多个目标时。

事件监听器存储在内存中，直到被显式移除或应用程序终止。

来源： crates/tauri/src/event/listener.rs126-266

最佳实践

1. 使用特定目标：如果可能，请将事件发送到特定目标，而不是广播到所有窗口。
2. 结构化事件名称：使用一致的事件命名模式，例如 namespace:event-name。
3. 清理监听器：始终在组件卸载或不再需要事件时存储并调用取消监听函数。
4. 验证载荷：确保事件载荷具有一致的结构，以便于处理。
5. 错误处理：为事件监听器实现适当的错误处理，以防止应用程序崩溃。

事件系统是构建使用 Tauri 的响应式应用程序的强大工具，它实现了 UI 和业务逻辑之间的清晰分离，同时保持高效的通信。