14 · 常见问题（FAQ）¶

入门¶

只能 import 哪些包？¶

应用：github.com/qianniancn/flowui/ui 测试：github.com/qianniancn/flowui/uitest 禁止：internal/...

Run 和 Application 怎么选？¶

场景	API
单窗口，无论是否有异步能力	`Run(Program)`
多窗口、托盘、窗口生命周期	`Application`

为什么按钮点了没反应？¶

检查：

OnClick 里是否 send(Msg)
Update 是否处理该 Msg
是否给了稳定 Key（Button 第一个参数）
是否 Disabled(true) / 被上层挡住命中

状态¶

可以在 View 里改 Model 吗？¶

不可以。View 只读；变更一律 send → Update。

Context 能存业务数据吗？¶

不要。Context 只有帧服务与交互槽。业务放 Model。UseState 仅瞬态交互。

受控 Select 打不开/关不掉？¶

调用了 Open(m.Open) 就必须：

Model 持有 Open bool
OnOpenChange → send
Update 写入 m.Open

否则属于半受控错误用法。

样式与布局¶

为什么 Gap 不能写在 Style 里？¶

兄弟间距是容器策略，用 Row(...).Gap(8)，不是盒模型属性。

Hover 样式不生效？¶

需要可交互 Host + Key
用 When(ui.Hovered, ...)
纯展示无 Key 的 Box 不保留交互态

主题色改了局部控件却不变？¶

实例 Style 或 Variant 可能覆盖了 Token。检查级联顺序与是否写死了 RGB(...)。

异步¶

Cmd 里能不能用 model 指针？¶

不能。只捕获 Update 时的不可变快照；slice/map 要拷贝。

搜索结果乱序/旧结果覆盖新结果？¶

用 ui.LatestCmd("search", ...)，key 用稳定工作流名。

订阅为什么不自动重跑？¶

结束后 key 会保留且不每帧重启。重试：换 key，或先从 Subscriptions 列表移除再加回。

队列满了？¶

普通消息队列上限 256，溢出报 QueueOverflowError。检查是否在循环里疯狂 send。

自定义组件¶

要抄 Button 源码吗？¶

不要。路径 A 组合；路径 B 使用 UseState、ResolveStyle / ResolveStylePart 和 LayoutInteractiveResolvedStyle。见 10-自定义组件。

自定义绘制如何处理主题色和指针？¶

使用 ResolveColor / ResolveBrush 解析主题值，使用 DrawBrush 绘制渐变；指针交互使用 AddPointerArea、NextPointerEvent、 IsPrimaryPointerPress 和 GrabPointer。局部波纹或焦点装饰可以用 LayoutVisualOverflow；若需要避免外层滚动或分栏视口裁掉，则使用 LayoutVisualOutset 或 VisualOutset 申报安全边距。浮层仍应使用 Popover、Portal 或其他浮层组件。

自绘图表边框花了？¶

外壳归 Style/Host；Canvas 只画内容（路径 C）。

多窗口¶

Open 没开出新窗口？¶

Open 返回 true 表示新窗口已启动；返回 false 表示同 key 的窗口已存在并被前置，或应用当前不接受新窗口。

子窗口 Model 互相串了？¶

initializer 必须每次 return Model{} 新值，不要返回共享指针。

环境¶

最低 Go 版本？¶

1.26.2+（以 go.mod 为准）。

和 Gio 文档冲突听谁的？¶

产品用法听 FlowUI ui 与本教程；Gio 是绘制 substrate。路径 C 才深入 Gio。

文档地图¶

你想…	去
5 分钟跑起来	01-快速开始
理解架构	02-核心概念
写表单	07-表单与受控状态
写异步	08-命令与订阅
写自定义控件	10-自定义组件
架构细节	FlowUI Architecture

示例索引（仓库）¶

examples/counter          最小 MVU
examples/form             受控输入
examples/async            Cmd + Run(Program)
examples/modules          子模块 MapCmd
examples/selects          Select / Open
examples/custom_widgets   路径 B/C
examples/multi_windows    Application
examples/animations       动画
examples/components       组件总览页
examples/grid_layout      固定列数与响应式网格
examples/fonts             系统字体与内置字体
examples/profiling         渲染与内存性能采样

运行：

go run ./examples/counter