20260816220132
This commit is contained in:
oneao committed
1 parent
b6f9a4c912
commit
72993ecdcd
179 files changed
+20050
-633
No files matched your search
@@ -0,0 +1,165 @@
|
||||
---
|
||||
name: form-component
|
||||
overview: 为 fms-vue 组件库新增一个精简的 Form 表单组件（Form + FormItem），支持 horizontal/vertical 两种布局、基础校验规则（required/pattern/min/max/len/type/自定义 validator）、提交与重置事件，并将校验错误态自动传递给内部 Input/Select/DatePicker 等控件。
|
||||
design:
|
||||
architecture:
|
||||
framework: vue
|
||||
styleKeywords:
|
||||
- 极简
|
||||
- 企业级
|
||||
- 清晰层级
|
||||
- token驱动
|
||||
fontSystem:
|
||||
fontFamily: PingFang SC
|
||||
heading:
|
||||
size: 18px
|
||||
weight: 500
|
||||
subheading:
|
||||
size: 12px
|
||||
weight: 500
|
||||
body:
|
||||
size: 14px
|
||||
weight: 400
|
||||
colorSystem:
|
||||
primary:
|
||||
- "#0f172b"
|
||||
- "#ffffff"
|
||||
background:
|
||||
- "#f5f6f8"
|
||||
- "#ffffff"
|
||||
text:
|
||||
- "#1f2329"
|
||||
- "#86909c"
|
||||
functional:
|
||||
- "#ef4444"
|
||||
- "#f59e0b"
|
||||
- "#16a34a"
|
||||
todos:
|
||||
- id: form-core
|
||||
content: 新增 form 目录：validate.js 校验工具、tokens.css 新增 form 专属 token
|
||||
status: completed
|
||||
- id: form-container
|
||||
content: 实现 form.vue 容器：provide 上下文、字段注册、submit/submitFailed/reset 事件，参考 [skill:antdv-next] Form API
|
||||
status: completed
|
||||
dependencies:
|
||||
- form-core
|
||||
- id: form-item
|
||||
content: 实现 form-item.vue 与 index.scss：label 布局、校验时机、错误态 provide，参考 [skill:antdv-next] FormItem 交互
|
||||
status: completed
|
||||
dependencies:
|
||||
- form-container
|
||||
- id: control-inject
|
||||
content: 为 Input/Select/DatePicker/RangePicker/TimeSelect 注入错误态，Button 新增 htmlType prop
|
||||
status: completed
|
||||
dependencies:
|
||||
- form-item
|
||||
- id: demo-register
|
||||
content: 新增 demo/form.vue 演示页并注册到 App.vue，用 [skill:ui-ux-pro-max] 把关视觉
|
||||
status: completed
|
||||
dependencies:
|
||||
- form-container
|
||||
- form-item
|
||||
- control-inject
|
||||
---
|
||||
|
||||
## 产品概述
|
||||
|
||||
一个轻量的 Form 表单组件，遵循项目开发规范，参考 antdv-next 组件库的 API 与交互设计，但刻意精简功能：仅覆盖日常表单填写、校验与提交的核心场景。
|
||||
|
||||
## 核心功能
|
||||
|
||||
- 两种布局：horizontal（label 在左）与 vertical（label 在上）
|
||||
- FormItem 表单项：label、必填红星标记、辅助说明（extra）、固定提示（help）
|
||||
- 校验规则：required、pattern、min/max/len、type（email/number/integer/url）、自定义 validator（支持同步/异步）
|
||||
- 提交/重置由原生 submit/reset 事件驱动，无需 ref 实例方法
|
||||
- 校验失败自动给内部 Input/Select/DatePicker 等控件注入红色错误态（边框 + aria-invalid）
|
||||
- 支持全局 disabled、label 对齐、label 宽度、必填标记开关、label 冒号等配置
|
||||
- 提交成功 / 失败事件（submit / submitFailed），供业务层回调
|
||||
|
||||
## 技术栈
|
||||
|
||||
- Vue 3 Composition API（`<script setup>`）+ SCSS + Lucide 图标
|
||||
- 复用现有 `--fms-*` CSS token；校验自研轻量实现，不引入 async-validator 新依赖
|
||||
|
||||
## 实现方案
|
||||
|
||||
- **上下文传递**：Form 通过 `provide('fms-form')` 下发配置与注册/校验机制，FormItem `inject` 消费并注册字段；FormItem 通过 `provide('fms-form-item')` 下发计算后的校验状态，Input/Select/DatePicker 等控件 `inject` 消费（可选注入，独立使用时行为不变，保持向后兼容）
|
||||
- **校验机制**：`validate.js` 纯函数按规则数组逐条执行，返回 `Promise<string[]>`；Form 提交时遍历注册字段并行校验，全部通过 emit submit，否则 emit submitFailed 并携带 errorFields
|
||||
- **校验时机**：submit 全量校验；validateTrigger 为 change 时 watch model[name] 明确依赖触发，为 blur 时通过 focusout 判断焦点离开控件区域触发
|
||||
- **性能**：watch 只限定单字段依赖，不做深监听；错误状态存本地 ref，仅失败项重渲染；过渡只用颜色/透明度低成本属性并支持 prefers-reduced-motion
|
||||
|
||||
### 系统架构
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Form["Form form.vue<br/>props: model/rules/layout/...<br/>provide('fms-form')"] -->|注册/校验| Item["FormItem form-item.vue<br/>props: name/label/rules/...<br/>provide('fms-form-item')"]
|
||||
Item -->|inject 可选| Input["Input / Select /<br/>DatePicker / RangePicker"]
|
||||
Form -->|原生 form submit| Validate["validate.js<br/>轻量校验纯函数"]
|
||||
Validate -->|错误数组| Item
|
||||
Item -->|is-error 样式| Input
|
||||
```
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
fms-vue/src/
|
||||
├── components/ui/
|
||||
│ ├── form/
|
||||
│ │ ├── form.vue # [NEW] Form 容器：配置下发、字段注册、submit/reset 事件
|
||||
│ │ ├── form-item.vue # [NEW] 表单项：label 布局、校验时机、错误态 provide
|
||||
│ │ ├── validate.js # [NEW] 校验纯函数：规则执行、消息生成，返回 Promise<string[]>
|
||||
│ │ └── index.scss # [NEW] 布局/必填星/错误提示样式（复用 token）
|
||||
│ ├── input/input.vue # [MODIFY] 可选 inject fms-form-item，合并错误态
|
||||
│ ├── select/select.vue # [MODIFY] 同上；index.scss 增加 is-error/is-warning 触发器边框
|
||||
│ ├── date/date-picker.vue # [MODIFY] 同上
|
||||
│ ├── date/range-picker.vue # [MODIFY] 同上
|
||||
│ ├── date/time-select.vue # [MODIFY] 同上（时间选择在表单中展示错误态）
|
||||
│ ├── date/index.scss # [MODIFY] 增加 .is-error .fms-date-trigger 等红色边框
|
||||
│ ├── button/button.vue # [MODIFY] 新增 htmlType prop（button|submit|reset）
|
||||
│ └── demo/form.vue # [NEW] 演示页：基础/纵向/自定义校验/错误态联动
|
||||
├── theme/tokens.css # [MODIFY] 新增 form 专属 token
|
||||
└── App.vue # [MODIFY] 「数据录入」分类注册 Form 表单 demo
|
||||
```
|
||||
|
||||
## 关键代码结构
|
||||
|
||||
```js
|
||||
// validate.js —— 校验纯函数签名
|
||||
export function validateRules(name, label, value, rules) // Promise<string[]>
|
||||
// 规则对象支持：{ required, pattern, min, max, len, type, message, validator }
|
||||
// validator: (value) => boolean | string | Promise<boolean | string>
|
||||
|
||||
// fms-form 上下文（form.vue provide）
|
||||
{ model, rules, layout, labelAlign, labelWidth, requiredMark, disabled,
|
||||
validateTrigger, colon, registerField(name, validateFn), unregisterField(name), validateAll() }
|
||||
|
||||
// fms-form-item 上下文（form-item.vue provide，供控件可选消费）
|
||||
{ status, errorMessage }
|
||||
```
|
||||
|
||||
## 实现注意事项
|
||||
|
||||
- 遵循 `开发规范.md`：props 全带类型/默认值、枚举带 validator、代码分块注释、样式只用 token、不主动构建测试
|
||||
- Button 现有 `type` 是视觉变体（default/secondary/...），新 prop 命名 `htmlType` 映射原生 type，避免冲突
|
||||
- Select 无 status prop，用根元素 class `is-error` + `index.scss` 新增触发器红色边框，样式与 input-error 一致（`--fms-danger` + focus 光圈）
|
||||
- date 系列共享 `date/index.scss`（已 import），错误态样式集中加在此文件，覆盖 date/range/time 三类触发器
|
||||
- 校验时机用 touched 标记避免初始空值即报红：仅在提交后或值变化后才展示错误
|
||||
|
||||
## 设计风格
|
||||
|
||||
延续现有组件库的极简企业风：token 驱动的浅色/深色主题自适应，干净的白底卡片式演示面板。Form 组件本体强调信息层级清晰——横向布局 label 定宽右对齐与控件严格对齐，垂直布局上下堆叠留白一致；错误态用红色文字 + 红色边框 + focus 光圈，与 Input 现有校验样式统一；必填红星、辅助说明、错误提示三级信息通过颜色和字号区分主次。
|
||||
|
||||
## 页面规划
|
||||
|
||||
demo/form.vue 按现有 showcase 规范组织，包含 4 个功能区块：基础用法（横向）、纵向布局、自定义校验（validator 联动）、错误态联动（Select/DatePicker 红色边框演示），顶部统一 section-heading，底部提交/重置按钮用 Button 组件呈现。
|
||||
|
||||
## Agent Extensions
|
||||
|
||||
### Skill
|
||||
|
||||
- **antdv-next**
|
||||
- 用途：实现 Form/FormItem 组件时，检索参考组件库中 Form 的 props/events/slots 与交互设计（必填星、错误态、布局细节）
|
||||
- 预期结果：确认 API 命名与交互细节对齐参考库的精简子集，避免遗漏关键行为
|
||||
- **ui-ux-pro-max**
|
||||
- 用途：demo/form.vue 演示页与表单视觉设计参考，确保错误态/必填星等视觉规范现代且统一
|
||||
- 预期结果：演示页布局清晰、视觉层级合理，符合组件库既有风格
|
||||
Reference in new issue
Block a user