refactor(form): 更新表单组件类型定义以使用Store替代FormValues

- 在FormBuilder中将FormValues类型替换为Store - 在ImportFile中更新onConfirm回调参数类型为UploadFile[] - 在Search组件中统一使用Store类型替代FormValues
2026-04-14 17:56:20 +08:00 · 2026-04-14 17:56:20 +08:00 · 7e899bdbcb
parent bb63ad5258
commit 7e899bdbcb
4 changed files with 34 additions and 37 deletions
--- a/src/components/FormBuilder/FormBuilder.d.ts
+++ b/src/components/FormBuilder/FormBuilder.d.ts
@ -1,14 +1,15 @@
 import type { FormInstance, FormProps } from "antd/es/form";
 import type { Gutter } from "antd/es/grid/row";
+import type { Store } from "rc-field-form/lib/interface";
 import type { FC, ReactNode } from "react";
-import type { FormOption, FormValues } from "./FormItemsRenderer";
+import type { FormOption } from "./FormItemsRenderer";

 /**
 * FormBuilder 组件属性
 */
 export interface FormBuilderProps extends Omit<FormProps, "form"> {
  /** 表单初始值 */
-  values?: FormValues;
+  values?: Store;
  /** 表单配置项数组 */
  options: FormOption[];
  /** 栅格间距，默认 24 */
--- a/src/components/FormBuilder/FormItemsRenderer.d.ts
+++ b/src/components/FormBuilder/FormItemsRenderer.d.ts
@ -2,6 +2,7 @@ import type { ColProps } from "antd/es/col";
 import type { FormItemProps, Rule } from "antd/es/form";
 import type { FormListFieldData } from "antd/es/form/FormList";
 import type { Gutter } from "antd/es/grid/row";
+import type { Store } from "rc-field-form/lib/interface";
 import type { FC, ReactNode } from "react";
 import type { FORM_ITEM_RENDER_TYPE_MAP } from "../../enum/formItemRender";

@ -31,11 +32,6 @@ export interface ItemsFieldConfig {
  labelKey?: string | ((item: Record<string, any>) => ReactNode);
 }

-/**
- * 表单值类型
- */
-export type FormValues = Record<string, any>;
-
 /**
 * Form.List 操作项
 */
@ -45,7 +41,7 @@ export interface FormListOperations {
  /** 当前项在列表中的索引位置 */
  fieldIndex: number;
  /** 新增方法 */
-  add: (defaultValue?: FormValues, insertIndex?: number) => void;
+  add: (defaultValue?: Store, insertIndex?: number) => void;
  /** 删除方法 */
  remove: (index: number | number[]) => void;
  /** 移动方法 */
@ -67,15 +63,20 @@ export interface FormListUniqueProps {
  /** 表单配置项 */
  options: (field: FormListFieldData, fieldIndex: number, operations: FormListOperations) => FormOption[];
  /** 点击新增按钮时的默认值 */
-  addDefaultValue?: FormValues;
+  addDefaultValue?: Store;
  /** 点击新增按钮时插入的索引位置 */
  addInsertIndex?: number;
 }

+/**
+ * 条件类型辅助工具
+ */
+type WhenTrue<Condition extends boolean, T> = Condition extends true ? never : T;
+
 /**
 * 表单配置项属性类型辅助工具
 */
-type FormOptionProperty<O extends boolean, C extends boolean, T> = O extends true ? never : (C extends true ? never : T);
+type FormOptionProperty<O extends boolean, C extends boolean, T> = WhenTrue<O, WhenTrue<C, T>>;

 /**
 * 表单配置项公共字段
@ -88,9 +89,9 @@ export interface FormOptionBase<O extends boolean = false, C extends boolean = f
  /** 表单项标签 */
  label?: ReactNode;
  /** 占据栅格列数，默认 12 */
-  span?: O extends true ? never : (number | string);
+  span?: WhenTrue<O, number | string>;
  /** 是否必填，默认 true，支持函数动态计算 */
-  required?: FormOptionProperty<O, C, boolean | ((formValues: FormValues) => boolean)>;
+  required?: FormOptionProperty<O, C, boolean | ((formValues: Store) => boolean)>;
  /** 验证规则 */
  rules?: FormOptionProperty<O, C, Rule | Rule[]>;
  /** 是否使用字符验证限制 */
@ -100,17 +101,17 @@ export interface FormOptionBase<O extends boolean = false, C extends boolean = f
  /** 提示信息，传入将在 label 右侧生成图标展示 tooltip */
  tip?: FormOptionProperty<O, C, ReactNode>;
  /** 是否隐藏，默认 false，支持函数动态计算 */
-  hidden?: O extends true ? never : (boolean | ((formValues: FormValues) => boolean));
+  hidden?: WhenTrue<O, boolean | ((formValues: Store) => boolean)>;
  /** 是否自定义渲染，完全交给外部控制渲染，默认 false */
  customizeRender?: C;
  /** 传递给 Form.Item 的属性，支持函数动态计算 */
-  formItemProps?: FormOptionProperty<O, C, FormItemProps | ((formValues: FormValues) => FormItemProps)>;
+  formItemProps?: FormOptionProperty<O, C, FormItemProps | ((formValues: Store) => FormItemProps)>;
  /** label 栅格配置，默认直接使用外层的 labelCol，如果 span 等于 24，是外层的 labelCol.span 一半 */
  labelCol?: FormOptionProperty<O, C, ColProps>;
  /** wrapper 栅格配置，默认 24 - labelCol.span */
  wrapperCol?: FormOptionProperty<O, C, ColProps>;
  /** 是否应该更新（用于表单联动） */
-  shouldUpdate?: FormOptionProperty<O, C, boolean | ((prevValues: FormValues, nextValues: FormValues, info: { source?: string }) => boolean)>;
+  shouldUpdate?: FormOptionProperty<O, C, boolean | ((prevValues: Store, nextValues: Store, info: { source?: string }) => boolean)>;
  /** 依赖字段（用于表单联动） */
  dependencies?: FormOptionProperty<O, C, FormFieldName[]>;
  /** 是否仅用于保存标签，不渲染到页面上，只在表单中保存数据，默认 false */
@ -120,19 +121,19 @@ export interface FormOptionBase<O extends boolean = false, C extends boolean = f
 /**
 * 按 render 类型区分的表单项
 */
-export type FormOptionByRender<K extends keyof FORM_ITEM_RENDER_TYPE_MAP, O extends boolean = false, C extends boolean = false> = FormOptionBase<O, C> & {
+export type FormOptionByRender<R extends keyof FORM_ITEM_RENDER_TYPE_MAP, O extends boolean = false, C extends boolean = false> = FormOptionBase<O, C> & {
  /** 渲染类型（写字面量时 componentProps 会按该类型推导） */
-  render: K;
+  render: R;
  /** 传递给表单控件的属性，类型由 render 决定 */
-  componentProps?: FormOptionProperty<O, C, FORM_ITEM_RENDER_TYPE_MAP[K] | ((formValues: FormValues) => FORM_ITEM_RENDER_TYPE_MAP[K])>;
+  componentProps?: FormOptionProperty<O, C, FORM_ITEM_RENDER_TYPE_MAP[R] | ((formValues: Store) => FORM_ITEM_RENDER_TYPE_MAP[R])>;
  /** 选项数据（用于 select、radio、checkbox） */
-  items?: FormOptionProperty<O, C, K extends "select" | "radio" | "checkbox" ? OptionItem[] : never>;
+  items?: FormOptionProperty<O, C, R extends "select" | "radio" | "checkbox" ? OptionItem[] : never>;
  /** 字段键配置 */
-  itemsField?: FormOptionProperty<O, C, K extends "select" | "radio" | "checkbox" ? ItemsFieldConfig : never>;
+  itemsField?: FormOptionProperty<O, C, R extends "select" | "radio" | "checkbox" ? ItemsFieldConfig : never>;
  /** checkbox 的栅格数量，如果不传入不使用栅格，传入才使用 */
-  checkboxCol?: FormOptionProperty<O, C, K extends "checkbox" ? number : never>;
+  checkboxCol?: FormOptionProperty<O, C, R extends "checkbox" ? number : never>;
  /** Form.List 独有的属性 */
-  formListUniqueProps?: FormOptionProperty<O, C, K extends "formList" ? FormListUniqueProps | ((formValues: FormValues) => FormListUniqueProps) : never>;
+  formListUniqueProps?: FormOptionProperty<O, C, R extends "formList" ? FormListUniqueProps | ((formValues: Store) => FormListUniqueProps) : never>;
 };

 /**
@ -142,7 +143,7 @@ export type FormOptionDefault<O extends boolean = false, C extends boolean = fal
  /** 渲染类型，默认 input */
  render?: "input" | undefined;
  /** 传递给 Input 的属性 */
-  componentProps?: FORM_ITEM_RENDER_TYPE_MAP["input"] | ((formValues: FormValues) => FORM_ITEM_RENDER_TYPE_MAP["input"]);
+  componentProps?: FORM_ITEM_RENDER_TYPE_MAP["input"] | ((formValues: Store) => FORM_ITEM_RENDER_TYPE_MAP["input"]);
  /** 选项数据（用于 select、radio、checkbox），input 时不需要 */
  items?: never;
  /** 字段键配置，input 时不需要 */
@ -160,7 +161,7 @@ export type FormOptionCustomRender<O extends boolean = false, C extends boolean
  /** 渲染类型，默认 ReactNode */
  render: ReactNode;
  /** 传递给表单控件的属性，自定义渲染时不需要 */
-  componentProps?: FormOptionProperty<O, C, never>;
+  componentProps?: never;
  /** 选项数据（用于 select、radio、checkbox），自定义渲染时不需要 */
  items?: never;
  /** 字段键配置，自定义渲染时不需要 */
@ -198,7 +199,7 @@ export interface FormItemsRendererProps {
  /** 自动生成必填规则，默认 true */
  useAutoGenerateRequired?: boolean;
  /** 初始值，用于在表单未初始化时提供默认值 */
-  initialValues?: FormValues;
+  initialValues?: Store;
  /** 栅格间距，继承自 FormBuilder */
  gutter?: Gutter | [Gutter, Gutter];
  /** label 栅格配置，继承自 FormBuilder */
--- a/src/components/ImportFile/index.d.ts
+++ b/src/components/ImportFile/index.d.ts
@ -1,11 +1,7 @@
 import type { FormInstance, FormProps } from "antd/es/form";
+import type { UploadFile } from "antd/es/upload";
 import type { FC, ReactNode } from "react";

-/**
- * 表单值类型
- */
-export type FormValues = Record<string, any>;
-
 export interface ImportFileProps extends Omit<FormProps, "form"> {
  /** 弹窗是否显示 */
  visible: boolean;
@ -16,7 +12,7 @@ export interface ImportFileProps extends Omit<FormProps, "form"> {
  /** 子组件 */
  children?: ReactNode | ((props: { form: FormInstance }) => ReactNode);
  /** 确认回调 */
-  onConfirm: (values: FormValues) => void;
+  onConfirm: (values: { file?: UploadFile[]; [key: string]: any }) => void;
  /** 取消回调 */
  onCancel: () => void;
  /** 导出模板按钮文字，默认 “导出模板” */
--- a/src/components/Search/index.d.ts
+++ b/src/components/Search/index.d.ts
@ -1,9 +1,8 @@
 import type { FormInstance, FormProps } from "antd/es/form";
+import type { Store } from "rc-field-form/lib/interface";
 import type { FC, ReactNode } from "react";
 import type { FormOption } from "../FormBuilder/FormItemsRenderer";

-type FormValues = Record<string, any>;
-
 /**
 * Search 组件属性
 */
@ -11,13 +10,13 @@ export interface SearchProps extends Omit<FormProps, "form" | "onFinish"> {
  /** 表单配置项数组 */
  options: FormOption[];
  /** 表单值 */
-  values?: FormValues;
+  values?: Store;
  /** 搜索和重置都会触发的回调 */
-  onFinish?: (values: FormValues, type: "submit" | "reset") => void;
+  onFinish?: (values: Store, type: "submit" | "reset") => void;
  /** 搜索回调 */
-  onSubmit?: (values: FormValues) => void;
+  onSubmit?: (values: Store) => void;
  /** 重置回调 */
-  onReset?: (values: FormValues) => void;
+  onReset?: (values: Store) => void;
  /** 搜索按钮文本，默认"搜索" */
  searchText?: string;
  /** 重置按钮文本，默认"重置" */