gpui

GPUI 最佳实践

构建 GPUI 桌面应用的综合指南。GPUI 是为 Zed 编辑器提供支持的 UI 框架。包含 8 个类别、40 多条规则，并按影响程度排序。

适用场景

遇到以下情况时，请参考这些指南：

• 编写新的 GPUI 视图或组件
• 使用 Entity 实现状态管理
• 处理事件和键盘快捷键
• 使用异步任务和后台工作
• 构建表单、列表或对话框
• 使用类似 Tailwind 的 API 为组件设置样式
• 测试 GPUI 应用

按优先级划分的规则类别

优先级	类别	影响程度	前缀
1	核心概念	CRITICAL	core-
2	渲染	CRITICAL	render-
3	状态管理	HIGH	state-
4	事件处理	HIGH	event-
5	异步与并发	MEDIUM-HIGH	async-
6	样式	MEDIUM	style-
7	组件	MEDIUM	comp-
8	反模式	CRITICAL	anti-

快速参考

1. 核心概念（CRITICAL）

• core-ownership-model - 理解 GPUI 的单一所有权模型
• core-entity-operations - 正确使用 read/update/observe/subscribe
• core-weak-entity - 使用 WeakEntity 打破循环引用
• core-context-types - 了解何时使用 App、Context、AsyncApp

2. 渲染（CRITICAL）

• render-render-vs-renderonce - 有状态视图选择 Render，组件选择 RenderOnce
• render-element-composition - 使用 div() 和方法链构建元素树
• render-conditional - 使用 .when() 和 .when_some() 实现条件样式
• render-shared-string - 使用 SharedString 避免复制字符串
• render-builder-pattern - 使用构建器模式设计组件

3. 状态管理（HIGH）

• state-notify - 状态更改后务必调用 cx.notify()
• state-observe - 使用 cx.observe() 响应 Entity 更改
• state-subscribe - 使用 cx.subscribe() 处理类型化事件
• state-global - 使用 Global trait 管理应用级状态
• state-keyed-state - 使用 window.use_keyed_state() 保存持久状态

4. 事件处理（HIGH）

• event-actions - 定义并注册键盘快捷键对应的操作
• event-listener - 使用 cx.listener() 处理绑定到视图的事件
• event-focus - 使用 FocusHandle 和 key_context 管理焦点
• event-propagation - 理解事件冒泡和 stop_propagation

5. 异步与并发（MEDIUM-HIGH）

• async-task-lifecycle - 存储或分离任务，防止任务取消
• async-debounce - 使用计时器和任务替换实现防抖
• async-background-spawn - 使用 background_spawn 处理 CPU 密集型工作
• async-weak-entity - 使用 WeakEntity 安全地跨 await 访问数据
• async-error-handling - 使用 .log_err() 和 .detach_and_log_err()

6. 样式（MEDIUM）

• style-flexbox - 使用 h_flex() 和 v_flex() 设置布局
• style-theme-colors - 务必使用 cx.theme() 获取颜色
• style-spacing - 使用 DynamicSpacing 实现自适应间距
• style-elevation - 使用 elevation 系统设置分层表面

7. 组件（MEDIUM）

• comp-stateless - 优先使用带有 #[derive(IntoElement)] 的 RenderOnce
• comp-traits - 实现 Disableable、Selectable、Sizable traits
• comp-focus-ring - 添加焦点环以提升无障碍性
• comp-dialog - 使用 WindowExt 管理对话框
• comp-variant - 使用变体枚举设置组件样式

8. 反模式（CRITICAL）

• anti-silent-error - 绝不要使用 let _ = 静默丢弃错误
• anti-drop-task - 绝不要丢弃 Task，务必存储或分离
• anti-drop-subscription - 务必分离或存储订阅
• anti-circular-reference - 避免 Entity 循环，使用 WeakEntity
• anti-missing-notify - 状态更改后绝不要忘记调用 cx.notify()
• anti-unwrap - 避免使用 unwrap()，改用 ? 或显式处理

架构概述

┌─────────────────────────────────────────────────────────┐
│                    Application (App)                     │
│              (Single owner of all Entities)              │
└─────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
    ┌───────────┐       ┌───────────┐       ┌──────────┐
    │ Entity<A> │       │ Entity<B> │       │ Global<C>│
    └───────────┘       └───────────┘       └──────────┘
        │                   │                   │
        │ read/update       │ read/update       │ via App
        │ via Context<A>    │ via Context<B>    │
        │
    ┌─────────────────────────────────────────────────┐
    │           UI Rendering (Render trait)           │
    │      Each frame: fn render(&mut self, ...)      │
    │      Returns: impl IntoElement (Element tree)   │
    └─────────────────────────────────────────────────┘
        │
        ├─ observe() → changes trigger render
        ├─ subscribe() → events trigger reactions
        ├─ notify() → signal changes
        └─ emit() → send typed events

如何使用

阅读各个规则文件，了解详细说明和代码示例：

rules/core-ownership-model.md
rules/render-render-vs-renderonce.md
rules/anti-silent-error.md

每个规则文件都包含：

• 简要说明其重要性
• 错误代码示例及说明
• 正确代码示例及说明
• 补充背景信息和参考资料