breaking(TSwitch): separate loading from content variant

Author: RSS1102

specs/014-switch-loading-state/acceptance.md

@@ -0,0 +1,27 @@
+# 验收记录
+
+## 验证环境
+
+- 分支：rss1102/style/switch-miniprogram-alignment
+- 提交：本 Spec 与 breaking API 实现一并提交
+- Flutter/Dart：Flutter 3.32.0 / Dart 3.8.0；latest 待 CNB CI 验证
+
+## 自动化验证
+
+| 命令 | 结果 | 备注 |
+| --- | --- | --- |
+| `flutter test test/components/switch/t_switch_test.dart --coverage` | 通过 | 15 项；Switch 生产目录 341/358，95.25% |
+| `flutter test test/switch_page_test.dart --coverage` | 通过 | 4 项；Demo 49/49，100%；light/dark Golden 非更新模式通过 |
+| `flutter analyze`（tdesign-component） | 通过 | 0 issues |
+| `flutter analyze`（example） | 通过 | 0 issues |
+| `dart run tool/generate_example_code.dart --check --verbose` | 通过 | 所有片段已同步 |
+| `node tool/generate_api.mjs` | 通过 | Switch API 文档已同步 |
+| `git diff --check` | 通过 | 无空白错误 |
+
+## 人工验收
+
+- [ ] Android 实机确认 Switch 加载状态与分组展示
+
+## 未覆盖项与后续工作
+
+- Flutter latest 依赖 CNB CI 验证；本地未安装第二套 SDK。

specs/014-switch-loading-state/plan.md

@@ -0,0 +1,35 @@
+# 实施方案
+
+## 技术方案
+
+在 TSwitch 上新增必选默认值参数 `loading = false`，并从
+`TSwitchVariant` 删除 `loading`。构建时先根据 `loading` 决定交互能力和
+加载指示器，再由 `variant` 处理非加载内容形态，避免两个加载状态源。
+
+## 影响范围
+
+| 范围 | 文件或模块 | 影响 |
+| --- | --- | --- |
+| 组件 | switch/t_switch.dart、t_switch_types.dart | breaking API 收敛 |
+| 测试 | t_switch_test.dart、switch_page_test.dart | 更新加载态和回归覆盖 |
+| 示例 | t_switch_page.dart、Golden、生成片段 | 迁移到 loading 参数 |
+| 文档 | Switch API 产物、Spec | 记录新契约和迁移方式 |
+
+## API 变化
+
+- 新增 `TSwitch.loading`，默认 `false`。
+- 删除 `TSwitchVariant.loading`。
+- 迁移：`variant: TSwitchVariant.loading` 改为 `loading: true`。
+
+## 风险与取舍
+
+- 删除枚举值是 breaking change，不保留兼容别名，以免形成双状态源。
+- loading 与 variant 同时传入时，loading 负责当前状态并覆盖滑块内容；
+  loading 结束后恢复 variant 指定的内容形态。
+
+## 验证策略
+
+- 单元测试：加载渲染、禁用交互、variant 恢复和 API 形态。
+- 集成或 Widget 测试：Demo 状态矩阵、交互及 light/dark Golden。
+- 静态检查：组件包和 Example 包 flutter analyze。
+- 人工验收：Android 实机查看加载、禁用、尺寸分组。

specs/014-switch-loading-state/spec.md

@@ -0,0 +1,53 @@
+# TSwitch 加载状态 API 收敛
+
+## 背景
+
+`TSwitchVariant` 同时包含 `filled`、`text`、`icon` 三种内容形态和
+`loading` 状态，导致同一枚举混合展示形态与交互状态。加载状态需要成为
+独立且唯一的公开状态源。
+
+## 目标
+
+- 以 `final bool loading` 作为 TSwitch 加载状态的唯一入口。
+- `TSwitchVariant` 只保留 `filled`、`text`、`icon` 三种内容形态。
+- 加载中显示加载指示器并禁用交互。
+- 同步示例、测试、Golden、API 文档和迁移说明。
+
+## 非目标
+
+- 不新增 `disabled`，禁用仍由 `onChanged == null` 表达。
+- 不引入非受控值或自定义值类型。
+- 不改变尺寸、颜色和主题优先级。
+
+## 范围
+
+### 涉及
+
+- TSwitch 构造参数、加载渲染与交互语义。
+- TSwitchVariant 枚举。
+- Switch 组件测试、示例测试、示例代码和 Golden。
+- 生成的 Switch API 文档与代码片段。
+
+### 不涉及
+
+- TCupertinoSwitch 公开契约。
+- ExampleItem、ExamplePage 或公共 Example 抽象。
+
+## 行为契约
+
+- `loading` 默认为 `false`。
+- `loading == true` 时，滑块内容显示加载指示器，`onChanged` 不会触发，
+  语义节点为不可交互。
+- `loading == false` 时，`variant` 决定 `filled`、`text` 或 `icon` 内容形态。
+- `TSwitchVariant.loading` 被删除；迁移方式为
+  `variant: TSwitchVariant.loading` → `loading: true`。
+- `onChanged == null` 仍是普通禁用状态的唯一入口。
+
+## 验收标准
+
+- [ ] TSwitchVariant 仅保留 filled、text、icon。
+- [ ] TSwitch 仅通过 loading 表达加载状态，默认值为 false。
+- [ ] 加载态渲染、禁用交互和语义测试通过。
+- [ ] 示例、代码片段、API 文档与 Golden 同步。
+- [ ] Switch 生产目录覆盖率不低于 95%。
+- [ ] Flutter 3.32.0 与 latest 的 analyze/test 门禁通过。

specs/014-switch-loading-state/tasks.md

@@ -0,0 +1,8 @@
+# 实施任务
+
+- [x] DONE 明确需求和验收边界
+- [x] DONE 完成实现
+- [x] DONE 补充或更新测试
+- [x] DONE 更新示例和 API 文档
+- [x] DONE 执行验证并记录结果
+- [x] DONE 完成 Review

tdesign-component/example/assets/api/switch_api.md

@@ -6,6 +6,7 @@
 | --- | --- | --- | --- |
 | closeText | String? | - | text 形态的关闭文案。 |
 | key | Key? | - | 组件标识，用于区分或保留组件状态。 |
+| loading | bool | false | 是否处于加载状态；加载时显示指示器并禁用交互。 |
 | onChanged | ValueChanged<bool>? | - | 开关状态变更回调；为 null 时禁用。 |
 | openText | String? | - | text 形态的开启文案。 |
 | size | TSwitchSize? | - | 开关尺寸；未传时读取 `TSwitchThemeData.defaultSize`。 |

tdesign-component/example/assets/code/switch._buildStatus.txt

@@ -7,12 +7,9 @@ Widget _buildStatus(BuildContext context) => const Column(
         cells: [
           TCell(
             title: Text('加载状态'),
-            note: TSwitch(value: false, variant: TSwitchVariant.loading),
-          ),
-          TCell(
-            title: Text('加载状态'),
-            note: TSwitch(value: true, variant: TSwitchVariant.loading),
+            note: TSwitch(value: false, loading: true),
           ),
+          TCell(title: Text('加载状态'), note: TSwitch(value: true, loading: true)),
         ],
       ),
       _SwitchGroupLabel('禁用状态', top: 24),

tdesign-component/example/lib/page/t_switch_page.dart

@@ -112,12 +112,9 @@ class TSwitchPage extends StatelessWidget {
         cells: [
           TCell(
             title: Text('加载状态'),
-            note: TSwitch(value: false, variant: TSwitchVariant.loading),
-          ),
-          TCell(
-            title: Text('加载状态'),
-            note: TSwitch(value: true, variant: TSwitchVariant.loading),
+            note: TSwitch(value: false, loading: true),
           ),
+          TCell(title: Text('加载状态'), note: TSwitch(value: true, loading: true)),
         ],
       ),
       _SwitchGroupLabel('禁用状态', top: 24),

tdesign-component/example/test/switch_page_test.dart

@@ -134,7 +134,7 @@ void main() {
     final switches = tester.widgetList<TSwitch>(find.byType(TSwitch)).toList();
     final variants = switches.map((widget) => widget.variant).toSet();
     final loadingValues = switches
-        .where((widget) => widget.variant == TSwitchVariant.loading)
+        .where((widget) => widget.loading)
         .map((widget) => widget.value)
         .toSet();
     final disabledValues = switches

tdesign-component/lib/src/components/switch/t_switch.dart

@@ -11,8 +11,9 @@ export 't_switch_types.dart';
 
 /// 严格受控的开关组件。
 ///
-/// [value] 由父级持有；[onChanged] 为 null 时禁用。文字、图标和加载形态
-/// 无法由 Material Switch 完整表达，因此底层保留 TDesign 自定义开关实现。
+/// [value] 由父级持有；[onChanged] 为 null 时禁用；[loading] 为 true 时
+/// 显示加载指示器并禁用交互。文字、图标和加载内容无法由 Material Switch
+/// 完整表达，因此底层保留 TDesign 自定义开关实现。
 class TSwitch extends StatelessWidget {
   const TSwitch({
     super.key,
@@ -29,6 +30,9 @@ class TSwitch extends StatelessWidget {
     /// 开关内容形态；未传时读取 [TSwitchThemeData.defaultVariant]。
     this.variant,
 
+    /// 是否处于加载状态；加载时显示指示器并禁用交互。
+    this.loading = false,
+
     /// text 形态的开启文案。
     this.openText,
 
@@ -48,6 +52,9 @@ class TSwitch extends StatelessWidget {
   /// 开关内容形态。
   final TSwitchVariant? variant;
 
+  /// 是否处于加载状态；加载时显示指示器并禁用交互。
+  final bool loading;
+
   /// text 形态的开启文案。
   final String? openText;
 
@@ -60,8 +67,7 @@ class TSwitch extends StatelessWidget {
     final resolvedSize = size ?? theme?.defaultSize ?? TSwitchSize.medium;
     final resolvedVariant =
         variant ?? theme?.defaultVariant ?? TSwitchVariant.filled;
-    final enabled =
-        onChanged != null && resolvedVariant != TSwitchVariant.loading;
+    final enabled = onChanged != null && !loading;
     final resolved = TSwitchResolve.resolve(
       context: context,
       enabled: enabled,
@@ -79,6 +85,7 @@ class TSwitch extends StatelessWidget {
       thumbView: _buildThumb(
         resolved: resolved,
         variant: resolvedVariant,
+        loading: loading,
         openText: openText,
         closeText: closeText,
       ),
@@ -105,9 +112,17 @@ class TSwitch extends StatelessWidget {
   Widget? _buildThumb({
     required TSwitchResolvedStyle resolved,
     required TSwitchVariant variant,
+    required bool loading,
     required String? openText,
     required String? closeText,
   }) {
+    if (loading) {
+      return TCircleIndicator(
+        color: resolved.thumbContentOnColor,
+        size: 16,
+        lineWidth: 3,
+      );
+    }
     return switch (variant) {
       TSwitchVariant.text => SizedBox(
         width: 16,
@@ -130,11 +145,6 @@ class TSwitch extends StatelessWidget {
           ),
         ),
       ),
-      TSwitchVariant.loading => TCircleIndicator(
-        color: resolved.thumbContentOnColor,
-        size: 16,
-        lineWidth: 3,
-      ),
       TSwitchVariant.icon => Icon(
         value ? TIcons.check : TIcons.close,
         size: 16,

tdesign-component/lib/src/components/switch/t_switch_types.dart

@@ -18,9 +18,6 @@ enum TSwitchVariant {
   /// 滑块内显示开关文案。
   text,
 
-  /// 滑块内显示加载指示器，并禁用交互。
-  loading,
-
   /// 滑块内显示开关图标。
   icon,
 }