[RSS1102]

🤔 这个 PR 的性质是？

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

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

🔗 相关 Issue

无关联 Issue。发布准备整理独立交付于 #1169；本 PR 仅收口版本。

💡 需求背景和解决方案

将组件1.0.0-alpha.1和Demo展示1.0.0-alpha.5统一为1.0.0。Demo pubspec 已为1.0.0+1，保留原构建号和历史构建时间，正式构建仍由既有工具写入元数据。Android实际versionCode仍由现有日期策略生成。

当前head 7d3cb3e 的CodeCC已通过：check116424269590，严重漏洞数0。最新develop完整test-build run38733652355亦全部通过。最终候选改变后须重新核对。

基于 develop 596e013；不混入组件修复、测试/快照、CI或文档目录整理。Spec：075 版本升级。

验证：Flutter3.32.0真实Git工作区与3.47.7隔离副本的pub publish --dry-run均通过、0 warnings、归档464KB；迁移宿主两SDK各21项通过、严格分析零问题，版本来源一致。

本PR保持草稿。合并release/分支会触发现有tag工作流；须先关闭#1169收录的Token、设备/设计及候选来源门槛，并确认最终head的CodeCC，核对自动生成发布说明，再同步最终develop并完成最终head全矩阵。当前没有上传pub.dev、创建tag或更新正式APK。

查看整理后的完整发布说明候选稿（待最终核对）

1.0.0 发布说明候选稿（本轮文档核对后）

从自动生成评论6192136199整理；合并重复主题文档记录、移除2条Spec元数据、修正Others中的fix/breaking分组，补齐已合入的反色主题与稀疏深色JSON修复。尚需在最终候选核对全部内容与0.2.7迁移说明；这份预览不确认正式发布，不触发CHANGELOG写入。

🚨 Breaking Changes

• 图标迁移到TIcon和外部包TIcons；0.0.6不提供旧list、video_camera_3、video_camera_3_filled同名常量，旧all改为allIconsMap，旧私有图标数据name及字体身份不作为兼容契约。具体替代选择见迁移指南，不能直接复制旧字体码点。(#967)
• Popup使用TPopupOptions与TPopupHandle，打开、关闭和结果由公开句柄管理，不继续复用旧面板和路由类。 (#946)
• Picker、DateTimePicker、Calendar只处理选择；旧静态弹出入口、默认Popup、Header及业务确认流程改由TPickerPopup或TPopup组合，按受控值回写并分别处理确认和取消。 (#921) (#926) (#942) (#953)
• 主题复制统一为copyWith(name: ..., spacerMap: ...)，移除旧复制包装、ofColor/ofFont/ofCorner/ofFontFamily/ofShadow/ofExtra及公开parseThemeData；copyWith/lerp返回TThemeData，并修正默认值和引用链过渡。 (#1152)
• 最低环境为Flutter3.32.0、Dart3.8.0，移除历史Flutter版本适配依赖。 (#976)
• 全库从0.2.7的TD入口迁到T入口与当前Widget/Theme组合，旧构造、样式与辅助类型不保留兼容别名；按迁移指南逐组件处理，不能批量改名前缀后直接上线。 (#907) (#967)
• TSwipeCell: 打开/关闭阈值默认由面板宽度 50% 调整为 30% @RSS1102 (#1021)
• TSwipeCell: 展开/收起动画默认时长由 200ms 调整为 600ms @RSS1102 (#1021)
• TSwipeCell: 操作项图标大小默认由 18 调整为 20、图标-文字间距默认由 2 调整为 8、新增面板左右内边距默认 16 @RSS1102 (#1021)
• TSwipeCell: 移除 flutter_slidable 依赖；TSwipeCellController 收敛为 open(side) / close()；删除二次确认、拖拽移除、互斥组等历史 API @RSS1102 (#1021)
• TPullDownRefresh: 新增最小化、Flutter 模式的下拉刷新组件作为推荐入口；移除低层 TRefreshHeader 与 TRefreshThemeData（旧入口不再可用，需迁移到 TPullDownRefresh） @RSS1102 (#1029)
• TPullDownRefresh: 默认 loadingBarHeight=50、maxBarHeight=80，触发阈值与官方对齐（由原先 48 调整为 50，默认渲染高度有变化） @RSS1102 (#1029)
• TFab: 默认动作层固定为 large/fill/primary，纯图标为圆形、图文为胶囊形，并使用 TDesign add 图标、spacer4 与 shadowsMiddle 投影 @RSS1102 (#1040)
• TFab: 父级 TButtonThemeData 不再影响默认动作层，完整视觉自定义请使用 TFab.child @RSS1102 (#1040)
• TFab: 调整 TFabBounds 边界语义（right/bottom 坐标系下 start/end 物理方向映射）并新增非负有限值校验 @RSS1102 (#1040)
• TText: 普通文本与富文本统一对齐 Flutter 原生 Text 契约，内容参数改为必填 @RSS1102 (#1042)
• TText: 移除组件内字体下载、块背景、线性缩放、独立 package 及全局配置入口，改用 Flutter 原生组合 @RSS1102 (#1042)
• TDivider: 对齐默认线条、文字、间距和垂直尺寸 @RSS1102 (#1044)
• TLink: 移除互斥 variant，改为可独立组合的下划线和前后图标，并统一链接尺寸、语义颜色、交互状态及无障碍行为 @RSS1102 (#1043)
• Search: 收敛搜索框取消按钮、自动聚焦和样式相关 API，请迁移到 actionText、onActionPressed、autofocus 与 TSearchBarThemeData @RSS1102 (#1051)
• TFormField: 移除 rules 校验入口，统一通过 validator 定义字段约束 @RSS1102 (#1038)
• TInput: 移除 label、multiline、showClearButton 和 decoration，统一表单标签、多行输入、清除按钮及视觉配置入口 @RSS1102 (#1038)
• TTextarea: 移除 Material decoration 透传，由组件主题管理容器和输入视觉 @RSS1102 (#1038)
• upload: 使用统一文件点击回调 TUpload.onFileTap 取代 onPreview / onRetry @RSS1102 (#1047)
• TSwitch: 将加载状态迁移为独立的 loading 参数，移除 TSwitchVariant.loading @RSS1102 (#1050)
• checkbox: 带文案的普通 TCheckbox 默认最小高度按档位调整为 48dp / 56dp / 64dp（默认 medium 单行 56dp），纯指示器仍遵循 Material 点击热区，卡片模式保持 56dp / 82dp；依赖旧行高的使用方需显式控制高度。 @RSS1102 (#1048)
• checkbox: TCheckbox 默认指示器由方形调整为圆形，依赖方形指示器的使用方需通过 TCheckboxThemeData(variant: TCheckboxVariant.square) 显式配置。 @RSS1102 (#1048)
• checkbox: TCheckbox 与 TCheckboxGroup 在普通模式下默认显示分割线（原默认不显示），末项不绘制分割线，卡片模式不绘制分割线；依赖原无分割线布局的使用方需显式传入 showDivider: false。 @RSS1102 (#1048)
• checkbox: TCheckbox 主标题默认最大行数由 1 调整为 3，副标题默认最大行数由 1 调整为 5，超出后省略；依赖原单行显示的使用方需显式传入 titleMaxLines: 1 或 subTitleMaxLines: 1。 @RSS1102 (#1048)
• checkbox: Checkbox 主标题与副标题颜色不再继承 Material TextTheme 的颜色值，改由 TCheckboxThemeData.titleColor / subTitleColor 或 TDesign 语义 token 解析；依赖通过 TextTheme 设置 Checkbox 文字颜色的使用方需改用 TCheckboxThemeData 显式配置。 @RSS1102 (#1048)
• checkbox: 横向卡片模式（cardMode: true 且 direction: Axis.horizontal）角标尺寸由 28dp 调整为 24dp，勾选图标由 14dp 调整为 12dp；纵向卡片不受影响。 @RSS1102 (#1048)
• radio: 默认选中标记由圆点调整为 TDesign 实心勾选图标，并新增 TRadioIconType 与 TRadio.iconType / TRadioGroup.iconType 参数 @RSS1102 (#1049)
• radio: 默认主标题 / 副标题最大行数由 1 行调整为 3 / 5 行，TRadioGroup 新增标题行数与图标样式透传 @RSS1102 (#1049)
• radio: TRadio 与 TRadioGroup 默认显示分割线，显式关闭方式保持不变，卡片模式不显示分割线 @RSS1102 (#1049)
• rate: 移除 TRateThemeData.showText，评分文案统一由 TRate.texts 控制 @RSS1102 (#1056)
• rate: 整星点击、长按和拖动默认显示评分提示，新增 showValueIndicator: false 以关闭该提示 @RSS1102 (#1056)
• popup: 蒙层配置统一迁移到 TPopupOverlayConfig，原六个蒙层散参（showOverlay、closeOnOverlayClick、overlayColor、overlayOpacity、modal、onOverlayClick）不再从 TPopupOptions 暴露 @RSS1102 (#1037)
• popup: bottom 和 center 默认只展示 child，不再自动展示头部或关闭按钮；标题与操作请通过 headerBuilder 组合 TPopupHeader @RSS1102 (#1037)
• popup: 移除 titleWidget、cancelBuilder、confirmBuilder，bottom 头部内容请通过 headerBuilder + TPopupHeader 组合 @RSS1102 (#1037)
• popup: 移除 onOpen、onClose 与 TPopupTrigger.cancel/confirm，请使用 onVisibleChange / onOpened / onClosed 代替 @RSS1102 (#1037)
• popup: left/right 默认改为无圆角全高矩形；如需圆角可显式设置 radius 或 TPopupThemeData.panelRadius @RSS1102 (#1037)
• popup: useSafeArea 默认改为 false，Popup 默认贴合屏幕边缘；需要原安全区避让行为时请显式开启 @RSS1102 (#1037)
• TTag: 删除 TTagThemeData.colorScheme；原 TTagThemeData(colorScheme: value) 改为在每个 TTag(..., colorScheme: value) 或 TSelectTag(..., colorScheme: value) 实例中传入 @RSS1102 (#1058)
• TPopover: 删除 TPopoverThemeData.colorScheme；原 TPopoverThemeData(colorScheme: value) 改为在 TPopover.showPopover(..., colorScheme: value) 或 TPopoverWidget(..., colorScheme: value) 调用中传入 @RSS1102 (#1058)
• TTag: 删除 TTagThemeData.isLight/isOutline；改为在 TTag 或 TSelectTag 实例中传入 variant：false/false → dark、true/false → light、false/true → outline、true/true → lightOutline（顺序为 isLight/isOutline） @RSS1102 (#1058)
• TPopover: 将 TPopoverColorScheme.dark/info/error 分别改为 defaultTheme/primary/danger；light/success/warning 无需修改，视觉效果不变 @RSS1102 (#1058)
• TNoticeBar: left 迁移为 prefix，prefixIcon: IconData 迁移为 prefix: Icon(...)；prefix 为 null 时显示 status 默认图标，传入 SizedBox.shrink() 可隐藏前缀 @RSS1102 (#1032)
• TNoticeBar: 移除 TNoticeBarVariant 与 TNoticeBarThemeData.variant，状态改由实例 TNoticeBar.status（TNoticeBarStatus）驱动 @RSS1102 (#1032)
• TNoticeBar: right 迁移为 operation，并允许与 suffixIcon 共存 @RSS1102 (#1032)
• TNoticeBar: interval 默认值由 3 秒调整为 2 秒；垂直轮播改由 direction + items 驱动，items 非空时优先于 content @RSS1102 (#1032)
• popover: String content / contentWidget 统一为必填的 required Widget content @RSS1102 (#1033)
• popover: placement 可省略，默认使用 TPopoverPlacement.top @RSS1102 (#1033)
• popover: TPopoverWidget 不再从包入口公开，统一通过 TPopover.showPopover 使用 @RSS1102 (#1033)
• popover: onTap / onLongTap 改为无参数 VoidCallback @RSS1102 (#1033)
• popover: 任意 Widget 内容支持按真实尺寸定位，不再要求强制指定宽高 @RSS1102 (#1033)
• TLoading: size 由 TLoadingSize 枚举改为 double 像素值（默认 20），并移除 TLoadingSize 枚举 @RSS1102 (#1031)
• TLoading: 默认动画时长由 2000ms 调整为 800ms，转圈更快 @RSS1102 (#1031)
• TLoading: 默认图文排列方向由竖向（图标在上）改为横向（图标在左、文字在右） @RSS1102 (#1031)
• TMessage: 删除公开 visible 参数，声明式展示改为父级 Widget 树插入或移除组件；永久展示改为 duration: null，Duration.zero 不再生效 @RSS1102 (#1035)
• TMessage: 删除 TMessageLink、link 与 onLinkPressed，改用 Widget? action 承载操作 @RSS1102 (#1035)
• TMessage: TMessageVariant 与 variant 重命名为 TMessageStatus 与 status @RSS1102 (#1035)
• TMessage: 删除 TMessageThemeData.defaultOffset，默认位置连续 show 改为替换上一条，显式不同 offset 保留多消息 @RSS1102 (#1035)
• TMessage: 默认展示改为全宽安全可视区域条带、图标 22px、body-medium 文本与基础阴影，并默认 3 秒自动关闭 @RSS1102 (#1035)
• TTabsBar: 将 filled/capsule/card 收敛为 line/tag/card，调整 Tag 主题字段，并由组件提供不受 Material Theme 影响的 TDesign 默认视觉 @RSS1102 (#1072)
• TTab: 移除 badge 参数，请改用 TTab(child: TBadge(child: ...)) 组合完整徽标 @RSS1102 (#1072)
• TBadge: 移除 TBadgeVariant.small，请改用 size: TBadgeSize.medium 或 TBadgeSize.large @RSS1102 (#1071)
• ActionSheet: 公开入口收敛为 showList 与 showGrid，删除 showGroup、TActionSheetGroup 与 TActionSheetItem.group @RSS1102 (#1030)
• ActionSheet: 选择回调由 onChanged(item, index) 改为 onSelected(item)，并要求 TActionSheetItem.value 提供稳定业务值 @RSS1102 (#1030)
• ActionSheet: 宫格布局参数收敛为互斥的 TActionSheetGridLayout.fixed、paged、scroll，统一容量与行数语义 @RSS1102 (#1030)
• ActionSheet: 删除 showGrid.align，TActionSheetAlign 仅用于列表，宫格内容固定居中 @RSS1102 (#1030)
• ActionSheet: TActionSheetThemeData.itemHeight 改名为 gridItemHeight，并移除布局与状态字段 @RSS1102 (#1030)
• ActionSheet: TActionSheetItem.badge 放宽为 Widget 槽位，textStyle 不再隐式覆盖图标颜色 @RSS1102 (#1030)
• dialog: 普通操作未指定变体时默认配色由描边样式（outline/defaultTheme）调整为浅色填充（fill/light） @RSS1102 (#1036)
• dialog: actionsPadding 与 actionSpacing 公开字段改为可空，未指定时默认值由当前主题 token 解析 @RSS1102 (#1036)
• dialog: 三项及以上操作默认按主要/危险优先排序，混合 role 时默认显示顺序可能变化，全为普通操作时顺序不变 @RSS1102 (#1036)
• dropdown-menu: animationDuration 改为可空以明确主题继承，修复显式时长覆盖优先级；直接读取字段的代码需处理 null @RSS1102 (#1034)
• calendar: firstDayOfWeek 改用 TCalendarFirstDayOfWeek 枚举，移除整数参数写法 @RSS1102 (#1059)
• calendar: 日期格模型改为不可变快照，选择更新统一通过 value/onChanged @RSS1102 (#1059)
• picker: 父级未接收 onChanged 时，滚轮停止后恢复受控 value @RSS1102 (#1062)
• TBackTop: 将 shape 与 visibilityOffset 收敛为实例非空默认值并移除 Theme 中的同义状态，将 onPressed 调整为回顶完成通知 @RSS1102 (#1079)
• TDrawer: 命令式入口改为顶层 showTDrawer，TDrawer 收敛为声明式内容组件，TDrawerWidget 已删除，请按迁移路径改用 showTDrawer + TDrawer。 @RSS1102 (#1080)
• TDrawer: hover/bordered/isShowLastBordered 重命名为 enableFeedback/showDivider/showLastDivider 并收敛为组件实例非空布尔开关；方向、蒙层、顶部偏移与生命周期由 showTDrawer 持有，Theme 移除同义行为字段。 @RSS1102 (#1080)
• TDrawer: 标题、菜单正文、图标、分隔线与底部间距对齐设计规范，showDivider 只控制菜单项分隔线。 @RSS1102 (#1080)
• TIndexes: 将吸顶、滚动方向和胶囊模式收敛为组件实例默认行为，移除 Theme 中的同义状态入口 @RSS1102 (#1081)
• TIndexes: 调整侧栏、按压提示与锚点的默认尺寸、字体、颜色和间距 @RSS1102 (#1081)
• TNavBar: 默认不再显示返回按钮，返回图标调整为 24，height 与 useBorderStyle 收敛为非空实例参数，并移除 Theme 中的边框结构状态入口 @RSS1102 (#1082)
• TNavBar: 标题收敛为单一 Widget? title 并移除独立字体配置，提供 onBack 时不再自动返回 @RSS1102 (#1082)
• TNavBar: 默认标题调整为 Title Large 语义样式，并移除 TBarItemAction 与 TNavBarItem.toWidget @RSS1102 (#1082)
• TCascader: 分支点击改为等待调用方回写 value 后推进层级；旧用法需在 onChanged 中接收并回写候选路径。 @RSS1102 (#1060)
• TSideBar: 结构样式由 style 收敛为非空 variant（line / tag），并移除 Theme 中的 style 与 height 状态入口 @RSS1102 (#1083)
• TSideBar: 默认宽度调整为 103，并新增实例 width 覆盖入口 @RSS1102 (#1083)
• tabbar: 将 variant 拆分为 type、itemStyle 与 style，将 useVerticalDivider 更名为 split，移除 Theme 中的行为与结构选择器 @RSS1102 (#1085)
• tabbar: 删除 TTabBarBadgeConfig/badgeConfig，改用可空的 TTabBarItemConfig.badge，徽标偏移统一由 TBadge.offset 配置 @RSS1102 (#1085)
• tabbar: 不再公开内部徽标适配项、弹层路由、弹层状态与绘制器，请使用 TTabBar 和公开菜单配置组合 @RSS1102 (#1085)
• TSteps: 使用 TSteps.progress/selectable/display 收敛进度、可选择与纯展示模式，使用 indicator/onChange 替代 simple/readOnly/verticalSelect @RSS1102 (#1084)
• TSteps: 将 TStepsStatus.success 更名为 process、TStepsItemData.successIcon 更名为 icon，移除持有业务模式的 TStepsThemeData @RSS1102 (#1084)
• TTreeSelect: 默认列宽对齐移动端设计稿，375px 容器中的两列与三列布局不再水平溢出 @RSS1102 (#1065)
• TFooter: 移除 variant 和 width，改为由 logo、links、text 组合页脚内容；未设置 height 时由内容自然撑开 @RSS1102 (#1088)
• TEmpty: 移除场景枚举和内置操作参数，改用 operation Widget 组合操作区 @RSS1102 (#1086)
• TCollapse: 统一以 List<T> value/onChanged 管理展开状态，并移除旧的 Panel 状态与索引回调 API @RSS1102 (#1089)
• TImage: 以 TImageShape 和 BoxFit 分别控制形状与适配方式，默认形状调整为方形、适配方式调整为拉伸填充 @RSS1102 (#1087)
• TProgress: 调整各类进度条的默认尺寸、圆角和标签位置；线性进度的百分比改为右侧显示，原内显效果请使用 plump，原微型进度请按只读环形或可点击按钮迁移到 microCircular / microButton @RSS1102 (#1092)
• TResult: 结果状态改用 status / TResultStatus，描述内容改用 description，原 variant / TResultVariant 和 subtitle 需按迁移示例替换 @RSS1102 (#1093)
• TSkeleton: 将普通构造函数的 variant 收敛为非空预设，原 TSkeleton(variant: null) 需改用 TSkeleton()，自定义布局需改用 TSkeleton.custom(layout: ...) @RSS1102 (#1094)
• TSwiper: 从 TSwiperThemeData 移除 pagination、paginationPlacement 和 pageEffect，使用方需迁移到 TSwiper 同名实例参数 @RSS1102 (#1095)
• ImageViewer: 关闭完成统一通过 TImageViewer.show 返回的 Future 感知，移除 onClose 和无实际蒙层区域的 barrierDismissible @RSS1102 (#1091)
• TButton: 修复禁用态文字、描边颜色及浅色描边背景，默认视觉随设计稿调整 @RSS1102 (#1103)
• TDivider: 将垂直分割线默认左右间距由 8dp 调整为 16dp @RSS1102 (#1101)
• TForm: 横向布局标签字号调整为 16px，竖向布局保持 14px @RSS1102 (#1102)
• TInput: 仅有前置图标时，图标与输入内容间距调整为 16px @RSS1102 (#1102)
• TRadio: 选中状态统一由 TRadioGroup 管理，并以 inline、block、card variant 替代原 groupValue、onChanged 与 cardMode 配置 @RSS1102 (#1119)
• TRadioGroup: 数据项用法迁移至 TRadioGroup.options，并通过 child 支持自定义布局 @RSS1102 (#1119)
• TTextarea: 带内部标题的多行文本框默认改为横排，原竖排效果请使用 layout: TTextareaLayout.vertical @RSS1102 (#1111)
• TNavBar: TNavBarThemeData.copyWith 改为强类型参数，传入 null 改为保留原值，并修复主题切换时的间距、边框和阴影跳变 @RSS1102 (#1136)
• TabBar: 双层菜单未显式设置 popUpWidth 时，将默认宽度下限调整为 107px；显式设置不受影响 @RSS1102 (#1138)
• TTable: 调整默认列宽为自动均分，TTableColumn.width 改为可空；新增 onRowTap、实例级 bordered 和 stripe 配置，并同步优化排序、固定列和横向滚动视觉交互。 @RSS1102 (#1140)
• TTable: onCellTap 改为 TTableCellContext；新增行 key、合并单元格、列最小宽度和固定高度能力。 @RSS1102 (#1140)
• Badge: 将默认形态更名为 circle，新增 TBadge.custom 与 TBadgeConfig，统一预设徽标、自定义徽标及组合组件配置语义 @RSS1102 (#1141)
• TabBar: badge 改为 TBadgeConfig?，按纯文本、纯图标和图文模式提供组件级默认徽标定位 @RSS1102 (#1141)
• SideBar: badge 改为 TBadgeConfig?，默认将徽标定位到标签文字右上角 @RSS1102 (#1141)
• ActionSheet: badge 改为 TBadgeConfig?，分别按列表标题和宫格图标提供默认徽标定位 @RSS1102 (#1141)
• TProgress: 使用六个命名构造函数替代 variant 构造参数，并按形态收敛有效参数、默认尺寸、状态视觉与交互语义 @RSS1102 (#1143)
• TButton: 将图标与文字的默认间距从 8dp 调整为 4dp @RSS1102 (#1143)
• TFooter: 品牌内容可与说明文案组合展示，并调整链接分隔间距和颜色 @RSS1102 (#1143)
• TSwiper: 调整卡片缩放与淡化效果的默认绘制，使相邻卡片等比缩放、淡化并露出 @RSS1102 (#1143)
• TCell: 调整有主内容时 note 的默认宽度分配，使用受约束自然宽度 @RSS1102 (#1143)
• theme: 将 grayColor3/5/11 调整为 #E7E7E7、#C5C5C5、#383838 @RSS1102 (#1143)
• theme: 调整全局语义 Token 的名称与默认颜色、字体、间距和圆角；依赖旧默认视觉或旧 Token 名称的应用需复核主题配置。 @RSS1102 (#1146)
• components: 移除多个组件实例与 Theme 的同义配置入口；现有调用须按迁移清单改为唯一实例参数或组件 Theme 字段。 @RSS1102 (#1146)
• components: 将 Button、Tag、Link、BackTop、Popover 的 colorScheme 配色选择器统一改为 colorPreset，旧调用需更名。 @RSS1102 (#1146)
• TText: 未指定字体时，默认正文由 16dp/24dp 改为 14dp/22dp。 @RSS1102 (#1146)
• TText: 移除实例 fontWeight/fontFamily/textColor/isTextThrough/lineThroughColor；单实例文字样式改用 style: TextStyle(...)，font 仍选择字体 Token 预设。 @RSS1102 (#1146)
• TTag: 调整默认填充、描边、方形圆角和关闭图标的 Token 来源；方形圆角默认读取 radiusSmall。 @RSS1102 (#1146)
• TTabBar: 调整默认图标与项布局，移除 centerDistance、showTopBorder、topBorder、placeholder 及重复的实例视觉参数。 @RSS1102 (#1146)
• TAvatarGroup: 调整头像组默认描边、阴影及可见成员的尺寸继承；依赖旧头像缩放或描边效果的应用需复核显示。 @RSS1102 (#1146)
• TSideBar: 移除组件 Theme 的 selectedColor；改用 selectedTextStyle: TextStyle(color: ...) 统一设置选中文字、图标和指示线。 @RSS1102 (#1146)
• TSwipeCell: 移除操作项外观的重复 Theme 字段，逐项使用 TSwipeCellAction 配置；spacing 改名为 iconLabelSpacing，builder 与内置视觉参数混用会报错。 @RSS1102 (#1146)
• TPopup: 移除独立蒙层透明度和 Theme 动画时长；透明度写入颜色 alpha，动画时长使用 TPopupOptions.animationDuration。 @RSS1102 (#1146)
• theme: TDesign 组件不再从外部 Material 主题继承外观，需改用全局 Token、组件 Theme 或实例显式样式配置；独立 TIcon 默认 24dp 和文字主色。 @RSS1102 (#1146)
• TSwitch: 未选中轨道默认色改为组件背景激活色；依赖旧半透明轨道的应用需复核主题配置。 @RSS1102 (#1146)
• TForm: 表单根节点默认使用容器背景色，空白区域及组件 Theme 的背景色覆盖现在会生效。 @RSS1102 (#1146)
• TDropdownMenu: 单选和多选选项区默认最大高度为 280dp，更多选项在面板内滚动；显式 maxHeight 仍可调整上限。 @RSS1102 (#1146)
• TTag: 修正描边标签高度及各尺寸的图标占位、关闭图标和图文间距；依赖旧尺寸的应用需复核布局。 @RSS1102 (#1146)
• toast: 移除 infiniteDuration，统一零或负时长为不自动关闭，并将加载提示默认时长调整为 2000ms @RSS1102 (#1154)
• toast: 将遮罩 preventTap 更名为 preventScrollThrough，禁止背景点击和滚动 @RSS1102 (#1154)
• toast: 调整 middle 中心位置为 Overlay 高度 45%，并按内容实际尺寸计算提示中心 @RSS1102 (#1154)
• components: TD 内置文字、图标、控件视觉与可配置行为不再接受外部 Material/M2/M3 默认或显式主题；请使用 TD Theme、Token 或已开放的实例配置，自定义内容保留原主题。 @RSS1102 (#1157)
• button: 按钮内置布局使用标准密度，实例 style.visualDensity 不生效；显式尺寸、反馈、指针及其他受支持样式仍生效。 @RSS1102 (#1157)
• input: Input、Textarea 和 Search 的内置文字、提示词、操作按钮、选择高亮与默认编辑菜单使用 TD 配置；选择、复制、编辑、键盘及自定义前后缀主题保持。 @RSS1102 (#1157)
• components: 内置 Tooltip 触发与时长、反馈和指针、滚动效果及桌面滚动条不再继承外部 Material 配置；自定义内容中的对应配置仍有效。 @RSS1102 (#1157)
• swiper: 删除 controlIconSize，统一使用 controlStyle.iconSize，控制按钮 visualDensity 不生效；请通过公开尺寸/style 配置布局。 @RSS1102 (#1157)
• TButton: 对齐小程序 Button 契约，统一尺寸/tap target/圆角，移除 filled 与 margin @RSS1102 (#1039)

🚀 Features

• 放宽image_picker依赖约束，允许宿主按Flutter SDK解析兼容的图片选择器版本；平台最低要求仍需按实际解析的实现包核对。 (#1166)
• TNavBarItem提供customWidget承载自定义操作内容。 (#881)
• 底部导航TTabBar支持useSafeArea处理设备底部安全区。 (#885)
• Popup边缘方向支持useSafeArea，按当前Options配置安全区处理。 (#950)
• Calendar支持weekdayNames自定义星期标题；按星期日至星期六提供7个文案，未配置时使用当前国际化资源。 (#1142)
• 通用TPicker提供onColumnScrollEnd，可在列停止滚动后按需加载数据；与实时onChanged分别处理。 (#958)
• TButton: 新增渐变背景能力 @RSS1102 (#1005)
• TButton: 新增渐变背景能力 @RSS1102 (#1007)
• TSwipeCell: 新增组件级主题覆盖能力，可通过主题批量控制操作项背景色、图标色、文字样式、图标尺寸与间距 @RSS1102 (#1007)
• TButton: 新增渐变背景能力 @RSS1102 (#1010)
• TButton: 新增渐变背景能力 @RSS1102 (#1018)
• TToast: 新增可见半透明遮罩能力（TOverlayConfig.showOverlay / color / opacity），可独立于拦截点击展示蒙层 @RSS1102 (#1018)
• TButton: 新增渐变背景能力 @RSS1102 (#1021)
• TSwipeCell: 面板展开后点击本格或外部区域自动关闭 @RSS1102 (#1021)
• TPullDownRefresh: refreshTimeout 默认启用 3 秒刷新超时，超时经 onStateChanged(timeout) 上报并自动结束刷新，传 null 可关闭 @RSS1102 (#1029)
• TPullDownRefresh: onLoadMore 非空时按 lowerThreshold 自动启用触底加载 @RSS1102 (#1029)
• TText: 支持 TextScaler、语义标识和文本选区颜色，未设置缩放时继承系统无障碍策略 @RSS1102 (#1042)
• Icon: 新增 tablet、tablet-filled 图标（tdesign_flutter_icons 升级至 0.0.6） @RSS1102 (#1045)
• Search: 支持加权字数限制、受控操作按钮、焦点回调和实例级文字对齐 @RSS1102 (#1051)
• TForm: 支持按字段校验、清除校验状态和外部错误注入 @RSS1102 (#1038)
• upload: 新增列表布局（TUploadLayout.list）与长按拖拽排序（TUpload.draggable） @RSS1102 (#1047)
• upload: 新增可重试失败状态（TUploadFileStatus.retryableError） @RSS1102 (#1047)
• TTabsBarThemeData: 新增 disabledLabelStyle 禁用态样式入口 @RSS1102 (#1072)
• TBadge: 新增方形、气泡、左右带状角标、左右三角角标及实例位置偏移能力 @RSS1102 (#1071)
• dialog: 新增可选 barrierResult 与 closeButtonResult（默认 null），可区分蒙层/关闭按钮来源 @RSS1102 (#1036)
• TDateTimePicker: 新增月日选择模式并补齐日期、时间滚轮公开示例 @RSS1102 (#1061)
• TBackTop: 新增 light/dark 预设配色与可定制视觉字段，公开 Demo 对齐小程序选择操作与新版 Figma 页面布局 @RSS1102 (#1079)
• TDrawer: showTDrawer 新增蒙层点击通知 onOverlayClick 与关闭后销毁策略 destroyOnClose。 @RSS1102 (#1080)
• TIndexes: 新增 initialIndex 初始定位能力，并补齐侧栏、提示和锚点视觉主题配置 @RSS1102 (#1081)
• TCascader: 支持按活动层级展示次级标题，并完善 step/tab、任意层选择和搜索组合示例。 @RSS1102 (#1060)
• TPopover: 新增 TPopoverAnchor 与 TPopoverController，支持 open、close 和 isOpen 受控模式 @RSS1102 (#1099)
• tabbar: 完善文本、图文、图标、徽标、双层级与胶囊示例 @RSS1102 (#1085)
• TAvatar: 新增形状、实例颜色和字符文字样式能力，旧 variant 保持兼容 @RSS1102 (#1090)
• TAvatarGroup: 新增成员尺寸与方向感知的层叠配置 @RSS1102 (#1090)
• TCollapse: 新增 leadingBuilder 与 trailingBuilder，分别用于自定义标题左侧内容，以及标题右侧、展开图标前的操作内容 @RSS1102 (#1089)
• TCollapse: expandIconBuilder 支持替换默认展开图标，显式传入 null 时隐藏展开图标 @RSS1102 (#1089)
• TImage: 新增 onLoad 和 onError 事件，并明确空来源显示加载状态、空字符串显示失败状态 @RSS1102 (#1087)
• TImage: 对齐设计稿中的六种图片类型以及默认和自定义加载、失败提示 @RSS1102 (#1087)
• TProgress: 支持常规、警告、错误和成功状态，自动展示对应颜色、状态图标和百分比，并支持线性渐变和辅助技术可读的进度描述 @RSS1102 (#1092)
• TResult: 内置成功、错误、警告和信息状态统一为 80dp 图标，并对齐标题、描述的字号、行高和内容间距 @RSS1102 (#1093)
• TResult: 支持通过 TResultThemeData.iconSize 和 descriptionStyle 调整默认图标尺寸与描述文字样式 @RSS1102 (#1093)
• TSwiper: 支持为单个轮播配置切换时长、动画曲线和相邻卡片缩放效果 @RSS1102 (#1095)
• TBadge: 新增自定义徽标形态并支持设计稿默认锚点 @RSS1102 (#1106)
• ImageViewer: 支持双击和双指缩放、下拉关闭，放大时自动暂停切图与轮播 @RSS1102 (#1091)
• TTabsBar: 新增 small/large 选项卡尺寸并补齐尺寸示例 @RSS1102 (#1100)
• TPicker: 新增 TPickerPopup.show，统一 Picker 与 DateTimePicker 的标准弹层尺寸和配置 @RSS1102 (#1121)
• TIndexes: 新增 useSafeArea 参数，支持按需避让系统安全区 @runoob-coder (#1117)
• TSlider: 新增 normal/capsule 视觉形态，并统一胶囊轨道、游标与刻度绘制 @RSS1102 (#1144)
• TTag: 支持在组件 Theme 中分别定制 danger、success 基础色和 success 浅色填充。 @RSS1102 (#1146)
• TTabBar: 新增 iconTextLayout，支持图标与文字左右排列。 @RSS1102 (#1146)
• feat: 支持通过 TDesign 统一入口使用 Flutter Material 组件，简化最小接入。 @RSS1102 (#1158)
• indexes: 竖向索引条超出可用高度时支持滚动和点击选择，未溢出时保留拖动选择。 @RSS1102 (#1160)

🐞 Bug Fixes

• 修复官方Demo无法按站点kebab-case路由定位对应页面的问题。 (#1022)
• 修复底部导航选中态图标配色没有随选中状态变化的问题。 (#905)
• 修复Popup路由子树意外继承默认文字样式的问题，按当前TD主题契约展示。 (#951)
• 修复DropdownMenu锚定遮罩、滚动跟随与同组面板切换表现。 (#974)
• 修复Popover的生命周期清理、边界定位及锚点销毁后的浮层清理问题。 (#980)
• 修复Checkbox默认尺寸未随自定义主题Token变化的问题。 (#1057)
• TInput: 修复密文模式下无法粘贴的问题 @RSS1102 (#1005)
• TInput: 修复密文模式下无法粘贴的问题 @RSS1102 (#1007)
• TSwipeCell: 修复二次确认在重建操作项实例时失效的问题，支持按 id 稳定匹配 @RSS1102 (#1007)
• TInput: 修复密文模式下无法粘贴的问题 @RSS1102 (#1010)
• TSlider: 适配 flutter@3.47.0，showThumbValue 值提示按连续 / 离散滑块正确显示（替换 flutter@3.47.0 中已废弃的 ShowValueIndicator.always） @RSS1102 (#1010)
• TDropdownMenu: 替换 flutter@3.47.0 中已废弃的 SizeTransition.axisAlignment，修复新版本兼容问题 @RSS1102 (#1010)
• TCupertinoSwitch: 替换 flutter@3.47.0 中已废弃的 transform API，修复新版本兼容问题 @RSS1102 (#1010)
• TSwiper: 适配 flutter@3.32.0 与 flutter@3.47.0 的 TickerMode API 差异（valuesOf 在 flutter@3.32.0 中尚不可用，of 在 flutter@3.47.0 中已废弃），消除弃用告警 @RSS1102 (#1010)
• TInput: 修复密文模式下无法粘贴的问题 @RSS1102 (#1018)
• TInput: 修复密文模式下无法粘贴的问题 @RSS1102 (#1021)
• TFab: 修复拖拽返回起点附近时误触点击的问题 @RSS1102 (#1040)
• TFab: 磁吸改为可取消的真实平滑动画，新拖拽或布局更新会终止旧动画 @RSS1102 (#1040)
• TFab: 对齐示例四个场景切换与自动收缩交互 @RSS1102 (#1040)
• TText: 统一实例样式、TTextThemeData、Flutter 文本主题与 Token 的覆盖顺序 @RSS1102 (#1042)
• TTextSpan: 未显式配置的子 Span 样式正确继承父 Span @RSS1102 (#1042)
• TFontLoader: 并发字体加载共享 Future，失败后可重试并拒绝同名字体切换 URL @RSS1102 (#1042)
• Search: 修复搜索框背景高度、禁用操作文字、只读态清除按钮和中文输入法组合文本截断问题 @RSS1102 (#1051)
• form-input: 修复表单校验时机、错误状态及 placeholder 主题优先级 @RSS1102 (#1038)
• rate: 修复整星小数归一化、半星与 RTL 命中、拖动清零、交互生命周期、读屏信息及长文案布局 @RSS1102 (#1056)
• TNoticeBar: 修复水平跑马灯滚动距离和首帧宽度计算，改用公告栏实际内容区宽度 @RSS1102 (#1032)
• TLoading: 自定义图标 customIcon 现在按动画时长持续旋转，并响应 duration 更新 @RSS1102 (#1031)
• TLoading: icon 为 null 时 customIcon 仍按最高优先级显示 @RSS1102 (#1031)
• TMessage: 图标与文本间距调整为 8px，并同步跑马灯宽度计算 @RSS1102 (#1035)
• TRate: 修复辅助文字垂直对齐；自定义部分 textStyle 时，未设置字段统一继承 fontBodyLarge，避免受外层文字样式影响 @RSS1102 (#1070)
• TBadge: 修复文字徽标在不同平台及文本缩放下的垂直对齐 @RSS1102 (#1070)
• TBadge: 修复大号徽标被默认 Material BadgeTheme 错误覆盖，并保留调用方显式主题配置 @RSS1102 (#1071)
• ActionSheet: 列表弹层按内容自适应，带描述项统一高度，长列表保持可滚动 @RSS1102 (#1030)
• ActionSheet: 空 subtitle 与 null 统一按无描述处理，避免空白描述区域和额外高度 @RSS1102 (#1030)
• ActionSheet: 统一宫格分页指示点、取消区域及分隔线样式 @RSS1102 (#1030)
• dropdown-menu: 修复多列选项宽度不一致 @RSS1102 (#1034)
• dropdown-menu: 保留自定义遮罩透明度 @RSS1102 (#1034)
• dropdown-menu: 修复仿射滤镜越界拉伸时菜单与面板分离 @RSS1102 (#1034)
• dropdown-menu: 对齐菜单触发项、单选项和多列筛选面板的默认样式 @RSS1102 (#1034)
• picker: 修复父级回传选中值时拖动与惯性被中断 @RSS1102 (#1062)
• picker: 统一滚轮文字、禁用状态与边缘渐隐，默认样式跟随 TDesign token 并保留显式 TextTheme 覆盖 @RSS1102 (#1062)
• popup: 修复标题默认出现诊断下划线，保留显式文字装饰 @RSS1102 (#1062)
• TPicker: 修复局部文字主题覆盖选中状态样式和高度主题插值异常 @RSS1102 (#1076)
• TDateTimePicker: 修复受控候选值拒绝后的自动回滚及惯性滚动中断 @RSS1102 (#1061)
• TNavBar: 修正 Material 主题字段回退优先级，并明确标题 Widget 自带样式优先于默认标题样式 @RSS1102 (#1082)
• TNavBar: 修正公开 Demo 的搜索、图片和标题样式组合，并隔离公共 Demo 页面标题视觉 @RSS1102 (#1082)
• TCascader: 修正受控交互、键盘操作、层级面板尺寸与主题回退，避免外部隐式主题污染组件视觉。 @RSS1102 (#1060)
• TSideBar: 公开 Demo 补齐 10 项纵向图文、Badge、锚点、禁用、图标与 tag 操作状态 @RSS1102 (#1083)
• TPopover: 修复动态主题切换时 nullable 样式被错误插值为透明色或零值的问题 @RSS1102 (#1099)
• tabbar: 修复水波纹路径重复点击识别风险，保证一次手势只进入一次选中回调链路 @RSS1102 (#1085)
• tabbar: 修复局部文字主题、菜单主题与面板背景覆盖以及空值主题插值问题 @RSS1102 (#1085)
• tabbar: 修复指示器动画模式切换和连续切换时的位置跳变 @RSS1102 (#1085)
• TSlider: 修复默认主题下 TSlider/TRangeSlider 的拇指、轨道与数值标签配色及禁用态颜色 @RSS1102 (#1063)
• TSlider: showThumbValue 数值改为常驻显示，垂直标签正向展示 @RSS1102 (#1063)
• TSteps: 修复局部文字主题覆盖失效、横向纯展示节点状态不一致以及可选择示例状态文案不随选择更新的问题 @RSS1102 (#1084)
• TStepper: 修复编辑草稿后加减按钮边界状态未及时更新的问题。 @RSS1102 (#1064)
• TStepper: 修复未设置主题字段时的尺寸与颜色动画插值。 @RSS1102 (#1064)
• TAvatarGroup: 修复成员形状裁剪、双向层叠、主题动画插值与非法尺寸边界 @RSS1102 (#1090)
• Avatar: 对齐公开 Demo 的头像资源、字符样式、徽标尺寸与位置、头像组规格、操作图标与尺寸布局 @RSS1102 (#1090)
• TProgress: Button 形态使用完整品牌色轨道和已完成进度渐变，公开 Demo 从“开始”平滑推进至 80% @RSS1102 (#1092)
• TProgress: 自定义 Material 主色不再改写进度的状态语义色 @RSS1102 (#1092)
• TResult: Theme 切换时默认图标保持尺寸稳定，局部文字样式未指定的字体属性继续使用组件默认值 @RSS1102 (#1093)
• TResult: 自定义结果插图保持原始宽高比，内置状态向辅助技术提供可读语义 @RSS1102 (#1093)
• TSkeleton: 对齐骨架屏的默认占位色、16dp 行间距、图片圆角及 2s 闪烁动效，改善默认预设与加载过程的视觉一致性 @RSS1102 (#1094)
• TSwiper: fraction 默认以紧凑胶囊展示，controls 默认在内容两侧居中，并正确支持外置分页和显式对齐 @RSS1102 (#1095)
• TSwiper: 对齐默认圆角、卡片露出和深浅主题导航视觉，确保切换按钮清晰可见 @RSS1102 (#1095)
• TSwiper: 公开 Demo 统一为六种目标形态、六张内容并从第一页开始 @RSS1102 (#1095)
• TBadge: 修复普通徽标的右上角位置偏差 @RSS1102 (#1106)
• TBadge: 修复中文环境中文字徽标样式及垂直对齐与设计稿不一致的问题 @RSS1102 (#1107)
• ImageViewer: 图片加载失败时显示错误占位，并优化关闭动效、全屏背景、页码与顶部操作按钮的尺寸和交互状态 @RSS1102 (#1091)
• TTabsBar: 将带内容区选项卡的内容文字改为辅助灰色 @RSS1102 (#1100)
• Calendar: 修复普通日期文字颜色未使用 Gy1 90% 主文字色的问题 @RSS1102 (#1118)
• TCheckbox: 修复多行内容、禁用未选样式、卡片间距和分割线起点未正确对齐的问题 @RSS1102 (#1104)
• theme: 将移动端 Gy4 默认色值从 #DDDDDD 修正为 #DCDCDC @RSS1102 (#1104)
• TInput: 修复状态、超长标签及图形/短信验证码操作区的对齐与分割线样式 @RSS1102 (#1102)
• TRadio: 修复群组分割线、横向间距、未选禁用态、状态文案及卡片内容安全间距 @RSS1102 (#1119)
• TPicker: 修复 Android 上选择器选项文字视觉偏下的问题 @RSS1102 (#1120)
• TPicker: 对齐地区选择示例的候选内容与页面尺寸 @RSS1102 (#1120)
• TPicker: 修复标准选择弹层中滚轮内容被压缩、裁切和中心项偏移的问题 @RSS1102 (#1121)
• TStepper: 修复步进器数字在不同平台下视觉偏上，并对齐小、中、大尺寸文字行高 @RSS1102 (#1122)
• Form: 修复表单示例默认态、布局、操作按钮与提交反馈 @RSS1102 (#1105)
• TTimeCounter: 修复动态启停、方向切换、终点回调和毫秒格式处理异常 @RSS1102 (#1096)
• TTimeCounter: 对齐三档尺寸及方形、圆形、单位倒计时的默认展示 @RSS1102 (#1096)
• TRate: 修复未评分辅助文案颜色不符合设计的问题 @RSS1102 (#1108)
• TRate: 修复评分大小示例容器之间缺少间距的问题 @RSS1102 (#1108)
• TRate: 修复评分风格标题、容器间距及线描评分颜色不符合设计的问题 @RSS1102 (#1108)
• TRate: 修复竖向带描述评分缺少容器填充及文案错误的问题 @RSS1102 (#1108)
• Demo: 修复移动端公开示例页头布局及 Search 搜索图标与设计不一致的问题 @RSS1102 (#1110)
• ActionSheet: 修正宫格默认图标槽位和带描述宫格间距 @RSS1102 (#1123)
• Dialog: 修复长内容缺少可见滚动条和关闭图标实际边距不正确的问题 @RSS1102 (#1124)
• DropdownMenu: 修复分栏多选禁用项默认背景色不符合组件禁用背景规范的问题 @RSS1102 (#1125)
• Loading: 修复 activity 指示器默认颜色错误显示为品牌蓝的问题 @RSS1102 (#1126)
• TMessage: 修复默认消息缺少左右 16px 外边距的问题 @RSS1102 (#1127)
• TNoticeBar: 修复自定义前缀图标与正文缺少 8px 间距的问题 @RSS1102 (#1128)
• TNoticeBar: 修复前缀间距不跟随 spacer8 Token 的问题 @RSS1102 (#1128)
• TNoticeBar: 修复动态主题过渡时尺寸从 0、颜色从透明色插值的问题 @RSS1102 (#1128)
• TPopover: 修复顶部和底部四角气泡箭头未保持 12px 边缘间距的问题 @RSS1102 (#1129)
• TSwipeCell: 修复外层文字样式覆盖滑动操作默认反色文字的问题 @RSS1102 (#1131)
• TSideBar: 修复徽标未贴合标签文字右上角的问题 @RSS1102 (#1135)
• TIndexes: 修复主题切换时固定默认尺寸在动画中间态跳变的问题 @RSS1102 (#1137)
• TSideBar: 修复主题切换时回退样式被半透明颜色或零内边距临时覆盖的问题 @RSS1102 (#1137)
• Badge: 修复 bubble 被 Material 胶囊形状裁剪及默认字距导致的尺寸偏差 @RSS1102 (#1141)
• Avatar: 修正头像徽标圆点尺寸、头像组尺寸及排列方式 @RSS1102 (#1141)
• ActionSheet: 对齐操作面板公开 Demo 的示例顺序、状态和宫格内容 @RSS1102 (#1141)
• SideBar: 补齐非通栏选项样式示例并对齐页面说明 @RSS1102 (#1141)
• TCheckbox: 修复单行与多行文案的垂直对齐，并将方形指示器圆角修正为 1.5px @RSS1102 (#1143)
• TCollapse: 修复标题默认字重被上层主题加粗的问题 @RSS1102 (#1143)
• TPopover: 修复角落气泡边缘及箭头 12px 内边距不符合设计，以及切换触发器时首次点击只关闭旧气泡的问题 @RSS1102 (#1143)
• TTabBar: 修复胶囊圆角及弱选中徽标位置 @RSS1102 (#1144)
• TCascader: 修复层级图标颜色与标题间距 @RSS1102 (#1144)
• TCheckbox: 修复列表分割线左侧残留浅灰线 @RSS1102 (#1144)
• TFormItem: 修复横排表单项的标签间距与行高 @RSS1102 (#1144)
• TFormItem: 修复显式 Material TextTheme 未正确作用于表单标签 @RSS1102 (#1144)
• TInput: 修复错误态清除图标颜色及表单内容对齐 @RSS1102 (#1144)
• TTextarea: 修复横排标签与输入提示文字未对齐 @RSS1102 (#1144)
• TDropdownMenu: 修复单选项选中时文字错误高亮，保留右侧勾选图标高亮 @RSS1102 (#1144)
• TTreeSelect: 补齐选中根节点左侧指示条 @RSS1102 (#1144)
• TButton: 修复 Loading 图标不能继承按钮前景色 @RSS1102 (#1144)
• TPullDownRefresh: 修复暗色模式下刷新状态文案层级过亮的问题 @RSS1102 (#1145)
• theme: 修复 Tag 配色及方角、Progress 环形内圆在动态 Theme 切换时的中间帧跳变或意外半透明。 @RSS1102 (#1146)
• TCell: 局部文字 Theme 仅覆盖显式字段，保留标题、副标题、说明和组标题的默认字号、行高与字重。 @RSS1102 (#1146)
• site: 完善官网主题控制器对 Flutter Web Demo 色彩、字体、圆角、阴影和尺寸 Token 的同步 @RSS1102 (#1132)
• upload: 修复异步选择完成后覆盖父级最新文件的问题 @RSS1102 (#1153)
• upload: 修复重复选择导致已添加文件丢失的问题 @RSS1102 (#1153)
• upload: 修复异步选择使用过期回调与文件限制的问题 @RSS1102 (#1153)
• toast: 修复可见遮罩在允许背景交互时仍拦截点击的问题 @RSS1102 (#1154)
• button: 修复渐变 outline/ghost 按钮宽高与普通按钮不一致的问题。 @RSS1102 (#1157)
• button: 修复实例状态样式只覆盖部分状态时丢失 TD 默认配色、边框及尺寸的问题。 @RSS1102 (#1157)
• swiper: 修复控制按钮显式样式合并、按状态回退及主题过渡，自定义图标和图层保留调用方主题。 @RSS1102 (#1157)
• message: 修复显式 TD 字体、字距或系统文字缩放下跑马灯结束时残留文字的问题。 @RSS1102 (#1157)
• picker: 修复自定义 itemBuilder 内容丢失调用方滚动配置的问题，保留内置滚轮选择与交互。 @RSS1102 (#1157)
• date-time-picker: 修复文案回调或展示配置更新时重建滚轮导致连续拖动与惯性中断的问题，保留动态文案更新和受控选择行为。 @RSS1102 (#1159)
• text: 修复内置单行文字在固定内容槽中的垂直偏移，保留显式 TD 排版、多行正文与自定义内容。 @RSS1102 (#1160)
• components: 修复 Tag、Switch、选择卡片、ActionSheet、Progress、Refresh、Upload 等默认尺寸不足时的文字裁切，保留显式尺寸与原生交互。 @RSS1102 (#1160)
• input: 修复输入及提示文字的自然行框布局，保留原生编辑、焦点、选择和前后插槽内容。 @RSS1102 (#1160)
• picker: 默认滚轮高度适应内置文字，Popup 保留完整滚轮区域及滚动后的选中项，显式高度和自定义选项保持生效。 @RSS1102 (#1160)
• tabs: 修复自定义标签使用 Column / Expanded 时的高度约束异常，保留内置标签居中及默认胶囊高度。 @RSS1102 (#1160)
• switch: 修复默认长状态文案的额外缩字和不可读省略，保留显式预设尺寸及两种状态的 TD 字号。 @RSS1102 (#1160)
• calendar: 默认日期、星期与月份区域适应内容，保留显式 TD 高度、自定义 builder 和日期选择。 @RSS1102 (#1160)
• sidebar: 修复字体放大时远端选中项无法准确滚动显露的问题，不增加选择回调。 @RSS1102 (#1160)
• demo: 修复构建日期长期不更新，并统一展示实际构建的北京时间日期。 @RSS1102 (#1168)
• demo: 图片预览确认删除后真正移除图片，正确处理末项和删空后的继续体验。 @RSS1102 (#1168)
• demo: 工具栏直接提供示例代码清单，修复 Fab 等页面代码入口不直观的问题。 @RSS1102 (#1168)
• demo: 修复 Popover 自定义内容在字体放大时底部溢出。 @RSS1102 (#1168)
• TCell: 修复辅助信息默认字号与右侧插槽对齐 @RSS1102 (#1026)
• TUpload: 区分选择器错误与业务回调异常 @RSS1102 (#1151)
• button: 修复默认幽灵按钮文字与描边未跟随自定义反色主题的问题，保留禁用与实例样式优先级。(#1166)
• theme: 修复稀疏自定义深色JSON未配置的背景、文字及引用错误回退为浅色Token的问题。(#1166)

📝 Documentation

• docs: 更新主题生成器文档 @RSS1102 (#1005) (#1007) (#1010) (#1018) (#1021)
• TText: Demo 补齐普通文本、富文本、样式、段落、辅助能力与主题用法 @RSS1102 (#1042)
• TStepper: 对齐步进器公开示例并提供可独立运行的示例代码。 @RSS1102 (#1064)
• docs: 增加迁移指南侧边导航，补充 Android APK 扫码下载与 iOS 源码体验入口。 @RSS1102 (#1167)

🚧 Others

• example: 对齐 Web 组件分类顺序并清理过时 V1.0/TODO 标记 @RSS1102 (#987)
• chore: use AGENTS.md + repo-level skill for repo conventions @RSS1102 (#1001)

仍需在最终候选裁定的4项历史修复

以下条目没有直接写成“已通过”的发布承诺。按最终实现和设备/设计证据确认后，再决定是补入最终日志，还是由对应重构/删除能力说明覆盖。

• #868：旧胶囊Slider滑块边界修复：现实现已重构，须以最终几何/视觉结果决定如何表述，不能仅沿用旧补丁标题。
• #890：旧TDTable固定首列与纵向滚动修复：需对最终TTable约束与固定列场景确认，不宣传旧接口的兼容修复。
• #880：旧TreeSelect向外弯折圆角：新实现外观以最终设计验收为准，不仅凭旧PR认定该像素效果通过。
• #903：旧Web文字垂直居中补偿：全局补偿入口已删除，应按最终文字/字体布局确认，不宣称恢复旧补偿算法。

本轮文档核对详见 #1169 的 Spec076。已对照0.2.7以来200个来源PR补充18条遗漏说明；仍有4项历史行为需按最终实现裁定。388项旧声明定位、57组件改法及本轮文档修复尚未进入当前版本head，合入文档PR后需同步并重新冻结候选。以上候选稿没有确认机器人评论或写入自动CHANGELOG。

📝 更新日志

• breaking: 发布1.0.0，最低Flutter3.32.0/Dart3.8.0；0.2.7用户按迁移指南升级T前缀API、受控值、主题与浮层接口。
• fix(button): 修复默认幽灵按钮文字与描边未跟随自定义反色主题的问题。
• fix(theme): 修复稀疏自定义深色JSON未配置的背景、文字和引用回退为浅色Token的问题。

以上为需纳入最终1.0发布说明的已合入变更，防止原准备PR标记无需日志而漏收。完整0.2.7→1.0变更仍须与自动生成草稿逐条核对；不手改自动CHANGELOG。

• 本条 PR 不需要纳入 Changelog

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

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

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

[github-actions]

Web Demo

• web-example

APK 下载

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

[github-actions]

🌈 TDesign Flutter 1.0.0 2026-10-15

TDesign Flutter 1.0 正式发布！

本次版本围绕组件 API、主题体系、默认视觉和交互体验完成系统性升级，统一常用组件的使用方式，并增强表单、上传、选择器、图片预览、表格和轮播等能力。

✨ 本次发布重点

• 统一组件 API：统一 T 前缀、内容插槽、回调与受控状态，梳理 Controller 和浮层职责，移除旧版兼容入口及重复配置。
• 完善主题体系：通过全局 Token、组件 Theme、局部主题和实例配置定制样式，统一深浅色及主题切换表现。
• 提升视觉与交互一致性：集中优化尺寸、排版、状态反馈、文字缩放和无障碍体验，使默认表现更贴合 TDesign 设计规范。
• 增强常用能力：新增标准选择器弹层、上传列表与拖拽排序、图片预览缩放、自定义徽标，以及表格、轮播和进度条配置。

📖 升级到 1.0.0

1.0 包含不兼容的 API 和默认行为调整，最低要求 Flutter ≥ 3.32.0、Dart ≥ 3.8.0。

从 0.2.7 升级时，请先阅读 0.2.7 → 1.0 迁移指南（仓库版本），按项目实际使用的组件迁移公共配置、参数、回调与业务流程。不能仅通过替换 TD 前缀完成升级；编译通过后，还需回归默认视觉、受控状态、确认/取消和异步操作。

🚨 Breaking Changes

• 公共 API 与运行环境
  • 最低环境要求调整为 Flutter ≥ 3.32.0、Dart ≥ 3.8.0，移除历史 Flutter 版本适配依赖。（#976）
  • 组件统一迁移到 T 前缀 API，移除旧构造、样式及辅助类型的兼容入口；从 0.2.7 升级时需按迁移指南调整参数、回调与业务组合，不能仅替换前缀。（#907、#967）
• TThemeData
  • 统一全局 Token、组件 Theme、局部主题和实例配置的职责，移除重复的样式与行为入口；内置文字、图标、控件、Tooltip、反馈及滚动表现由 TDesign 配置控制，不再继承外部 Material/M2/M3 的默认或显式配置，自定义内容保留调用方主题。（#1146、#1157）
  • 调整语义 Token 名称及默认颜色、字体、间距和圆角；grayColor3/5/11 分别调整为 #E7E7E7、#C5C5C5、#383838，Gy4 修正为 #DCDCDC。依赖旧 Token 或默认视觉的应用需复核主题。（#1104、#1143、#1146）
  • 主题复制统一使用 copyWith(name: ..., spacerMap: ...)，移除旧复制包装、ofColor/ofFont/ofCorner/ofFontFamily/ofShadow/ofExtra 和公开 parseThemeData；copyWith/lerp 返回 TThemeData。（#1152）
• TIcon / TIcons：图标迁移到 TIcon 与独立图标包的 TIcons；旧 all 改为 allIconsMap，部分旧图标名称不再提供同名常量，替代方式见迁移指南；独立 TIcon 默认尺寸为 24dp，颜色为主文字色。（#967、#1146）
• TButton
  • 统一尺寸、点击热区和圆角，移除 filled 与 margin；配色选择参数由 colorScheme 改为 colorPreset。（#1039、#1146）
  • 调整禁用态文字、描边与浅色描边背景，图标和文字默认间距由 8dp 改为 4dp；内置布局使用标准密度，style.visualDensity 不再生效，其他受支持的实例样式仍可配置。（#1103、#1143、#1157）
• TText
  • 普通文本与富文本统一对齐 Flutter 原生 Text 契约，内容参数改为必填；移除组件内字体下载、块背景、线性缩放、独立 package 和全局配置入口，改用原生能力组合。（#1042）
  • 移除实例级 fontWeight/fontFamily/textColor/isTextThrough/lineThroughColor，单实例样式改用 style: TextStyle(...)，font 仍用于选择字体 Token；默认正文由 16dp/24dp 改为 14dp/22dp。（#1146）
• TDivider：统一默认线条、文字、间距和垂直尺寸；垂直分割线默认左右间距由 8dp 改为 16dp。（#1044、#1101）
• TLink：移除互斥的 variant，改为独立组合下划线及前后图标；统一尺寸、状态和无障碍行为，配色参数由 colorScheme 改为 colorPreset。（#1043、#1146）
• TFab
  • 默认动作层统一为 large/fill/primary，纯图标使用圆形、图文使用胶囊形；默认使用 TDesign add 图标、spacer4 和 shadowsMiddle，不再受父级 TButtonThemeData 影响，完整自定义使用 child。（#1040）
  • 调整 TFabBounds 在 right/bottom 坐标系下的 start/end 方向映射，并增加非负有限值校验。（#1040）
• TForm：字段约束统一使用 validator，移除 TFormField.rules；横向标签字号改为 16px，竖向保持 14px，表单根节点默认使用容器背景色。（#1038、#1102、#1146）
• TInput
  • 移除 label/multiline/showClearButton/decoration，统一标签、多行输入、清除按钮及样式配置入口；仅有前置图标时，图标与输入内容间距改为 16px。（#1038、#1102）
  • 内置文字、提示词、选择高亮和默认编辑菜单使用 TDesign 配置；原生编辑、复制、选择、键盘与自定义前后缀内容保持原有职责。（#1157）
• TTextarea：移除 Material decoration 透传，由组件 Theme 管理容器与输入视觉；内置标题默认横排，原竖排效果使用 layout: TTextareaLayout.vertical，内置编辑视觉使用 TDesign 配置。（#1038、#1111、#1157）
• TSearchBar：取消按钮、自动聚焦和样式入口统一为 actionText/onActionPressed/autofocus/TSearchBarThemeData；内置文字、操作和编辑视觉使用 TDesign 配置。（#1051、#1157）
• TCheckbox / TCheckboxGroup
  • 默认指示器由方形改为圆形；普通模式默认显示分割线，末项和卡片模式不绘制分割线。需要旧效果时，显式配置方形主题或 showDivider: false。（#1048）
  • 带文案的普通模式最小高度按尺寸改为 48/56/64dp；标题和副标题默认最大行数改为 3/5，文字颜色由组件 Theme 或语义 Token 控制；横向卡片角标和勾选图标分别改为 24dp、12dp。（#1048）
• TRadio / TRadioGroup
  • 选中状态统一由 TRadioGroup 管理，数据项用法迁移到 TRadioGroup.options，通过 child 组合自定义布局；使用 inline/block/card variant 替代旧 groupValue/onChanged/cardMode 配置。（#1119）
  • 默认选中标记改为实心勾选图标，支持 iconType 配置；标题和副标题默认最大行数改为 3/5，普通模式默认显示分割线，卡片模式不显示分割线。（#1049）
• TSwitch：加载态改为独立 loading 参数，移除 TSwitchVariant.loading；未选中轨道默认使用组件背景激活色。（#1050、#1146）
• TRate：移除 TRateThemeData.showText，评分文案统一由 texts 控制；整星点击、长按和拖动默认显示评分提示，可通过 showValueIndicator: false 关闭。（#1056）
• TUpload：文件点击回调统一为 onFileTap，取代 onPreview/onRetry。（#1047）
• TCalendar：firstDayOfWeek 改为 TCalendarFirstDayOfWeek 枚举，日期格模型改为不可变快照；使用日期受控值并通过 value/onChanged 更新，弹层与确认流程由业务组合。（#942、#953、#1059）
• TPicker：选择内容与弹层、标题和确认流程分离；父级未接收并回写 onChanged 时，滚轮停止后恢复受控 value，标准弹层可通过 TPickerPopup 组合。（#921、#926、#1062、#1121）
• TDateTimePicker：选择内容与业务确认流程分离，按受控值回写；弹层与标题操作使用 TPickerPopup 或 TPopup 组合。（#921、#926、#1121）
• TCascader：分支点击后等待调用方回写 value 再推进层级，业务需在 onChanged 中接收并回写候选路径。（#1060）
• TPopup
  • 统一使用 TPopupOptions + TPopupHandle 管理展示、关闭和结果；蒙层配置集中到 TPopupOverlayConfig，透明度写入颜色 alpha，动画时长使用 TPopupOptions.animationDuration。（#946、#1037、#1146）
  • bottom/center 默认只展示 child，标题和操作通过 headerBuilder + TPopupHeader 组合，移除旧标题和确认/取消构建参数；生命周期使用 onVisibleChange/onOpened/onClosed。（#1037）
  • left/right 默认改为无圆角全高矩形；useSafeArea 默认改为 false，如需安全区避让须显式开启。（#1037）
• TPopover
  • 内容统一为必填 Widget content，默认位置为 top，按真实内容尺寸定位；onTap/onLongTap 改为无参数回调，内部 TPopoverWidget 不再作为公开入口。（#1033）
  • 配色选择从 Theme 移至实例，最终参数统一为 colorPreset，预设类型使用 TPopoverColorPreset；旧 dark/info/error 对应 defaultTheme/primary/danger。（#1058、#1146）
• TActionSheet
  • 入口收敛为 showList/showGrid，移除分组入口；选择回调改为 onSelected(item)，TActionSheetItem.value 需提供稳定业务值。（#1030）
  • 宫格布局统一为互斥的 TActionSheetGridLayout.fixed/paged/scroll，内容固定居中；itemHeight 改为 gridItemHeight，移除 Theme 中的布局和状态字段，文字样式不再隐式覆盖图标颜色。（#1030）
  • 徽标最终统一为 TBadgeConfig?，按列表标题或宫格图标提供默认定位，自定义外观使用徽标配置组合。（#1030、#1141）
• TDialog：普通操作默认改为浅色填充；actionsPadding/actionSpacing 改为可空并从主题 Token 解析默认值；三项及以上混合角色操作默认按主要/危险优先排序。（#1036）
• TDrawer
  • 命令式入口改为 showTDrawer，内容使用声明式 TDrawer，移除 TDrawerWidget；方向、蒙层、顶部偏移和生命周期由展示入口管理。（#1080）
  • hover/bordered/isShowLastBordered 分别改为 enableFeedback/showDivider/showLastDivider；统一标题、正文、图标、分隔线及底部间距，showDivider 仅控制菜单项分隔线。（#1080）
• TToast
  • 移除 infiniteDuration，零或负时长统一表示不自动关闭；加载提示默认展示 2000ms。（#1154）
  • 遮罩参数 preventTap 改为 preventScrollThrough，用于禁止背景点击与滚动；middle 中心位置改为 Overlay 高度的 45%，按内容真实尺寸定位。（#1154）
• TMessage
  • 移除 visible，声明式展示由父级插入或移除组件；永久展示使用 duration: null，默认 3 秒自动关闭；默认位置连续展示替换上一条，显式不同 offset 可保留多条消息。（#1035）
  • variant/TMessageVariant 改为 status/TMessageStatus，操作区统一为 Widget? action；移除 TMessageLink/link/onLinkPressed 和 defaultOffset，统一默认条带、图标、字体与阴影视觉。（#1035）
• TNoticeBar
  • 前后内容统一为 prefix/operation，移除旧 left/prefixIcon/right；状态改由实例 status 驱动，移除 TNoticeBarVariant 及对应 Theme 字段。（#1032）
  • 轮播周期默认由 3 秒改为 2 秒；垂直轮播由 direction + items 驱动，非空 items 优先于 content，operation 可与 suffixIcon 共存。（#1032）
• TLoading：size 改为逻辑像素数值，默认 20，移除 TLoadingSize；动画默认时长由 2000ms 改为 800ms，图文排列默认由竖向改为横向。（#1031）
• TSwipeCell
  • 移除 flutter_slidable，控制器收敛为 open(side)/close()，移除二次确认、拖拽移除及互斥组等历史 API；操作项外观统一由 TSwipeCellAction 配置，spacing 改为 iconLabelSpacing，自定义 builder 不可混用内置视觉参数。（#1021、#1146）
  • 默认开关阈值由面板宽度的 50% 改为 30%，动画时长由 200ms 改为 600ms；图标尺寸改为 20、图文间距改为 8，新增默认左右内边距 16。（#1021）
• TPullDownRefresh：统一使用 TPullDownRefresh，移除 TRefreshHeader/TRefreshThemeData；默认 loadingBarHeight=50、maxBarHeight=80，触发阈值由 48 改为 50。（#1029）
• TTabsBar：形态统一为 line/tag/card，调整 Tag 主题字段和默认视觉；移除 TTab.badge，改用 TTab(child: TBadge(child: ...)) 组合。（#1072）
• TTabBar
  • 将 variant 拆分为 type/itemStyle/style，useVerticalDivider 改为 split；移除重复的 Theme 与实例配置及内部适配类型，包括 centerDistance/showTopBorder/topBorder/placeholder。（#1085、#1146）
  • 徽标统一使用 TBadgeConfig?，替代旧 TTabBarBadgeConfig/badgeConfig，按文本、图标和图文模式提供默认定位；双层菜单默认宽度下限改为 107px，显式 popUpWidth 仍可覆盖。（#1085、#1138、#1141）
• TSideBar：style 改为非空 variant（line/tag），默认宽度改为 103；徽标使用 TBadgeConfig?，默认定位在文字右上角；移除 Theme 的 style/height/selectedColor，选中样式统一通过 selectedTextStyle 配置。（#1083、#1141、#1146）
• TNavBar
  • 默认不显示返回按钮，返回图标改为 24；标题统一为 Widget? title，默认使用 Title Large，提供 onBack 时不再自动返回；移除独立字体配置、TBarItemAction 和 TNavBarItem.toWidget。（#1082）
  • height/useBorderStyle 收敛为非空实例参数；TNavBarThemeData.copyWith 使用强类型参数，传入 null 表示保留原值。（#1082、#1136）
• TIndexes：吸顶、方向和胶囊模式统一由组件实例管理，移除 Theme 中的同义状态入口；调整侧栏、按压提示和锚点的默认尺寸、字体、颜色及间距。（#1081）
• TBackTop：shape/visibilityOffset 使用非空实例默认值，移除 Theme 同义状态；onPressed 改为回顶完成通知，配色参数统一为 colorPreset。（#1079、#1146）
• TSteps：使用 TSteps.progress/selectable/display 区分进度、可选择和纯展示模式，以 indicator/onChange 替代 simple/readOnly/verticalSelect；success 状态更名为 process，successIcon 更名为 icon，移除持有业务模式的 Theme。（#1084）
• TBadge：默认形态更名为 circle，移除 TBadgeVariant.small，尺寸使用 TBadgeSize.medium/large；统一预设、自定义及组合组件的徽标配置语义。（#1071、#1141）
• TTag
  • 移除 Theme 中的配色及 isLight/isOutline，实例使用 colorPreset 和 variant；四种旧布尔组合分别对应 dark/light/outline/lightOutline。（#1058、#1146）
  • 统一填充、描边、图标及关闭图标的尺寸和间距，方形圆角默认读取 radiusSmall；依赖旧尺寸的布局需复核。（#1146）
• TAvatarGroup：调整默认描边、阴影及可见成员的尺寸继承，依赖旧头像缩放或描边表现的布局需复核。（#1146）
• TCell：有主内容时，note 改用受约束的自然宽度分配。（#1143）
• TCollapse：展开状态统一由 List<T> value/onChanged 管理，移除旧 Panel 状态和索引回调 API。（#1089）
• TImage：形状和适配方式分别使用 TImageShape 与 BoxFit，默认改为方形和拉伸填充。（#1087）
• TImageViewer：关闭完成通过 TImageViewer.show 返回的 Future 感知，移除 onClose 和无实际蒙层区域的 barrierDismissible。（#1091）
• TSwiper
  • 分页、分页位置和页面效果由实例参数管理，移除 Theme 中的同义字段；控制图标尺寸统一使用 controlStyle.iconSize，移除 controlIconSize，控制按钮不再使用 visualDensity。（#1095、#1157）
  • 调整卡片缩放和淡化效果，使相邻卡片等比缩放、淡化并露出。（#1143）
• TProgress：使用 .linear/.plump/.circular/.microCircular/.button/.microButton 六个命名构造函数替代 variant；按形态统一有效参数、尺寸、圆角、标签位置和交互语义，线性进度百分比默认显示在右侧。（#1092、#1143）
• TTable：默认列宽改为自动均分，TTableColumn.width 改为可空；onCellTap 改用 TTableCellContext。（#1140）
• TTreeSelect：调整默认列宽，避免在 375px 容器中使用两列或三列布局时水平溢出。（#1065）
• TResult：状态统一为 status/TResultStatus，描述改为 description，替代旧 variant/TResultVariant/subtitle。（#1093）
• TSkeleton：预设构造的 variant 改为非空，原 variant: null 改用 TSkeleton()；自定义布局使用 TSkeleton.custom(layout: ...)。（#1094）
• TFooter：移除 variant/width，通过 logo/links/text 组合内容，未设置高度时由内容自然撑开；品牌内容可与说明文案共存，调整链接分隔间距和颜色。（#1088、#1143）
• TEmpty：移除场景枚举和内置操作参数，使用 operation Widget 组合操作区。（#1086）
• TDropdownMenu：animationDuration 改为可空，显式值优先于主题；单选和多选选项区默认最大高度改为 280dp，超出后在面板内滚动，可通过 maxHeight 覆盖。（#1034、#1146）

🚀 Features

• TButton：新增渐变背景能力。（#1005、#1007、#1010、#1018、#1021）
• TIcon / TIcons：图标包升级至 0.0.6，新增 tablet、tablet-filled 图标。（#1045）
• TText：支持 TextScaler、语义标识和文本选区颜色，未显式设置缩放时遵循系统无障碍策略。（#1042）
• TForm：支持字段级校验、清除校验状态和外部错误注入。（#1038）
• TSearchBar：支持加权字数限制、受控操作按钮、焦点回调和实例级文字对齐。（#1051）
• TUpload：新增列表布局 TUploadLayout.list、长按拖拽排序 draggable 和可重试失败状态 retryableError。（#1047）
• TDateTimePicker：新增月日选择模式。（#1061）
• TPicker：新增 TPickerPopup.show，统一 Picker 与 DateTimePicker 的标准弹层尺寸和配置。（#1121）
• TCascader：支持按活动层级展示次级标题。（#1060）
• TPopover：新增 TPopoverAnchor 与 TPopoverController，支持 open/close/isOpen 控制展示。（#1099）
• TDialog：新增可选 barrierResult/closeButtonResult，用于区分蒙层与关闭按钮的关闭来源。（#1036）
• TDrawer：showTDrawer 新增蒙层点击通知 onOverlayClick 和关闭后销毁策略 destroyOnClose。（#1080）
• TToast：支持可见半透明蒙层，并可独立控制是否拦截背景交互。（#1018、#1154）
• TSwipeCell：面板展开后，点击本格或外部区域可自动关闭。（#1021）
• TPullDownRefresh：默认启用 3 秒刷新超时，超时通过 onStateChanged(timeout) 通知并自动结束刷新，refreshTimeout: null 可关闭；配置 onLoadMore 后支持按 lowerThreshold 触底加载。（#1029）
• TTabsBar：新增 small/large 尺寸和 disabledLabelStyle 禁用标签样式入口。（#1072、#1100）
• TTabBar：新增 iconTextLayout，支持图标与文字左右排列。（#1146）
• TIndexes：新增 initialIndex 初始定位与 useSafeArea 安全区配置；竖向索引条超高时支持滚动和点击选择，未溢出时支持拖动选择。（#1081、#1117、#1160）
• TBackTop：新增 light/dark 配色预设及视觉定制字段。（#1079）
• TBadge：新增方形、气泡、左右带状角标和左右三角角标，支持位置偏移；通过 TBadge.custom/TBadgeConfig 统一预设、自定义和组合徽标。（#1071、#1106、#1141）
• TTag：支持在组件 Theme 中分别定制 danger/success 基础色和 success 浅色填充。（#1146）
• TAvatar：新增形状、实例颜色及字符文字样式配置。（#1090）
• TAvatarGroup：新增成员尺寸和方向感知的层叠配置。（#1090）
• TCollapse：新增 leadingBuilder/trailingBuilder 组合标题前后内容；expandIconBuilder 可替换展开图标，显式传入 null 可隐藏。（#1089）
• TImage：新增 onLoad/onError 事件，空来源显示加载态、空字符串显示失败态；完善图片类型及默认、自定义加载和失败提示。（#1087）
• TImageViewer：支持双击、双指缩放和下拉关闭，放大时自动暂停切图与轮播。（#1091）
• TSwiper：支持实例级切换时长、动画曲线和相邻卡片缩放效果。（#1095）
• TProgress：支持常规、警告、错误和成功状态、状态图标、百分比、线性渐变，以及辅助技术可读的进度描述。（#1092）
• TTable：新增 onRowTap、实例级 bordered/stripe、行 key、合并单元格、列最小宽度和固定高度，优化排序、固定列及横向滚动交互。（#1140）
• TResult：统一内置状态图标、字号与间距，支持通过 iconSize/descriptionStyle 定制图标和描述样式。（#1093）
• TSlider：新增 normal/capsule 视觉形态，统一胶囊轨道、游标和刻度绘制。（#1144）

🐞 Bug Fixes

• TThemeData：修复稀疏自定义深色 JSON 的未配置背景、文字及引用错误回退为浅色 Token 的问题。（#1169）
• TButton
  • 修复渐变 outline/ghost 按钮尺寸与普通按钮不一致，以及 Loading 图标未继承按钮前景色的问题。（#1144、#1157）
  • 修复实例样式仅覆盖部分状态时丢失默认配色、边框或尺寸，以及幽灵按钮文字与描边未跟随自定义反色主题的问题。（#1157、#1169）
• TText：修复实例与组件 Theme 的样式优先级、子 Span 样式继承，以及内置单行文字在固定内容槽中的垂直偏移，保留多行正文、显式排版和自定义内容。（#1042、#1160）
• TFontLoader：并发加载共享 Future，加载失败可重试，并拒绝同名字体切换 URL。（#1042）
• TForm：修复校验时机、错误状态和 placeholder 的主题优先级，以及横排表单标签的间距与行高。（#1038、#1144）
• TInput
  • 修复密文模式无法粘贴、错误态清除图标配色，以及超长标签、图形/短信验证码操作区和输入内容的对齐与分割线问题。（#1005、#1007、#1010、#1018、#1021、#1102、#1144）
  • 修复输入及提示文字的自然行框布局，保留原生编辑、焦点、选择与前后插槽内容。（#1160）
• TTextarea：修复横排标签与输入提示文字未对齐的问题。（#1144）
• TSearchBar：修复背景高度、禁用操作文字、只读态清除按钮及中文输入法组合文本截断问题。（#1051）
• TCheckbox / TCheckboxGroup：修复单行、多行和卡片文案对齐、禁用未选样式、卡片间距及分割线起点和残留线问题；方形指示器圆角修正为 1.5px。（#1104、#1143、#1144）
• TRadio / TRadioGroup：修复群组分割线、横向间距、未选禁用态、状态文案和卡片内容安全间距。（#1119）
• TSwitch：修复长状态文案被额外缩字或不可读省略的问题，保留显式尺寸和两种状态的组件字号。（#1160）
• TRate：修复整星小数归一化、半星及 RTL 命中、拖动清零、交互生命周期、读屏信息和长文案布局；统一辅助文案的垂直对齐、默认颜色及未显式配置的字体属性。（#1056、#1070、#1108）
• TStepper：修复编辑草稿后加减按钮边界状态未及时更新、数字跨平台垂直对齐、三档尺寸行高，以及未设置主题字段时的尺寸和颜色插值问题。（#1064、#1122）
• TUpload：修复异步或重复选择时覆盖最新文件、丢失已添加文件，以及使用过期回调和文件限制的问题；区分选择器错误与业务回调异常。（#1151、#1153）
• TCalendar：修复日期文字默认颜色，日期、星期和月份区域按内容适配，保留显式高度、自定义 builder 和日期选择能力。（#1118、#1160）
• TPicker
  • 修复受控值更新导致拖动和惯性中断，以及选项文字跨平台对齐、滚轮高度不足、弹层内容裁切和滚动后中心项偏移的问题。（#1062、#1120、#1121、#1160）
  • 修复局部文字主题覆盖选中状态样式及高度主题插值异常；自定义 itemBuilder 保留调用方滚动配置和内置滚轮交互。（#1076、#1157）
• TDateTimePicker：修复候选值被父级拒绝后的自动回滚，以及文案回调或展示配置更新导致滚轮重建、连续拖动和惯性中断的问题。（#1061、#1159）
• TCascader：修复受控交互、键盘操作、层级面板尺寸与主题回退，以及层级图标颜色和标题间距。（#1060、#1144）
• TPopup：修复标题默认出现诊断下划线的问题，保留显式文字装饰。（#1062）
• TPopover：修复角落气泡及箭头的 12px 边缘间距、切换触发器后首次点击只关闭旧气泡，以及动态主题切换时可空样式被错误插值为透明色或零值的问题。（#1099、#1129、#1143）
• TActionSheet：修复列表自适应高度、带描述项高度、空描述占位和长列表滚动；统一宫格图标槽位、描述间距、分页指示点、取消区及分隔线。（#1030、#1123）
• TDialog：修复长内容缺少可见滚动条和关闭图标实际边距不正确的问题。（#1124）
• TToast：修复允许背景交互时可见蒙层仍拦截点击的问题。（#1154）
• TMessage：修复图标与文字间距及默认左右外边距，跑马灯宽度和结束位置适配显式字体、字距与系统文字缩放，避免结束后残留文字。（#1035、#1127、#1157）
• TNoticeBar：修复跑马灯滚动距离及首帧宽度计算；前缀与正文间距统一跟随 spacer8，避免自定义图标缺少间距，并修复主题过渡时尺寸归零或颜色变透明的问题。（#1032、#1128）
• TLoading：修复 customIcon 在 icon 为空时的显示优先级，使其持续旋转并响应动画时长更新；修正 activity 指示器默认颜色。（#1031、#1126）
• TFab：修复拖拽返回起点附近的误触，磁吸改为可取消的平滑动画，新拖拽或布局变化可终止旧动画。（#1040）
• TSwipeCell：修复外层文字样式错误覆盖操作项默认反色文字的问题。（#1131）
• TPullDownRefresh：修复暗色模式下刷新状态文案层级过亮的问题。（#1145）
• TTabsBar：修复自定义标签使用 Column/Expanded 时的高度约束异常，保持内置标签居中及默认胶囊高度。（#1160）
• TTabBar：修复一次手势触发重复选中回调、指示器动画模式切换及连续切换时的位置跳变，并校正胶囊圆角和弱选中徽标定位；修复局部文字及菜单主题覆盖、面板背景和可空主题字段插值问题。（#1085、#1144）
• TSideBar：修复徽标偏离文字右上角，以及字体放大时远端选中项无法准确滚动显露的问题，不增加额外选择回调；修复主题过渡时回退样式被半透明颜色或零内边距临时覆盖的问题。（#1135、#1137、#1160）
• TIndexes：修复主题切换时固定默认尺寸在动画中间态跳变的问题。（#1137）
• TNavBar：明确标题 Widget 自带样式优先于默认标题样式，修复主题切换时间距、边框和阴影跳变。（#1082、#1136）
• TSteps：修复局部文字主题覆盖失效和横向纯展示节点状态不一致的问题。（#1084）
• TBadge：修复中文、跨平台及文本缩放下的垂直对齐、默认位置和尺寸偏差，以及 bubble 被 Material 胶囊形状错误裁剪的问题。（#1070、#1071、#1106、#1107、#1141）
• TAvatar / TAvatarGroup：修复头像组形状裁剪、双向层叠、非法尺寸边界、成员尺寸、徽标圆点规格及主题动画插值问题。（#1090、#1141）
• TTag：修复配色和方角在动态主题切换时的中间帧跳变或意外半透明。（#1146）
• TCell：修复辅助信息默认字号、右侧插槽对齐，以及局部文字 Theme 覆盖部分字段时丢失默认字号、行高和字重的问题。（#1026、#1146）
• TCollapse：修复标题默认字重被上层主题意外加粗的问题。（#1143）
• TImageViewer：图片加载失败时显示错误占位，优化关闭动效、全屏背景、页码及顶部操作按钮的尺寸和交互状态。（#1091）
• TSwiper：修复默认圆角、卡片露出、fraction 胶囊、控制按钮及外置分页布局；修复显式按钮样式合并、状态回退与主题过渡，保留自定义图标及图层的调用方主题。（#1095、#1157）
• TProgress：修复按钮形态轨道和渐变绘制，以及自定义 Material 主色错误改写状态语义色，以及环形内圆在主题切换时跳变或意外半透明的问题。（#1092、#1146）
• TResult：修复主题切换时图标尺寸不稳定和部分文字样式覆盖丢失默认属性的问题；自定义插图保留原始比例，内置状态提供可读语义。（#1093）
• TSkeleton：统一占位色、16dp 行间距、图片圆角和 2 秒闪烁动效，改善预设与加载过程的视觉一致性。（#1094）
• TSlider / TRangeSlider：修复轨道、滑块、数值标签及禁用态配色，数值提示常驻显示，垂直标签保持正向；修复 Flutter 3.47 下连续/离散滑块的提示兼容问题。（#1010、#1063）
• TTreeSelect：补齐选中根节点左侧指示条。（#1144）
• TTimeCounter：修复动态启停、方向切换、终点回调和毫秒格式处理异常，统一三档尺寸及方形、圆形和单位倒计时展示。（#1096）
• TDropdownMenu：修复多列宽度不一致、蒙层透明度丢失、仿射滤镜越界拉伸时菜单与面板分离，以及禁用项背景和单选项错误文字高亮问题；统一菜单触发项与筛选面板的默认视觉。（#1034、#1125、#1144）
• 组件文字布局：修复 Tag、Switch、选择卡片、ActionSheet、Progress、Refresh 和 Upload 等组件在默认尺寸下的文字裁切，保留显式尺寸与原生交互。（#1160）
• Flutter 版本兼容：修复 DropdownMenu、CupertinoSwitch 和 Swiper 的跨版本 API 兼容问题，兼顾 Flutter 3.32 与较新版本的行为。（#1010）

感谢所有参与开发、反馈和贡献的社区伙伴！