GPUI Kit 简介

GPUI Kit 是一个基于 GPUI 的综合性 Rust 桌面应用开发框架。依赖名 gpui-pre 指 GPUI Kit 固定版本使用的 GPUI 发布快照，并非另一套渲染框架；详见安装说明。

GPUI Kit 的核心架构包含五个层次：

gpui：底层 UI 运行时，提供 Entity、窗口、Element、布局与渲染。
gpui-kit：应用入口，通过一个依赖重新导出 GPUI，并整合 Base、Component 与默认资源。
gpui-base：无样式的行为、受控状态、Focus、浮层、虚拟列表、Dock 基础设施与语义化设计 token。
gpui-component：即 GPUI Component，完整的带样式组件库，提供 75+ 个有完整文档的组件与原语，以及主题、数据表格、Dock 布局和代码编辑器。
gpui-shell：让 Rust 宿主可以被 JavaScript 扩展，能力逐项授予。

普通应用通过 gpui-kit 使用 GPUI、Base、Component 与默认资源；需要承载 JavaScript 扩展时另行依赖 gpui-shell。它仍是框架核心架构的一层。

使用 gpui-component 可以获得统一、成熟的视觉风格；基于 gpui-base 则可以复用可靠的行为与基础设施，同时创建并拥有自己的设计系统。本节文档介绍 GPUI Kit 的入门配置、公共设计与编码指南，以及应用开发。各层 API 请参阅 GPUI Component、GPUI Base 与 GPUI Shell。

先读 Focus，理解 FocusHandle、Tab 顺序与键盘目标，再读 Action 理解命令派发；KeyBinding 介绍 Action 的绑定与当前快捷键的展示。Event 解释类型化通知以及 Action 与 Event 的关系。

理解核心渲染模型，可先阅读 Entity 和 Context，再阅读 Render、RenderOnce 与 ElementId。 Style 介绍 GPUI 的 fluent 样式方法；Element 与 Paint 解释更底层的绘制。 Task 介绍 callback 返回后仍继续运行的工作。

#按工作顺序学习 GPUI

可以按以下阶段学习。每一阶段都可以先完成一个小任务，再继续下一阶段：

**打开窗口：**按安装和开始使用运行按钮示例，确认点击后终端输出消息。
**持有并更新状态：**创建 Entity，通过 Context 更新它，再用 Render 显示新值。Window 说明更新落在哪个窗口。
**绘制自定义控件：**跟着 Element、Geometry 和 Paint 使用现有 Brush 示例；需要稳定身份或复用时，再看 ElementId 与 View Cache。
**处理输入和持续工作：**先用 Focus 建立键盘目标，再用 Action 或 Event 连接交互；使用 Task 执行异步工作，使用 Animation 构建能正确结束的动效。
**检查应用：**用无障碍和测试核对交互。谈论帧率前先看 FPS Monitor；应用需要相应目标时，再看 WebAssembly 或移动端。

核心页面会区分代码示例与运行结果，并连接后续概念。第一个窗口跑通后，可用编码指南整理所有权和架构约定。

#特性

75+ 组件与原语：覆盖表单、导航、浮层、数据展示、编辑、反馈和布局等场景
生产就绪：在实际桌面应用中持续打磨，并通过 GPUI Kit 的组件与示例不断验证；桌面主路径之外的能力以成熟度标注
WebAssembly：应用与组件示例可通过 wasm32-unknown-unknown 在 Web 中运行
无障碍：交互层内置 AccessKit role、name、state、relationship 与 action
UI 集成测试：在 headless window 中驱动真实鼠标、键盘、Focus、布局与无障碍行为
原生体验：设计灵感来自 macOS 与 Windows 的现代桌面控件
高刷新率支持：在 120 Hz 屏幕上，完整工作负载需要落在约 8.3 ms 的单帧预算内；实际流畅度取决于应用、设备与呈现链路。参阅帧率、刷新率与渲染模式
数据表格：虚拟滚动、固定列、列宽调整、排序与单元格选择，可承载数十万行数据
虚拟列表：只渲染可见区域，并支持不同尺寸的列表项
代码编辑器：20 万行、Tree-sitter 高亮、诊断、补全和悬浮提示
Dock 布局：可调整面板、可拖拽标签、嵌套分割和边缘停靠
丰富内容：原生 Markdown 与 HTML、语法高亮和图表
设计自由：使用完整视觉系统，或基于 gpui-base 构建自己的系统
类型化动效：CSS 对齐的 easing、timing、keyframes、spring、presence 与测量式展开，稳定采样路径零分配
跨平台：通过一份 Rust 代码交付 macOS、Windows 和 Linux

#成熟度

GPUI Kit 的桌面组件运行在包括 Longbridge 在内的生产应用中。其他能力的实践积累还比较短，因此在页面标题下方标注成熟度。没有标注的页面即为“稳定”。

标注	含义
稳定	已用于 macOS、Windows 与 Linux 上的生产桌面应用。
预览	可以使用且有文档。API 与边界行为在后续版本中仍可能调整。
实验性	可以运行，但存在已知缺口。依赖它之前，请针对你的产品验证。
仅用于演示	目前用于在浏览器中演示组件（showcase），不用于交付应用。
依赖平台	可用性或行为因操作系统或目标平台而异，页面会列出差异。

标注描述的是能力本身，而不是文档的完整程度。例如 WebAssembly 运行的是与桌面相同的组件，但目前仅用于组件 showcase 演示，尚不支持在浏览器中交付应用。

#最小示例

按安装说明准备平台依赖后，运行 cargo new gpui-hello 创建项目，再运行 cd gpui-hello 进入目录。在项目的 Cargo.toml 中加入：

[dependencies]
gpui-kit = "0.6"

将 src/main.rs 写成下面的完整程序，运行 cargo run。窗口会显示一段文字和按钮；点击按钮后，终端输出 Clicked!。

use gpui_kit::component::button::{Button, ButtonVariants};
use gpui_kit::*;

struct HelloWorld;

impl Render for HelloWorld {
    fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
        div()
            .flex()
            .flex_col()
            .size_full()
            .items_center()
            .justify_center()
            .gap_2()
            .child("Hello, World!")
            .child(
                Button::new("hello")
                    .primary()
                    .label("Click me")
                    .on_click(|_, _, _| println!("Clicked!")),
            )
    }
}

fn main() {
    application()
        .with_assets(assets::Assets)
        .run(|cx| {
            init(cx);

            open_window(WindowOptions::default(), cx, |_, cx| {
                cx.new(|_| HelloWorld)
            })
            .expect("Failed to open window");
        });
}

下一步跟着开始使用理解初始化、Render 和持久状态，再按上面的学习路线进入绘制与交互。

#下一步

#社区与支持

#许可证

Apache-2.0