名称: gpui风格指南描述: 基于gpui-component代码模式的GPUI组件项目风格指南。适用于编写新组件、审查代码或确保与现有gpui-component实现的一致性。涵盖了组件结构、trait实现、命名约定和实际代码库中观察到的API模式。

概述

基于gpui-component实现模式衍生的代码风格指南。

基于: 对crates/ui中Button、Checkbox、Input、Select等组件的分析

组件结构

基本组件模式

use gpui::{
    div, prelude::FluentBuilder as _, AnyElement, App, Div, ElementId,
    InteractiveElement, IntoElement, ParentElement, RenderOnce,
    StatefulInteractiveElement, StyleRefinement, Styled, Window,
};

#[derive(IntoElement)]
pub struct MyComponent {
    id: ElementId,
    base: Div,
    style: StyleRefinement,

    // 配置字段
    size: Size,
    disabled: bool,
    selected: bool,

    // 内容字段
    label: Option<Text>,
    children: Vec<AnyElement>,

    // 回调（使用Rc实现Clone）
    on_click: Option<Rc<dyn Fn(&ClickEvent, &mut Window, &mut App) + 'static>>,
}

impl MyComponent {
    pub fn new(id: impl Into<ElementId>) -> Self {
        Self {
            id: id.into(),
            base: div(),
            style: StyleRefinement::default(),
            size: Size::default(),
            disabled: false,
            selected: false,
            label: None,
            children: Vec::new(),
            on_click: None,
        }
    }

    // 构建器方法
    pub fn label(mut self, label: impl Into<Text>) -> Self {
        self.label = Some(label.into());
        self
    }

    pub fn on_click(mut self, handler: impl Fn(&ClickEvent, &mut Window, &mut App) + 'static) -> Self {
        self.on_click = Some(Rc::new(handler));
        self
    }
}

impl InteractiveElement for MyComponent {
    fn interactivity(&mut self) -> &mut gpui::Interactivity {
        self.base.interactivity()
    }
}

impl StatefulInteractiveElement for MyComponent {}

impl Styled for MyComponent {
    fn style(&mut self) -> &mut StyleRefinement {
        &mut self.style
    }
}

impl RenderOnce for MyComponent {
    fn render(self, window: &mut Window, cx: &mut App) -> impl IntoElement {
        // 实现
        self.base
    }
}

状态组件模式

#[derive(IntoElement)]
pub struct Select {
    state: Entity<SelectState>,
    style: StyleRefinement,
    size: Size,
    // ...
}

pub struct SelectState {
    open: bool,
    selected_index: Option<usize>,
    // ...
}

impl Select {
    pub fn new(state: &Entity<SelectState>) -> Self {
        Self {
            state: state.clone(),
            size: Size::default(),
            style: StyleRefinement::default(),
        }
    }
}

Trait实现

可调整大小

impl Sizable for MyComponent {
    fn with_size(mut self, size: impl Into<Size>) -> Self {
        self.size = size.into();
        self
    }
}

可选

impl Selectable for MyComponent {
    fn selected(mut self, selected: bool) -> Self {
        self.selected = selected;
        self
    }

    fn is_selected(&self) -> bool {
        self.selected
    }
}

可禁用

impl Disableable for MyComponent {
    fn disabled(mut self, disabled: bool) -> Self {
        self.disabled = disabled;
        self
    }

    fn is_disabled(&self) -> bool {
        self.disabled
    }
}

变体模式

枚举变体

#[derive(Clone, Copy, PartialEq, Eq, Default, Debug)]
pub enum ButtonVariant {
    Primary,
    #[default]
    Secondary,
    Danger,
    Success,
    Warning,
    Ghost,
    Link,
}

基于Trait的变体API

pub trait ButtonVariants: Sized {
    fn with_variant(self, variant: ButtonVariant) -> Self;

    /// 使用按钮的主要样式。
    fn primary(self) -> Self {
        self.with_variant(ButtonVariant::Primary)
    }

    /// 使用按钮的危险样式。
    fn danger(self) -> Self {
        self.with_variant(ButtonVariant::Danger)
    }

    // ... 更多变体
}

自定义变体模式

#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct ButtonCustomVariant {
    color: Hsla,
    foreground: Hsla,
    border: Hsla,
    hover: Hsla,
    active: Hsla,
    shadow: bool,
}

impl ButtonCustomVariant {
    pub fn new(cx: &App) -> Self {
        Self {
            color: cx.theme().transparent,
            foreground: cx.theme().foreground,
            // ...
            shadow: false,
        }
    }

    pub fn color(mut self, color: Hsla) -> Self {
        self.color = color;
        self
    }

    // ... 更多构建器方法
}

操作和键绑定模式

上下文常量

const CONTEXT: &str = "Select";

初始化函数

pub(crate) fn init(cx: &mut App) {
    cx.bind_keys([
        KeyBinding::new("up", SelectUp, Some(CONTEXT)),
        KeyBinding::new("down", SelectDown, Some(CONTEXT)),
        KeyBinding::new("enter", Confirm { secondary: false }, Some(CONTEXT)),
        KeyBinding::new("escape", Cancel, Some(CONTEXT)),
    ])
}

操作使用

use crate::actions::{Cancel, Confirm, SelectDown, SelectUp};

div()
    .key_context(CONTEXT)
    .on_action(cx.listener(Self::on_action_select_up))
    .on_action(cx.listener(Self::on_action_confirm))

Trait定义

项目Trait

pub trait SelectItem: Clone {
    type Value: Clone;

    fn title(&self) -> SharedString;

    fn display_title(&self) -> Option<AnyElement> {
        None
    }

    fn render(&self, _: &mut Window, _: &mut App) -> impl IntoElement {
        self.title().into_element()
    }

    fn value(&self) -> &Self::Value;

    fn matches(&self, query: &str) -> bool {
        self.title().to_lowercase().contains(&query.to_lowercase())
    }
}

为常见类型实现

impl SelectItem for String {
    type Value = Self;

    fn title(&self) -> SharedString {
        SharedString::from(self.to_string())
    }

    fn value(&self) -> &Self::Value {
        &self
    }
}

impl SelectItem for SharedString { /* ... */ }
impl SelectItem for &'static str { /* ... */ }

图标模式

IconNamed Trait

pub trait IconNamed {
    fn path(self) -> SharedString;
}

impl<T: IconNamed> From<T> for Icon {
    fn from(value: T) -> Self {
        Icon::build(value)
    }
}

图标名称枚举

#[derive(IntoElement, Clone)]
pub enum IconName {
    ArrowDown,
    ArrowUp,
    Check,
    Close,
    // ... 所有图标名称
}

文档模式

组件文档

/// 一个Checkbox元素。
#[derive(IntoElement)]
pub struct Checkbox { }

方法文档

impl Checkbox {
    /// 使用给定的id创建一个新的Checkbox。
    pub fn new(id: impl Into<ElementId>) -> Self { }

    /// 为复选框设置标签。
    pub fn label(mut self, label: impl Into<Text>) -> Self { }

    /// 设置复选框的点击处理程序。
    ///
    /// `&bool` 参数表示点击后的新选中状态。
    pub fn on_click(mut self, handler: impl Fn(&bool, &mut Window, &mut App) + 'static) -> Self { }
}

导入组织模式

// 1. 外部crate导入
use std::rc::Rc;

// 2. Crate导入
use crate::{
    ActiveTheme, Disableable, FocusableExt, Icon, IconName,
    Selectable, Sizable, Size, StyledExt,
};

// 3. GPUI导入
use gpui::{
    div, prelude::FluentBuilder as _, px, relative, rems,
    AnyElement, App, Div, ElementId, InteractiveElement,
    IntoElement, ParentElement, RenderOnce,
    StatefulInteractiveElement, StyleRefinement, Styled, Window,
};

字段组织

pub struct Component {
    // 1. 标识
    id: ElementId,
    base: Div,
    style: StyleRefinement,

    // 2. 配置
    size: Size,
    disabled: bool,
    selected: bool,
    tab_stop: bool,
    tab_index: isize,

    // 3. 内容/子元素
    label: Option<Text>,
    children: Vec<AnyElement>,
    prefix: Option<AnyElement>,
    suffix: Option<AnyElement>,

    // 4. 回调（最后）
    on_click: Option<Rc<dyn Fn(Args, &mut Window, &mut App) + 'static>>,
}

常见模式

可选元素

pub fn prefix(mut self, prefix: impl IntoElement) -> Self {
    self.prefix = Some(prefix.into_any_element());
    self
}

回调模式

// 模式1: 事件参数在前
pub fn on_click(mut self, handler: impl Fn(&ClickEvent, &mut Window, &mut App) + 'static) -> Self {
    self.on_click = Some(Rc::new(handler));
    self
}

// 模式2: 状态参数
pub fn on_change(mut self, handler: impl Fn(&bool, &mut Window, &mut App) + 'static) -> Self {
    self.on_change = Some(Rc::new(handler));
    self
}

静态处理函数

fn handle_click(
    on_click: &Option<Rc<dyn Fn(&bool, &mut Window, &mut App) + 'static>>,
    checked: bool,
    window: &mut Window,
    cx: &mut App,
) {
    let new_checked = !checked;
    if let Some(f) = on_click {
        (f)(&new_checked, window, cx);
    }
}

布尔方法

// 启用/禁用模式
pub fn cleanable(mut self, cleanable: bool) -> Self {
    self.cleanable = cleanable;
    self
}

// 切换方法（无参数）
pub fn mask_toggle(mut self) -> Self {
    self.mask_toggle = true;
    self
}

大小方法

大小Trait

impl Sizable for Component {
    fn with_size(mut self, size: impl Into<Size>) -> Self {
        self.size = size.into();
        self
    }
}

便捷大小方法（来自StyleSized trait）

组件通过StyleSized trait自动获得.xsmall()、.small()、.medium()、.large()。

渲染模式

RenderOnce模式

impl RenderOnce for MyComponent {
    fn render(self, window: &mut Window, cx: &mut App) -> impl IntoElement {
        let (width, height) = self.size.input_size();

        self.base
            .id(self.id)
            .flex()
            .items_center()
            .gap(px(8.))
            .min_w(width)
            .h(height)
            .when(self.disabled, |this| {
                this.opacity(0.5).cursor_not_allowed()
            })
            .children(self.children)
    }
}

主题使用

// 访问主题颜色
cx.theme().surface
cx.theme().foreground
cx.theme().border
cx.theme().primary
cx.theme().transparent

// 在组件中使用
div()
    .bg(cx.theme().surface)
    .text_color(cx.theme().foreground)
    .border_color(cx.theme().border)

参考文档

组件示例: 参见component-examples.md
- 完整组件实现
- 常见模式示例
Trait模式: 参见trait-patterns.md
- 详细trait实现指南
- 自定义trait设计模式

快速检查清单

在crates/ui中创建新组件时：

[ ] #[derive(IntoElement)] 在结构体上
[ ] 包括 id: ElementId、base: Div、style: StyleRefinement
[ ] 实现 InteractiveElement、StatefulInteractiveElement、Styled
[ ] 实现 RenderOnce trait
[ ] 如果组件有大小，实现 Sizable
[ ] 如果组件可选，实现 Selectable
[ ] 如果组件可禁用，实现 Disableable
[ ] 使用 Rc<dyn Fn> 用于回调
[ ] 使用 Option<AnyElement> 用于可选子元素
[ ] 导入 prelude::FluentBuilder as _
[ ] 通过 cx.theme() 使用主题颜色
[ ] 遵循字段组织模式

名称: gpui风格指南 描述: 基于gpui-component代码模式的GPUI组件项目风格指南。适用于编写新组件、审查代码或确保与现有gpui-component实现的一致性。涵盖了组件结构、trait实现、命名约定和实际代码库中观察到的API模式。

概述

组件结构

基本组件模式

状态组件模式

Trait实现

可调整大小

可选

可禁用

变体模式

枚举变体

基于Trait的变体API

自定义变体模式

操作和键绑定模式

上下文常量

初始化函数

操作使用

Trait定义

项目Trait

为常见类型实现

图标模式

IconNamed Trait

图标名称枚举

文档模式

组件文档

方法文档

导入组织模式

字段组织

常见模式

可选元素

回调模式

静态处理函数

布尔方法

大小方法

大小Trait

便捷大小方法（来自StyleSized trait）

渲染模式

RenderOnce模式

主题使用

参考文档

快速检查清单

名称: gpui风格指南描述: 基于gpui-component代码模式的GPUI组件项目风格指南。适用于编写新组件、审查代码或确保与现有gpui-component实现的一致性。涵盖了组件结构、trait实现、命名约定和实际代码库中观察到的API模式。