新增表单校验规则

本 skill 提供一套标准的工作流程，用于为项目的表单验证系统添加新的校验规则。

概述

项目采用 Ant Design Vue 4.x + 自定义规则引擎 的表单验证方案：

类型定义：src/components/atoms/AtmForm/index.ts 中的 BuiltInRules 接口
规则实现：src/hooks/useForm/getAntDFormRules.ts 中的规则转换逻辑
验证函数：src/utils/validation/ 目录下的具体验证实现
单元测试：src/hooks/useForm/getAntDFormRules.spec.ts 中的测试用例

核心流程

1. 添加类型定义

位置：src/components/atoms/AtmForm/index.ts

在 BuiltInRules 接口中添加新的规则属性：

export interface BuiltInRules {
  // 示例：添加新规则
  myNewRule?: string | number | boolean | RegExp
}

规则类型指南：

简单布尔规则（无参数）：boolean — 如 email?: boolean
带参数的规则：根据参数类型 — 如 dateFormat?: string、maxValue?: number
多参数规则：string（JSON格式）— 如 range?: '[1,10]'
正则表达式：RegExp 类型
数组参数：string[] | string — 如 fileExtension?: string | string[]

2. 实现规则逻辑

位置：src/hooks/useForm/getAntDFormRules.ts

简单规则（simpleRules）- 正则/直接模式

用于无需参数的规则，在 simpleRules 对象中添加：

const simpleRules: Record<string, Rule> = {
  mySimpleRule: {
    pattern: /your-regex-pattern/,
    message: '错误提示文案',
    trigger: 'blur'
  }
}

复杂规则（getValidationRule）- 自定义验证器

在 getValidationRule 函数返回的规则对象中添加：

myComplexRule: {
  validator: (_, value) => {
    // 验证逻辑
    return validationHelper(validateResult, errorMessage);
  },
  trigger: rule?.trigger || 'blur',
  transform: rule?.transform
}

验证函数调用：优先使用已有验证函数（如 validateDateFormat、validateNumberRange），减少新增文件。

2.1 更新 isBuiltInRule 函数

位置：src/hooks/useForm/getAntDFormRules.ts 中的 isBuiltInRule 函数

在添加新规则属性到 BuiltInRules 接口后，必须在 isBuiltInRule 函数中的 ruleKeys 数组里添加对应的属性名：

function isBuiltInRule(value: any): value is RuleOptions {
  if (!isObject(value)) return false

  const ruleKeys = [
    'required',
    'pattern',
    // ... 其他现有属性 ...
    'myNewRule' // ← 添加新属性名
  ]

  // ... 后续逻辑保持不变 ...
}

⚠️ 这一步容易遗漏！ 如果不更新 ruleKeys，新规则将被错误地识别为无效对象，导致规则处理失败。

3. 添加或重用验证函数

位置：src/utils/validation/ 目录

决策树：

如果是正则模式（简单规则），直接在 simpleRules 中定义，不需要创建验证函数
如果需要复杂验证逻辑：
- ✅ 优先选择：现有的 .ts 文件（date.ts、number.ts、string.ts、file.ts）
- ❌ 最后选择：创建新的验证文件，仅当逻辑完全不相关时

验证函数特征：

输入参数是值和规则配置
返回 boolean 或 { valid: boolean; message?: string }
处理 null、undefined 等边界情况

4. 编写单元测试

位置：src/hooks/useForm/getAntDFormRules.spec.ts

测试模板：

it('myNewRule 规则正确转换', () => {
  const rules: FormRules = {
    field: {
      myNewRule: true // 或对应的参数值
    }
  }

  const result = getAntDFormRules(rules)
  const fieldRules = result!.field as Rule[]

  expect(fieldRules).toContainEqual({
    pattern: expect.any(RegExp), // 或 validator: expect.any(Function)
    message: expect.any(String),
    trigger: 'blur'
  })
})

// 对于带参数的规则，添加验证器功能测试
it('myNewRule 验证器正确工作', async () => {
  const rules: FormRules = {
    field: {
      myNewRule: 'paramValue'
    }
  }

  const result = getAntDFormRules(rules)
  const fieldRules = result!.field as Rule[]
  const myRule = fieldRules.find(rule => rule.validator)

  // 成功情况
  await expect(myRule!.validator!({}, 'validValue', () => {})).resolves.toBeUndefined()

  // 失败情况
  await expect(myRule!.validator!({}, 'invalidValue', () => {})).rejects.toThrow('错误提示文案')
})

5. 执行测试

# 运行指定测试文件
npm test -- getAntDFormRules.spec.ts --run

# 运行所有表单相关测试
npm test -- useForm --run

# 查看测试覆盖率
npm test -- --coverage --run

代码示例

示例 1：简单的正则校验规则

添加一个汉字验证规则：

1. 类型定义 (AtmForm/index.ts)：

export interface BuiltInRules {
  chineseCharacters?: boolean
}

2. 规则实现 (getAntDFormRules.ts)：

const simpleRules: Record<string, Rule> = {
  chineseCharacters: {
    pattern: /^[\u4e00-\u9fff]+$/,
    message: '仅支持汉字输入',
    trigger: 'blur'
  }
}

3. 单元测试 (getAntDFormRules.spec.ts)：

it('chineseCharacters 规则正确转换', () => {
  const rules: FormRules = {
    name: { chineseCharacters: true }
  }
  const result = getAntDFormRules(rules)
  expect(result!.name).toContainEqual({
    pattern: expect.any(RegExp),
    message: '仅支持汉字输入',
    trigger: 'blur'
  })
})

示例 2：带参数的自定义验证规则

添加一个字符串长度百分比验证规则（例如，验证实际输入不超过最大长度的80%）：