gpui-component

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

gpui-component Best Practices

gpui-component 最佳实践

Comprehensive guide for building UI components with gpui-component, a component library for GPUI applications.

这是一份使用gpui-component构建UI组件的综合指南，gpui-component是一款面向GPUI应用的组件库。

When to Apply

适用场景

Reference these guidelines when:

Creating reusable UI components
Implementing theme-aware styling
Building dialogs, popovers, or sheets
Creating form components (Input, Checkbox, etc.)
Implementing component animations
Following Longbridge component patterns

在以下场景中参考本指南：

创建可复用UI组件
实现支持主题的样式
构建对话框、弹出层或侧边栏
创建表单组件（输入框、复选框等）
实现组件动画
遵循Longbridge组件模式

Rule Categories by Priority

按优先级划分的规则类别


comp-
trait-
theme-
dialog-
form-
anim-

Priority	Category	Impact	Prefix
1	Component Architecture	CRITICAL	`comp-`
2	Trait System	CRITICAL	`trait-`
3	Theme System	HIGH	`theme-`
4	Dialog & Popover	HIGH	`dialog-`
5	Form Components	MEDIUM	`form-`
6	Animation	MEDIUM	`anim-`


comp-
trait-
theme-
dialog-
form-
anim-

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

Quick Reference

快速参考

1. Component Architecture (CRITICAL)

1. 组件架构（关键）

```
comp-renderonce
```
- Use RenderOnce with #[derive(IntoElement)]
```
comp-structure
```
- Standard component structure template
```
comp-builder
```
- Fluent builder pattern for components
```
comp-stateful
```
- Entity + RenderOnce for stateful components
```
comp-callbacks
```
- Use Rc<dyn Fn> for event callbacks

```
comp-renderonce
```
- 将RenderOnce与#[derive(IntoElement)]结合使用
```
comp-structure
```
- 标准组件结构模板
```
comp-builder
```
- 组件的流畅构建器模式
```
comp-stateful
```
- 使用Entity + RenderOnce实现有状态组件
```
comp-callbacks
```
- 使用Rc<dyn Fn>处理事件回调

2. Trait System (CRITICAL)

2. Trait系统（关键）

```
trait-styled
```
- Implement Styled for style customization
```
trait-disableable
```
- Implement Disableable for disabled state
```
trait-selectable
```
- Implement Selectable for selection state
```
trait-sizable
```
- Implement Sizable with Size enum
```
trait-parent-element
```
- Implement ParentElement for children
```
trait-interactive
```
- Implement InteractiveElement for events

```
trait-styled
```
- 实现Styled以支持样式自定义
```
trait-disableable
```
- 实现Disableable以支持禁用状态
```
trait-selectable
```
- 实现Selectable以支持选中状态
```
trait-sizable
```
- 结合Size枚举实现Sizable
```
trait-parent-element
```
- 实现ParentElement以支持子元素
```
trait-interactive
```
- 实现InteractiveElement以处理事件

3. Theme System (HIGH)

3. 主题系统（高）

```
theme-colors
```
- Use ThemeColor for consistent colors
```
theme-active
```
- Use ActiveTheme trait for theme access
```
theme-variants
```
- Implement variant enums (ButtonVariant, etc.)
```
theme-size-system
```
- Use StyleSized for size-based styling

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

4. Dialog & Popover (HIGH)

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

```
dialog-root
```
- Use Root component as window root
```
dialog-window-ext
```
- Use WindowExt for dialog management
```
dialog-confirm
```
- Implement confirm/alert dialogs
```
dialog-form
```
- Build form dialogs with input state
```
popover-pattern
```
- Popover vs PopupMenu vs Sheet selection

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

5. Form Components (MEDIUM)

5. 表单组件（中等）

```
form-input-state
```
- Entity-based input state management
```
form-focus
```
- Focus management with keyed state
```
form-validation
```
- Input validation patterns

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

6. Animation (MEDIUM)

6. 动画（中等）

```
anim-with-animation
```
- Use with_animation for transitions
```
anim-keyed-state
```
- Persist animation state with use_keyed_state
```
anim-easing
```
- Use cubic_bezier for smooth animations

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

Component Structure Template

组件结构模板

rust

#[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)>>,
}

rust

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

    // 2. 基础元素（用于事件委托）
    base: Div,

    // 3. 样式覆盖
    style: StyleRefinement,

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

    // 5. 状态配置
    disabled: bool,
    selected: bool,
    size: Size,

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

Architecture Overview

架构概览

┌─────────────────────────────────────────────────────────────┐
│  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                             │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  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                             │
└─────────────────────────────────────────────────────────────┘

Popup Component Comparison

弹出组件对比

Feature	Dialog	Popover	PopupMenu	Sheet
Position	Centered	Anchored	Anchored	Side
Overlay	Yes	No	No	Yes
State	Root	keyed_state	Entity	Root
Stacking	Multiple	Single	Submenus	Single
Close	ESC/Click/Button	ESC/Outside	ESC/Select	ESC/Overlay

特性	Dialog	Popover	PopupMenu	Sheet
位置	居中	锚定	锚定	侧边
遮罩层	有	无	无	有
状态管理	Root	keyed_state	Entity	Root
堆叠	可多层	单层	子菜单	单层
关闭方式	ESC/点击外部/按钮	ESC/点击外部	ESC/选择选项	ESC/点击遮罩层

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

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

Each rule file contains:

Brief explanation of why it matters
Code examples with correct patterns
Common mistakes to avoid

阅读单个规则文件获取详细说明和代码示例：

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

每个规则文件包含：

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