| name | tolyui-anchor |
| description | 使用本地 tolyui_anchor 包构建或修改 Flutter 锚点导航。适用于 TolyUI 导航演示或需要 TolyAnchor、TolyAnchorScrollable、TolyAnchorController、锚点链接、滚动监听、自定义 linkBuilder 样式、长锚点列表或横向锚点标签的应用页面。 |
TolyUI Anchor
使用此技能来添加、修复或解释由本地 tolyui_anchor 包提供的锚点导航。
组件架构
flowchart TB
subgraph Controller["TolyAnchorController"]
ISC["ItemScrollController\n(控制滚动)"]
IPL["ItemPositionsListener\n(监听可见项)"]
end
Controller --> Anchor
Controller --> Scrollable
subgraph Anchor["TolyAnchor"]
NAV["导航列表"]
end
subgraph Scrollable["TolyAnchorScrollable"]
CONTENT["内容区域"]
end
Anchor <-.->|"联动"| Scrollable
工作原理
flowchart TD
A["用户滚动内容"] --> B["ItemPositionsListener 检测可见项"]
B --> C["更新 activeIndex\n(取第一个可见项)"]
C --> D["TolyAnchor 收到通知"]
D --> E["更新导航项高亮状态"]
D --> F["滚动导航列表确保激活项可见"]
D --> G["触发 linkBuilder 重新构建"]
工作流程
- 检查目标页面，确认它导入了
package:tolyui_anchor/tolyui_anchor.dart。
- 在
StatefulWidget 中为每对导航/内容区域创建一个 TolyAnchorController。
- 将锚点数据定义为
List<TolyAnchorLink>，其顺序必须与内容项顺序完全匹配。
- 使用
TolyAnchor(controller: ..., links: ...) 渲染导航。
- 使用
TolyAnchorScrollable(controller: ..., itemCount: links.length, itemBuilder: ...) 渲染内容。
- 在
dispose 中释放控制器。
具体的代码模板和本地示例，请阅读 references/usage-patterns.md。
核心类型
classDiagram
class TolyAnchorController {
+int activeIndex
+String? activeTag
+ItemScrollController itemScrollController
+ItemPositionsListener itemPositionsListener
+scrollToIndex(int index)
+jumpToIndex(int index)
+scrollTo(String tag)
+dispose()
}
class TolyAnchorLink {
+String title
+String href
+List~TolyAnchorLink~? children
}
class TolyAnchor {
+TolyAnchorController controller
+List~TolyAnchorLink~ links
+TolyAnchorLinkBuilder? linkBuilder
+Axis scrollDirection
+bool shrinkWrap
+ScrollController? scrollController
}
class TolyAnchorScrollable {
+TolyAnchorController controller
+int itemCount
+IndexedWidgetBuilder itemBuilder
}
TolyAnchorController --> TolyAnchor : 控制
TolyAnchorController --> TolyAnchorScrollable : 控制
TolyAnchor --> TolyAnchorLink : 渲染
实现规则
TolyAnchor 和 TolyAnchorScrollable 必须共用同一个 TolyAnchorController。- 在自定义
linkBuilder 的点击事件中，优先使用 scrollToIndex(index)，因为它直接匹配列表顺序。
- 仅当功能天然基于标签驱动时才使用
scrollTo(href)；href 值由 TolyAnchor 注册。
- 保持
links.length、itemCount 和内容数据长度同步。
- 使用
StatefulWidget 持有控制器。不要在 build 内部创建控制器。
- 对于长左侧导航，向
TolyAnchor 传入专用的 ScrollController(keepScrollOffset: false) 并在 dispose 中释放。
- 对于横向顶部标签，设置
TolyAnchor(scrollDirection: Axis.horizontal, shrinkWrap: true)，通常保持 TolyAnchorScrollable 为竖直方向。
- 通过
linkBuilder(BuildContext context, TolyAnchorLink link, bool active) 添加自定义激活样式。
适用场景
flowchart LR
subgraph Docs["文档阅读"]
D1["API 文档"]
D2["使用指南"]
D3["帮助中心"]
end
subgraph Settings["设置面板"]
S1["系统设置"]
S2["用户配置"]
S3["应用偏好"]
end
subgraph Content["内容导航"]
C1["章节目录"]
C2["文章大纲"]
C3["商品分类"]
end
TolyAnchor --> Docs
TolyAnchor --> Settings
TolyAnchor --> Content
参考文档
references/usage-patterns.md - 使用模式和代码模板references/api-reference.md - API 快速参考references/troubleshooting.md - 常见问题和解决方案
验证
编辑 Flutter 代码后，运行最小范围的检查：
flutter analyze
flutter test
如果是可视化变更，还需运行应用并验证：
- 点击锚点能滚动内容到对应区域。
- 滚动内容能更新激活的锚点。
- 激活的锚点在长导航列表中保持可见。
- 横向标签不会溢出其固定高度的容器。
