gpui-kit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GPUI Kit

Applications depend on one crate,

gpui-kit

. GPUI is

use gpui_kit::*;

, and each layer is reachable by name:

gpui_kit::component

(styled components),

gpui_kit::base

(unstyled behavior),

gpui_kit::assets

(default icons),

gpui_kit::platform

应用程序仅依赖一个crate：

gpui-kit

。GPUI可通过

use gpui_kit::*;

引入，各层级可通过名称直接访问：

gpui_kit::component

（带样式的组件）、

gpui_kit::base

（无样式的行为逻辑）、

gpui_kit::assets

（默认图标）、

gpui_kit::platform

（平台相关模块）。

Read the Guides First

先阅读指南

Two guides hold the rules this skill assumes. They are requirements, not inspiration. Read the guide file itself; do not answer from this page, from a similar file in the codebase, or from training data.

Guide	Read before
Design Guides, skill `gpui-kit-design-guides`	Choosing components, layout, spacing, hierarchy, color, density, interaction states, overlays, motion, interface copy
Coding Guides	Crate layering, `RenderOnce` vs `Entity<T>` , state ownership, `ElementId` , events, focus, async, public API, naming, testing

Read the Design Guides first when the change has a visible surface: code structure preserves product intent, it does not replace it. If the design skill is not installed, fetch

https://gpui-kit.com/docs/design-guides.md

. The coding guide is a verbatim copy of

https://gpui-kit.com/docs/coding-guides.md

, so its links to

./design-guides.md

and

./getting-started.md

mean the design skill and

https://gpui-kit.com/docs/getting-started.md

本技能基于两份指南中的规则，这些规则是硬性要求而非参考建议。请直接阅读指南文件本身，不要基于本页面、代码库中类似文件或训练数据作答。

指南	阅读时机
设计指南（对应技能 `gpui-kit-design-guides` ）	选择组件、布局、间距、层级、颜色、密度、交互状态、覆盖层、动效、界面文案前
编码指南	进行 crate 分层设计、 `RenderOnce` 与 `Entity<T>` 选型、状态所有权分配、 `ElementId` 使用、事件处理、焦点管理、异步操作、公共API设计、命名、测试前

当修改涉及可见界面时，请先阅读设计指南：代码结构是为了实现产品设计意图，而非替代它。若未安装设计技能，可获取

https://gpui-kit.com/docs/design-guides.md

。编码指南是

https://gpui-kit.com/docs/coding-guides.md

的完整副本，因此其中指向

./design-guides.md

和

./getting-started.md

的链接分别对应设计技能和

https://gpui-kit.com/docs/getting-started.md

。

Coding Guides section map

编码指南章节概览

Read the whole guide for a new crate, module, or feature. For a narrow change, read "Architecture at a glance" and "Rules for coding agents" first, then the section for the change (

grep -n '^## ' references/coding-guides.md

Section	Read when
Architecture at a glance	Always; crate layering, ownership boundary
Bootstrap and root ownership	`main` , `init` , `Root` , window creation, app-level state
Understand GPUI's phases and contexts	Anything touching `App` , `Window` , `Context<T>` , render vs update
Choose the right unit	Deciding `RenderOnce` vs `Entity<T>` vs custom `Element`
State ownership	Where a piece of state lives, who mutates it, `Entity<State>` handles
Stable identity	`ElementId` , lists, repeated elements, keyed state
Rendering and composition	`render` , builder chains, `when` / `map` , child composition
Behavior and presentation boundary	`gpui-base` vs `gpui-component` vs application code
Theme and styling	`cx.theme()` , tokens, `Styled` , sizes, variants
Events, actions, and focus	`cx.emit` , `subscribe` , `actions!` , keybindings, `FocusHandle`
Async work and side effects	`cx.spawn` , `background_spawn` , `Task` , I/O, timers
Layout, measurement, and scrolling	Flex layout, sizing, `overflow` , scroll handles, measuring
Lists, tables, and large data	`VirtualList` , `List` , `DataTable` , delegates, large collections
Public API design	Anything `pub` : builders, private fields, setter and reader naming
Platform and capability boundaries	macOS/Windows/Linux/wasm differences, feature gates
File and naming conventions	New files, modules, type and method names, `Kind` suffix, `Context`
Testing strategy	What to test, `#[gpui_kit::test]` , `TestAppContext`
Performance rules	Render cost, allocation, re-render triggers
Common failure modes	Before finishing; invented APIs, state in render, index ids
Rules for coding agents	Always when an agent writes code
Implementation checklist	Before finishing; run every item against the work

若要创建新的crate、模块或功能，请通读完整指南。若仅进行局部修改，请先阅读「架构概览」和「编码代理规则」，再阅读与修改相关的章节（可通过

grep -n '^## ' references/coding-guides.md

查找）。

章节	阅读时机
架构概览	任何场景；crate分层、所有权边界
启动流程与根所有权	`main` 、 `init` 、 `Root` 、窗口创建、应用级状态相关开发
理解GPUI的阶段与上下文	涉及 `App` 、 `Window` 、 `Context<T>` 、渲染与更新的开发
选择合适的单元	决定使用 `RenderOnce` 、 `Entity<T>` 还是自定义 `Element` 时
状态所有权	确定状态存储位置、修改权限、 `Entity<State>` 处理逻辑时
稳定标识	`ElementId` 、列表、重复元素、带键状态相关开发
渲染与组合	`render` 方法、构建器链、 `when` / `map` 、子元素组合相关开发
行为与展示边界	`gpui-base` 、 `gpui-component` 与应用代码的划分
主题与样式	`cx.theme()` 、样式令牌、 `Styled` 、尺寸、变体相关开发
事件、动作与焦点	`cx.emit` 、 `subscribe` 、 `actions!` 、快捷键绑定、 `FocusHandle` 相关开发
异步工作与副作用	`cx.spawn` 、 `background_spawn` 、 `Task` 、I/O操作、定时器相关开发
布局、测量与滚动	Flex布局、尺寸设置、 `overflow` 、滚动句柄、测量相关开发
列表、表格与大数据	`VirtualList` 、 `List` 、 `DataTable` 、委托、大型集合相关开发
公共API设计	任何 `pub` 相关内容：构建器、私有字段、设置器与读取器命名
平台与能力边界	macOS/Windows/Linux/wasm差异、特性门控相关开发
文件与命名规范	创建新文件、模块、类型与方法名称、 `Kind` 后缀、 `Context` 命名时
测试策略	测试内容、 `#[gpui_kit::test]` 、 `TestAppContext` 相关开发
性能规则	渲染成本、内存分配、重渲染触发条件相关优化
常见失败模式	完成开发前；避免自创API、在渲染中存储状态、使用索引作为ID
编码代理规则	当代理编写代码时必须遵守
实现检查清单	完成开发前；对照清单检查所有工作内容

Non-negotiables

不可协商规则

A floor, not a substitute for the guides.

Never invent an API. Search the current source for the real signature. Do not translate a React, CSS, or older-GPUI example by analogy; a plausible-looking method that does not exist is the most common failure.

One dependency. Applications depend on

gpui-kit

alone. GPUI is

use gpui_kit::*;

; the layers are

gpui_kit::component

gpui_kit::base

gpui_kit::assets

gpui_kit::platform

Framework owns behavior, application owns presentation. Do not put colors, sizing, or layout in
```
gpui-base
```
; do not put interaction behavior in application styling code.
Stable identity. Repeated elements need domain-derived
```
ElementId
```
s, not list indexes.
No
pub
fields across the seam. Public data types use builders and reader methods.
Spell
Context
out.
```
cx
```
is GPUI's; name anything else after what it holds.

这些是最低要求，不能替代完整指南。

禁止自创API：在现有源码中查找真实的方法签名。不要通过类比React、CSS或旧版GPUI示例来编写代码；看似合理但实际不存在的方法是最常见的错误。

单一依赖：应用程序仅依赖

gpui-kit

。GPUI通过

use gpui_kit::*;

引入；各层级为

gpui_kit::component

、

gpui_kit::base

、

gpui_kit::assets

、

gpui_kit::platform

。

框架负责行为，应用负责展示：不要在
```
gpui-base
```
中添加颜色、尺寸或布局代码；不要在应用样式代码中添加交互行为逻辑。
稳定标识：重复元素需要基于业务领域生成的
```
ElementId
```
，而非列表索引。
跨边界无
pub
字段：公共数据类型需使用构建器和读取器方法。
Context
需完整拼写：
```
cx
```
是GPUI专用的缩写；其他上下文需根据其存储内容命名。

Documentation

文档

Full reference: fetch
```
https://gpui-kit.com/llms-full.txt
```

Per-component API: fetch

https://gpui-kit.com/docs/components/{name}.md

, e.g.

button.md

input.md

select.md

dialog.md

data-table.md

Any site page can be fetched as Markdown by appending
```
.md
```
to the URL

完整参考文档：获取
```
https://gpui-kit.com/llms-full.txt
```

组件API文档：获取

https://gpui-kit.com/docs/components/{name}.md

，例如

button.md

、

input.md

、

select.md

、

dialog.md

、

data-table.md

网站任意页面：在URL后添加
```
.md
```
即可获取对应Markdown格式文档

Quick Reference

快速参考

Setup and examples: references/usage.md.

rust

use gpui_kit::*;
use gpui_kit::component::Root;

gpui_kit::application()
    .with_assets(gpui_kit::assets::Assets)
    .run(|cx| {
        gpui_kit::init(cx);                       // first, before anything else
        // ... open_window(..., |window, cx| cx.new(|cx| Root::new(view, window, cx)))
    });

Stateless (

RenderOnce

): build in

render

Button::new("save").primary().label("Save").on_click(|_, _, _| {})

Stateful: hold

Entity<State>

in the view, pass a reference in

render

let input = cx.new(|cx| InputState::new(window, cx));

then

Input::new(&self.input)

Sizes:
```
.xsmall()
```
```
.small()
```
```
.medium()
```
(default)
```
.large()
```

Theme:

cx.theme().primary

.background

.foreground

.border

.muted

Overlays:

window.open_dialog(...)

open_sheet(...)

push_notification(...)

via

gpui_kit::component::WindowExt

搭建示例与用法：references/usage.md。

rust

use gpui_kit::*;
use gpui_kit::component::Root;

gpui_kit::application()
    .with_assets(gpui_kit::assets::Assets)
    .run(|cx| {
        gpui_kit::init(cx);                       // 首先执行，其他操作之前
        // ... open_window(..., |window, cx| cx.new(|cx| Root::new(view, window, cx)))
    });

无状态组件（

RenderOnce

）：在

render

中构建：

Button::new("save").primary().label("Save").on_click(|_, _, _| {})

有状态组件：在视图中持有

Entity<State>

，在

render

中传入引用：

let input = cx.new(|cx| InputState::new(window, cx));

然后使用

Input::new(&self.input)

尺寸选项：
```
.xsmall()
```
```
.small()
```
```
.medium()
```
（默认）
```
.large()
```

主题访问：

cx.theme().primary

.background

.foreground

.border

.muted

覆盖层：通过

gpui_kit::component::WindowExt

调用

window.open_dialog(...)

、

open_sheet(...)

、

push_notification(...)

Component Catalog

组件目录

Import paths are relative to

gpui_kit::component::

, so

input::{Input, InputState}

means

use gpui_kit::component::input::{Input, InputState};

. For the full API fetch the component's

.md

doc.

导入路径基于

gpui_kit::component::

，因此

input::{Input, InputState}

表示

use gpui_kit::component::input::{Input, InputState};

。如需完整API，请获取对应组件的

.md

文档。

Input & Form

输入与表单

Component	Import	Notes
`Input`	`input::{Input, InputState}`	Stateful. Text, password, mask, validation
`Textarea`	`input::{Textarea, TextareaState}`	Stateful. Multi-line text
`Editor`	`input::{Editor, EditorState}`	Stateful. Code editor, `tree-sitter` feature
`NumberInput`	`input::{NumberInput, NumberInputEvent}`	Stateful. Numeric with step
`OtpInput`	`input::OtpInput`	Stateful. One-time password
`Select`	`select::{Select, SelectState}`	Stateful. Dropdown picker
`Combobox`	`combobox::{Combobox, ComboboxState}`	Stateful. Searchable select
`Checkbox`	`checkbox::Checkbox`	Stateless. `on_click` receives `&bool`
`Switch`	`switch::Switch`	Stateless. Toggle
`Radio`	`radio::{Radio, RadioGroup}`	Stateless.
`Slider`	`slider::{Slider, SliderState}`	Stateful.
`Toggle`	`button::Toggle`	Stateless.
`Rating`	`rating::Rating`	Stateless.
`Stepper`	`stepper::Stepper`	Stateless. Multi-step progress
`ColorPicker`	`color_picker::{ColorPicker, ColorPickerState}`	Stateful.
`DatePicker`	`date_picker::{DatePicker, DatePickerState}`	Stateful.
`Calendar`	`calendar::{Calendar, CalendarState}`	Stateful. Inline month view
`Form`	`form::{v_form, h_form, field}`	Layout container for form fields

组件	导入路径	说明
`Input`	`input::{Input, InputState}`	有状态。支持文本、密码、掩码、验证
`Textarea`	`input::{Textarea, TextareaState}`	有状态。多行文本输入
`Editor`	`input::{Editor, EditorState}`	有状态。代码编辑器，支持 `tree-sitter` 特性
`NumberInput`	`input::{NumberInput, NumberInputEvent}`	有状态。带步长的数值输入
`OtpInput`	`input::OtpInput`	有状态。一次性密码输入
`Select`	`select::{Select, SelectState}`	有状态。下拉选择器
`Combobox`	`combobox::{Combobox, ComboboxState}`	有状态。可搜索的选择器
`Checkbox`	`checkbox::Checkbox`	无状态。 `on_click` 接收 `&bool` 参数
`Switch`	`switch::Switch`	无状态。开关组件
`Radio`	`radio::{Radio, RadioGroup}`	无状态。单选按钮
`Slider`	`slider::{Slider, SliderState}`	有状态。滑块组件
`Toggle`	`button::Toggle`	无状态。切换按钮
`Rating`	`rating::Rating`	无状态。评分组件
`Stepper`	`stepper::Stepper`	无状态。多步骤进度组件
`ColorPicker`	`color_picker::{ColorPicker, ColorPickerState}`	有状态。颜色选择器
`DatePicker`	`date_picker::{DatePicker, DatePickerState}`	有状态。日期选择器
`Calendar`	`calendar::{Calendar, CalendarState}`	有状态。内联月历视图
`Form`	`form::{v_form, h_form, field}`	表单字段的布局容器

Display & Feedback

展示与反馈

Component	Import	Notes
`Button`	`button::{Button, ButtonGroup}`	Stateless. Primary UI action
`Icon`	`{Icon, IconName}`	Stateless. Lucide icons
`Badge`	`badge::Badge`	Stateless.
`Tag`	`tag::Tag`	Stateless. Closable tags
`Avatar`	`avatar::Avatar`	Stateless.
`Label`	`label::Label`	Stateless. Form label
`Kbd`	`kbd::Kbd`	Stateless. Keyboard key display
`Alert`	`alert::Alert`	Stateless. Info/success/warning/error
`Spinner`	`spinner::Spinner`	Stateless. Loading indicator
`Skeleton`	`skeleton::Skeleton`	Stateless. Loading placeholder
`Shimmer`	`shimmer::{ShimmerText, ShimmerStyle}`	Stateless. Streaming-text shimmer
`Marker`	`marker::{Marker, MarkerVariant}`	Stateless. Inline status marker
`Progress`	`progress::{Progress, ProgressCircle}`	Stateless.
`Tooltip`	`tooltip::Tooltip`	Via `.tooltip()` on elements
`HoverCard`	`hover_card::{HoverCard, HoverCardState}`	Stateful.
`Clipboard`	`clipboard::Clipboard`	Stateless. Copy button
`TextView`	`text::TextView`	`TextView::markdown(id, text)` , HTML too
Image	`gpui_kit::{img, ImageSource, ObjectFit}`	GPUI's `img()` element

组件	导入路径	说明
`Button`	`button::{Button, ButtonGroup}`	无状态。主要UI操作按钮
`Icon`	`{Icon, IconName}`	无状态。Lucide图标库
`Badge`	`badge::Badge`	无状态。徽章组件
`Tag`	`tag::Tag`	无状态。可关闭标签
`Avatar`	`avatar::Avatar`	无状态。头像组件
`Label`	`label::Label`	无状态。表单标签
`Kbd`	`kbd::Kbd`	无状态。键盘按键展示
`Alert`	`alert::Alert`	无状态。信息/成功/警告/错误提示
`Spinner`	`spinner::Spinner`	无状态。加载指示器
`Skeleton`	`skeleton::Skeleton`	无状态。加载占位符
`Shimmer`	`shimmer::{ShimmerText, ShimmerStyle}`	无状态。流式文本闪烁效果
`Marker`	`marker::{Marker, MarkerVariant}`	无状态。行内状态标记
`Progress`	`progress::{Progress, ProgressCircle}`	无状态。进度条/圆形进度组件
`Tooltip`	`tooltip::Tooltip`	通过元素的 `.tooltip()` 方法添加
`HoverCard`	`hover_card::{HoverCard, HoverCardState}`	有状态。悬停卡片
`Clipboard`	`clipboard::Clipboard`	无状态。复制按钮
`TextView`	`text::TextView`	支持 `TextView::markdown(id, text)` ，也可渲染HTML
Image	`gpui_kit::{img, ImageSource, ObjectFit}`	GPUI的 `img()` 元素

Overlay & Popups

覆盖层与弹窗

Component	Import	Notes
`Dialog`	`dialog::Dialog` + `WindowExt`	Via `window.open_dialog(...)`
`AlertDialog`	`WindowExt`	Via `window.open_alert_dialog(...)`
`Sheet`	`sheet::Sheet` + `WindowExt`	Side panel, via `window.open_sheet(...)`
`Notification`	`notification::Notification` + `WindowExt`	Via `window.push_notification(...)`
`Popover`	`popover::Popover`	Floating overlay
`Menu`	`menu::{PopupMenu, DropdownMenu}`	Context menus
`DropdownButton`	`button::DropdownButton`	Button with dropdown menu
`Command`	`command::{Command, CommandState, CommandGroup}`	Stateful. Command palette
Focus trap	`FocusTrapElement`	`.focus_trap(id, &handle)` on a container; `Dialog` and `Sheet` have it built in

组件	导入路径	说明
`Dialog`	`dialog::Dialog` + `WindowExt`	通过 `window.open_dialog(...)` 调用
`AlertDialog`	`WindowExt`	通过 `window.open_alert_dialog(...)` 调用
`Sheet`	`sheet::Sheet` + `WindowExt`	侧边面板，通过 `window.open_sheet(...)` 调用
`Notification`	`notification::Notification` + `WindowExt`	通过 `window.push_notification(...)` 调用
`Popover`	`popover::Popover`	浮动覆盖层
`Menu`	`menu::{PopupMenu, DropdownMenu}`	上下文菜单
`DropdownButton`	`button::DropdownButton`	带下拉菜单的按钮
`Command`	`command::{Command, CommandState, CommandGroup}`	有状态。命令面板
Focus trap	`FocusTrapElement`	在容器上调用 `.focus_trap(id, &handle)` ； `Dialog` 和 `Sheet` 已内置该功能

Navigation & Layout

导航与布局

Component	Import	Notes
`Tabs` / `TabBar`	`tab::{Tab, TabBar}`	Tabbed interface
`Sidebar`	`sidebar::{Sidebar, SidebarMenu, ...}`	App navigation panel
`TitleBar`	`TitleBar`	Window title bar
`StatusBar`	`status_bar::StatusBar`	Window status bar
`Breadcrumb`	`breadcrumb::Breadcrumb`	Navigation breadcrumb
`Pagination`	`pagination::Pagination`	Page navigation
`Accordion`	`accordion::Accordion`	Collapsible sections
`Collapsible`	`collapsible::Collapsible`	Single collapsible
`GroupBox`	`group_box::GroupBox`	Labeled container
`Resizable`	`resizable::{h_resizable, v_resizable, resizable_panel, ResizableState}`	Draggable split panes
`Scrollbar`	`scroll::Scrollbar`	Custom scrollbar

组件	导入路径	说明
`Tabs` / `TabBar`	`tab::{Tab, TabBar}`	标签页界面
`Sidebar`	`sidebar::{Sidebar, SidebarMenu, ...}`	应用导航面板
`TitleBar`	`TitleBar`	窗口标题栏
`StatusBar`	`status_bar::StatusBar`	窗口状态栏
`Breadcrumb`	`breadcrumb::Breadcrumb`	导航面包屑
`Pagination`	`pagination::Pagination`	分页导航
`Accordion`	`accordion::Accordion`	可折叠区域
`Collapsible`	`collapsible::Collapsible`	单个可折叠组件
`GroupBox`	`group_box::GroupBox`	带标签的容器
`Resizable`	`resizable::{h_resizable, v_resizable, resizable_panel, ResizableState}`	可拖拽拆分面板
`Scrollbar`	`scroll::Scrollbar`	自定义滚动条

Data Display

数据展示

Component	Import	Notes
`DataTable`	`table::{DataTable, TableState, TableDelegate}`	Stateful. Full-featured table
`Table`	`table::{Table, ...}`	Simpler table
`VirtualList`	`{v_virtual_list, h_virtual_list}`	High-perf large lists
`List`	`list::{List, ListState, ListDelegate}`	Stateful. Searchable list
`Tree`	`tree::{Tree, TreeState, TreeItem, TreeEntry}`	Stateful. Hierarchy
`DescriptionList`	`description_list::DescriptionList`	Key-value pairs
`Settings`	`setting::Settings`	Settings panel

组件	导入路径	说明
`DataTable`	`table::{DataTable, TableState, TableDelegate}`	有状态。全功能表格
`Table`	`table::{Table, ...}`	简易表格
`VirtualList`	`{v_virtual_list, h_virtual_list}`	高性能大数据列表
`List`	`list::{List, ListState, ListDelegate}`	有状态。可搜索列表
`Tree`	`tree::{Tree, TreeState, TreeItem, TreeEntry}`	有状态。层级树组件
`DescriptionList`	`description_list::DescriptionList`	键值对列表
`Settings`	`setting::Settings`	设置面板

Chat & Messaging

聊天与消息

Component	Import	Notes
`Message`	`message::{Message, MessageContent, MessageAlignment}`	Stateless. Chat message row
`Bubble`	`bubble::{Bubble, BubbleContent, BubbleVariant}`	Stateless. Message bubble
`Attachment`	`attachment::{Attachment, AttachmentContent, ...}`	Stateless. File/media attachment card
`MessageScroller`	`message_scroller::{MessageScroller, MessageScrollerState}`	Stateful. Auto-scrolling message list

组件	导入路径	说明
`Message`	`message::{Message, MessageContent, MessageAlignment}`	无状态。聊天消息行
`Bubble`	`bubble::{Bubble, BubbleContent, BubbleVariant}`	无状态。消息气泡
`Attachment`	`attachment::{Attachment, AttachmentContent, ...}`	无状态。文件/媒体附件卡片
`MessageScroller`	`message_scroller::{MessageScroller, MessageScrollerState}`	有状态。自动滚动消息列表

Charts

图表

Component	Import	Notes
`Chart`	`chart::{AreaChart, BarChart, LineChart, PieChart, RadarChart}`	Bar, line, area, pie charts
`Plot`	`plot::Plot`	`#[derive(IntoPlot)]` for data

组件	导入路径	说明
`Chart`	`chart::{AreaChart, BarChart, LineChart, PieChart, RadarChart}`	柱状图、折线图、面积图、饼图
`Plot`	`plot::Plot`	数据需实现 `#[derive(IntoPlot)]`

GPUI References

GPUI参考文档

Load the file for the mechanism the task touches. Each file starts with a contents line.

Topic	File	Load when
Actions & keybindings	action.md	`actions!` , `bind_keys` , `on_action` , `key_context`
Async & background tasks	async.md	`cx.spawn` , `background_spawn` , `Task` , async I/O
Context management	context.md	`App` , `Window` , `Context<T>` , `AsyncApp`
Custom elements (low-level)	element.md	`Element` trait, `request_layout` , `prepaint` , `paint`
Entity state	entity.md	`Entity<T>` , `WeakEntity` , state management
Events & subscriptions	event.md	`cx.emit` , `cx.subscribe` , `cx.observe`
Focus & keyboard nav	focus-handle.md	`FocusHandle` , `track_focus` , Tab navigation
Global state	global.md	`Global` trait, `cx.set_global` , app-wide config
Layout & styling	layout-style.md	`div()` , `h_flex()` , `v_flex()` , flexbox, overflow, positioning
ElementId	element-id.md	`ElementId` , `.id()` , uniqueness rules, stateful elements
Testing	test.md	`#[gpui_kit::test]` , `TestAppContext` , `VisualTestContext`

Deep dives, for when the topic file is not enough:

Element trait: element-api.md (complete API, hitbox, events) · element-patterns.md (text, interactive, container, composite) · element-examples.md (full examples) · element-best-practices.md (performance, state, pitfalls) · element-advanced.md (custom layouts, async updates, virtual lists)
Entities: entity-api.md (complete API, lifecycle) · entity-patterns.md (model-view, cross-entity, observer) · entity-best-practices.md (memory, performance) · entity-advanced.md (collections, registry, debounce, state machines)
Testing: test-examples.md (organization, setup, assertions, running tests) · test-reference.md (re-entrancy, property tests, mocking)

根据任务涉及的机制加载对应文件，每个文件开头都有目录说明。

主题	文件	加载时机
动作与快捷键绑定	action.md	使用 `actions!` 、 `bind_keys` 、 `on_action` 、 `key_context` 时
异步与后台任务	async.md	使用 `cx.spawn` 、 `background_spawn` 、 `Task` 、异步I/O时
上下文管理	context.md	涉及 `App` 、 `Window` 、 `Context<T>` 、 `AsyncApp` 时
自定义元素（底层）	element.md	实现 `Element` trait、 `request_layout` 、 `prepaint` 、 `paint` 时
实体状态	entity.md	使用 `Entity<T>` 、 `WeakEntity` 、状态管理时
事件与订阅	event.md	使用 `cx.emit` 、 `cx.subscribe` 、 `cx.observe` 时
焦点与键盘导航	focus-handle.md	使用 `FocusHandle` 、 `track_focus` 、Tab导航时
全局状态	global.md	使用 `Global` trait、 `cx.set_global` 、应用级配置时
布局与样式	layout-style.md	使用 `div()` 、 `h_flex()` 、 `v_flex()` 、Flexbox、overflow、定位时
ElementId	element-id.md	使用 `ElementId` 、 `.id()` 、唯一性规则、有状态元素时
测试	test.md	使用 `#[gpui_kit::test]` 、 `TestAppContext` 、 `VisualTestContext` 时

深度解析（当主题文件不足以覆盖需求时）：

Element trait：element-api.md（完整API、点击区域、事件）· element-patterns.md（文本、交互、容器、复合元素模式）· element-examples.md（完整示例）· element-best-practices.md（性能、状态、常见陷阱）· element-advanced.md（自定义布局、异步更新、虚拟列表）
Entities：entity-api.md（完整API、生命周期）· entity-patterns.md（模型-视图、跨实体、观察者模式）· entity-best-practices.md（内存、性能）· entity-advanced.md（集合、注册表、防抖、状态机）
测试：test-examples.md（测试组织、设置、断言、运行测试）· test-reference.md（可重入性、属性测试、模拟）