@xclqmc/base-form 1.0.0

package/src/components/BaseForm/rules.ts

@@ -0,0 +1,234 @@
+/**
+ * BaseForm 字段校验：把 fields 上的声明式校验配置翻译成 element-plus 的 el-form 规则
+ * 支持：必填 / 简化 validator / 原生规则（含内置格式 type：phone/idCard/english、长度、数值范围、正则）
+ */
+import type { BaseFormField } from "./types";
+
+/** 内置校验正则 */
+export const PATTERNS: Record<string, RegExp> = {
+  /** 手机号：1 开头 + 3-9 + 9 位数字 */
+  phone: /^1[3-9]\d{9}$/,
+  /** 身份证号：15 位 或 18 位（末位可为 X/x） */
+  idCard: /(^\d{15}$)|(^\d{18}$)|(^\d{17}(\d|X|x)$)/,
+  /** 邮箱 */
+  email: /^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/,
+  /** 数值：整数或小数，可带负号 */
+  number: /^-?\d+(\.\d+)?$/,
+  /** 纯英文：只允许英文字母 A-Z / a-z（不含数字、空格与中文） */
+  english: /^[A-Za-z]+$/,
+};
+
+/** 内置格式校验项的默认提示：以字段 label 为前缀，风格统一为「{label}手机不正确」「{label}的邮箱格式不正确」等 */
+const builtInMessage = (key: string, label: string): string => {
+  switch (key) {
+    case "phone":
+      return `${label}手机格式不正确`;
+    case "idCard":
+      return `${label}身份证格式不正确`;
+    case "email":
+      return `${label}的邮箱格式不正确`;
+    case "number":
+      return `${label}数值不正确`;
+    case "english":
+    case "en":
+      return `${label}只能输入英文`;
+    default:
+      return `${label}格式不正确`;
+  }
+};
+
+/** el-form 原生 `type` 校验的中文名（用于生成默认 message） */
+const TYPE_MSG: Record<string, string> = {
+  email: "邮箱",
+  url: "链接",
+  date: "日期",
+  integer: "整数",
+  float: "浮点数",
+  number: "数字",
+  hex: "十六进制",
+  enum: "枚举",
+};
+
+/** 非 el-form 原生的内置格式 type（phone/idCard/number/english）：el-form 不认识这些 type，
+ *  rules 里写 `type: 'phone'` 时转成内置正则 pattern 校验，默认提示见 builtInMessage（如「{label}手机不正确」）。
+ *  这样 `rules: [{ type: 'phone' }]` 与字段级 `phone` 属性等价，方便网盘等模块统一用 rules 写法。
+ *  `english` 为纯英文校验（只允许 A-Z/a-z），等价别名 `en`。 */
+const NON_NATIVE_TYPE_PATTERNS: Record<string, RegExp> = {
+  phone: PATTERNS.phone,
+  idCard: PATTERNS.idCard,
+  number: PATTERNS.number,
+  english: PATTERNS.english,
+  en: PATTERNS.english,
+};
+
+/** 校验触发时机：选项类字段（radio / select）用 change，其余用 blur */
+const getTrigger = (field: BaseFormField) =>
+  field.type === "radio" || field.type === "select" ? "change" : "blur";
+
+/** 值为空：非必填字段留空时跳过格式校验，交给 required 规则处理 */
+const isBlank = (value: any) =>
+  value === null ||
+  value === undefined ||
+  value === "" ||
+  (Array.isArray(value) && value.length === 0);
+
+/** 是否必填：支持布尔与 (formData) => boolean 函数 */
+const getRequired = (
+  field: BaseFormField,
+  getForm: () => Record<string, any>,
+) =>
+  typeof field.required === "function"
+    ? !!field.required(getForm())
+    : !!field.required;
+
+/**
+ * 构建单个字段的校验规则数组
+ * @param field 字段配置
+ * @param getForm 取当前表单值的函数，作为自定义校验 validator 的第二个入参
+ */
+export function buildFieldRules(
+  field: BaseFormField,
+  getForm: () => Record<string, any>,
+): any[] {
+  const rules: any[] = [];
+  const trigger = getTrigger(field);
+
+  // 必填：用原生 required 以保留 el-form-item 的红色星号；默认提示「{label}必填项」
+  if (getRequired(field, getForm)) {
+    rules.push({ required: true, message: `${field.label}必填项`, trigger });
+  }
+
+  // 原生规则：直接追加在最后，用于复杂场景。
+  // 其中 validator 采用简化契约：(formData) => any，
+  // 返回空（undefined/null/''）或布尔 = 通过；返回非空字符串 = 错误提示。
+  // 其余属性（required/min/max/pattern/type/message/trigger 等）保持原生 el-form 写法。
+  if (field.rules?.length) {
+    field.rules.forEach((rule: any) => {
+      if (typeof rule.validator === "function") {
+        const simpleValidator = rule.validator;
+        rules.push({
+          ...rule,
+          // trigger 缺省统一为 blur
+          trigger: rule.trigger ?? "blur",
+          validator: (_r: any, _v: any, callback: any) => {
+            const res = simpleValidator(getForm());
+            if (res == null || res === "" || typeof res === "boolean")
+              return callback();
+            callback(new Error(String(res)));
+          },
+        });
+      } else {
+        // 原生规则：缺省 trigger = blur；message 按常见类型自动补全，避免每条都手写
+        const filled = { ...rule };
+        if (filled.trigger == null) filled.trigger = "blur";
+
+        // 非 el-form 原生的内置格式（phone/idCard/number）：el-form 不认识 type，转成内置正则 pattern 校验
+        if (filled.type && NON_NATIVE_TYPE_PATTERNS[filled.type]) {
+          const regex = NON_NATIVE_TYPE_PATTERNS[filled.type];
+          rules.push({
+            ...filled,
+            pattern: regex,
+            type: undefined,
+            message: filled.message ?? builtInMessage(filled.type, field.label),
+          });
+          return;
+        }
+
+        // 长度/数值范围走自定义 validator，自动提示在各自分支里生成，此处不抢先补 message
+        const hasLength = filled.minLength != null || filled.maxLength != null;
+        const hasRange = filled.min != null || filled.max != null;
+
+        if (filled.message == null && !hasLength && !hasRange) {
+          if (filled.required) {
+            filled.message = `${field.label}必填项`;
+          } else if (filled.type) {
+            const name = TYPE_MSG[filled.type] ?? filled.type;
+            filled.message = `${field.label}的${name}格式不正确`;
+          } else if (filled.pattern) {
+            // 自定义正则：缺省提示为「{label}格式不正确」
+            filled.message = `${field.label}格式不正确`;
+          }
+        }
+
+        // 长度校验（minLength/maxLength）：el-form 原生无此键（原生只有 len/min/max），
+        // 直接透传会被 async-validator 静默忽略，故转成自定义 validator 按字符数校验。
+        // 空值跳过（交给 required 规则处理），与其余内置校验行为一致。
+        if (hasLength) {
+          const min: number | null = filled.minLength ?? null;
+          const max: number | null = filled.maxLength ?? null;
+          delete filled.minLength;
+          delete filled.maxLength;
+          const message =
+            rule.message ??
+            (min != null && max != null
+              ? `${field.label}长度需在 ${min}~${max} 之间`
+              : min != null
+                ? `${field.label}长度不能少于 ${min} 个字符`
+                : `${field.label}长度不能超过 ${max} 个字符`);
+          rules.push({
+            ...filled,
+            message,
+            validator: (_r: any, value: any, callback: any) => {
+              if (isBlank(value)) return callback();
+              const len = String(value).length;
+              if (min != null && len < min) return callback(new Error(message));
+              if (max != null && len > max) return callback(new Error(message));
+              callback();
+            },
+          });
+          return;
+        }
+
+        // 数值范围（min/max）：el-form 原生对字符串按「长度」处理，与本项目约定（min/max=数值范围）
+        // 不一致，故同样转成自定义 validator，按 Number(value) 比较
+        if (hasRange) {
+          const min: number | null = filled.min ?? null;
+          const max: number | null = filled.max ?? null;
+          delete filled.min;
+          delete filled.max;
+          const message =
+            rule.message ??
+            (min != null && max != null
+              ? `${field.label}数值需在 ${min}~${max} 之间`
+              : min != null
+                ? `${field.label}数值不能小于 ${min}`
+                : `${field.label}数值不能大于 ${max}`);
+          rules.push({
+            ...filled,
+            message,
+            validator: (_r: any, value: any, callback: any) => {
+              if (isBlank(value)) return callback();
+              const num = Number(value);
+              if (Number.isNaN(num))
+                return callback(new Error(`${field.label}数值不正确`));
+              if (min != null && num < min) return callback(new Error(message));
+              if (max != null && num > max) return callback(new Error(message));
+              callback();
+            },
+          });
+          return;
+        }
+
+        rules.push(filled);
+      }
+    });
+  }
+
+  return rules;
+}
+
+/**
+ * 构建整个表单的 rules（key 为字段 value，值为规则数组）
+ * @param fields 字段列表
+ * @param getForm 取当前表单值的函数
+ */
+export function buildRules(
+  fields: BaseFormField[] = [],
+  getForm: () => Record<string, any>,
+): Record<string, any[]> {
+  return fields.reduce((prev: Record<string, any[]>, field: BaseFormField) => {
+    const rules = buildFieldRules(field, getForm);
+    if (rules.length) prev[field.value] = rules;
+    return prev;
+  }, {});
+}

package/src/components/BaseForm/types.ts

@@ -0,0 +1,292 @@
+/**
+ * BaseForm 相关类型定义（与组件 index.vue 分离，仅放类型）
+ */
+import type { Component } from "vue";
+
+/** 表单字段配置（属性按使用频率/重要程度排列：核心 value/label/type → 显隐/占位/默认值 → 校验 → 渲染/布局 → 回调） */
+export interface BaseFormField {
+  /** 字段名（v-model 绑定的 key，必填） */
+  value: string;
+  /** 字段标签（表单左侧显示，必填） */
+  label: string;
+  /**
+   * 字段级标签宽度：存在时优先级高于 config.labelWidth（仅作用于本字段的 el-form-item）。
+   * 常用于上传/图片类控件想顶头左对齐（如 '0px'），避免被统一标签宽留白。
+   */
+  labelWidth?: string | null;
+  /**
+   * 字段类型（渲染组件）：
+   * - 内置：input=输入框；radio=单选组；select=下拉框；editor=富文本（wangEditor）
+   * - 自定义：先经 registerField(type, component) 注入组件，
+   *   再在字段里引用该 type；注入的 type 与内置重复时以注入为准（覆盖内置渲染）
+   */
+  type: string;
+  /**
+   * 是否显示该字段，缺省 true。用于按条件动态显隐。
+   * - 布尔值：true 显示 / false 移除 DOM（布局重排、回收空间）
+   * - 函数：(formData) => boolean，入参为当前表单值，返回 true 显示、false 移除
+   * 注意：show=false 是「移除 DOM」，会回收布局空间；若想保留布局空间仅隐藏，请用 hidden
+   */
+  show?: boolean | ((formData: any) => boolean);
+  /**
+   * 是否隐藏但保留布局空间，缺省 false。
+   * - 布尔值：true 隐藏 / false 显示（默认）
+   * - 函数：(formData) => boolean，入参为当前表单值，返回 true 隐藏
+   * 与 show 的区别：show=false 会「移除 DOM」（空间回收、布局重排）；hidden=true 仅「不可见」，
+   * DOM 仍在、仍占据布局空间（visibility:hidden），常用于占位对齐或值由程序填充的隐藏字段
+   */
+  hidden?: boolean | ((formData: any) => boolean);
+  /** 占位提示文案 */
+  placeholder?: string;
+  /** 默认值（新增时回填；编辑时被详情覆盖） */
+  defaultValue?: any;
+  /**
+   * 是否必填，缺省 false。
+   * - 布尔值：true 必填 / false 非必填
+   * - 函数：(formData) => boolean，入参为当前表单值，返回 true 必填
+   * 校验失败提示取 placeholder，缺省"不能为空"
+   */
+  required?: boolean | ((formData: any) => boolean);
+  /**
+   * 校验规则数组（原生 el-form 规则写法 + 本库扩展），追加在内置必填规则之后；复杂校验统一写在这里。
+   * 支持：原生 required/pattern/type/message/trigger、简化 validator((formData)=>提示)、
+   * 长度 minLength/maxLength、数值范围 min/max、内置格式 type（phone/idCard/english）
+   */
+  rules?: BaseFormRule[] | null;
+  /**
+   * 是否禁用该字段。
+   * - 布尔值：true 禁用 / false 不禁用（默认 false）
+   * - 函数：(formData) => boolean，入参为当前表单值，返回 true 禁用、false 不禁用
+   */
+  disabled?: boolean | ((formData: any) => boolean);
+  /**
+   * 字段渲染格式：
+   * - `input`：字符串，输入框类型（如 `'textarea'` 多行 / `'number'` 数字框）
+   * - `radio` / `select`：选项来源，三选一：
+   *   ① 字符串 = 字典 code，由字段控件经 BaseForm 注入的 `api.dict(code)` 拉取选项
+   *   ② 数组 = 直接注入的选项数组
+   *   ③ 函数 `(formData) => 数组`（支持 Promise），入参为当前表单值，便于选项依赖其它字段（联动）
+   */
+  format?:
+    | string
+    | any[]
+    | ((formData: any) => Promise<any> | any[] | string)
+    | null;
+  /**
+   * 字段级组件入参：整体透传给该字段渲染的组件（`input`→`el-input`、`radio`→`BaseRadio`、`select`→`BaseSelect`、`editor`→`BaseEditor`）。
+   * 支持两种写法：**对象**（静态）或 **函数 `(formData) => 配置对象`**（按当前表单值动态算，如数量/参数依赖其它字段）。
+   * `type='select'` 常用项：label（选项文案的键名，默认 'label'）/ value（选项值的键名，默认 'value'）
+   * / multiple（是否多选）/ disabledName（选项禁用标记的键名，默认 'disabled'）/ maxCollapseTags（多选折叠标签数）
+   */
+  params?:
+    | Record<string, any>
+    | ((formData: any) => Record<string, any>)
+    | null;
+  /** 表单项栅格 span（24=整行，缺省见 config.span） */
+  span?: number | null;
+  /** 表单项下边距（缺省见 config.marginBottom） */
+  marginBottom?: string | null;
+  /**
+   * 字段点击回调（所有类型均生效）。入参为原生 click 事件对象。
+   * 常用于只读字段点击触发选择器弹窗等场景。
+   */
+  click?: ((event: any) => void) | null;
+  /**
+   * 字段值变化回调（所有类型均生效）。入参为变化后的新值。
+   * - input：输入框 change 事件（失焦/回车时触发），值为输入值
+   * - radio：单选组 change 事件，值为选中项的值
+   * - select：下拉框 change 事件，值为选中项的值（多选时为数组）
+   * - editor：内容变化即触发，值为最新 HTML
+   * 需要在回调里改动其它字段时，直接读写父组件的 `formData`（即 v-model:form 绑定的对象）
+   */
+  change?: ((value: any) => void) | null;
+  /**
+   * 联动依赖字段：当这些字段的值变化时，会重新获取本字段的选项列表（仅 radio / select 生效）并触发 onWatch。
+   * 字符串表示单个字段，数组表示多个字段。常用于「下拉框选项依赖另一字段」场景
+   */
+  watch?: string | string[] | null;
+  /**
+   * 联动回调：当 watch 中任一依赖字段变化时触发。
+   * 入参为 (formData, changedKey)：formData 为当前表单值，changedKey 为发生变化的字段名。
+   * 典型用法：依赖变化后清空/重置本字段值，如 formData[this.value] = ''
+   */
+  onWatch?: ((formData: any, changedKey?: string) => void) | null;
+}
+
+/** 字段级校验规则：原生 el-form 规则写法 + 本库扩展（简化 validator / 长度 / 数值范围 / 内置格式 type） */
+export interface BaseFormRule {
+  /** 是否必填 */
+  required?: boolean;
+  /** 校验失败提示 */
+  message?: string;
+  /** 触发时机，缺省 blur */
+  trigger?: "blur" | "change" | ("blur" | "change")[];
+  /** 自定义正则 */
+  pattern?: RegExp;
+  /**
+   * 格式类型：
+   * - el-form 原生：email / url / date / integer / float / number / hex / enum
+   * - 本库扩展（el-form 不认识，自动转内置正则校验）：phone=手机号 / idCard=身份证号 / english=纯英文（别名 en）
+   */
+  type?: string;
+  /** 数值范围下限（本库按数值大小比较，非字符串长度） */
+  min?: number;
+  /** 数值范围上限 */
+  max?: number;
+  /** 长度下限（本库扩展，按字符数校验；el-form 原生无此键） */
+  minLength?: number;
+  /** 长度上限（本库扩展） */
+  maxLength?: number;
+  /** 简化校验器：(formData) => any。返回空（undefined/null/''）或布尔 = 通过；返回非空字符串 = 错误提示 */
+  validator?: (formData: any) => any;
+  /** 其余原生 el-form 规则键原样透传 */
+  [key: string]: any;
+}
+
+/** 表单接口配置（get=详情 / add=新增 / put=修改，按 CRUD 自然顺序；dict=字典） */
+export interface BaseFormApi {
+  /** 详情接口：可返回 axios 响应（{ data }）或直接返回数据本体 */
+  get?: ((id: any) => Promise<any>) | null;
+  /** 新增接口 */
+  add?: ((data: any) => Promise<any>) | null;
+  /** 修改接口 */
+  put?: ((data: any) => Promise<any>) | null;
+  /** 字典接口：radio / select 的 format 为字符串（字典 code）时，字段控件经 BaseForm 注入按 code 拉取选项列表 */
+  dict?: ((code: string) => Promise<any[]>) | null;
+}
+
+/** 弹窗/表单全局配置（属性按使用频率/重要程度排列：主键/标签宽 → 形态/尺寸 → 标题/高度 → 布局 → 抽屉方向） */
+export interface BaseFormConfig {
+  /** 实体主键字段名（默认 id）。openDialog 据此包裹主键、submit 据此判定新增/编辑 */
+  id?: string;
+  /** 标签宽度 */
+  labelWidth?: string;
+  /**
+   * 显示形态（统一入口，三选一）：
+   * - 'dialog' = 弹窗（居中弹窗，默认）
+   * - 'drawer' = 抽屉（右侧滑出，用 BaseDrawer 渲染）
+   * - 'form'   = 原始表单（表单直接内嵌在父组件中，不包裹弹窗/抽屉）
+   */
+  mode?: "dialog" | "drawer" | "form";
+  /** 弹窗宽度（mode 为 dialog/drawer 时生效），缺省 600px */
+  width?: string;
+  /**
+   * 弹窗标题：
+   * - 省略 → 按主键（id）判断：存在值=「编辑」，无值=「新增」
+   * - 字符串 → 直接使用
+   * - 函数 (formData) => string → 以表单值为入参动态生成
+   */
+  title?: string | ((formData: any) => string) | null;
+  /** 弹窗高度（mode 为 dialog/drawer 时生效），缺省 null（不限制，由内容自适应）。传入如 '70vh' / '500px' 则固定弹窗高度、内容区滚动 */
+  height?: string | null;
+  /** 表单项栅格 span（24=整行） */
+  span?: number;
+  /** 表单项下边距（最后一行自动去除） */
+  marginBottom?: string;
+  /**
+   * 抽屉方向（保留备用）。当前 drawer 使用 BaseDrawer（仅右侧滑出），direction 暂不生效
+   */
+  direction?: "rtl" | "ltr" | "ttb" | "btt";
+}
+
+/** 打开弹窗钩子：返回数据则作为表单值回填（覆盖默认空表单），不返回则保持默认 */
+export type BaseFormOpen = (row: any) => any | Promise<any>;
+
+/** 子组件注册项：component 为组件本身，ref 为别名（通过 getComponentRef(ref) 获取实例） */
+export interface BaseFormComponent {
+  component: Component;
+  ref: string;
+}
+
+/** 提交钩子：提供后覆盖内置提交逻辑（自行调 add/put、自定义提示），BaseForm 仍负责关闭弹窗与刷新列表 */
+export type BaseFormSubmit = (formData: any) => any | Promise<any>;
+
+/** 事件钩子集合：open / submit / beforeClose / close 归类于此，避免散落在 options 顶层 */
+export interface BaseFormEvent {
+  /** 打开弹窗执行代码：返回表单值则直接回填 */
+  open?: BaseFormOpen | null;
+  /** 提交执行代码：提供后覆盖内置 submit */
+  submit?: BaseFormSubmit | null;
+  /** 关闭之前回调：关闭弹窗/抽屉前触发（X / 取消 / ESC / 提交成功后关闭均生效） */
+  beforeClose?: (() => void) | null;
+  /** 关闭回调：关闭完成后触发（与组件 @close 事件同时机） */
+  close?: (() => void) | null;
+}
+
+/** BaseForm options 配置（属性按轻重排列：轻量配置 config/api 在上，内容最多的 fields 在下，可选扩展 components/event 在底部） */
+export interface BaseFormOptions {
+  /** 弹窗/表单全局配置（含显示形态 mode、主键 id、标题 title、宽高 width/height 等） */
+  config?: BaseFormConfig;
+  /** 接口（详情/新增/编辑） */
+  api?: BaseFormApi;
+  /** 字段列表（内容最多，置于底部） */
+  fields?: BaseFormField[];
+  /**
+   * 子组件列表：注册到组件内，可通过 `getComponentRef(ref)` 获取实例并调用其方法。
+   * 形如 [{ component: Permission, ref: 'permissionRef' }]，常用于表单内嵌关联的弹窗（如授权）。
+   */
+  components?: BaseFormComponent[];
+  /** 事件钩子集合：open（打开弹窗，返回表单值则直接回填）/ submit（覆盖内置提交逻辑） */
+  event?: BaseFormEvent;
+}
+
+/** 默认 options 配置：穷举全部属性（无值的一律写 null），宿主传值后同键覆盖 */
+export const defaultFormOptions: BaseFormOptions = {
+  config: {
+    id: "id",
+    labelWidth: "75px",
+    mode: "dialog",
+    width: "600px",
+    title: null,
+    height: null,
+    span: 24,
+    marginBottom: "17px",
+    direction: "rtl",
+  },
+  api: {
+    get: null,
+    add: null,
+    put: null,
+    dict: null,
+  },
+  fields: [
+    {
+      value: "",
+      label: "",
+      labelWidth: null,
+      type: "input",
+      show: true,
+      hidden: false,
+      placeholder: "请输入值",
+      defaultValue: null,
+      required: false,
+      rules: null,
+      disabled: false,
+      format: null,
+      params: null,
+      span: null,
+      marginBottom: null,
+      click: null,
+      change: null,
+      watch: null,
+      onWatch: null,
+    },
+  ],
+  components: [],
+  event: {
+    open: null,
+    submit: null,
+    beforeClose: null,
+    close: null,
+  },
+};
+
+/**
+ * 设置全局默认 options：入参为局部配置，config / api / event 逐键合并进默认值，
+ * 在应用入口调用一次即可对所有 BaseForm 生效；表单级 options 传值仍优先于全局默认
+ */
+export function setDefaultFormOptions(partial: BaseFormOptions = {}) {
+  if (partial.config) Object.assign(defaultFormOptions.config!, partial.config);
+  if (partial.api) Object.assign(defaultFormOptions.api!, partial.api);
+  if (partial.event) Object.assign(defaultFormOptions.event!, partial.event);
+}