Browse Source

docs: 增加业务表单控件迁移 TDesign 设计

第一轮覆盖设备/任务/固件页,约定 select/input/number/time
映射与 v-model 行为,其余页面后续轮次。
main
xiaosi 3 weeks ago
parent
commit
64806167d3
  1. 68
      docs/superpowers/specs/2026-08-28-tdesign-form-controls-migration-design.md

68
docs/superpowers/specs/2026-08-28-tdesign-form-controls-migration-design.md

@ -0,0 +1,68 @@
# 业务表单控件迁移到 TDesign
## 背景
项目已接入 `tdesign-vue-next`(Vite `TDesignResolver` 按需引入)。登录页已用 `t-input` / `t-button` 等,但业务页筛选栏与弹窗表单仍大量使用原生 `<select>` / `<input>`。全站 `t-select` 用量为 0。
目标方向:**能换的表单控件尽量全换**。本需求按页面分轮推进。
## 目标
1. 统一业务页表单控件为 TDesign,优先视觉与交互一致。
2. 第一轮完成高频页:`DevicesView` / `TasksView` / `FirmwaresView`
3. 不改变业务逻辑与接口契约。
## 非目标
- 不改后台。
- 不重做页面布局 / 表格体系。
- 不在本轮替换地图内特殊控件、自定义外观开关(若强绑定原型 CSS,可暂留并标注)。
- 不在本轮做完整 TDesign 主题定制(与 `prototype.css` 深度对齐另开)。
- 第二轮页面(Users / OperationLogs / Account / DeviceDetail 等)不纳入本轮实现。
## 第一轮范围
| 页面 | 控件 |
|------|------|
| `DevicesView` | 搜索 input、状态/绑定 select、新增机巢表单 inputs、升级固件 select |
| `TasksView` | 各 Tab 搜索 input、计划/设备/结果 select、任务/航线/航点表单 inputs、number、time、星期 select;原始视频录制自定义 checkbox → `t-switch``t-checkbox`(保持布尔语义) |
| `FirmwaresView` | 搜索 input、状态 select、创建/编辑表单 inputs + number + select |
## 控件映射
| 原生 | TDesign | 约定 |
|------|---------|------|
| `<select>` | `t-select` | `:options="[{ label, value }]"`;少用 `<option>` 插槽 |
| 文本 `<input>` | `t-input` | 搜索框可 `clearable`;短必填码按需 |
| `type="number"` | `t-input-number` | 保留 `min/max/step`;`v-model` 数值语义不变 |
| `type="time"` | `t-time-picker` | 绑定现有 `HH:mm` 字符串字段 |
| 自定义录制 checkbox | `t-switch`(优先)或 `t-checkbox` | 仍绑定 `boolean` |
| 纯展示/地图专用 input | 暂不换 | 标注原因 |
尺寸:默认 `size="medium"`。筛选栏与工具栏用现有容器 class 限宽,尽量少覆盖 TDesign 主题变量。
## 行为约定
1. **v-model 类型不变**:空筛选项继续用 `''`;数值 select(如星期)继续 number。
2. **事件**:原 `@change="reload"` 改为 `t-select``@change` 调同一 `reload`(或等价 watch,但优先显式事件以免双触发)。
3. **选项数据**:在 `<script setup>` 提成常量/computed(如 `statusOptions`),模板只绑 `:options`
4. **无障碍**:原 `aria-label` 迁到 `t-select``placeholder` / 外层 label。
5. **依赖**:不新增 npm 包;沿用自动按需引入。
## 验收
1. 上述三页无业务表单原生 `<select>`;可换的文本/数字/时间输入已换 TDesign。
2. 筛选变更仍触发列表刷新;创建/编辑提交字段与改前一致。
3. 登录页与其它未纳入页面行为不回归。
4. 每页至少一次浏览器冒烟:打开筛选、改 select、打开一个表单弹窗填报。
## 风险
- TDesign 高度/边框与 `prototype.css` 工具栏不完全一致 → 用有限 class 调宽高,不全局改主题。
- `t-input-number` / `t-time-picker` 空值与原生 string/number 混用 → 提交前保持与现有校验一致。
- 任务页控件多 → 按页面拆 commit,避免巨石 diff。
## 后续轮次(不在本轮)
- Users / OperationLogs / Account / DeviceDetail 等剩余原生 select/input。
- 可选:TDesign 主题 token 与原型色板对齐。
Loading…
Cancel
Save