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("...")（默认身份由构造位置推导） - 是否
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
- 用
On(style.Hovered, ...) - 纯展示无 Key 的 Box 不保留交互态
主题色改了局部控件却不变？¶
实例 Style 或组件 Variant 可能覆盖了主题预设值。检查级联顺序与是否写死了 RGB(...)。
异步¶
Cmd 里能不能用 model 指针？¶
不能。只捕获 Update 时的不可变快照；slice/map 要拷贝。
搜索结果乱序/旧结果覆盖新结果？¶
用 ui.LatestCmd("search", ...)，key 用稳定工作流名。
订阅为什么不自动重跑？¶
结束后 key 会保留且不每帧重启。重试：换 key，或先从 Subscriptions 列表移除再加回。
队列满了？¶
普通消息队列上限 256，溢出报 QueueOverflowError。检查是否在循环里疯狂 send。
自定义组件¶
要抄 Button 源码吗？¶
不要。路径 A 组合；路径 B 使用 UseState、resolve.Resolve / resolve.ResolvePart
和 layout.InteractiveResolved（解析入口在 style/resolve 子包，不在 style）。
见 10-自定义组件。
自定义绘制如何处理主题色和指针？¶
使用 resolve.Color / resolve.Brush 解析主题值，使用 draw.Fill 绘制渐变；
指针交互使用 AddPointerArea、NextPointerEvent、
IsPrimaryPointerPress 和 GrabPointer。局部波纹或焦点装饰可以用
layout.VisualOverflow；若需要避免外层滚动或分栏视口裁掉，则使用
layout.VisualOutset 或 style.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 |
示例¶
默认主题示例位于当前 module 的 examples/。在仓库根目录执行
go run ./examples/counter、go run ./examples/buttons、go run ./examples/inputs
或 go run ./examples/showcase。其他设计风格及其示例已迁入独立主题模块，
接入方法见 默认主题与外部风格。