06 · 组件一览

本节按用途分类列出当前公开 API 的主路径组件。每个构造函数通常返回 XxxWidget，用 fluent 方法配置；具体签名以当前 go doc 和 ui 包为准。

更完整的交互请直接跑 examples/<name>。

内容

API	说明
Text	文本
Label	标签（可与字段关联）
Description	描述/辅助说明
Image	图片
Avatar	头像
Badge	徽章
Icon	图标（可配合 lucide 包）

ui.Text("标题").Size(20)
ui.Icon(lucide.Plus).Size(16)

按钮与操作

API	说明
Button	按钮（协议样板控件）
ButtonGroup	按钮组
DropdownButton	主操作 + 下拉触发器的组合按钮
ToggleButton	切换按钮
CloseButton	关闭按钮
Chip	芯片/标签按钮

ui.Button("save", ui.Text("保存")).
    Variant(ui.ButtonPrimary).
    Size(ui.ButtonMedium).
    OnClick(func() { send(Save{}) })

ui.Button("del", ui.Text("删除")).
    Variant(ui.ButtonDanger).
    Loading(m.Busy).
    Disabled(m.Busy)

常见 Variant：ButtonPrimary、Secondary、Tertiary、Ghost、Outline、Danger、DangerSoft。

表单

API	说明
Input	单行输入
TextArea	多行
InputGroup	输入组合
InputGroupAction	输入组合的前后缀操作
Checkbox	复选
Switch	开关
RadioGroup	单选组
Select / SelectMultiple / SelectSections	选择器
ComboBox	组合框
DatePicker / 相关日期控件	日期
ColorPicker	颜色
Slider	滑块

受控写法见 07-表单与受控状态。

导航

API	说明
Tabs	标签页
Sidebar	侧栏
Tree	树（含 Filter 等）
Menubar	菜单栏
Menu / ContextMenu	菜单
Pagination	分页
Toolbar	工具栏

Sidebar 用于应用主导航，可通过 SidebarItem.Children 表达多级目的地，并使用 OpenKeys / OnOpenChange 由应用模型受控保存展开状态；InlineIndent 可调整层级缩进， ExpandAction 可选择在展开侧栏中点击或 hover 展开，item 可用 Switcher / ExpandedSwitcher 替换默认箭头。 侧栏折叠时，包含子项的导航项会在右侧弹出其子菜单。Menu 仍用于命令和上下文操作， 文件资源管理器等内容层级使用 Tree。

Tabs 以 TabsSecondary 为常用线型变体，也支持 TabsPrimary 分段样式，以及 TabsSmall、TabsMedium、TabsLarge 尺寸和 TabsTop / TabsBottom / TabsStart / TabsEnd 放置方向。TabItem 可以设置 Leading、 Icon、Content、Trailing、Closable、AccessibleLabel、Description 和 Panel；Tabs 本身可以配置 Leading / Trailing 插槽、OnClose、OnAdd、OnEdit、OverflowTrigger、KeepAlive、ForceRender、 DestroyOnHidden 与独立动画时长：

ui.Tabs("workspace-tabs", model.Active, items).
    Variant(ui.TabsSecondary).
    Size(ui.TabsLarge).
    KeepAlive(true).
    ForceRender(true).
    PanelTransition(ui.TabsPanelFade).
    OnClose(closeTab)

可编辑标签请使用 TabItem.Editable 配合 EditingKey 和 OnEdit； 可关闭标签使用 Closable 配合 OnClose。

KeepAlive(true) 会保留隐藏面板已经创建的控件状态，但不会重新布局隐藏面板； ForceRender(true)（或 Lazy(false)）会在隔离的禁用输入布局中初始化未选中的面板；需要切换后重新创建时， 使用 DestroyOnHidden(true)，它优先于前两者。

当标签不适合当前宽度时，可以使用 Overflow(TabsOverflowMenu) 或 Overflow(TabsOverflowAuto) 把隐藏标签放进可键盘导航的 More 菜单；关闭当前标签会 优先请求下一个可用标签，没有下一个时回退到上一个。TabItem.Editable 配合 EditingKey 和 OnEdit 可受控地进行内联标题编辑；IndicatorWidth 与 IndicatorAlign 可配置指示器长度和对齐方式，Activation(TabsActivationManual) 可启用先移动焦点、再按 Enter/Space 激活的键盘模式。编辑器提交支持 Enter 和失焦，Escape 会取消；当前 Gio 没有独立的 TabList/Tab/TabPanel 语义类， 因此标签使用 Button-compatible 语义，同时为 tab list 和当前面板提供描述、标签及启用状态。

Tree 支持单选、多选、拖放、异步加载、重命名、过滤、复选框树（Checkable、CheckedKeys、HalfCheckedKeys、CheckStrictly）、目录树常见的 ExpandAction 单击/双击展开控制，以及 item 级 Content / Switcher / ExpandedSwitcher 自定义渲染。复选框级联会将 Disabled、DisabledKeys 和 DisableCheckbox 视为关联边界，且不影响这些边界外的父节点推导。DragDisabled / DropDisabled 可分别限制节点作为拖拽源或放置目标；OnDragStart、OnDragEnter、OnDragLeave、OnDragOver、OnDragEnd 提供有效放置目标的拖拽过程事件，最终提交仍使用 OnDrop。OnLoadChildrenEvent 会提供加载 key、是否重试和当前展开状态（旧 OnLoadChildren 仍可用）。FilterFunc 可按业务字段筛选，祖先节点会自动保留；动态谓词配合 FilterVersion 让缓存正确失效。大规模稳定数据应设置 DataVersion，层级或行内容变更时递增该值。扁平数据可通过 TreeItemsFromSimple 转为层级项，未知父 key 会作为根节点处理。

时间轴

TimeLine 对齐 Ant Design Timeline 的常用能力，支持垂直/水平布局、start、end、alternate 模式、filled/outlined 节点、反向排序、pending 节点以及自定义 Widget 内容。ui.Timeline 已用于动画 API，因此 UI 组件使用 ui.TimeLine：

items := []ui.TimeLineItem{
    {Title: ui.Text("创建订单"), Content: ui.Text("订单已提交"), Color: ui.TimeLineBlue},
    {Title: ui.Text("完成支付"), Content: ui.Text("支付成功"), Color: ui.TimeLineGreen},
}
ui.TimeLine(items).Mode(ui.TimeLineAlternate).Variant(ui.TimeLineFilled)

节点颜色可使用 TimeLineBlue、TimeLineRed、TimeLineGreen、TimeLineGray，或通过 Tint 设置自定义颜色。Pending 用于追加尚未完成的末尾事件，PendingLoading 可控制其加载标记，Disabled 可禁用整条时间轴；TitleSpan / TitleWidth、item 级 Placement 和 Gap 可分别控制双栏占比/固定标题宽度、单项落位与圆点到文字的间距。

浮层与反馈

API	说明
Modal	模态框
AlertDialog	确认对话框
Popover	弹出层
Tooltip	提示
Dropdown	下拉
Toast	吐司
Alert	内联警告
Portal	底层视口挂载（高级）

见 09-浮层与弹出。

数据与进度

API	说明
Table	表格
ListBox	列表框
ProgressBar / ProgressCircle	进度
Meter	计量
Spinner	加载指示

图表

API	说明
LineChart	折线
BarChart	柱状
PieChart	饼图
CandlestickChart	K 线
Heatmap	日历/时间热力图
GanttChart	甘特图（任务、依赖、进度、基线）
NodeGraph	节点图画布（节点、端口、连线、平移和缩放）

示例：examples/line_charts、bar_charts、pie_charts、candlestick_charts、heatmaps、gantt_charts。

甘特图的任务编辑、层级折叠和时间窗口契约见 15-甘特图。

节点图的受控视口与当前交互范围见 17-节点图。

布局与壳

API	说明
Box / Row / Column / Grid / Wrap / Stack	布局
Scroll / SplitPane	滚动与分割
DockLayout / DockSplit / DockPanel	可嵌套的工作台分割布局
PanelHost / ViewStack	只负责视图生命周期的面板宿主
Surface / Card	表面与卡片
Overlay	叠层布局
WindowTitleBar / StatusBar	标题栏 / 状态栏
Collapsible	折叠

PanelHost 和 ViewStack 不绘制标签栏，只布局当前视图。使用 KeepAlive(true) 保留隐藏视图的控件状态，使用 ForceRender(true) 在隔离的 隐藏布局中预初始化视图；DestroyOnHidden(true) 会优先释放隐藏状态。

DockLayout 通过 DockPanel 和 DockSplit 描述工作台树。每个分割节点有独立 的拖动比例，可以通过 DockLayoutSnapshot 保存和恢复；MaximizedKey 可以让某个 节点暂时占满工作区，传入空 key 恢复树形布局。标题栏、标签栏以及折叠按钮仍由 外部普通组件提供：

root := ui.DockSplit("workspace", ui.DockHorizontal,
    ui.DockPanel("explorer", explorer),
    ui.DockSplit("editor-bottom", ui.DockVertical,
        ui.DockPanel("editor", editor),
        ui.DockPanel("bottom", bottom),
    ).Ratio(.72),
).Ratio(.24)

ui.DockLayout("workbench", root).
    OnChange(func(snapshot ui.DockLayoutSnapshot) { send(LayoutChanged{snapshot}) })

WorkbenchState 和 WorkbenchController 负责协调标签组、Dock 几何状态与 侧边栏、底部面板、状态栏等壳层区域的可见性，但不保存编辑器缓冲区或视图内容。 使用 BindTabs、BindPanel、BindDock 连接普通组件；通过控制器的 Commands 或 CommandScope 方法安装切换标签、关闭标签和显示/隐藏壳层区域的标准快捷命令。

WorkbenchSnapshot 只持久化稳定的组/标签 key、Dock 几何状态和壳层可见性。 使用 MarshalWorkbenchSnapshot / UnmarshalWorkbenchSnapshot 编解码， key 重命名时通过 WorkbenchMigration 交给 Restore。恢复会在修改状态前 校验完整快照；没有版本号的旧快照不包含壳层字段，因此会保留当前可见性设置。

统一使用习惯

1. Key：有交互的控件第一个参数通常是 key 字符串。
2. 值从 Model 来：Input("name", m.Name)。
3. 变更用 send：OnChange / OnClick 里 send(Msg{...})。
4. 外观用 Style / Variant / Size，不要复制一套私有绘制。
5. Open 状态 遵循 07 的契约。

综合展示

仓库内还有聚合页：

go run ./examples/components

完整的示例截图见组件截图。

自定义控件或领域绘制请参阅自定义组件，其中包含公共的 样式解析、文本测量、画刷、指针和视觉越界辅助 API。

下一步

• 07-表单与受控状态
• 09-浮层与弹出