# learn-gpui

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

## Basic Information

- **Project Name**: learn-gpui
- **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-09
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Learn GPUI 项目

一个用于学习 GPUI（Zed 编辑器使用的 Rust GUI 框架）的教程项目。

## 项目概述

这是一个渐进式的 GPUI 学习项目，包含 12 个从基础到高级的示例，帮助你掌握 GPUI 框架的核心概念和最佳实践。

### 主要技术
- **语言**: Rust (Edition 2024)
- **GUI 框架**: GPUI（来自 Zed Industries）
- **项目类型**: 学习/教程项目

## 项目结构

```
learn-gpui/
├── src/
│   └── main.rs              # 基础的 Hello World 程序
├── examples/                # 教程示例（12个渐进式示例）
│   ├── 01_hello_world.rs
│   ├── 02_counter.rs
│   ├── 03_entity_publisher.rs
│   ├── 04_todo_list.rs
│   ├── 05_context_system.rs
│   ├── 06_elements_render.rs
│   ├── 07_layout_system.rs
│   ├── 08_elements_advanced.rs
│   ├── 09_layout_advanced.rs
│   ├── 10_interactions.rs
│   ├── 11_async.rs
│   └── 12_advanced.rs
├── docs/                    # 文档资源
├── Cargo.toml               # Rust 项目配置
└── README.md                # 本文件
```

## 快速开始

### 前置要求
- Rust 工具链（需要支持 2024 edition）
- Cargo 包管理器

### 安装和构建

```bash
# 克隆项目（如果需要）
git clone <repository-url>
cd learn-gpui

# 构建项目
cargo build

# 运行主程序
cargo run
```

### 运行示例

#### 基础示例（01-07）- ✅ 已验证可运行

```bash
# 示例 1: Hello World
cargo run --example 01_hello_world

# 示例 2: 计数器
cargo run --example 02_counter

# 示例 3: 实体发布者
cargo run --example 03_entity_publisher

# 示例 4: 待办事项列表
cargo run --example 04_todo_list

# 示例 5: 上下文系统
cargo run --example 05_context_system

# 示例 6: 元素渲染
cargo run --example 06_elements_render

# 示例 7: 布局系统
cargo run --example 07_layout_system
```

#### 进阶示例（08-12）- ✅ 已修复可运行

```bash
# 示例 8: 高级元素系统
cargo run --example 08_elements_advanced

# 示例 9: 进阶布局模式
cargo run --example 09_layout_advanced

# 示例 10: 交互和事件处理
cargo run --example 10_interactions

# 示例 11: 异步编程
cargo run --example 11_async

# 示例 12: 高级主题
cargo run --example 12_advanced
```

## 示例说明

### 基础示例

| 示例 | 描述 | 核心概念 |
|------|------|----------|
| 01_hello_world | 最基础的 GPUI 应用 | 窗口创建、Render trait、flexbox 布局 |
| 02_counter | 交互式计数器 | 状态管理、事件处理、通知机制 |
| 03_entity_publisher | 实体和发布者-订阅者 | Entity、观察者模式、跨实体通信 |
| 04_todo_list | 待办事项列表 | 实体列表、嵌套结构、CRUD 操作 |
| 05_context_system | 上下文系统 | 全局状态、子实体创建、状态同步 |
| 06_elements_render | 元素渲染系统 | RenderOnce、可复用组件、条件渲染 |
| 07_layout_system | 布局系统 | Flexbox、对齐、常见布局模式 |

### 进阶示例

| 示例 | 描述 | 核心概念 |
|------|------|----------|
| 08_elements_advanced | 高级元素系统 | Tab 导航、组件组合、状态管理 |
| 09_layout_advanced | 进阶布局模式 | 居中、侧边栏、网格、响应式布局 |
| 10_interactions | 交互和事件处理 | 键盘快捷键、动作系统、鼠标事件 |
| 11_async | 异步编程 | spawn、异步任务、倒计时 |
| 12_advanced | 高级主题 | 动画系统、拖放、性能优化 |

## GPUI 核心概念

### 1. Entity（实体）
GPUI 中的核心概念，代表可观察的状态。

```rust
let entity = cx.new(|cx| MyComponent::new());
```

### 2. Render（渲染）
定义组件如何渲染的 trait。

```rust
impl Render for MyComponent {
    fn render(&mut self, _window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        div().child("Hello, GPUI!")
    }
}
```

### 3. Context（上下文）
提供访问应用上下文和更新机制。

```rust
cx.notify();  // 触发重新渲染
cx.observe(&other_entity, |this, other, cx| {
    // 观察其他实体的变化
});
```

### 4. 布局系统
基于 Taffy 的 Flexbox 引擎。

```rust
div()
    .flex()
    .flex_col()
    .items_center()
    .justify_center()
```

## 常用模式

### 创建实体
```rust
let entity = cx.new(|cx| MyEntity::new());
```

### 建立观察关系
```rust
cx.observe(&other_entity, |this, other, cx| {
    // 当 other_entity 变化时触发
    cx.notify();
});
```

### 触发重新渲染
```rust
cx.notify();
```

### 处理点击事件
```rust
div()
    .id("my-button")
    .cursor_pointer()
    .on_click(cx.listener(|this, _, _, cx| {
        this.handle_click(cx);
    }))
```

## 学习路径

### 初学者路径（1-4）
1. **01_hello_world** - 理解基本结构
2. **02_counter** - 学习状态管理
3. **03_entity_publisher** - 理解观察者模式
4. **04_todo_list** - 构建完整应用

### 进阶路径（5-7）
5. **05_context_system** - 全局状态管理
6. **06_elements_render** - 元素渲染技巧
7. **07_layout_system** - 布局系统

### 高级路径（8-12）
8. **08_elements_advanced** - 高级组件开发
9. **09_layout_advanced** - 复杂布局模式
10. **10_interactions** - 交互系统
11. **11_async** - 异步编程
12. **12_advanced** - 性能优化和动画

## 项目状态

### ✅ 已验证可运行（全部 12 个示例）
- ✅ 01_hello_world.rs
- ✅ 02_counter.rs
- ✅ 03_entity_publisher.rs
- ✅ 04_todo_list.rs
- ✅ 05_context_system.rs
- ✅ 06_elements_render.rs
- ✅ 07_layout_system.rs
- ✅ 08_elements_advanced.rs（已修复）
- ✅ 09_layout_advanced.rs（已修复）
- ✅ 10_interactions.rs（已修复）
- ✅ 11_async.rs（已修复）
- ✅ 12_advanced.rs（已修复）

## 重要说明

### 异步编程限制（示例 11）

**注意**: 在当前版本的 GPUI 中，**不能在异步线程中调用 `cx.notify()`**。

**原因**:
- `AsyncApp` 不实现 `AppContext` trait
- `AsyncApp` 不实现 `VisualContext` trait
- 无法从异步上下文更新实体状态

**当前限制**:
- ✅ 异步线程可以启动
- ✅ 异步线程可以执行异步操作（如 sleep）
- ❌ 无法从异步线程更新UI状态
- ❌ 无法从异步线程通知重新渲染

**示例 11 的实现**:
- 展示了异步线程的结构
- 说明了当前 API 的限制
- 为未来框架更新做好准备

## 调试技巧

### 启用检查器
```rust
#[cfg(debug_assertions)]
cx.show_inspector();
```

### 日志输出
```rust
env_logger::init();
```

## 常见问题

### Q: GPUI API 经常变化怎么办？
A: 由于使用的是开发版本，API 可能会变化。请参考最新的 GPUI 文档和源码。

### Q: 如何优化性能？
A: 使用 `cargo build --release` 进行优化构建，避免不必要的重新渲染。

### Q: 窗口无法显示？
A: 确保系统支持 GPU 加速（Metal/DirectX/OpenGL）。

## GPUI 与其他框架对比

### 与 React 对比
| 特性 | GPUI | React |
|------|------|-------|
| 语言 | Rust | JavaScript/TypeScript |
| 渲染 | GPU 加速 | DOM |
| 性能 | 极高 | 中等 |
| 包大小 | 小 | 大 |
| 学习曲线 | 陡峭 | 平缓 |
| 状态管理 | Entity + Context | Hooks + Context |

### 与 Tauri 对比
| 特性 | GPUI | Tauri |
|------|------|-------|
| 渲染方式 | 原生 GPU | WebView |
| 性能 | 最高 | 中等 |
| Web 技术栈 | 不支持 | 完整支持 |
| 适用场景 | 高性能应用 | Web 技术栈应用 |

## GPUI 核心优势

1. **性能优先**: 60fps 的流畅体验
2. **类型安全**: 利用 Rust 的类型系统
3. **GPU 加速**: 硬件加速渲染
4. **现代布局**: 基于 Taffy 的 Flexbox 引擎
5. **Tailwind 风格**: 熟悉的实用类优先样式

## 相关资源

### 官方资源
- [GPUI GitHub](https://github.com/zed-industries/zed)
- [GPUI 文档](https://github.com/zed-industries/zed/tree/main/crates/gpui/docs)
- [Zed 编辑器](https://zed.dev)

### 学习资源
- [Rust 官方文档](https://doc.rust-lang.org/)
- [Rust by Example](https://doc.rust-lang.org/rust-by-example/)
- [The Rust Programming Language](https://doc.rust-lang.org/book/)

## 贡献指南

欢迎贡献新的示例或改进现有示例：

1. 遵循现有的代码风格
2. 添加清晰的注释
3. 确保示例可以编译运行
4. 更新文档

## 许可证

本项目仅用于学习目的。GPUI 框架的许可证请参考 Zed 项目。

---

**最后更新**: 2026年1月9日  
**版本**: 0.1.0