[RSS1102]

🤔 这个 PR 的性质是？

勾选规则:
1.只要有新增参数，就勾选”新特性提交“
2.只修改内部bug，未新增参数，才勾选”日常 bug 修复“
3.其他选项视具体改动判断

• 日常 bug 修复
• 新特性提交
• 文档改进
• 演示代码改进
• 组件样式/交互改进
• CI/CD 改进
• 重构
• 代码风格优化
• 测试用例
• 分支合并
• 其他

🔗 相关 Issue

来源：从 #1202 拆分，按要求优先处理。无关联 Issue。

本 PR 直接基于 develop 920babc9，不依赖 #1202 或 #1208，可独立审查和合并。#1202 的主题与通用导航问题继续单独处理。

💡 需求背景和解决方案

迁移说明存在重复入口、组件信息难以对照及折叠表格样式缺失。本 PR 整理文档及其必要展示：

• 明确 0.2.7 → 1.0 的版本边界、null 禁用语义和迁移步骤，精简重复说明，不增加专用搜索。
• 57 个组件使用六组直接可见的三列表格；目录保留 14 个主要章节，保留全部显式锚点、12 段示例和 388 项旧类型对照。
• 旧类型附录使用原生 details/summary，读者点击展开；组件行始终可见，避免依赖 fix(site): 修复主题初始化与文档导航状态恢复 #1202 的折叠展开与历史恢复。
• 文档范围内补齐表头、配色、间距、分隔线和列宽；空兼容锚点通过布局为固定页头保留 120px 空间，刷新直达也可见，不修改 Vue Router。
• 独立消费示例增加页签、底部导航和轮播片段；正文与包内 MIGRATION.md 从既有唯一源码同步，增加链接、标题及完整表格检查。

正文源：tdesign-site/site/docs/migration-0.2.7-to-1.0.md；示例源：tdesign-component/example/lib/migration_examples.dart，独立验证：test/migration_consumer/；包内副本由同步脚本生成。Spec：文档体验。没有更改站点依赖、主题初始化、路由或导航模块，也没有新增 Spec 图片。

迁移消费验证项目属于仓库开发基础设施，目录去除 fixtures 中间层，包名统一为 tdesign_migration_consumer。验证项目在 test/migration_consumer/，专用运行器在同目录 run.dart，从自身位置定位仓库，只复制验证输入，支持从仓库外直接运行。文档生成器、测试、GitHub 路径过滤及 GitHub/CNB 共用工具入口同步更新；正文和包内副本逐字节不变。

测试按用途拆分：Example 的 lib/migration_examples.dart 是指南唯一示例源，文档生成器直接读取，独立消费者在运行时复制同一文件，不维护副本；lib/public_api_examples.dart 承载由静态分析检查的公开签名/参数替代示例；运行时只保留 12 项指南交互组合和 4 项 Theme 链/TabBar/Popover/Popup 的独立消费契约。4 项构造类检查改用静态分析，Text/Avatar/Tag 的 3 项重复样式及 1 项仅挂载用例复用既有组件/Demo 回归，运行时用例由 24 项收敛为 16 项。维护与测试边界。

仓库级测试集中在根目录 test/：脚本测试在 test/scripts/，独立消费者在 test/migration_consumer/；迁移专用运行器与测试项目放在同一目录（test/migration_consumer/run.dart），scripts/ 保留通用运行和生成脚本。共用自动化入口及 CI 路径过滤已同步。测试目录说明。

已补齐共享 Golden 字体的“概”（U+6982），同步字符清单并使用原 Noto Sans SC 2.004 / HarfBuzz 11.4.5 重新生成。既有 1182 个码点的轮廓、横纵度量和全局度量保持一致，未修改 Golden 图片。双版本完整 Dart 工具测试各 179/179、7 项脚本测试及文档同步通过。

远端最终验证：提交 bafca4e 的全部检查完成，30 项成功、1 项按条件跳过（同步删除分支）；双版本分析、组件/示例/工具测试、Linux Golden、Android/iOS/Web 构建均通过。主验证流水线：https://github.com/Tencent/tdesign-flutter/actions/runs/40375886822 。未合并 PR。

验证：

• 按 develop 原始锁文件冻结安装；实际为 theme-generator 1.2.7 / site-components 0.18.1，确认没有借用 fix(site): 修复主题初始化与文档导航状态恢复 #1202 的依赖升级。
• 本地站点 42/42 测试及脚本 7/7 测试（合计 49/49）、57 页/360 示例映射、8 份文档同步、生产构建及差异检查通过。
• 本次测试目录迁移后，双版本通过共用入口及本机缓存依赖（临时为 pub get 添加 --offline）复验分析与各 16 项测试；联网依赖解析未完成，未作为通过证据。
• Flutter 3.32.0 / 3.47.7：独立消费者严格分析均无诊断，测试各 16/16；3.32.0 经 CI 共用 shell 入口、3.47.7 从仓库根目录直接运行入口验证；移动后额外确认该文件在 Example 自身配置下分析无诊断。
• 本地生产预览实际验证全部 469 处页内链接、60 个不同跨页/API 目标；表格与 14 项目录渲染完整，刷新直达组件锚点不会遮挡文字。
• 临时负向对照确认：未被调用的公开示例中使用不存在的参数，静态分析仍按 undefined_named_parameter 失败；负向样本不进入仓库。
• 与独立 docs(specs): 清理截图并合并重复验收附件 #1208 组合可干净合并，组合树的应用和文档源码与本分支相同。历史浏览器附件仍绑定原候选，不冒充本次运行记录；本次详细检查结果临时保存，Spec 仅保留摘要。

边界：未部署，未运行完整组件/Golden/设备矩阵；不强行适配手机侧栏和页头，也不声称修复现有站点的历史恢复或通用异步导航。最终远端 CI 按本 PR 新 head 核对。

📝 更新日志

本次为文档与配套验证整理，不改变组件库公开 API 或默认行为。

• 本条 PR 不需要纳入 Changelog

☑️ 请求合并前的自查清单

⚠️ 请自检并全部勾选全部选项。⚠️

• 标题遵循 Conventional Commits 格式：type(<scope>?): 修改描述。
  示例：fix(TBottomTabBar): 修复 iconText 模式底部溢出
• “相关 Issue”处带上修复的 Issue 链接或无关联 Issue
• 已添加对应的 Spec 链接，或已由 Review 确认本次改动无需 Spec
• 相关文档已补充或无须补充

[github-actions]

Web Demo

• web-example

APK 下载

• 下载 APK（ZIP，解压后安装）