gpui-component

gpui-component 最佳实践

使用 gpui-component 构建 UI 组件的综合指南。gpui-component 是一个用于 GPUI 应用的组件库。

适用场景

在以下情况下参考这些指南：

• 创建可复用的 UI 组件
• 实现主题感知样式
• 构建对话框、弹出框或面板
• 创建表单组件（Input、Checkbox 等）
• 实现组件动画
• 遵循 Longbridge 组件模式

按优先级划分的规则类别

优先级	类别	影响	前缀
1	组件架构	严重	comp-
2	Trait 系统	严重	trait-
3	主题系统	高	theme-
4	对话框与弹出框	高	dialog-
5	表单组件	中	form-
6	动画	中	anim-

快速参考

1. 组件架构（严重）

• comp-renderonce - 使用 RenderOnce 和 #[derive(IntoElement)]
• comp-structure - 标准组件结构模板
• comp-builder - 组件的流式构建器模式
• comp-stateful - 为有状态组件使用 Entity + RenderOnce
• comp-callbacks - 使用 Rc 处理事件回调

2. Trait 系统（严重）

• trait-styled - 实现 Styled 以自定义样式
• trait-disableable - 实现 Disableable 以设置禁用状态
• trait-selectable - 实现 Selectable 以设置选中状态
• trait-sizable - 使用 Size 枚举实现 Sizable
• trait-parent-element - 实现 ParentElement 以添加子元素
• trait-interactive - 实现 InteractiveElement 以处理事件

3. 主题系统（高）

• theme-colors - 使用 ThemeColor 确保颜色一致
• theme-active - 使用 ActiveTheme trait 访问主题
• theme-variants - 实现变体枚举（ButtonVariant 等）
• theme-size-system - 使用 StyleSized 实现基于尺寸的样式

4. 对话框与弹出框（高）

• dialog-root - 使用 Root 组件作为窗口根节点
• dialog-window-ext - 使用 WindowExt 管理对话框
• dialog-confirm - 实现确认/警告对话框
• dialog-form - 使用输入状态构建表单对话框
• popover-pattern - 选择 Popover、PopupMenu 或 Sheet

5. 表单组件（中）

• form-input-state - 基于 Entity 管理输入状态
• form-focus - 使用带键状态管理焦点
• form-validation - 输入验证模式

6. 动画（中）

• anim-with-animation - 使用 with_animation 实现过渡
• anim-keyed-state - 使用 use_keyed_state 保留动画状态
• anim-easing - 使用 cubic_bezier 实现平滑动画

组件结构模板

#[derive(IntoElement)]
pub struct MyComponent {
    // 1. Identifier
    id: ElementId,

    // 2. Base element (for event delegation)
    base: Div,

    // 3. Style override
    style: StyleRefinement,

    // 4. Content
    label: Option<SharedString>,
    children: Vec<AnyElement>,

    // 5. State configuration
    disabled: bool,
    selected: bool,
    size: Size,

    // 6. Callbacks
    on_click: Option<Rc<dyn Fn(&ClickEvent, &mut Window, &mut App)>>,
}

架构概览

┌─────────────────────────────────────────────────────────────┐
│  Window                                                      │
│  ├── Root (Entity, manages overlay state)                   │
│  │   ├── view: AnyView (user's main view)                   │
│  │   ├── active_dialogs: Vec<ActiveDialog>                  │
│  │   ├── active_sheet: Option<ActiveSheet>                  │
│  │   └── notification: Entity<NotificationList>             │
│  │                                                          │
│  └── Render Layers                                          │
│      ├── Layer 0: Root.view (main content)                  │
│      ├── Layer 1: Sheet (side drawer)                       │
│      ├── Layer 2: Dialogs (stackable)                       │
│      └── Layer 3: Notifications                             │
└─────────────────────────────────────────────────────────────┘

弹出组件对比

特性	对话框	Popover	PopupMenu	Sheet
位置	居中	锚定	锚定	侧边
遮罩层	是	否	否	是
状态	Root	keyed_state	Entity	Root
堆叠	多个	单个	子菜单	单个
关闭	ESC/点击/按钮	ESC/外部点击	ESC/选择	ESC/遮罩层

使用方法

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

rules/comp-renderonce.md
rules/trait-styled.md
rules/dialog-root.md

每个规则文件都包含：

• 简要说明其重要性
• 展示正确模式的代码示例
• 需要避免的常见错误