# learn-gpui-component

**Repository Path**: andnnl/learn-gpui-component

## Basic Information

- **Project Name**: learn-gpui-component
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-10
- **Last Updated**: 2026-01-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GPUI Component 学习项目

这是一个学习 GPUI Component 库的 Rust 项目，通过 19 个完整的组件示例，系统地展示如何使用 GPUI Component 创建现代化的跨平台桌面应用程序。

## 项目概述

GPUI Component 是一个用于构建跨平台桌面应用程序的 UI 组件库，基于 GPUI 框架构建。本项目提供了从基础到高级的完整学习路径，涵盖所有主要组件的使用方法，包括窗口布局和可调整大小的面板。

### 技术栈

- **语言**: Rust (edition 2024)
- **核心框架**: GPUI 0.2.2
- **UI 组件库**: gpui-component 0.5.0
- **图形渲染**: wgpu 0.19.1
- **窗口管理**: winit 0.29
- **WebView 支持**: wry 0.15

## 快速开始

### 前置要求

- Rust 1.70 或更高版本
- 支持的操作系统：Windows、macOS、Linux

### 运行示例

```bash
# 克隆项目
git clone <repository-url>
cd learn-gpui-component

# 运行特定示例
cargo run -p button_example
cargo run -p input_example
cargo run -p checkbox_example
cargo run -p dock_example

# 构建所有示例
cargo build --workspace
```

### 运行官方示例

```bash
cd gpui-component-0.5.0
cargo run
```

## 项目结构

```
learn-gpui-component/
├── examples/                    # 19 个学习示例
│   ├── alert_example/          # 警告组件
│   ├── avatar_example/         # 头像组件
│   ├── badge_example/          # 徽章组件
│   ├── button_example/         # 按钮组件
│   ├── card_example/           # 卡片组件
│   ├── checkbox_example/       # 复选框组件
│   ├── divider_example/        # 分隔符组件
│   ├── dock_example/           # 窗口布局示例（可调整大小面板）
│   ├── icon_example/           # 图标组件
│   ├── input_example/          # 输入框组件
│   ├── label_example/          # 标签组件
│   ├── progress_example/       # 进度条组件
│   ├── radio_example/          # 单选框组件
│   ├── select_example/         # 选择器组件
│   ├── slider_example/         # 滑块组件
│   ├── spinner_example/        # 加载中组件
│   ├── switch_example/         # 开关组件
│   ├── tabs_example/           # 选项卡组件
│   └── tag_example/            # 标签组件
├── gpui-component-0.5.0/       # GPUI Component 库源码
│   ├── crates/
│   │   ├── ui/                 # 核心 UI 组件库
│   │   ├── story/              # 组件展示和测试用例
│   │   ├── assets/             # 资源管理
│   │   └── macros/             # 宏定义
│   ├── examples/               # 官方基础示例
│   └── docs/                   # 官方文档
├── Cargo.toml                  # 工作空间配置
└── Cargo.lock                  # 依赖锁定文件
```

## 学习路径

### 1. 基础组件（推荐从这些开始）

- **button_example** - 按钮组件（多种变体、尺寸、样式）
- **input_example** - 输入框组件（密码框、前缀后缀）
- **label_example** - 标签组件（不同颜色、字重）
- **icon_example** - 图标组件（常用图标、尺寸变化）
- **badge_example** - 徽章组件（计数、图标）
- **tag_example** - 标签组件（可关闭、带图标）

### 2. 表单组件

- **checkbox_example** - 复选框组件
- **radio_example** - 单选框组件
- **switch_example** - 开关组件
- **select_example** - 选择器组件

### 3. 布局组件

- **divider_example** - 分隔符组件
- **card_example** - 卡片组件
- **dock_example** - 窗口布局示例（可调整大小的面板）

### 4. 反馈组件

- **alert_example** - 警告组件
- **progress_example** - 进度条组件
- **spinner_example** - 加载中组件

### 5. 导航组件

- **tabs_example** - 选项卡组件

### 6. 其他组件

- **slider_example** - 滑块组件
- **avatar_example** - 头像组件

## 核心概念

### 组件使用模式

1. **初始化**: 在应用启动时必须调用 `gpui_component::init(cx)`
2. **窗口创建**: 使用 `cx.open_window()` 创建窗口
3. **Root 组件**: 窗口的顶层必须是 `Root` 组件
4. **布局**: 使用 `div()` 配合 `v_flex()` 和 `h_flex()` 进行布局
5. **事件处理**: 使用 `on_click()`、`on_mouse_down()` 等方法处理交互

### 基本示例

```rust
use gpui::*;
use gpui_component::*;

pub struct Example;

impl Render for Example {
    fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .v_flex()
            .gap_4()
            .p_6()
            .size_full()
            .child("Hello, GPUI Component!")
            .child(
                Button::new("my-button")
                    .primary()
                    .label("Click Me")
                    .on_click(|_, _, _| println!("Clicked!")),
            )
    }
}

fn main() {
    let app = Application::new();
    app.run(move |cx| {
        gpui_component::init(cx);
        cx.spawn(async move |cx| {
            cx.open_window(WindowOptions::default(), |window, cx| {
                let view = cx.new(|_| Example);
                cx.new(|cx| Root::new(view, window, cx))
            })?;
            Ok::<_, anyhow::Error>(())
        }).detach();
    });
}
```

## 注意事项

1. **必须初始化**: 在使用任何 GPUI Component 功能前，必须调用 `gpui_component::init(cx)`
2. **Root 组件**: 窗口的第一层必须是 `Root` 组件
3. **Size 类型**: 始终使用 `gpui::Size { ... }` 而不是 `Size { ... }` 避免类型歧义
4. **性能优化**: 开发模式下已启用 `opt-level = 3` 以获得更好的性能
5. **图标**: 使用 `IconName` 枚举中的预定义图标
6. **资源加载**: 使用图标时需要添加 `gpui-component-assets` 依赖并使用 `Application::new().with_assets(Assets)`

## 学习资源

### 官方文档

- [GPUI Component 官方文档](https://longbridge.github.io/gpui-component/)
- [GPUI Component README](gpui-component-0.5.0/README.md)
- [贡献指南](gpui-component-0.5.0/CONTRIBUTING.md)

### 示例代码

- **学习示例**: `examples/` - 18 个完整的学习示例
- **基础示例**: `gpui-component-0.5.0/examples/` - 单一功能的简单示例
- **组件库**: `gpui-component-0.5.0/crates/story/` - 完整的组件展示和测试用例

### UI 设计参考

- [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)
- [Microsoft Fluent Design System](https://learn.microsoft.com/en-us/windows/apps/design/)
- [shadcn/ui](https://ui.shadcn.com/)

## 项目状态

- ✅ 19 个完整的学习示例，涵盖所有主要组件和布局
- ✅ 所有示例都已修复并可以正常运行
- ✅ 系统化的学习路径，从基础到高级
- ✅ GPUI Component 0.5.0 的完整源码
- ✅ 窗口布局和可调整大小面板的完整示例

## 许可证

本项目遵循 Apache-2.0 许可证。GPUI Component 库也遵循 Apache-2.0 许可证。

## 贡献

欢迎提交 Issue 和 Pull Request 来改进这个学习项目！

## 相关链接

- [GPUI Component GitHub](https://github.com/longbridge/gpui-component)
- [GPUI](https://github.com/zed-industries/zed)