gpui-component

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Read This First

请先阅读以下内容

Before changing UI, interaction, interface language, layout, styling, components, or application architecture, read the relevant guide:

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

These guides are requirements, not optional inspiration. Do not copy generic web conventions, infer a design system from one existing screen, or add a control merely because the underlying feature exists. Review the finished work against both guides before considering it complete.

Read the guide file itself. Do not answer from what this page summarizes, from an existing screen in the codebase, or from training data — those are the three ways the guides get quietly ignored.

在修改UI、交互、界面语言、布局样式、组件或应用架构之前，请阅读相关指南：

指南	适用场景
设计指南	选择组件、布局、间距、层级、颜色、密度、交互状态、浮层、界面文案
编码指南	Crate分层、 `RenderOnce` 与 `Entity<T>` 对比、状态归属、 `ElementId` 、焦点处理、异步操作、公共API、测试

这些指南是硬性要求，而非可选参考。请勿照搬通用Web惯例、从单一现有界面推断设计系统，或仅因底层功能存在就添加控件。完成工作后需对照两份指南进行审核，确认无误后方可视为完成。

请直接阅读指南文件内容。请勿根据本页摘要、代码库中现有界面或训练数据作答——这三种方式会导致指南被悄然忽略。

Non-negotiables

不可妥协的原则

These are a floor, not a substitute. Read the guide for anything past this list.

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 name that does not exist is the most common failure mode here.
Desktop before web convention. Keyboard access, window chrome, menus, dense data views, resizable regions, persistent navigation.
Button
vs
Link
.
```
Button
```
for every in-app command — use
```
ghost
```
or
```
outline
```
when it should read quietly.
```
Link
```
only for external URLs and email addresses.
Tokens before values. No raw hex or
```
rgb(...)
```
in application UI; use
```
cx.theme()
```
semantic tokens. Use rem-based helpers (
```
p_2()
```
,
```
gap_3()
```
,
```
text_sm()
```
) so window zoom works. Any spacing number you see quoted is the current default scale, not a literal to repeat.
State must be visible. Hover, focus, selection, disabled, loading, validation, and destructive states each need distinct, consistent treatment.
Stable identity. Repeated elements need domain-derived
```
ElementId
```
s, not list indexes.
Overlays. Escape dismisses the topmost surface and returns focus to its trigger.
Copy. Name the object and the verb —
```
Delete “Roadmap”?
```
with a
```
Delete
```
button, not
```
Are you sure?
```
with
```
OK
```
.

以下是基础要求，不能替代完整指南。超出此列表的内容请查阅指南文件。

切勿自行创造API。在当前源码中查找真实的方法签名。请勿通过类比React、CSS或旧版GPUI示例进行转换——看似合理但实际不存在的方法名是最常见的错误。
优先遵循桌面端惯例。键盘访问、窗口边框、菜单、高密度数据视图、可调整大小区域、持久化导航。
区分
Button
与
Link
。
```
Button
```
用于所有应用内命令——需要低调显示时使用
```
ghost
```
或
```
outline
```
样式。
```
Link
```
仅用于外部URL和邮箱地址。
优先使用令牌而非直接值。应用UI中禁止使用原始十六进制值或
```
rgb(...)
```
；使用
```
cx.theme()
```
语义化令牌。使用基于rem的辅助函数（
```
p_2()
```
、
```
gap_3()
```
、
```
text_sm()
```
）以支持窗口缩放。所有引用的间距数值均为当前默认比例，并非需要重复使用的固定值。
状态必须可见。悬停、焦点、选中、禁用、加载、验证和破坏性状态都需要有清晰一致的处理方式。
保持稳定标识。重复元素需使用领域相关的
```
ElementId
```
，而非列表索引。
浮层处理。按下Esc键可关闭最上层浮层，并将焦点返回至触发它的元素。
文案规范。同时指定对象和动作——例如使用“删除「Roadmap」？”搭配
```
Delete
```
按钮，而非“确定吗？”搭配
```
OK
```
按钮。

Documentation

文档资源

Full reference: fetch

https://longbridge.github.io/gpui-component/llms-full.txt

Per-component API: fetch

https://longbridge.github.io/gpui-component/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://longbridge.github.io/gpui-component/llms-full.txt

单组件API文档：获取

https://longbridge.github.io/gpui-component/docs/components/{name}.md

示例：

button.md

、

input.md

、

select.md

、

dialog.md

、

data-table.md

所有站点页面均可通过在URL后添加
```
.md
```
获取Markdown格式内容

Quick Reference

快速参考

Setup — always required:

rust

gpui_component::init(cx);               // in app.run(), must be first
Root::new(view, window, cx)             // first-level view in every window

Stateless — use directly in render:

rust

Button::new("id").primary().label("OK").on_click(|_, _, _| {})

Stateful — hold

Entity<State>

in struct, pass ref in render:

rust

// in new():  let input = cx.new(|cx| InputState::new(window, cx));
// in render: Input::new(&self.input)

Sizes:

.xsmall()

.small()

.medium()

(default)

.large()

Theme:

cx.theme().primary

.background

.foreground

.border

.muted

配置——必须执行：

rust

gpui_component::init(cx);               // 在app.run()中调用，必须是第一个执行的方法
Root::new(view, window, cx)             // 每个窗口中的顶级视图

无状态组件——可直接在渲染中使用：

rust

Button::new("id").primary().label("OK").on_click(|_, _, _| {})

有状态组件——在结构体中持有

Entity<State>

，并在渲染时传入引用：

rust

// 在new()方法中:  let input = cx.new(|cx| InputState::new(window, cx));
// 在render()方法中: Input::new(&self.input)

尺寸选项：

.xsmall()

.small()

.medium()

（默认）

.large()

主题令牌：

cx.theme().primary

.background

.foreground

.border

.muted

Component Catalog

组件目录

When you need a component, find it here. For full API, fetch its

.md

doc.

需要使用组件时，请在此查找。完整API请查看对应的

.md

文档。

Input & Form

输入与表单

Component	Import	Notes
`Input`	`input::{Input, InputState}`	Stateful. Text, password, mask, validation
`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(
`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. Increment/decrement
`ColorPicker`	`color_picker::{ColorPicker, ColorPickerState}`	Stateful.
`DatePicker`	`date_picker::{DatePicker, DatePickerState}`	Stateful.
`Form`	`form::{v_form, h_form, field}`	Layout container for form fields

组件	导入路径	说明
`Input`	`input::{Input, InputState}`	有状态。支持文本、密码、掩码、验证
`NumberInput`	`input::{NumberInput, NumberInputEvent}`	有状态。带步长的数值输入
`OtpInput`	`input::OtpInput`	有状态。一次性密码输入
`Select`	`select::{Select, SelectState}`	有状态。下拉选择器
`Combobox`	`combobox::{Combobox, ComboboxState}`	有状态。可搜索的选择器
`Checkbox`	`checkbox::Checkbox`	无状态。`on_click(
`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}`	有状态。日期选择器
`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
`Progress`	`progress::{Progress, ProgressCircle}`	Stateless.
`Tooltip`	`tooltip::Tooltip`	Via `.tooltip()` on elements
`HoverCard`	`hover_card::{HoverCard, HoverCardState}`	Stateful.
`Clipboard`	`clipboard::Clipboard`	Stateless. Copy button

组件	导入路径	说明
`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`	无状态。加载占位符
`Progress`	`progress::{Progress, ProgressCircle}`	无状态。进度条/进度环
`Tooltip`	`tooltip::Tooltip`	通过元素的 `.tooltip()` 方法使用
`HoverCard`	`hover_card::{HoverCard, HoverCardState}`	有状态。悬停卡片
`Clipboard`	`clipboard::Clipboard`	无状态。复制按钮

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

组件	导入路径	说明
`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`	带下拉菜单的按钮

Navigation & Layout

导航与布局

Component	Import	Notes
`Tabs` / `TabBar`	`tab::{Tab, TabBar}`	Tabbed interface
`Sidebar`	`sidebar::{Sidebar, SidebarMenu, ...}`	App navigation panel
`TitleBar`	`TitleBar`	Window title 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
`Scrollable`	`scroll::Scrollbar`	Custom scrollbar
`FocusTrap`	`gpui_base::focus_trap::FocusTrapElement`	Keyboard trap for modals

组件	导入路径	说明
`Tabs` / `TabBar`	`tab::{Tab, TabBar}`	标签页界面
`Sidebar`	`sidebar::{Sidebar, SidebarMenu, ...}`	应用导航面板
`TitleBar`	`TitleBar`	窗口标题栏
`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}`	可拖拽分割面板
`Scrollable`	`scroll::Scrollbar`	自定义滚动条
`FocusTrap`	`gpui_base::focus_trap::FocusTrapElement`	模态框的键盘焦点陷阱

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`	设置面板

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)]`

Reference Files

参考文件

usage.md — setup patterns, component types, common examples
style-guide.md — code style for contributors

usage.md — 配置模式、组件类型、常见示例
style-guide.md — 贡献者代码风格指南