环境准备#

# 1. 安装 Rust（如果还没有）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 2. 创建新项目
cargo new my-gpui-app
cd my-gpui-app

# 3. 添加 GPUI 依赖
# 编辑 Cargo.toml，添加：
# [dependencies]
# gpui = { git = "https://github.com/zed-industries/zed" }

Hello World#

use gpui::*;

// 定义应用主窗口结构体
// 这是一个零大小类型（ZST），不包含任何状态
// 对于简单的静态内容，使用 ZST 可以优化内存占用
struct HelloWorld;

// 实现 Render trait，这是 GPUI 组件的核心 trait
// 所有可渲染的组件都必须实现这个 trait
impl Render for HelloWorld {
    // render 方法定义了组件如何渲染
    // 参数：
    //   - &mut self: 可变引用，允许在渲染时修改组件状态
    //   - _cx: ViewContext，提供上下文功能，这里暂时不用所以加下划线前缀
    // 返回值：impl IntoElement，任何可以转换为 Element 的类型
    fn render(&mut self, _cx: &mut ViewContext<Self>) -> impl IntoElement {
        div()  // 创建一个 div 容器，类似 HTML 的 <div>
            .flex()  // 使用 Flexbox 布局，等价于 CSS: display: flex
            .items_center()  // 垂直居中对齐，等价于 CSS: align-items: center
            .justify_center()  // 水平居中对齐，等价于 CSS: justify-content: center
            .w_full()  // 宽度100%，等价于 CSS: width: 100%
            .h_full()  // 高度100%，等价于 CSS: height: 100%
            .bg(rgb(0x1e1e1e))  // 背景色，使用十六进制颜色值 #1e1e1e（深灰色）
            .child(  // 添加子元素
                div()
                    .text_3xl()  // 文字大小，等价于 CSS: font-size: 1.875rem (30px)
                    .font_bold()  // 粗体，等价于 CSS: font-weight: bold
                    .text_color(rgb(0xffffff))  // 文字颜色白色 #ffffff
                    .child("Hello, GPUI!")  // 文本内容
            )
    }
}

fn main() {
    // 创建 GPUI 应用实例
    App::new().run(|cx: &mut AppContext| {
        // cx: AppContext 是应用级上下文，管理全局状态和窗口

        // 打开一个新窗口
        // 参数：
        //   1. WindowOptions::default(): 使用默认窗口配置（大小、位置等）
        //   2. 闭包: 接收 WindowContext，返回窗口的根视图
        cx.open_window(WindowOptions::default(), |cx| {
            // cx.new_view 创建一个新的视图实例
            // 闭包参数 _cx 是视图级的上下文，这里不需要所以用下划线
            cx.new_view(|_cx| HelloWorld)
        });
    });
}

代码解析：

1. 链式调用：GPUI 的样式方法都返回 self，可以无限链式调用
2. 类型安全：所有样式、颜色、尺寸都是类型安全的，编译期检查
3. 零成本抽象：这些链式调用在编译后会优化掉，没有运行时开销
4. 声明式 UI：代码直接描述 UI 应该是什么样，而不是如何构建

运行项目：

cargo run

你应该能看到一个黑色背景的窗口，中间显示白色的 “Hello, GPUI!” 文字。

核心特性#

GPUI 是一个专为构建高性能桌面应用而设计的 UI 框架，具有以下核心特性：

1. GPU 加速渲染：使用 Metal（macOS）、DirectX（Windows）等原生图形 API，实现高性能 2D 渲染
2. 声明式 UI：受 React、SwiftUI 等现代框架启发，提供声明式的组件模型
3. 类型安全：Rust 的类型系统确保组件 API 的安全性和正确性
4. 高性能状态管理：基于细粒度的响应式系统，只更新必要的 UI 部分
5. 跨平台支持：统一的 API 抽象，支持 macOS、Linux、Windows

设计理念#

GPUI 的设计哲学可以概括为以下几点：

性能优先 > 易用性 > 灵活性

核心设计原则：

1. 性能优先 每个设计决策都以性能为第一考量。GPUI 直接操作 GPU，避免了传统 Web 技术栈的多层抽象开销。在 Zed 中，即使打开 100 万行的文件，滚动依然保持 60fps 以上。

2. 声明式优于命令式 开发者描述”UI 应该是什么样”而不是”如何构建 UI”。这与 React 的理念一致，但 GPUI 通过 Rust 的零成本抽象，实现了更高的性能。

3. 组合优于继承 通过组合小型组件构建复杂界面。每个组件职责单一，易于测试和维护。

4. 不可变数据 状态更新通过创建新值而非修改旧值。这利用了 Rust 的所有权系统，在编译期就能发现数据竞争问题。

5. 细粒度响应式 类似前端框架的 Signals 机制，GPUI 只更新真正变化的 UI 部分，避免了 React 式的虚拟 DOM diff 开销。

1. Element（元素）#

Element 是 GPUI 中最基础的 UI 单元，类似于 HTML 中的 DOM 节点或 React 中的 Element。

// Element trait 定义了 GPUI 中所有 UI 元素的基本行为
pub trait Element: 'static + IntoElement {
    // 关联类型：布局阶段的状态
    // 用于在布局计算时存储中间数据，如子元素的布局 ID
    // 'static 生命周期要求确保数据在整个程序运行期间有效
    type RequestLayoutState: 'static;

    // 关联类型：预绘制阶段的状态
    // 用于存储绘制前的准备数据，如文本纹理、裁剪区域等
    type PrepaintState: 'static;

    // 第一阶段：布局计算
    // 作用：计算元素及其子元素的尺寸和位置
    // 参数：
    //   - state: 上一次布局的状态（如果有），用于优化重复布局
    //   - cx: 窗口上下文，提供布局引擎和全局状态
    // 返回：
    //   - LayoutId: 布局系统分配的唯一 ID，用于后续阶段引用
    //   - RequestLayoutState: 本次布局的状态，传递给下一阶段
    fn request_layout(
        &mut self,
        state: Option<Self::RequestLayoutState>,
        cx: &mut WindowContext,
    ) -> (LayoutId, Self::RequestLayoutState);

    // 第二阶段：预绘制准备
    // 作用：准备绘制所需的资源，但不实际绘制
    // 参数：
    //   - bounds: 元素的最终边界（位置和尺寸）
    //   - state: 布局阶段传来的状态
    //   - cx: 窗口上下文
    // 返回：PrepaintState，包含绘制所需的所有数据
    //
    // 为什么需要预绘制阶段？
    // 1. 可以在后台线程并行处理（如文本渲染）
    // 2. 避免在绘制时做昂贵的计算
    // 3. 支持增量更新，只重新准备变化的部分
    fn prepaint(
        &mut self,
        bounds: Bounds<Pixels>,
        state: &mut Self::RequestLayoutState,
        cx: &mut WindowContext,
    ) -> Self::PrepaintState;

    // 第三阶段：GPU 绘制
    // 作用：将元素绘制到屏幕
    // 参数：
    //   - bounds: 元素的边界
    //   - state: 布局状态
    //   - prepaint: 预绘制状态
    //   - cx: 窗口上下文，提供绘制 API
    //
    // 这个阶段会生成 GPU 绘制命令，如：
    // - 填充矩形
    // - 绘制文本
    // - 渲染图像
    // - 应用裁剪和变换
    fn paint(
        &mut self,
        bounds: Bounds<Pixels>,
        state: &mut Self::RequestLayoutState,
        prepaint: &mut Self::PrepaintState,
        cx: &mut WindowContext,
    );
}

为什么是三阶段？

这个设计源自游戏引擎和图形系统的最佳实践：

1. Layout（布局） - CPU 密集型，可并行

   • 计算位置和尺寸
   • 处理约束和对齐
   • 生成布局树

2. Prepaint（预绘制） - CPU 和 GPU 交互

   • 生成文本纹理
   • 准备图像资源
   • 计算裁剪区域
   • 可在后台线程执行

3. Paint（绘制） - GPU 密集型

   • 生成绘制命令
   • 批量提交给 GPU
   • 应用变换和混合

Element 的生命周期分为三个阶段：

1. Layout（布局）

   • 计算元素的尺寸和位置
   • 使用 Flexbox 或自定义布局算法
   • 返回 LayoutId 供后续阶段使用
   • 性能关键：只在布局真正改变时重新计算

2. Prepaint（预绘制）

   • 准备绘制所需的资源（纹理、缓冲区等）
   • 处理剪裁区域、变换矩阵
   • 优化：预绘制阶段可以在后台线程执行

3. Paint（绘制）

   • 实际的 GPU 绘制操作
   • 直接调用 Metal/DirectX/Vulkan API
   • 渲染文本、图形、图像等内容
   • 所有绘制命令批处理后一次性提交给 GPU

性能提示：GPUI 的三阶段渲染管线允许并行处理，这是它比传统 UI 框架快的关键原因之一。

2. Component（组件）#

Component 是有状态的 UI 单元，类似于 React 的类组件或函数组件。

pub trait Component: 'static + Sized {
    type State: 'static;

    fn render(
        &mut self,
        view_state: &mut Self::State,
        cx: &mut ViewContext<Self::State>,
    ) -> impl IntoElement;
}

一个简单的计数器组件示例：

use gpui::*;

// ============ 第一步：定义组件状态 ============
// 组件是一个普通的 Rust 结构体，字段就是组件的状态
struct Counter {
    count: usize,  // 计数值，这是组件的唯一状态
}

impl Counter {
    // 构造函数：创建初始状态
    fn new() -> Self {
        Self { count: 0 }
    }

    // ============ 第二步：定义事件处理方法 ============

    // 增加计数
    // 参数：
    //   - &mut self: 可变引用，允许修改组件状态
    //   - _: ClickEvent，点击事件数据（这里不需要所以用 _ 忽略）
    //   - cx: ViewContext，组件的上下文，提供框架功能
    fn increment(&mut self, _: &ClickEvent, cx: &mut ViewContext<Self>) {
        self.count += 1;  // 修改状态

        // ⚠️ 关键：调用 notify() 告诉 GPUI 状态已变化
        // 如果忘记调用，UI 不会更新！
        // notify() 的作用：
        // 1. 标记当前组件为"脏"（需要重新渲染）
        // 2. 触发下一帧的渲染调度
        // 3. 只重新渲染这个组件，不影响其他组件（细粒度更新）
        cx.notify();
    }

    // 减少计数（带边界检查）
    fn decrement(&mut self, _: &ClickEvent, cx: &mut ViewContext<Self>) {
        if self.count > 0 {  // 防止下溢
            self.count -= 1;
            cx.notify();
        }
        // 注意：如果 count == 0，不修改状态也不调用 notify()
        // 这是性能优化：没有状态变化就不触发渲染
    }

    // 重置计数
    fn reset(&mut self, _: &ClickEvent, cx: &mut ViewContext<Self>) {
        self.count = 0;
        cx.notify();
    }
}

// ============ 第三步：实现 Render trait ============
// Render trait 定义组件如何渲染成 UI
impl Render for Counter {
    // render 方法在每次需要渲染时被调用
    // 注意：这个方法应该是纯函数（除了调用 cx）
    // 不应该在这里修改状态或执行副作用
    fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement {
        div()  // 最外层容器
            // === 布局样式 ===
            .flex()  // Flexbox 布局
            .flex_col()  // 垂直排列子元素（column）
            .gap_4()  // 子元素间距 1rem (16px)

            // === 间距和尺寸 ===
            .p_4()  // 内边距 1rem（上下左右）

            // === 颜色和边框 ===
            .bg(rgb(0xffffff))  // 白色背景
            .border_1()  // 1px 边框
            .border_color(rgb(0xe0e0e0))  // 浅灰色边框
            .rounded_lg()  // 圆角 large (8px)
            .shadow_md()  // 中等阴影

            // === 子元素 1：标题 ===
            .child(
                div()
                    .text_2xl()  // 字号 1.5rem (24px)
                    .font_bold()  // 粗体
                    .text_color(rgb(0x333333))  // 深灰色文字
                    .child("Counter Demo")  // 文本内容
            )

            // === 子元素 2：计数显示 ===
            .child(
                div()
                    .text_4xl()  // 大字号 2.25rem (36px)
                    .font_bold()  // 粗体
                    .text_color(rgb(0x007bff))  // 蓝色（Bootstrap primary）
                    .text_center()  // 文字居中
                    // format! 宏：将数字转换为字符串
                    // 每次渲染都会读取最新的 self.count 值
                    .child(format!("{}", self.count))
            )

            // === 子元素 3：按钮组 ===
            .child(
                div()
                    .flex()  // 水平排列按钮
                    .gap_2()  // 按钮间距 0.5rem (8px)

                    // 减少按钮
                    .child(
                        button()
                            .flex_1()  // 均分宽度
                            .child("−")  // 按钮文本

                            // ⚠️ 关键：cx.listener() 创建事件监听器
                            // 它会自动：
                            // 1. 捕获 self（组件引用）
                            // 2. 调用指定的方法（Self::decrement）
                            // 3. 处理生命周期和所有权问题
                            //
                            // 等价于闭包：|event, cx| this.decrement(event, cx)
                            // 但 listener 更高效，编译期生成代码
                            .on_click(cx.listener(Self::decrement))
                    )

                    // 重置按钮
                    .child(
                        button()
                            .flex_1()
                            .child("Reset")
                            .on_click(cx.listener(Self::reset))
                    )

                    // 增加按钮
                    .child(
                        button()
                            .flex_1()
                            .child("+")
                            .on_click(cx.listener(Self::increment))
                    )
            )
    }
}

关键点深入解析：

1. cx.notify() 的重要性

   self.count += 1;  // ✅ 状态改变
   cx.notify();      // ✅ 告诉框架重新渲染

   如果忘记 notify()，状态虽然改变了，但 UI 不会更新！

2. cx.listener() vs 普通闭包

   // ❌ 错误：普通闭包需要手动管理 self
   .on_click(|event, cx| {
       // 这里访问不到 self！
   })
   
   // ✅ 正确：listener 自动绑定 self
   .on_click(cx.listener(Self::increment))

3. impl IntoElement 返回类型

   • 这是一个 trait object，允许返回任何实现了 IntoElement 的类型
   • GPUI 会自动将返回值转换为内部的 Element 类型
   • 编译器会优化掉这些抽象，运行时没有开销

4. 链式调用的本质

   div()        // 创建 Div 对象
       .flex()  // Div.flex(self) -> Self，返回 self
       .p_4()   // Div.p_4(self) -> Self，返回 self

   所有样式方法都返回 self，所以可以无限链式调用

3. ViewContext（视图上下文）#

ViewContext 是组件与框架交互的桥梁，提供了状态管理、事件处理、窗口操作等功能。

impl<V> ViewContext<V> {
    // 通知框架组件需要重新渲染
    pub fn notify(&mut self);

    // 订阅全局事件
    pub fn subscribe<T>(&mut self, handler: impl Fn(&mut V, &T, &mut ViewContext<V>));

    // 创建监听器（自动绑定 self）
    pub fn listener<E>(
        &mut self,
        handler: impl Fn(&mut V, &E, &mut ViewContext<V>),
    ) -> impl Fn(&E, &mut WindowContext);

    // 访问应用状态
    pub fn global<T: 'static>(&self) -> &T;
    pub fn global_mut<T: 'static>(&mut self) -> &mut T;
}

4. Model（模型）#

Model 是 GPUI 的状态容器，用于管理应用数据。它支持细粒度的订阅和更新。

// ============ 定义共享状态 ============
// AppState 是应用级的全局状态
// 多个组件可以共享这个状态
struct AppState {
    theme: Theme,           // 主题设置（深色/浅色）
    user_settings: UserSettings,  // 用户配置
}

// ============ 在组件中使用 Model ============
impl MyComponent {
    // 构造函数：接收 Model<AppState> 作为参数
    // Model<T> 是一个智能指针，包装了 T 并提供响应式功能
    fn new(app_state: Model<AppState>, cx: &mut ViewContext<Self>) -> Self {
        // ⚠️ 关键：使用 observe 订阅状态变化
        // 参数：
        //   1. &app_state: 要观察的 Model
        //   2. 闭包：当 app_state 更新时调用
        //      - this: &mut MyComponent，组件自身的可变引用
        //      - model: &Model<AppState>，状态的引用
        //      - cx: &mut ViewContext，上下文
        cx.observe(&app_state, |this, model, cx| {
            // 读取 Model 中的数据
            // model.read(cx) 返回 &AppState
            // 注意：read 需要传入 cx，用于权限检查
            let state = model.read(cx);

            // 根据新状态更新组件
            this.handle_state_change(state);

            // 通知框架重新渲染
            // 当 app_state 变化时，这个组件也需要更新
            cx.notify();
        })
        .detach();  // ⚠️ 重要：detach() 让订阅在组件销毁时自动取消

        // 保存 Model 引用，以便后续使用
        Self { app_state }
    }
}

Model 的核心概念：

1. 创建 Model

   // 在应用启动时创建全局状态
   let app_state = cx.new_model(|_cx| AppState {
       theme: Theme::Dark,
       user_settings: UserSettings::default(),
   });

2. 读取 Model

   // 需要传入 cx 进行权限检查
   let theme = app_state.read(cx).theme;

3. 更新 Model

   // update 方法接收一个闭包，修改内部数据
   app_state.update(cx, |state, cx| {
       state.theme = Theme::Light;  // 修改状态
       cx.notify();  // 通知所有订阅者
   });

4. 订阅 Model（两种方式）

   // 方式一：observe - 任何更新都触发
   cx.observe(&app_state, |this, model, cx| {
       // app_state 变化时调用
       cx.notify();
   }).detach();
   
   // 方式二：subscribe - 订阅特定事件（需要 Model 实现事件系统）
   cx.subscribe(&app_state, |this, model, event, cx| {
       // 收到特定事件时调用
       match event {
           AppEvent::ThemeChanged => { /* ... */ }
           AppEvent::SettingsChanged => { /* ... */ }
       }
   }).detach();

5. 为什么要 detach()?

   cx.observe(&model, |...| { ... }).detach();
   //                                 ^^^^^^^^
   //                                 这个很重要！

   • observe 返回一个 Subscription 对象
   • detach() 让订阅绑定到组件的生命周期
   • 组件销毁时，订阅自动取消，防止内存泄漏
   • 如果不 detach，需要手动管理订阅的生命周期

Model vs 组件状态

使用建议：

• ✅ 用 Model：主题、用户设置、应用状态、数据库连接
• ✅ 用组件状态：表单输入、局部 UI 状态、临时数据

构建一个待办事项组件#

让我们通过构建一个完整的待办事项（Todo）组件来深入理解 GPUI 的组件开发流程。

use gpui::*;

// ============ Todo 项数据结构 ============
// derive 宏：
//   - Clone: 允许复制（在渲染时需要）
//   - Debug: 支持调试打印，方便开发
#[derive(Clone, Debug)]
struct TodoItem {
    id: usize,        // 唯一标识符，用于删除和切换状态
    text: String,     // 待办内容
    completed: bool,  // 是否已完成
}

// ============ TodoList 组件状态 ============
struct TodoList {
    items: Vec<TodoItem>,  // 所有待办项的列表
    next_id: usize,        // 下一个待办项的 ID（自增）
    input_text: String,    // 输入框的当前文本
}

impl TodoList {
    // 构造函数：初始化空列表
    fn new() -> Self {
        Self {
            items: Vec::new(),
            next_id: 1,  // ID 从 1 开始
            input_text: String::new(),
        }
    }

    // ============ 业务逻辑方法 ============

    /// 添加新的待办项
    /// 参数：
    ///   - text: 待办内容（会检查是否为空）
    ///   - cx: 上下文，用于通知重新渲染
    fn add_item(&mut self, text: String, cx: &mut ViewContext<Self>) {
        // 过滤空白输入
        // trim() 移除首尾空格，is_empty() 检查是否为空
        if !text.trim().is_empty() {
            // 创建新的待办项
            self.items.push(TodoItem {
                id: self.next_id,  // 使用当前 ID
                text,
                completed: false,   // 新项默认未完成
            });

            self.next_id += 1;         // ID 自增，确保唯一性
            self.input_text.clear();   // 清空输入框

            // ⚠️ 关键：通知 GPUI 状态已改变
            // 这会触发重新渲染，显示新添加的项
            cx.notify();
        }
        // 注意：如果输入为空，不做任何操作，也不调用 notify()
        // 这是性能优化：避免无意义的渲染
    }

    /// 切换待办项的完成状态
    /// 参数：
    ///   - id: 要切换的项的 ID
    ///   - cx: 上下文
    fn toggle_item(&mut self, id: usize, cx: &mut ViewContext<Self>) {
        // iter_mut() 获取可变迭代器，允许修改元素
        // find() 查找第一个匹配的元素
        if let Some(item) = self.items.iter_mut().find(|i| i.id == id) {
            // ! 运算符：取反，true -> false, false -> true
            item.completed = !item.completed;
            cx.notify();  // 通知渲染
        }
        // 如果找不到对应 ID 的项，什么都不做
        // 这种情况理论上不应该发生（除非有并发问题）
    }

    /// 删除待办项
    /// 参数：
    ///   - id: 要删除的项的 ID
    ///   - cx: 上下文
    fn delete_item(&mut self, id: usize, cx: &mut ViewContext<Self>) {
        // retain() 保留满足条件的元素，删除不满足的
        // |item| item.id != id 表示：保留 ID 不等于给定 id 的项
        // 等价于：删除 ID 等于给定 id 的项
        self.items.retain(|item| item.id != id);

        cx.notify();  // 通知重新渲染

        // retain 的优势：
        // 1. 一次遍历完成删除
        // 2. 不需要找到索引再删除
        // 3. 可以同时删除多个元素（虽然这里只删一个）
    }
}

impl Render for TodoList {
    fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement {
        div()
            .flex()
            .flex_col()
            .w_full()
            .h_full()
            .p_4()
            .gap_4()
            .bg(rgb(0xffffff))
            // 标题
            .child(
                div()
                    .text_3xl()
                    .font_bold()
                    .child("Todo List")
            )
            // 输入框
            .child(self.render_input(cx))
            // 待办列表
            .child(
                div()
                    .flex()
                    .flex_col()
                    .gap_2()
                    .children(
                        self.items
                            .iter()
                            .map(|item| self.render_todo_item(item, cx))
                    )
            )
            // 统计信息
            .child(self.render_stats())
    }
}

impl TodoList {
    fn render_input(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement {
        div()
            .flex()
            .gap_2()
            .child(
                input()
                    .flex_1()
                    .placeholder("What needs to be done?")
                    .value(self.input_text.clone())
                    .on_input(cx.listener(|this, text: &str, _cx| {
                        this.input_text = text.to_string();
                    }))
                    .on_enter(cx.listener(|this, _event, cx| {
                        let text = this.input_text.clone();
                        this.add_item(text, cx);
                    }))
            )
            .child(
                button()
                    .child("Add")
                    .on_click(cx.listener(|this, _event, cx| {
                        let text = this.input_text.clone();
                        this.add_item(text, cx);
                    }))
            )
    }

    /// 渲染单个待办项
    /// 参数：
    ///   - &self: 组件的不可变引用（只读）
    ///   - item: 要渲染的待办项数据
    ///   - cx: 视图上下文
    /// 返回：一个可以转换为 Element 的类型
    fn render_todo_item(
        &self,
        item: &TodoItem,
        cx: &mut ViewContext<Self>,
    ) -> impl IntoElement {
        // ⚠️ 关键：复制 item.id 到局部变量
        // 为什么？因为闭包需要捕获 ID，而不能直接捕获 &item
        // item 的生命周期只在这个方法内，但闭包可能在之后才执行
        // 复制 ID（usize 是 Copy 类型）解决了这个问题
        let item_id = item.id;

        div()
            .flex()  // 水平排列：[复选框] [文本] [删除按钮]
            .items_center()  // 垂直居中对齐
            .gap_2()  // 子元素间距 0.5rem
            .p_2()   // 内边距 0.5rem
            .rounded_md()  // 中等圆角
            .bg(rgb(0xf5f5f5))  // 浅灰背景

            // ⚠️ 交互式样式：hover 伪类
            // hover() 接收一个闭包，返回鼠标悬停时的样式
            // |style| 参数是当前样式，可以在此基础上修改
            .hover(|style| style.bg(rgb(0xeeeeee)))  // 悬停时背景变深

            // === 子元素 1：复选框 ===
            .child(
                checkbox()
                    .checked(item.completed)  // 根据状态显示选中/未选中

                    // ⚠️ 重点：on_change 事件处理
                    // listener 创建的闭包会捕获组件的可变引用
                    // move 关键字：将 item_id 移动到闭包内（因为 ID 是 Copy 类型，实际是复制）
                    .on_change(cx.listener(move |this, _event, cx| {
                        // this: &mut TodoList，组件的可变引用
                        // _event: 事件数据（这里不需要）
                        // cx: 上下文
                        // item_id: 从外部作用域捕获的 ID

                        this.toggle_item(item_id, cx);
                        // 调用 toggle_item，它内部会调用 cx.notify()
                    }))
            )

            // === 子元素 2：待办文本 ===
            .child(
                div()
                    .flex_1()  // 占据剩余空间（让删除按钮靠右）

                    // ⚠️ 条件样式：when() 方法
                    // 只有当 item.completed == true 时才应用额外样式
                    // 这是性能优化：避免创建不必要的样式对象
                    .when(item.completed, |div| {
                        div
                            .line_through()  // 删除线
                            .text_color(rgb(0x888888))  // 灰色文字
                    })

                    .child(&item.text)  // 显示待办文本
                    // 注意：&item.text 是 &String 引用
                    // GPUI 会自动将其转换为文本元素
            )

            // === 子元素 3：删除按钮 ===
            .child(
                button()
                    .child("Delete")  // 按钮文字
                    .text_color(rgb(0xff0000))  // 红色文字（提示危险操作）

                    // 点击事件处理
                    // 同样使用 move 捕获 item_id
                    .on_click(cx.listener(move |this, _event, cx| {
                        this.delete_item(item_id, cx);
                    }))
            )
    }

### 样式系统

GPUI 提供了类似 Tailwind CSS 的链式样式 API：

```rust
div()
    // 布局
    .flex()                 // display: flex
    .flex_col()             // flex-direction: column
    .gap_4()                // gap: 1rem
    .items_center()         // align-items: center
    .justify_between()      // justify-content: space-between

    // 尺寸
    .w_full()               // width: 100%
    .h(px(200.))           // height: 200px
    .min_w(px(100.))       // min-width: 100px

    // 间距
    .p_4()                  // padding: 1rem
    .px_2()                 // padding-left/right: 0.5rem
    .m_auto()               // margin: auto

    // 颜色
    .bg(rgb(0xffffff))     // background-color
    .text_color(rgb(0x000000))

    // 边框
    .border_1()             // border-width: 1px
    .border_color(rgb(0xcccccc))
    .rounded_lg()           // border-radius: large

    // 文字
    .text_xl()              // font-size: xl
    .font_bold()            // font-weight: bold
    .line_height(relative(1.5))

    // 交互状态
    .hover(|style| style.bg(rgb(0xf0f0f0)))
    .active(|style| style.scale(0.95))

局部状态 vs 全局状态#

GPUI 支持两种状态管理方式：

struct Counter {
    count: usize,  // 组件私有状态
}

impl Render for Counter {
    fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement {
        div().child(format!("Count: {}", self.count))
    }
}

// 定义全局状态
#[derive(Clone)]
struct AppSettings {
    theme: Theme,
    font_size: f32,
}

// 在应用启动时初始化
cx.set_global(AppSettings {
    theme: Theme::Dark,
    font_size: 14.0,
});

// 在组件中访问
impl Render for MyComponent {
    fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement {
        let settings = cx.global::<AppSettings>();
        div().text_size(px(settings.font_size))
    }
}

Model 状态容器#

对于复杂的共享状态，使用 Model：

struct EditorState {
    text: String,
    cursor_position: usize,
    selection: Option<Range<usize>>,
}

impl EditorState {
    fn insert_text(&mut self, text: &str, cx: &mut ModelContext<Self>) {
        self.text.insert_str(self.cursor_position, text);
        self.cursor_position += text.len();
        cx.notify(); // 通知订阅者
    }
}

// 创建 Model
let editor_state = cx.new_model(|_cx| EditorState {
    text: String::new(),
    cursor_position: 0,
    selection: None,
});

// 在组件中使用
struct Editor {
    state: Model<EditorState>,
}

impl Editor {
    fn new(state: Model<EditorState>, cx: &mut ViewContext<Self>) -> Self {
        // 订阅状态变化
        cx.observe(&state, |_this, _model, cx| {
            cx.notify(); // 状态变化时重新渲染
        }).detach();

        Self { state }
    }
}

1. 内置事件#

button()
    .on_click(cx.listener(|this, event: &ClickEvent, cx| {
        this.handle_click(event, cx);
    }))
    .on_mouse_down(cx.listener(|this, event: &MouseDownEvent, cx| {
        this.handle_mouse_down(event, cx);
    }))

2. 自定义事件#

// 定义事件
struct ItemSelected {
    item_id: usize,
}

// 发送事件
cx.emit(ItemSelected { item_id: 42 });

// 订阅事件
cx.subscribe(&some_view, |this, _view, event: &ItemSelected, cx| {
    this.handle_item_selected(event.item_id, cx);
}).detach();

3. 键盘事件#

div()
    .on_key_down(cx.listener(|this, event: &KeyDownEvent, cx| {
        match event.key.as_str() {
            "Enter" => this.submit(cx),
            "Escape" => this.cancel(cx),
            _ => {}
        }
    }))

1. 避免不必要的渲染#

// ❌ 不好：每次都创建新对象
impl Render for MyComponent {
    fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement {
        let items = self.fetch_items(); // 每次渲染都重新计算
        div().children(items)
    }
}

// ✅ 好：缓存计算结果
struct MyComponent {
    items_cache: Vec<Item>,
    items_dirty: bool,
}

impl Render for MyComponent {
    fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement {
        if self.items_dirty {
            self.items_cache = self.fetch_items();
            self.items_dirty = false;
        }
        div().children(&self.items_cache)
    }
}

2. 使用 when/when_some 条件渲染#

div()
    .when(show_header, |div| {
        div.child(render_header())
    })
    .when_some(optional_content, |div, content| {
        div.child(content)
    })

3. 虚拟化长列表#

对于大量数据（如 10000+ 条记录），只渲染可见部分，极大提升性能。

use gpui::*;

/// 虚拟化列表组件
/// 适用场景：需要显示大量数据，但一次只能看到几十条
/// 原理：只渲染视口内的项，其他项用占位空间代替
struct VirtualList {
    items: Vec<String>,    // 所有数据（可能有几千甚至几万条）
    scroll_offset: f32,    // 当前滚动位置（像素）
    viewport_height: f32,  // 视口高度（可见区域高度）
    item_height: f32,      // 每一项的固定高度（虚拟化需要固定高度）
}

impl Render for VirtualList {
    fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement {
        // ============ 第一步：计算可见范围 ============

        // 计算第一个可见项的索引
        // 例如：scroll_offset=1000px, item_height=50px
        //       start_index = floor(1000/50) = 20
        //       意味着第 20 项开始可见
        let start_index = (self.scroll_offset / self.item_height).floor() as usize;

        // 计算可见项的数量
        // 例如：viewport_height=600px, item_height=50px
        //       visible_count = ceil(600/50) + 1 = 13
        //       +1 是缓冲区，防止滚动时闪烁
        let visible_count = (self.viewport_height / self.item_height).ceil() as usize + 1;

        // 计算最后一个可见项的索引
        // min() 确保不超过数组边界
        let end_index = (start_index + visible_count).min(self.items.len());

        // ============ 第二步：构建虚拟化容器 ============

        div()
            // 固定视口高度
            .h(px(self.viewport_height))

            // 允许垂直滚动
            .overflow_y_scroll()

            // ⚠️ 关键：监听滚动事件
            // 每次滚动都会更新 scroll_offset，触发重新计算可见范围
            .on_scroll(cx.listener(|this, event, cx| {
                this.scroll_offset = event.scroll_top;  // 记录滚动位置
                cx.notify();  // 触发重新渲染（只渲染新的可见项）
            }))

            .child(
                // ============ 第三步：创建占位容器 ============
                div()
                    // ⚠️ 关键：设置容器总高度
                    // 总高度 = 项数 × 每项高度
                    // 这让滚动条显示正确的比例
                    // 例如：10000 项 × 50px = 500000px 总高度
                    .h(px(self.items.len() as f32 * self.item_height))

                    // 相对定位，作为绝对定位子元素的参考
                    .relative()

                    // ============ 第四步：只渲染可见项 ============
                    .children(
                        // 切片：只取可见范围的数据
                        self.items[start_index..end_index]
                            .iter()
                            .enumerate()  // 获取索引和值
                            .map(|(i, item)| {
                                // 计算原始索引（在完整列表中的位置）
                                let index = start_index + i;

                                div()
                                    // ⚠️ 关键：绝对定位
                                    // 每一项的位置根据索引计算，而不是自然排列
                                    .absolute()

                                    // 计算垂直位置
                                    // top = 索引 × 每项高度
                                    // 例如：第 20 项，top = 20 × 50px = 1000px
                                    .top(px(index as f32 * self.item_height))

                                    // 设置项高度（必须固定）
                                    .h(px(self.item_height))

                                    // 显示内容
                                    .child(item.clone())
                            })
                    )
            )
    }
}

虚拟化原理图解：

假设有 10000 项数据，每项高度 50px

┌─────────────────────────┐
│ 滚动条                   │ ← 总高度 500000px (10000 × 50px)
│ ▓                       │
│ ░                       │ ← 当前滚动到 30% 位置
│ ░                       │
│ ░                       │
└─────────────────────────┘

视口（600px 高度）：
┌─────────────────────────┐
│ [项 600]               │ ← start_index = 600
│ [项 601]               │
│ [项 602]               │
│ ...                    │ ← 只渲染 13 个 DOM 节点！
│ [项 611]               │
│ [项 612]               │ ← end_index = 612
└─────────────────────────┘

未虚拟化：需要 10000 个 DOM 节点
虚拟化后：只需要 ~13 个 DOM 节点
性能提升：约 750 倍！

性能对比：

使用限制：

1. ✅ 要求固定高度

   item_height: f32,  // 每项必须相同高度

   如果高度不固定，虚拟化会很复杂

2. ✅ 需要切片支持

   self.items[start..end]  // Vec 必须支持切片

3. ✅ 不适合嵌套滚动 虚拟化列表中再嵌套虚拟化列表会导致问题

优化技巧：

1. 增加缓冲区

   let visible_count = (...).ceil() as usize + 3;  // +3 而不是 +1
   // 好处：滚动更流畅，但多渲染几个 DOM 节点

2. 防抖滚动事件

   .on_scroll(cx.listener(|this, event, cx| {
       // 只在滚动 > 10px 时更新
       if (event.scroll_top - this.scroll_offset).abs() > 10.0 {
           this.scroll_offset = event.scroll_top;
           cx.notify();
       }
   }))

3. 估算容器高度（当数据量极大时）

   // 不精确计算所有项的高度
   .h(px(self.estimated_total_height))
   // 滚动时动态调整估算值

实际应用场景：

• ✅ 日志查看器（数万条日志）
• ✅ 大数据表格
• ✅ 聊天记录列表
• ✅ 文件浏览器（大目录）
• ✅ 代码编辑器（长文件）

这就是为什么 Zed 能流畅打开百万行文件！

GPUI vs Electron#

GPUI vs Tauri#

GPUI vs SwiftUI/Jetpack Compose#

GPUI 的设计理念与 SwiftUI、Jetpack Compose 类似，都是声明式 UI 框架：

// GPUI
div()
    .flex()
    .child(text("Hello"))

// SwiftUI
VStack {
    Text("Hello")
}

// Jetpack Compose
Column {
    Text("Hello")
}

但 GPUI 的优势在于：

• 跨平台：一套代码支持多平台
• 性能：更接近底层的渲染控制
• Rust 的优势：内存安全、并发安全

渲染流程#

用户交互 → 状态更新 → cx.notify() → 标记为脏 → 下一帧渲染
    ↓
Layout Pass（布局计算）
    ↓
Prepaint Pass（准备绘制数据）
    ↓
Paint Pass（GPU 绘制）
    ↓
Present（呈现到屏幕）

与 React 对比#

与 Signals 的相似之处#

GPUI 的响应式机制与前端框架的 Signals 非常相似：

// GPUI 的 Model 类似 Signals
let model = cx.new_model(|_| MyData { value: 0 });

// 订阅变化（类似 createEffect）
cx.observe(&model, |this, model, cx| {
    // 当 model 更新时自动调用
    println!("Value changed: {}", model.read(cx).value);
}).detach();

// 更新数据
model.update(cx, |data, cx| {
    data.value += 1;
    cx.notify(); // 触发订阅者
});

相比 React 的 useState，GPUI 的 Model 更像 Solid.js 的 Signal：只有真正使用数据的地方才会更新。

GPUI vs 现代前端框架的响应式系统#

关键差异：

• GPUI 需要显式调用 cx.notify()，但换来了零运行时开销和编译期保证
• React 最简单但性能最差，需要手动优化（memo, useMemo）
• Solid/Vue 自动追踪依赖，性能好但有运行时开销
• GPUI 是唯一在编译期完全类型检查的方案

1. 可复用的按钮组件#

fn custom_button(
    label: impl Into<String>,
    on_click: impl Fn(&ClickEvent, &mut WindowContext) + 'static,
) -> impl IntoElement {
    div()
        .px_4()
        .py_2()
        .bg(rgb(0x007bff))
        .text_color(rgb(0xffffff))
        .rounded_md()
        .cursor_pointer()
        .hover(|style| style.bg(rgb(0x0056b3)))
        .active(|style| style.scale(0.95))
        .on_click(move |event, cx| on_click(event, cx))
        .child(label.into())
}

// 使用
custom_button("Click me", |_event, _cx| {
    println!("Button clicked!");
})

2. 输入框组件#

struct Input {
    value: String,
    placeholder: String,
    on_change: Option<Box<dyn Fn(String)>>,
}

impl Input {
    fn new() -> Self {
        Self {
            value: String::new(),
            placeholder: String::new(),
            on_change: None,
        }
    }

    fn value(mut self, value: impl Into<String>) -> Self {
        self.value = value.into();
        self
    }

    fn placeholder(mut self, text: impl Into<String>) -> Self {
        self.placeholder = text.into();
        self
    }

    fn on_change<F>(mut self, handler: F) -> Self
    where
        F: Fn(String) + 'static,
    {
        self.on_change = Some(Box::new(handler));
        self
    }
}

impl Render for Input {
    fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement {
        div()
            .w_full()
            .px_3()
            .py_2()
            .border_1()
            .border_color(rgb(0xcccccc))
            .rounded_md()
            .bg(rgb(0xffffff))
            .child(&self.value)
    }
}

3. 加载中状态#

struct LoadingSpinner;

impl Render for LoadingSpinner {
    fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement {
        div()
            .flex()
            .items_center()
            .justify_center()
            .w(px(40.))
            .h(px(40.))
            .child(
                div()
                    .w(px(30.))
                    .h(px(30.))
                    .border_4()
                    .border_color(rgb(0x007bff))
                    .rounded_full()
                    // 添加旋转动画
                    .animate()
            )
    }
}

// 在组件中使用
div()
    .when(is_loading, |div| {
        div.child(LoadingSpinner)
    })
    .when_some(data, |div, data| {
        div.child(data_view(data))
    })

4. 模态框组件#

struct Modal {
    is_open: bool,
    title: String,
    content: String,
}

impl Render for Modal {
    fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement {
        div()
            .when(self.is_open, |div| {
                div
                    // 遮罩层
                    .absolute()
                    .top_0()
                    .left_0()
                    .w_full()
                    .h_full()
                    .bg(rgba(0x000000, 0.5))
                    .flex()
                    .items_center()
                    .justify_center()
                    // 模态框内容
                    .child(
                        div()
                            .bg(rgb(0xffffff))
                            .rounded_lg()
                            .p_6()
                            .shadow_xl()
                            .min_w(px(400.))
                            .child(
                                div()
                                    .text_xl()
                                    .font_bold()
                                    .mb_4()
                                    .child(&self.title)
                            )
                            .child(
                                div()
                                    .mb_4()
                                    .child(&self.content)
                            )
                            .child(
                                div()
                                    .flex()
                                    .justify_end()
                                    .gap_2()
                                    .child(
                                        button()
                                            .child("Close")
                                            .on_click(cx.listener(|this, _, cx| {
                                                this.is_open = false;
                                                cx.notify();
                                            }))
                                    )
                            )
                    )
            })
    }
}

5. 列表组件（带虚拟滚动）#

struct VirtualizedList<T> {
    items: Vec<T>,
    item_height: f32,
    viewport_height: f32,
    scroll_offset: f32,
}

impl<T: Clone> VirtualizedList<T> {
    fn new(items: Vec<T>, item_height: f32) -> Self {
        Self {
            items,
            item_height,
            viewport_height: 600.,
            scroll_offset: 0.,
        }
    }

    fn render_item(&self, item: &T, index: usize) -> impl IntoElement {
        // 子类实现
        div()
            .h(px(self.item_height))
            .child(format!("Item {}", index))
    }
}

impl<T: Clone + 'static> Render for VirtualizedList<T> {
    fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement {
        let start_index = (self.scroll_offset / self.item_height).floor() as usize;
        let visible_count = (self.viewport_height / self.item_height).ceil() as usize + 2;
        let end_index = (start_index + visible_count).min(self.items.len());

        div()
            .h(px(self.viewport_height))
            .overflow_y_scroll()
            .on_scroll(cx.listener(|this, event, cx| {
                this.scroll_offset = event.scroll_top;
                cx.notify();
            }))
            .child(
                div()
                    .h(px(self.items.len() as f32 * self.item_height))
                    .relative()
                    .children(
                        self.items[start_index..end_index]
                            .iter()
                            .enumerate()
                            .map(|(i, item)| {
                                let index = start_index + i;
                                div()
                                    .absolute()
                                    .top(px(index as f32 * self.item_height))
                                    .w_full()
                                    .child(self.render_item(item, index))
                            })
                    )
            )
    }
}

1. 开启调试模式#

cx.set_debug_mode(true);  // 显示布局边界，帮助调试布局问题

2. 性能分析#

use std::time::Instant;

impl Render for MyComponent {
    fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement {
        let start = Instant::now();
        let element = self.build_ui(cx);
        let duration = start.elapsed();

        // 如果渲染超过 16ms（60fps），输出警告
        if duration.as_millis() > 16 {
            log::warn!("Slow render: {:?}", duration);
        }

        element
    }
}

3. 结构化日志#

use tracing::{info, debug, warn, error};

// 在关键位置添加日志
impl MyComponent {
    fn handle_event(&mut self, event: &Event, cx: &mut ViewContext<Self>) {
        debug!(?event, "Handling event");

        match self.process_event(event) {
            Ok(_) => info!("Event processed successfully"),
            Err(e) => error!(?e, "Failed to process event"),
        }

        cx.notify();
    }
}

4. 内存使用监控#

use std::alloc::{GlobalAlloc, Layout, System};
use std::sync::atomic::{AtomicUsize, Ordering};

// 自定义全局分配器，跟踪内存使用
struct TrackingAllocator;

static ALLOCATED: AtomicUsize = AtomicUsize::new(0);

unsafe impl GlobalAlloc for TrackingAllocator {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
        let ret = System.alloc(layout);
        if !ret.is_null() {
            ALLOCATED.fetch_add(layout.size(), Ordering::SeqCst);
        }
        ret
    }

    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
        System.dealloc(ptr, layout);
        ALLOCATED.fetch_sub(layout.size(), Ordering::SeqCst);
    }
}

#[global_allocator]
static GLOBAL: TrackingAllocator = TrackingAllocator;

// 查看内存使用
println!("Allocated: {} bytes", ALLOCATED.load(Ordering::SeqCst));

1. 组件设计原则#

• 单一职责：每个组件只做一件事
• 小而专：大组件拆分成多个小组件
• 可复用：抽取通用逻辑到独立组件
• 无副作用：render 方法应该是纯函数（除了 cx 调用）

2. 状态管理建议#

• 就近原则：状态定义在使用它的最近父组件
• 不可变更新：状态更新创建新值而非修改旧值
• 避免过度订阅：只订阅必要的状态变化

3. 性能优化清单#

• ✅ 使用 when 条件渲染避免无用计算
• ✅ 大列表使用虚拟化
• ✅ 缓存昂贵的计算结果
• ✅ 避免在 render 中进行 I/O 操作
• ✅ 使用 cx.notify() 控制更新时机

1. 组件不更新怎么办？#

问题： 修改了状态，但 UI 没有更新。

原因： 忘记调用 cx.notify()

// ❌ 错误：UI 不会更新
fn update_data(&mut self) {
    self.data = "new value".to_string();
    // 忘记通知框架
}

// ✅ 正确：调用 notify
fn update_data(&mut self, cx: &mut ViewContext<Self>) {
    self.data = "new value".to_string();
    cx.notify(); // 告诉 GPUI 需要重新渲染
}

2. 如何在组件间通信？#

方案一：通过 Model 共享状态

// 创建共享状态
let shared_data = cx.new_model(|_| SharedData::new());

// 组件 A 持有并修改
struct ComponentA {
    data: Model<SharedData>,
}

impl ComponentA {
    fn update_shared(&mut self, cx: &mut ViewContext<Self>) {
        self.data.update(cx, |data, cx| {
            data.value += 1;
            cx.notify();
        });
    }
}

// 组件 B 订阅并显示
struct ComponentB {
    data: Model<SharedData>,
}

impl ComponentB {
    fn new(data: Model<SharedData>, cx: &mut ViewContext<Self>) -> Self {
        cx.observe(&data, |_this, _model, cx| {
            cx.notify(); // 数据变化时重新渲染
        }).detach();

        Self { data }
    }
}

方案二：通过事件系统

// 定义事件
struct DataChanged {
    new_value: String,
}

// 组件 A 发送事件
cx.emit(DataChanged {
    new_value: "hello".to_string(),
});

// 组件 B 订阅事件
cx.subscribe(&component_a, |this, _emitter, event: &DataChanged, cx| {
    this.handle_data_change(&event.new_value, cx);
}).detach();

3. 性能优化：如何避免过度渲染？#

使用 when 和 when_some 条件渲染

div()
    // 只有 show_panel 为 true 时才创建子元素
    .when(show_panel, |div| {
        div.child(expensive_panel_component())
    })
    // 只有数据存在时才渲染
    .when_some(optional_data, |div, data| {
        div.child(data_view(data))
    })

缓存昂贵的计算

struct MyComponent {
    data: Vec<Item>,
    filtered_cache: Vec<Item>,
    filter_dirty: bool,
}

impl Render for MyComponent {
    fn render(&mut self, cx: &mut ViewContext<Self>) -> impl IntoElement {
        // 只在需要时重新计算
        if self.filter_dirty {
            self.filtered_cache = self.data
                .iter()
                .filter(|item| item.matches_filter())
                .cloned()
                .collect();
            self.filter_dirty = false;
        }

        div().children(&self.filtered_cache)
    }
}

4. 如何处理异步操作？#

use futures::StreamExt;

impl MyComponent {
    /// 从 API 获取数据（异步操作）
    /// 这个方法演示了如何在 GPUI 中处理异步任务
    fn fetch_data(&mut self, cx: &mut ViewContext<Self>) {
        // ============ cx.spawn() 创建异步任务 ============
        // spawn 接收一个闭包，返回 Future
        // 参数：
        //   - this: WeakView<MyComponent>，组件的弱引用
        //     为什么是弱引用？防止循环引用导致内存泄漏
        //     如果组件被销毁，弱引用会失效，任务自动取消
        //   - mut cx: AsyncAppContext，异步上下文
        //     提供异步环境下的框架功能
        cx.spawn(|this, mut cx| async move {
            // ============ 执行异步操作 ============
            // await 异步等待 API 调用完成
            // ? 运算符：如果失败，提前返回错误
            let data = fetch_from_api().await?;

            // ⚠️ 关键：从异步上下文更新组件
            // this.update() 尝试获取组件的强引用并更新
            // 如果组件已销毁，update 会安全地失败（返回 Err）
            this.update(&mut cx, |this, cx| {
                // 这个闭包在主线程执行，可以安全修改组件状态

                this.data = data;  // 更新组件状态
                cx.notify();       // 触发重新渲染

                Ok(())  // 返回 Result，表示更新成功
            })
        })
        .detach();  // ⚠️ detach() 让任务在后台运行
                    // 不 detach 的话，需要手动管理 Future 的生命周期
    }
}