用途
gpui-style-guide 是一份代码风格指南，依据 gpui-component 的实现模式整理而成，其基础是对 crates/ui 目录中 Button、Checkbox、Input、Select 等组件的分析。它适用于在编写新组件、审查代码，或需要确保代码与 gpui-component 现有模式保持一致时参考。
主要能力（覆盖的规范内容）
组件结构
- 基础组件模式：以
#[derive(IntoElement)]的结构体为例，展示id: ElementId、base: Div、style: StyleRefinement，配置字段（size、disabled、selected）、内容字段（label、children）以及使用Rc保存回调用以支持 Clone 的字段写法，并给出new构造方法与 label、on_click 等构建器方法。 - 有状态组件模式：以 Select 为例，展示持有
Entity<SelectState>的写法，以及 SelectState 中 open、selected_index 等状态字段。
Trait 实现
- 交互与渲染相关：InteractiveElement（转发 interactivity）、StatefulInteractiveElement、Styled（返回 StyleRefinement）、RenderOnce（实现 render）。
- 能力相关：Sizable（with_size）、Selectable（selected / is_selected）、Disableable（disabled / is_disabled）。
变体（Variant）模式
- 枚举变体：如 ButtonVariant 的 Primary、Secondary（#[default]）、Danger、Success、Warning、Ghost、Link。
- 基于 trait 的变体 API：如 ButtonVariants trait 提供 with_variant 以及 primary、danger 等便捷方法。
- 自定义变体：如 ButtonCustomVariant 结构，包含 color、foreground、border、hover、active、shadow 等字段及构建器方法，颜色取自主题。
Action 与按键绑定
- 以
const CONTEXT: &str = "Select";作为上下文常量。 - 在 init 函数中通过
cx.bind_keys([...])绑定 up、down、enter、escape 等按键到对应 Action。 - 在元素上使用
key_context(CONTEXT)与on_action(cx.listener(...))接入。
Trait 定义
- Item Traits：以 SelectItem 为例，展示 title、display_title、render、value、matches 等方法的定义，以及为 String、SharedString、&'static str 等通用类型实现该 trait 的方式。
- 图标：IconNamed trait 的 path 方法、
From<T: IconNamed> for Icon的实现，以及 IconName 枚举的写法。
文档与组织规范
- 文档注释模式：组件级与方法级注释示例，例如 on_click 注释中说明
&bool参数表示点击后的新选中状态。 - 导入组织：按外部 crate 导入、crate 内导入、GPUI 导入的顺序排列。
- 字段组织：按身份（id、base、style）、配置、内容/子元素、回调的顺序排列字段。
常见写法
- 可选元素使用
Option<AnyElement>与into_any_element()。 - 回调两种模式：事件参数在前，或状态参数（如
&bool）。 - 静态 handler 函数示例（handle_click）。
- 布尔方法：如 cleanable(bool)，以及无参数的切换方法 mask_toggle。
- 尺寸方法：实现 Sizable，并通过 StyleSized trait 自动获得 xsmall、small、medium、large 等方法。
- 渲染：RenderOnce 的 render 中使用
size.input_size()取得宽高，并用 flex、items_center、gap、min_w、h、when 等链式方法。 - 主题：通过
cx.theme()访问 surface、foreground、border、primary、transparent 等颜色，并用于 bg、text_color、border_color。
参考资料与检查清单
- 组件示例见 component-examples.md，trait 模式见 trait-patterns.md。
- 创建新组件时的检查清单：结构体加
#[derive(IntoElement)]；包含 id、base、style 字段；实现 InteractiveElement、StatefulInteractiveElement、Styled；实现 RenderOnce；有尺寸时实现 Sizable；可选中时实现 Selectable；可禁用时实现 Disableable；回调使用Rc<dyn Fn>；可选子元素使用Option<AnyElement>；导入prelude::FluentBuilder as _；使用cx.theme()主题颜色；遵循字段组织模式。
使用方式
本资料为规范文档，未提供安装命令、CLI 用法或运行步骤。按照文档中的规则与示例在 crates/ui 中编写或审查 GPUI 组件即可，具体引用方式暂未提供。
适用场景
适用于基于 GPUI 开发 UI 组件、审查 gpui-component 相关代码，以及在项目内统一组件实现风格的场景。
限制
该指南以 gpui-component（crates/ui）的既有实现为基准，属于风格与结构约定，不描述独立产品的功能或服务；文档未提供版本、许可、依赖版本、平台支持、性能或收费等信息，这些暂未提供。