breaking(TSwitch): 独立加载状态并收敛示例 (#1050)

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._buildBasic.txt

@@ -1,4 +1,4 @@
 Widget _buildBasic(BuildContext context) => const TCell(
-        title: Text('基础开关'),
-        note: _StatefulSwitch(),
-      );
+    title: Text('基础开关'),
+    note: _StatefulSwitch(initialValue: true),
+  );

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

@@ -0,0 +1,9 @@
+Widget _buildColor(BuildContext context) => Theme(
+    data: Theme.of(
+      context,
+    ).mergeExtension(const TSwitchThemeData(trackOnColor: Color(0xFF00A870))),
+    child: const TCell(
+      title: Text('自定义颜色开关'),
+      note: _StatefulSwitch(initialValue: true),
+    ),
+  );

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

@@ -0,0 +1,17 @@
+Widget _buildLabel(BuildContext context) => const TCellGroup(
+    cells: [
+      TCell(
+        title: Text('带文字开关'),
+        note: _StatefulSwitch(
+          initialValue: true,
+          variant: TSwitchVariant.text,
+          openText: '开',
+          closeText: '关',
+        ),
+      ),
+      TCell(
+        title: Text('带图标开关'),
+        note: _StatefulSwitch(initialValue: true, variant: TSwitchVariant.icon),
+      ),
+    ],
+  );