前言

> **"让 UI 回归声明，让逻辑回归纯粹，让 Rust 桌面开发拥抱每一位前端工程师。"**

为什么要写这本书

Rust 生态在过去数年完成了从"系统编程语言"到"全栈语言"的跨越。在桌面 UI 领域，Zed 编辑器团队开源的 GPUI 框架以 GPU 加速、混合即时/保留模式的渲染能力，证明了 Rust 完全可以支撑工业级桌面应用。然而，GPUI 原生的链式调用 API 把 UI 结构、样式、事件、业务逻辑全部塞进同一个 Rust 文件，带来了三个长期痛点：

1. **UI 与逻辑深度耦合**——结构、样式、事件、状态交织，难以审查与维护； 2. **设计师无法参与**——非工程师无法阅读 Rust 链式调用； 3. **缺乏标准化**——每个项目各自为政，无法沉淀设计资产。

RML（Rust Markup Language）正是为解决这三件事而生。它把 WPF XAML 的 MVVM 设计精髓与 HTML 的语法亲和力结合起来，通过 `.rml`（独立标记文件）+ `.rml.rs`（纯 Rust 业务逻辑）的文件级分离，把 GPUI 的能力释放给更广泛的开发者群体。

本书的使命，是帮助每一位读者从零开始，**深进浅出**地掌握 RML 框架的产品形态，理解其设计哲学，最终成为能够独立设计复杂桌面应用的 RML 开发高手。

RML 的愿景

RML 不是一个简单的模板引擎，而是一套面向 Rust 桌面应用的**完整 UI 工程体系**。它的愿景可以浓缩为三层：

第一层：让 UI 回归声明

UI 的本质是**数据的外观**，而非逻辑的载体。RML 坚持把界面结构、布局、绑定、事件全部声明在 `.rml` 文件中，让"界面长什么样"与"界面怎么运作"在文件层面彻底分离。这一层借鉴了 HTML 的语法亲和力——任何写过网页的人，都能在五分钟内读懂一份 `.rml` 文件；同时保留了 WPF XAML 的 MVVM 精髓——双向绑定、计算属性、值转换器、命令系统一应俱全。

第二层：让逻辑回归纯粹

业务逻辑应当是**可测试、可复用、无 UI 依赖**的纯 Rust 代码。RML 的 `.rml.rs` 文件只承载 ViewModel：状态字段、命令方法、生命周期回调、计算属性。它不写任何渲染代码——`Render` trait 的实现由编译器在 `build.rs` 阶段自动生成。这意味着你可以像写后端服务一样写桌面 UI 的逻辑：单元测试不依赖窗口、状态变更可追踪、命令调用可组合。

第三层：让 Rust 桌面开发拥抱所有人

Rust 的学习曲线不应成为桌面 UI 开发的门槛。RML 的目标是**让前端工程师用 HTML 心智模型进入 Rust 桌面开发，让设计师直接编辑可运行的设计稿，让团队负责人建立可沉淀的 UI 资产体系**。当 `.rml` 文件成为设计师与工程师的共同语言，当组件库可以像 npm 包一样分发复用，当热重载让 UI 迭代像 Web 一样敏捷，Rust 桌面开发就真正拥抱了更广泛的开发者群体。

> **一句话愿景**：让 Rust 写桌面应用，像写 Web 一样自然，像写后端一样严谨。

本书写给谁

本书面向所有希望用 Rust 构建桌面 UI 的开发者，无需 GPUI 前置经验。不同背景的读者可以从不同章节切入：

Web 前端工程师

你已经熟悉 HTML、CSS、JavaScript，或许还用过 Vue 或 React。RML 对你而言几乎没有语法学习成本——`.rml` 就是 HTML 的超集，`{ }` 插值对应 Vue 的 mustache，`value={field}` 自动双向绑定对应 `v-model`，`if`/`each` 指令对应 `v-if`/`v-for`。你需要补的是 **Rust 所有权与生命周期**的基础概念，以及 GPUI 的 Entity 模型。

- **推荐路径**：第 1 章 → 第 2 章 → 第 3 章 → 第 11 章迁移指南 - **重点章节**：第 4 章（理解 ViewModel 与 Rust 命令系统）、第 9 章（架构最佳实践）

Rust 后端工程师

你已经能熟练写 Rust，但桌面 UI 是新领域。GPUI 原生的链式调用 API 让你把 UI 结构、样式、事件全塞进一个 `render` 方法，难以维护。RML 让你用 MVVM 的方式组织 UI：ViewModel 就是你熟悉的 struct，命令就是方法，状态变更就是 `cx.notify()`。你会感到"原来桌面 UI 也能写得像后端一样清爽"。

- **推荐路径**：第 1 章 → 第 4 章 → 第 3 章 → 第 9 章 - **重点章节**：第 2 章（理解 `.rml` 标记语法）、第 6 章（组件封装与复用）

UI/UX 设计师

你不写 Rust，但你需要产出**可运行的设计稿**，而不是停留在 Figma 静态图。RML 的 `.rml` 文件就是你的画布——HTML 语法你看得懂，样式系统借鉴 CSS，布局用 Flexbox。你可以直接调整 `.rml` 文件，配合热重载实时看到效果，与工程师并行工作。

- **推荐路径**：第 1 章 → 第 2 章 → 第 7 章 - **重点章节**：第 7 章（样式与主题）、第 6 章（理解组件边界）

团队技术负责人

你需要为团队建立**标准化的 UI 开发流程**：设计资产可沉淀、组件可复用、代码可审查、新人可上手。RML 的文件级分离让 PR 审查更清晰——`.rml` 的改动看结构，`.rml.rs` 的改动看逻辑；组件库机制让 UI 资产像 crate 一样版本化管理；职责划分让架构决策有据可依。

- **推荐路径**：第 1 章 → 第 9 章 → 第 10 章 → 第 11 章 - **重点章节**：第 9 章（职责边界与架构原则）、第 10 章（构建流程与工具链）

跨平台迁移者

你从 WPF / Vue / React / SwiftUI 迁移而来，带着既有心智模型找 Rust 桌面的对应物。RML 的设计目标就是**让你用熟悉的概念操作陌生的框架**：WPF 的 `Binding`/`Command`/`StaticResource` 在 RML 中都有对应；Vue 的 `v-model`/`v-if`/`v-for` 直接映射到 RML 指令；React 的组件 props/slots 对应 RML 的组件属性与插槽。

- **推荐路径**：第 1 章 → 第 11 章迁移指南 → 按需深入各章 - **重点章节**：第 11 章（包含完整的迁移对照表与避坑清单）

本书的结构

本书遵循**渐进式披露**原则编排：从理念到语法，从语法到绑定，从绑定到组件，从组件到架构，最终落到实战。每一章都建立在前一章之上，但每一章也独立成篇，方便查阅。

- **第一部分 · 起步**（第 1 章）：建立对 RML 的整体认知，跑通第一个应用。 - **第二部分 · 标记与绑定**（第 2 ~ 3 章）：掌握 `.rml` 的全部语法与数据绑定机制。 - **第三部分 · 逻辑与事件**（第 4 ~ 5 章）：掌握 `.rml.rs` 的宏系统与事件流。 - **第四部分 · 组件与样式**（第 6 ~ 7 章）：掌握自定义组件封装与样式系统。 - **第五部分 · 生命周期与架构**（第 8 ~ 9 章）：掌握生命周期管理、职责划分与架构原则。 - **第六部分 · 高级与实战**（第 10 ~ 11 章）：掌握性能优化、调试、热重载与实战案例。

阅读约定

- **代码块**：`.rml` 文件以 HTML 语法高亮显示，`.rml.rs` 文件以 Rust 语法高亮显示，生成代码以注释标注。 - **图标约定**： - 💡 **提示**：补充说明或最佳实践 - ⚠️ **注意**：常见陷阱与避坑指南 - 🔧 **进阶**：深入实现细节 - 📋 **清单**：可对照执行的检查项 - **版本说明**：本书内容基于 RML 设计文档 v1.0 编写，对应 GPUI 锁定的 git rev。

致谢

RML 站在巨人的肩膀上：感谢 Zed 团队开源 GPUI，感谢 WPF 团队确立 MVVM 范式，感谢 Web 社区把 HTML 推广为最广泛的标记语言。本书的每一行示例，都源于对这些先行者的敬意。

愿你在 RML 的世界里，写出优雅、可维护、令人愉悦的桌面应用。

—— RML 文档组