gpui-component

请先阅读

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

指南	操作前阅读
设计指南	选择组件、布局、间距、层级、颜色、密度、交互状态、叠加层、界面文案
编码指南	Crate 分层、RenderOnce 与 Entity<T> 的选择、状态所有权、ElementId、焦点、异步、公有 API、测试

这些指南是必须遵守的要求，而不是可有可无的灵感来源。不要照搬通用 Web 惯例，不要根据某个现有界面推断设计系统，也不要仅仅因为底层功能存在就添加控件。完成后，请依据两份指南检查工作，再考虑将其视为完成。

请阅读指南文件本身。不要根据本页的摘要、代码库中的现有界面或训练数据作答——这三种做法都会悄悄导致指南被忽略。

不可妥协的要求

这些只是最低要求，不能替代指南。超出此列表的内容，请查阅指南。

• 绝不臆造 API。 搜索当前源码，确认真实签名。不要类比翻译 React、CSS 或较旧 GPUI 示例——看似合理、实际不存在的方法名是这里最常见的失败原因。
• 优先桌面体验，而非 Web 惯例。 键盘访问、窗口边框、菜单、密集数据视图、可调整大小的区域、持久导航。
• 区分 Button 和 Link。 所有应用内命令都使用 Button——需要弱化显示时使用 ghost 或 outline。Link 仅用于外部 URL 和电子邮件地址。
• 优先使用令牌，而非直接填写数值。 应用 UI 中不得使用原始十六进制颜色值或 rgb(...)；请使用 cx.theme() 语义令牌。使用基于 rem 的辅助函数（p_2()、gap_3()、text_sm()），确保窗口缩放正常工作。引用的任何间距数值都是当前默认比例，不应照抄为固定值。
• 状态必须清晰可见。 悬停、焦点、选中、禁用、加载、验证和破坏性状态都需要各自明确且一致的样式。
• 身份标识必须稳定。 重复元素需要根据领域数据生成 ElementId，不能使用列表索引。
• 叠加层。 按下 Escape 应关闭最上层界面，并将焦点返回其触发控件。
• 文案。 明确指出对象和操作——使用 Delete “Roadmap”? 并配上 Delete 按钮，而不是 Are you sure? 配上 OK。

文档

• 完整参考：获取 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 格式获取

快速参考

设置——始终需要：

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

无状态——直接在 render 中使用：

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

有状态——在结构体中持有 Entity<State>，在 render 中传入引用：

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

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

主题：cx.theme().primary · .background · .foreground · .border · .muted

组件目录

需要组件时，请在此处查找。要查看完整 API，请获取对应的 .md 文档。

输入与表单

组件	导入	说明
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}	表单字段的布局容器

显示与反馈

组件	导入	说明
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	无状态。复制按钮

覆盖层与弹出窗口

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

导航与布局

组件	导入	说明
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	模态窗口的键盘焦点陷阱

数据展示

组件	导入	说明
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	设置面板

图表

组件	导入	说明
Chart	chart::{AreaChart, BarChart, LineChart, PieChart, RadarChart}	柱状图、折线图、面积图、饼图
Plot	plot::Plot	使用 #[derive(IntoPlot)] 处理数据

参考文件

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