06 · 组件一览¶

组件从 github.com/qianniancn/flowui/widget/<组件包> 导入，主构造函数统一为 New，返回 Widget，用链式方法配置。同包里的相关控件保留语义名称，例如 input.TextArea、button.Group；ui 包负责应用运行时。具体签名以组件包的 go doc 为准。

全部组件演示见仓库 examples/showcase：65 个分类页面覆盖全部公开 widget 包，支持搜索、交互、用法代码、默认主题明暗切换和窄窗目录。

FlowUI 组件展示

内容¶

API	说明
`text.New`	文本
`text.NewLabel`	标签（可与字段关联）
`text.NewDescription`	描述/辅助说明
`image.New`	图片
`avatar.New`	头像
`badge.New`	徽章
`icon.New`	图标（可配合 lucide 包）
`code.New`	可选中代码块（Chroma 高亮，可选行号）

text.New("标题").Size(20)
icon.New(lucide.Plus).Size(16)

code.New("sample", "go", source)
code.New("inline", "go", oneLine).LineNumbers(false)

code.New 默认使用 Chroma v2 词法器；多行代码块显示行号，单行自动隐藏，可用 .LineNumbers(true/false) 强制开关。

按钮与操作¶

API	说明
`button.New`	按钮（协议样板控件）
`button.Group`	按钮组
`dropdown.Button`	主操作 + 下拉触发器的组合按钮
`toggle.NewToggleButton`	切换按钮
`button.NewCloseButton`	关闭按钮
`chip.New`	芯片/标签按钮

button.New("保存").
    Primary().
    Size(button.Medium).
    OnClick(func() { send(Save{}) })

button.New("删除").
    Variant(button.Danger).
    Loading(m.Busy).
    Disabled(m.Busy)

常见 Variant：button.Primary、button.Secondary、button.Tertiary、button.Ghost、button.Outline、button.Danger、button.DangerSoft。常用主操作可用 .Primary() 简写 .Variant(button.Primary)；固定宽度可直接用 .Width(dp)，铺满可用宽度用 .FillWidth()。

按钮、切换按钮、Tooltip 和输入框附属操作直接接收字符串；需要图标、带样式的文本或组合布局时使用 .Content(...)：

toggle.NewToggleButton("加粗").Key("bold").Selected(m.Bold).OnChange(setBold)
tooltip.New("save-tip", saveButton, "保存修改")
input.GroupAction("clear", "清空").OnClick(clear)
button.New("保存").Content(icon.New(lucide.Save)).IconOnly()
button.New("保存").Content(text.New("保存").Size(20))

按钮、切换按钮和输入框附属操作的文本同时作为默认无障碍标签；.Content(...) 保留该标签，.Label(...) 可单独覆盖标签而不改变显示内容。卡片、工具栏、弹窗正文和 Popover 等是内容容器，继续接收组件；独立文本仍使用 text.New。

迁移旧代码时，将主构造函数改为 New，把纯文本子组件改为字符串，自定义子组件移到 .Content(...)。input.GroupAction 改为两个参数，自定义第三参数移到 .Content(...)；toast.Toast 改为 toast.NewItem。旧构造函数不再保留。

表单¶

API	说明
`input.New`	单行输入
`input.TextArea`	多行
`input.Group`	输入组合
`input.GroupAction`	输入组合的前后缀操作
`numericinput.New`	数字输入，支持范围、步进与精度
`toggle.NewSegmented`	紧凑的分段单选，支持禁用项与等宽布局
`toggle.NewCheckbox`	复选
`toggle.NewSwitch`	开关
`radiogroup.New`	单选组
`selector.New` / `selector.NewSelectSections`（`SelectedKey` / `SelectedKeys`）	选择器
`combobox.New`	组合框
`datepicker.New` / 相关日期控件	日期
`colorpicker.New`	颜色
`slider.New`	滑块

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

numericinput.New("amount", m.Amount).Range(-100, 100).Step(0.25).
    Precision(2).Label("金额").OnChange(setAmount)

toggle.NewSegmented([]toggle.SegmentedItem{
    {Key: "day", Label: "日"}, {Key: "week", Label: "周"},
}).Key("period").SelectedKey(m.Period).OnChange(setPeriod)

numericinput 的值为 float64，编辑时保留 - 等未完成草稿，回车或失焦时提交；非法输入恢复受控值，加减按钮立即提交。Range 限定边界，Precision 指定小数位数。segmented 只请求切换到其他可用项，再次点击当前项不会取消选中；使用 FillWidth() 等分容器宽度。

导航¶

API	说明
`tabs.New`	标签页
`sidebar.New`	侧栏
`tree.New`	树（含 Filter 等）
`menubar.New`	菜单栏
`menu.New` / `menu.ContextMenu`	菜单
`navigation.NewPagination`	分页
`toolbar.New` / `toolbar.Commands`	组合控件工具栏 / 自适应命令工具栏
`navigation.NewBreadcrumb`	层级路径，祖先可点击，最后一项为当前位置

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

tabs.New 以 tabs.Secondary 为常用线型变体，也支持 tabs.Primary 分段样式，以及 tabs.Small、tabs.Medium、tabs.Large 尺寸和 tabs.Top / tabs.Bottom / tabs.Start / tabs.End 放置方向。tabs.Item 可以设置 Leading、 Icon、Content、Trailing、Closable、AccessibleLabel、Description 和 Panel；Tabs 本身可以配置 Leading / Trailing 插槽、OnClose、OnAdd、OnEdit、OverflowTrigger、KeepAlive、ForceRender、 DestroyOnHidden 与独立动画时长：

tabs.New("workspace-tabs", model.Active, items).
    Variant(tabs.Secondary).
    Size(tabs.Large).
    KeepAlive(true).
    ForceRender(true).
    PanelTransition(tabs.PanelFade).
    OnClose(closeTab)

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

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

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

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

时间轴¶

timeline.New 提供常用的时间线展示能力，支持垂直/水平布局、start、end、alternate 模式、filled/outlined 节点、反向排序、pending 节点以及自定义 Widget 内容。使用方式：

items := []timeline.Item{
    {Title: text.New("创建订单"), Content: text.New("订单已提交"), Color: timeline.ColorBlue},
    {Title: text.New("完成支付"), Content: text.New("支付成功"), Color: timeline.ColorGreen},
}
timeline.New(items).Mode(timeline.ModeAlternate).Variant(timeline.VariantFilled)

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

浮层与反馈¶

API	说明
`modal.New`	模态框
`commandpalette.New`	可搜索的应用命令面板
`alertdialog.New`	确认对话框
`popover.New`	弹出层
`tooltip.New`	提示
`dropdown.New`	下拉
`toast.New`	吐司
`toast.MessageItem`	轻量单行消息（顶部居中、自动消失）
`alert.New`	内联警告
`portal.New`	底层视口挂载（高级）

见 09-浮层与弹出。

commandpalette.New("commands", m.Open, commands).OnOpenChange(setOpen) 复用 []command.Command，搜索名称、描述和 key，支持方向键、回车、Esc、禁用命令和 KeepOpen。按钮、菜单和面板可以共享同一份命令；应用快捷键仍通过 command.Scope 注册。

数据与进度¶

API	说明
`table.New`	表格
`table.NewVirtual`	通过行提供函数按需构建的大数据表格
`listbox.New`	列表框
`progress.Bar` / `progress.Circle`	进度
`progress.Meter`	计量
`spinner.New`	加载指示
`skeleton.New`	内容加载前的占位，支持尺寸、圆形和脉冲动效

skeleton.New().Width(160).Height(16) 创建占位条，Circle().Height(48) 创建圆形占位。默认宽度填满容器；Animated(false) 或主题关闭 Motion 时停止动效刷新。

大量数据可用 layout.List(count, rowAt) 或 table.NewVirtual("table", columns, count, rowAt)，并为滚动区域设置有限高度。虚拟表格的排序由应用在行提供函数中完成。Showcase 的“虚拟列表”“虚拟表格”各演示 10,000 条记录，“树 · 高级操作”演示加载、过滤、勾选、重命名和拖放。

聊天和日志等持续追加内容可在虚拟列表上调用 .FollowEnd()，用户滚离末尾时暂停跟随，返回末尾后自动恢复。

图表¶

API	说明
`linechart.New`	折线
`barchart.New`	柱状
`piechart.New`	饼图
`candlestick.New`	K 线
`heatmap.New`	日历/时间热力图
`gantt.New`	甘特图（任务、依赖、进度、基线）
`nodegraph.New`	节点图画布（节点、端口、连线、平移和缩放）

图表代码为用法片段，需接入自己的应用；相关行为测试位于 widget/ 下对应图表包。

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

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

布局与壳¶

API	说明
`layout.Box` / `layout.Row` / `layout.Column` / `layout.Grid` / `layout.Wrap` / `layout.Stack`	布局
`layout.Scroll` / `splitpane.New`	滚动与分割
`dock.New` / `dock.Split` / `dock.Panel`	可嵌套的工作台分割布局
`surface.NewPanel`	只负责视图生命周期的面板宿主
`surface.New` / `surface.NewCard`	表面与卡片
`layout.Overlay`	叠层布局
`titlebar.New` / `statusbar.New`	标题栏 / 状态栏
`collapsible.New`	折叠
`animation.Tween` / `animation.AnimateLayout`	数值与布局尺寸过渡，遵循主题 Motion 设置

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

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

root := dock.Split("workspace", dock.Horizontal,
    dock.Panel("explorer", explorer),
    dock.Split("editor-bottom", dock.Vertical,
        dock.Panel("editor", editor),
        dock.Panel("bottom", bottom),
    ).Ratio(.72),
).Ratio(.24)

dock.New("workbench", root).
    OnChange(func(snapshot dock.Snapshot) { send(LayoutChanged{snapshot}) })

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

workbench.Snapshot 只持久化稳定的组/标签 key、Dock 几何状态和壳层可见性。使用 workbench.MarshalSnapshot / workbench.UnmarshalSnapshot 编解码；快照必须使用当前 schema 版本，恢复会在修改状态前校验完整快照。

统一使用习惯¶

Key：构造器只接收内容；状态身份默认由构造位置推导，动态重排或需要稳定标识时链式调用 .Key("...")。
值从 Model 来：input.New(m.Name)。
变更用 send：OnChange / OnClick 里 send(Msg{...})。
外观用 Style / Variant / Size，不要复制一套私有绘制。
Open 状态 遵循 07 的契约。

综合展示¶

在仓库根目录运行 go run ./examples/showcase 可浏览全部组件和基本用法。 go run ./examples/showcase 提供默认主题的紧凑预览。

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

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