表单规则

这一页说明 apps/admin 当前的认证表单校验入口。它不是通用表单库文档，而是解释应用内 features/auth/use-auth-form-rules.ts 如何把共享正则、i18n 文案和 Ant Design Form 规则组合起来。

当前事实：useAuthFormRules() 只被登录、验证码登录、注册和重置密码页面使用。管理页列表里的搜索表单由 表格与表单 说明；这里聚焦认证场景的字段级校验规则。

只想查 useAuthFormRules() 的返回值、预设规则集合和规则工厂签名，直接看 表单规则 API。

适用场景

当前实现位置

为什么不放进 admin-i18n

packages/web/admin-i18n 只负责 i18next 初始化、语言状态、语言切换 UI 和 locale 资源。form.json 放在那里是因为它是翻译资源；Ant Design FormRule、字段名和确认密码逻辑不属于 i18n 运行时。

useAuthFormRules() 同时依赖三类东西：

因此当前最佳位置是 apps/admin/src/features/auth。如果未来多个页面、多个应用或多个包都需要通用规则工厂，再考虑抽出纯工厂能力，例如 createRequiredRule(message)、createPatternRule(options)、createConfirmFieldRule(options)；认证字段集合仍应留在应用或认证模块里。

核心概念

useAuthFormRules() 返回五类能力：

规则本身是 Ant Design FormRule，因此最终仍交给 Form.Item 的 rules 消费。useAuthFormRules() 只负责把认证页常用模式收口。

最小可用示例

登录页当前用法可以简化成：

import { useAuthFormRules } from '@/features/auth/use-auth-form-rules';

interface LoginFormModel {
  /** 用户登录名。 */
  userName: string;
  /** 用户登录密码。 */
  password: string;
}

const LoginForm = () => {
  const [form] = AForm.useForm<LoginFormModel>();
  const {
    formRules: { pwd, userName }
  } = useAuthFormRules();

  function handleSubmit(params: LoginFormModel) {
    login(params);
  }

  return (
    <AForm form={form} onFinish={handleSubmit}>
      <AForm.Item name="userName" rules={userName}>
        <AInput size="large" />
      </AForm.Item>
      <AForm.Item name="password" rules={pwd}>
        <AInput.Password autoComplete="password" size="large" />
      </AForm.Item>
    </AForm>
  );
};

页面不需要重复写用户名和密码正则，也不需要自己拼 i18n key。

预设规则

formRules 当前包含：

如果只需要格式校验，使用 patternRules。例如可选邮箱字段可以这样写：

const { patternRules } = useAuthFormRules();

<AForm.Item name="email" rules={[patternRules.email]}>
  <AInput allowClear />
</AForm.Item>;

确认密码规则

createConfirmPwdRule(form) 当前读取的是表单里的 password 字段：

const pwd = form.getFieldValue('password');

因此使用它时，主密码字段必须叫 password：

const { createConfirmPwdRule, formRules } = useAuthFormRules();

<AForm form={form}>
  <AForm.Item name="password" rules={formRules.pwd}>
    <AInput.Password />
  </AForm.Item>
  <AForm.Item name="confirmPassword" rules={createConfirmPwdRule(form)}>
    <AInput.Password />
  </AForm.Item>
</AForm>;

如果业务表单里的主密码字段不叫 password，不要在页面里偷改 Form 值。要么保持字段命名一致，要么先扩展 createConfirmPwdRule() 的入参，让规则能显式接收源字段名。

验证码按钮

注册和验证码登录页面除了 Form 规则，还会用 REG_PHONE 判断发送验证码按钮是否可点：

const phone = AForm.useWatch('phone', form);
const isValidPhone = REG_PHONE.test(phone);

这只是交互层的即时判断，不替代 formRules.phone。提交时仍然应由 Ant Design Form 执行完整校验。

新增规则

新增一个认证字段规则时，按这个顺序做：

1. 如果需要新正则，先在 @skyroc/utils 增加或复用常量。
2. 在 packages/web/admin-i18n/src/langs/*/form.json 增加 required / invalid 文案。
3. 在 apps/admin/src/types/locales/form.d.ts 增加类型。
4. 在 apps/admin/src/features/auth/use-auth-form-rules.ts 增加 patternRules 和 formRules。
5. 在页面里只消费 useAuthFormRules()，不要复制正则和文案。

常见误区

相关链接

• API 速查（返回值 / 规则集合 / 工厂签名）：表单规则 API
• 表格与表单
• 登录认证
• 国际化与图标
• 项目结构