GPUI Rust UI 框架上手：5 步搭出你的第一个 GPU 加速窗口-平芜编程栈

GPUI Rust UI 框架上手：5 步搭出你的第一个 GPU 加速窗口

【免费下载链接】zedCode at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.项目地址: https://gitcode.com/GitHub_Trending/ze/zed

GPUI 是一个混合即时模式与保留模式、GPU 加速的 Rust UI 框架，也是 Zed 编辑器底层的 UI 基座。本文用「跑窗口、管状态、画界面、绑快捷键、测试与无障碍」5 步，带你从依赖配不明白走到能自己开窗口、管状态、绑快捷键、接屏幕阅读器。

1️⃣ 先让窗口跑起来

先说清前提：GPUI 处于 pre-1.0 阶段，版本之间经常有破坏性变更，需要配合最新稳定版 Rust 使用，依赖版本要跟随上游而不是锁死旧号。当前仓库里它的版本号是0.2.2，以 Apache-2.0 发布，可以直接当 crates.io 依赖用。

打开 Cargo.toml 写两行依赖，注意两者分工不同：gpui是框架主体，装元素树、布局、状态这些平台无关的东西；gpui_platform是平台后端装配层，按 feature 拼出窗口、渲染、文本后端。一个是脑子，一个是身子。

gpui = { version = "*" } gpui_platform = { version = "*", features = ["font-kit", "wayland", "x11"] }

三平台 feature 组合一次配齐

上面这组是"安全的跨平台默认值"，单平台构建可以裁剪：

macOS：渲染走 Metal，始终可用；需要font-kit做字形光栅化。不开它，GPUI 会退回到一个"占位文本系统"——文本能排版，但一个字形都渲染不出来。
Linux / FreeBSD：至少开wayland或x11之一，否则没有桌面窗口。这两个 feature 会连带编译渲染器和文本系统，不需要再单独开文本 feature。
Windows：不需要任何 feature。窗口走 Win32，文本走 DirectWrite，font-kit在这个平台上无效。

macOS 还有一件事：渲染依赖 Metal，需要从 App Store 或 Apple Developer 装 Xcode 并首次启动装好 macOS 组件，再执行下面两条命令装好并指向命令行工具：

xcode-select --install sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

所有独立 GPUI 应用的入口都一样：gpui_platform::application()按宿主操作系统选好窗口与文本后端（仓库里还有面向 Web 后端的application_with_web_backend），然后给Application::run()传一个回调就启动了。回调里的cx是&mut App，用它open_window开窗并注册根视图：

use gpui::*; use gpui_platform::application; struct HelloWorld { text: SharedString } impl Render for HelloWorld { fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement { // .shadow_lg()/.border_1() 等样式方法从略 div().flex().flex_col() .bg(rgb(0x505050)).size(px(500.0)) .justify_center().items_center() .text_xl().text_color(rgb(0xffffff)) .child(format!("Hello, {}!", self.text)) } } fn main() { application().run(|cx: &mut App| { // 字体加载从略 let bounds = Bounds::centered(None, size(px(500.), px(500.0)), cx); cx.open_window( WindowOptions { window_bounds: Some(WindowBounds::Windowed(bounds)), ..Default::default() }, |_, cx| cx.new(|_| HelloWorld { text: "World".into() }), ).unwrap(); cx.activate(true); }); }

在 Zed 仓库根目录执行cargo run -p gpui --example hello_world，就能看到灰色圆角窗口里的 "Hello, World!"。完整版在 crates/gpui/examples/hello_world.rs。

2️⃣ 状态住在哪里

结论先行：应用里每一个 model 或 view，实际都归同一个顶层对象App所有。你"创建"状态时，是 App 拿走了所有权，你只得到一个句柄。这么设计，状态才能天然参与窗口、通知、事件这些应用级服务，任何实体之间也都能互相通信。完整设定写在 crates/gpui/src/_ownership_and_data_flow.rs 的模块文档里，值得通读一遍。

句柄写作Entity<Counter>：clone 它引用计数加一，drop 减一，像Rc；但和Rc不同，没有App引用就摸不到底层状态——句柄本身只是个惰性标识符加编译期类型标签。

实验一：cx.new创建、update修改。new的第一个参数是创建上下文，回调里构造出状态本体：

let counter: Entity<Counter> = cx.new(|_cx| Counter { count: 0 }); counter.update(cx, |counter, _cx| { counter.count += 1; }); let value = counter.read(cx).count;

注意update回调的第二个参数Context<Counter>：它包装App，额外记录"绑定在哪个实体上"，所以多了notify这类实体级服务；它能解引用成App，凡是接受&mut App的函数也接受它。

实验二：observe+notify观察。想让另一份状态跟着走，先建一个"观察者"实体（first_counter假定已创建）：

let second_counter = cx.new(|cx: &mut Context<Counter>| { cx.observe(&first_counter, |second, first: Entity<Counter>, cx| { second.count = first.read(cx).count * 2; }).detach(); Counter { count: 0 } }); first_counter.update(cx, |counter, cx| { counter.count += 1; cx.notify(); // 通知所有观察者 }); assert_eq!(second_counter.read(cx).count, 2);

两个细节：观察回调拿到的是被观察实体的句柄，读状态要read；observe返回Subscription，.detach()表示订阅存续到任一实体销毁，想提前退订就存下句柄自行 drop。

实验三：subscribe+emit发类型化事件。observe只说"状态变了"，要附带数据就用事件。先声明Counter会发某种事件：

struct CounterChangeEvent { increment: usize } impl EventEmitter<CounterChangeEvent> for Counter {} let second_counter = cx.new(|cx| { cx.subscribe(&first_counter, |second, _first, event, _cx| { second.count += event.increment * 2; }).detach(); Counter { count: 0 } }); first_counter.update(cx, |first, cx| { first.count += 2; cx.emit(CounterChangeEvent { increment: 2 }); cx.notify(); });

顺带一提：实体所有权还能在窗口之间迁移，examples 目录下的move_entity_between_windows就是干这个的验证示例。

3️⃣ 界面怎么画

GPUI 把"画"拆成两层。上层是view：实现了Rendertrait 的实体就是 view（trait 定义在 crates/gpui/src/element.rs）。每帧开始时，GPUI 调用窗口根视图的render方法，你返回一棵元素树。上面HelloWorld就是 view：render收下&mut Window和&mut Context<Self>，返回impl IntoElement。

元素树用div这类元素搭，样式 API 是 Tailwind 风格链式方法：.flex()开弹性布局，.gap_3()设间距，.bg(rgb(0x505050))设背景，.shadow_lg()加阴影，.border_dashed()换虚线边框。完整方法集在 crates/gpui/src/styled.rs。div覆盖面最广，绝大多数布局靠它加文本就够。

下层是Element：元素能完全掌控自己与子元素的渲染方式，换来说就是命令式 API。九成时间你不需要碰它，两个场景例外：

大列表——虚拟化列表只为可见行创建元素，crates/gpui/src/elements/下有现成实现，配uniform_list示例看（cargo run -p gpui --example uniform_list）；
自定义布局——给代码编辑器写专属布局算法时，直接实现Elementtrait，接管 prepaint 和 paint。

实用原则：先用 view + div 写，发现某处慢到或表达不了的，再把那处下沉到 Element，别一上来就全命令式。

4️⃣ 键盘怎么管

GPUI 是键盘优先的框架：给鼠标露功能，画个按钮挂点击处理器；给键盘露功能，就在 key context 里绑定 action。闭环四步：

第一步，定义 action。它就是普通 struct，unit struct 用actions!宏一行搞定：

mod menu { actions!(gpui, [MoveUp, MoveDown]); }

需要字段就用#[gpui::action]标普通 struct，比如Move { direction: Direction, select: bool }，能表达"向上还是向下、是否选中"。

第二、三步，绑处理器并声明上下文。在元素上链.on_action挂处理器，链.key_context("menu")声明这棵子树属于menu上下文：

div() .key_context("menu") .on_action(|this: &mut Menu, _: &MoveUp, window: &mut Window, cx: &mut Context<Menu>| { // 处理"上移" }) .on_action(|this, _: &MoveDown, cx| { // 处理"下移" })

第四步，写 keymap JSON。action 用全限定类型名（模块路径 + 类型名）标识，复杂 action 以[名字, 载荷]数组附带序列化参数：

{ "context": "menu", "bindings": { "up": "menu::MoveUp", "down": "menu::MoveDown", "shift-up": ["menu::Move", { "direction": "up", "select": true }] } }

想看真实规模，assets/keymaps/default-linux.json 一个文件近 1700 行绑定："ctrl-q": "zed::Quit"、"alt-enter": ["picker::ConfirmInput", { "secondary": false }]，还有"Picker || menu"这种"命中任一上下文即生效"的表达式。keymap 解析与上下文匹配在 crates/gpui/src/keymap.rs，整体分发流程见 crates/gpui/src/key_dispatch.rs，配套文档是 crates/gpui/docs/key_dispatch.md。

5️⃣ 让它可靠又包容

用 #[gpui::test] 把行为测下来

#[gpui::test]宏让测试函数直接拿到一个TestAppContext：能做App能做的所有事，还能模拟平台输入；访问不存在的 app 或窗口时它会 panic 而不是给你异步错误，问题更难溜走：

#[gpui::test] fn basic_testing(cx: &mut TestAppContext) { let counter = cx.new(|cx| Counter::new(cx)); counter.update(cx, |counter, _| counter.count = 42); // TestAppContext 不支持 read(cx)，用 read_with let count = counter.read_with(cx, |c, _| c.count); assert_eq!(count, 42); }

需要窗口时用VisualTestContext::from_window包装，每次 update 后窗口都会被绘制，可以断言渲染相关行为，action 分发也和真机一致。测试还能写async，但执行器是单线程的，后台任务要等你await才推进。跑示例测试：cargo test -p gpui --example testing --features test-support；想先看交互效果就cargo run -p gpui --example testing。

text! 的 ID 冲突这样修

GPUI 通过集成 AccessKit 提供程序化无障碍：屏幕阅读器、语音控制能检查并操作你的应用。它建立在两件事上——上报当前 UI 状态和响应辅助动作。

先说 ID。元素可以有id（div().id("my-id")），有 ID 的元素会获得一个GlobalElementId，由祖先链上所有非None的 ID 组合而成。同一帧内全局 ID 重复会出 bug；跨帧全局 ID 相同的节点被辅助技术视为"同一个"节点——屏幕阅读器只在有意义的变化时才播报，所以 ID 就是你对"变化算不算数"的开关。而节点要真正被上报，还必须设置非None的role（按钮、标签、表格等）。

最隐蔽的坑在text!宏：它的 ID 派生自调用处在源码中的位置。下面这段就是典型事故现场：

// 错：map 里只写了一次 text!，所有节点共享同一全局 ID let todo_divs = todos.into_iter().map(|todo| text!(todo)); // 修法一：给每个节点单独设 ID let todo_divs = todos.into_iter().enumerate().map(|(i, todo)| text!(todo).with_id(i)); // 修法二：包一层有唯一全局 ID 的节点 let todo_divs = todos.into_iter().enumerate().map(|(i, todo)| div().id(i).child(text!(todo)));

release 构建下冲突节点会被静默丢弃，排查起来很折磨。反向操作也有：Text::new_inaccessible创建无 ID 的文本，自定义按钮组件常用它——父 div 设 label，避免文字在无障碍树里出现两遍。

再说响应动作。辅助技术把动作派发到特定节点，用.on_a11y_action()应答。注意AccessibleAction与 GPUI 的Actiontrait 完全无关：

div() .id("my-slider") .role(Role::Slider) .on_a11y_action(AccessibleAction::Increment, |_extra, _window, cx| { position += 1; cx.notify(); }) .child(my_cool_slider());

常见动作会自动注册：.on_click()会附一个AccessibleAction::Click处理器去调你的点击逻辑。若你写自定义元素、想让它在无障碍树里"看起来"由多个节点组成（比如本体是Role::TextInput、子节点是一串Role::TextRun），实现Element::a11y_synthetic_children：builder.synthetic_node_id(0)建合成节点，builder.push_child挂接，builder.parent_node().set_text_selection(...)上报光标选区。合成子节点在元素 prepaint 之后添加，可以利用 prepaint 状态按可见范围决定上报多少。

最小可运行示例是 crates/gpui/examples/a11y.rs：cargo run -p gpui --example a11y，里面有计数器（SpinButton 角色加 Increment/Decrement 动作）、开关和待办清单。

6️⃣ 一句话串起来

App持有全部状态，Entity是触达状态的句柄，View 声明式地描述 UI，Element 命令式地控制渲染，Context 是贯穿所有服务的统一接口。抓住这条主线，你在 GPUI 里找任何功能都有落脚处：

主题	入口文件
应用与上下文	crates/gpui/src/app.rs、crates/gpui/src/app/context.rs、crates/gpui/docs/contexts.md
View 与 Element	crates/gpui/src/element.rs、crates/gpui/src/view.rs、crates/gpui/src/styled.rs
内置元素库	crates/gpui/src/elements/
动作与键位分发	crates/gpui/src/action.rs、crates/gpui/src/keymap.rs、crates/gpui/src/key_dispatch.rs
状态所有权文档	crates/gpui/src/_ownership_and_data_flow.rs
无障碍文档	crates/gpui/src/_accessibility.rs
真实 keymap 文件	assets/keymaps/default-linux.json、assets/keymaps/default-macos.json、assets/keymaps/default-windows.json