FormBuilder增加泛型支持，可以根据泛型推断出name值

2026-04-21 16:08:44 +08:00 · 2026-04-21 16:08:44 +08:00 · fb42f2299b
parent 5d29fa6ea0
commit fb42f2299b
4 changed files with 74 additions and 64 deletions
--- a/src/components/FormBuilder/FormBuilder.d.ts
+++ b/src/components/FormBuilder/FormBuilder.d.ts
@ -1,17 +1,16 @@
 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 { ReactElement, ReactNode } from "react";
 import type { FormOption } from "./FormItemsRenderer";

 /**
 * FormBuilder 组件属性
 */
-export interface FormBuilderProps extends Omit<FormProps, "form"> {
+export interface FormBuilderProps<Values = any> extends Omit<FormProps, "form" | "onFinish"> {
  /** 表单初始值 */
-  values?: Store;
+  values?: Values;
  /** 表单配置项数组 */
-  options: FormOption[];
+  options: FormOption<Values>[];
  /** 栅格间距，默认 24 */
  gutter?: Gutter | [Gutter, Gutter];
  /** 占据栅格列数，默认 12 */
@ -35,15 +34,21 @@ export interface FormBuilderProps extends Omit<FormProps, "form"> {
  /** 是否处于加载状态，默认 false */
  loading?: boolean;
  /** 表单实例（通过 Form.useForm() 创建） */
-  form: FormInstance;
+  form: FormInstance<Values>;
+  /** 表单提交时的回调函数 */
+  onFinish?: (values: Values) => void;
 }

 /**
 * 表单构建器组件
 */
-declare const FormBuilder: FC<FormBuilderProps> & {
+type FormBuilderComponent = {
  useForm: typeof import("antd").Form.useForm;
  useWatch: typeof import("antd").Form.useWatch;
+} & {
+  <Values = any>(props: FormBuilderProps<Values>): ReactElement;
 };

+declare const FormBuilder: FormBuilderComponent;
+
 export default FormBuilder;
--- a/src/components/FormBuilder/FormItemsRenderer.d.ts
+++ b/src/components/FormBuilder/FormItemsRenderer.d.ts
@ -2,13 +2,10 @@ 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 { NamePath, Store } from "rc-field-form/lib/interface";
+import type { ReactElement, ReactNode } from "react";
 import type { FORM_ITEM_RENDER_TYPE_MAP } from "../../enum/formItemRender";

-/** 表单项 name */
-export type FormFieldName = string | number | (string | number)[];
-
 /**
 * 选择项数据类型
 */
@ -76,74 +73,74 @@ type WhenTrue<Condition extends boolean, T> = Condition extends true ? never : T
 /**
 * 表单配置项属性类型辅助工具
 */
-type FormOptionProperty<O extends boolean, C extends boolean, T> = WhenTrue<O, WhenTrue<C, T>>;
+type FormOptionProperty<IsOnlyForLabel extends boolean, IsCustomizeRender extends boolean, T> = WhenTrue<IsOnlyForLabel, WhenTrue<IsCustomizeRender, T>>;

 /**
 * 表单配置项公共字段
 */
-export interface FormOptionBase<O extends boolean = false, C extends boolean = false> {
+export interface FormOptionBase<Values = any, IsOnlyForLabel extends boolean = false, IsCustomizeRender extends boolean = false> {
  /** React 需要的 key，如果传递了唯一的 name，则不需要 */
  key?: string;
  /** 表单项字段名 */
-  name?: FormFieldName;
+  name?: NamePath<Values>;
  /** 表单项标签 */
  label?: ReactNode;
  /** 占据栅格列数，默认 12 */
-  span?: WhenTrue<O, number | string>;
+  span?: WhenTrue<IsOnlyForLabel, number | string>;
  /** 是否必填，默认 true，支持函数动态计算 */
-  required?: FormOptionProperty<O, C, boolean | ((formValues: Store) => boolean)>;
+  required?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, boolean | ((formValues: Values) => boolean)>;
  /** 验证规则 */
-  rules?: FormOptionProperty<O, C, Rule | Rule[]>;
+  rules?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, Rule | Rule[]>;
  /** 是否使用字符验证限制 */
-  useConstraints?: FormOptionProperty<O, C, boolean>;
+  useConstraints?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, boolean>;
  /** 占位符文本，默认会根据传入的 render 类型自动判断（请选择、请输入）和 label 组合 */
-  placeholder?: FormOptionProperty<O, C, ReactNode>;
+  placeholder?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, ReactNode>;
  /** 提示信息，传入将在 label 右侧生成图标展示 tooltip */
-  tip?: FormOptionProperty<O, C, ReactNode>;
+  tip?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, ReactNode>;
  /** 是否隐藏，默认 false，支持函数动态计算 */
-  hidden?: WhenTrue<O, boolean | ((formValues: Store) => boolean)>;
+  hidden?: WhenTrue<IsOnlyForLabel, boolean | ((formValues: Values) => boolean)>;
  /** 是否自定义渲染，完全交给外部控制渲染，默认 false */
-  customizeRender?: C;
+  customizeRender?: IsCustomizeRender;
  /** 传递给 Form.Item 的属性，支持函数动态计算 */
-  formItemProps?: FormOptionProperty<O, C, FormItemProps | ((formValues: Store) => FormItemProps)>;
+  formItemProps?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, FormItemProps | ((formValues: Values) => FormItemProps)>;
  /** label 栅格配置，默认直接使用外层的 labelCol，如果 span 等于 24，是外层的 labelCol.span 一半 */
-  labelCol?: FormOptionProperty<O, C, ColProps>;
+  labelCol?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, ColProps>;
  /** wrapper 栅格配置，默认 24 - labelCol.span */
-  wrapperCol?: FormOptionProperty<O, C, ColProps>;
+  wrapperCol?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, ColProps>;
  /** 是否应该更新（用于表单联动） */
-  shouldUpdate?: FormOptionProperty<O, C, boolean | ((prevValues: Store, nextValues: Store, info: { source?: string }) => boolean)>;
+  shouldUpdate?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, boolean | ((prevValues: Values, nextValues: Values, info: { source?: string }) => boolean)>;
  /** 依赖字段（用于表单联动） */
-  dependencies?: FormOptionProperty<O, C, FormFieldName[]>;
+  dependencies?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, NamePath<Values>[]>;
  /** 是否仅用于保存标签，不渲染到页面上，只在表单中保存数据，默认 false */
-  onlyForLabel?: O;
+  onlyForLabel?: IsOnlyForLabel;
 }

 /**
 * 按 render 类型区分的表单项
 */
-export type FormOptionByRender<R extends keyof FORM_ITEM_RENDER_TYPE_MAP, O extends boolean = false, C extends boolean = false> = FormOptionBase<O, C> & {
+export type FormOptionByRender<RenderType extends keyof FORM_ITEM_RENDER_TYPE_MAP, Values = any, IsOnlyForLabel extends boolean = false, IsCustomizeRender extends boolean = false> = FormOptionBase<Values, IsOnlyForLabel, IsCustomizeRender> & {
  /** 渲染类型（写字面量时 componentProps 会按该类型推导） */
-  render: R;
+  render: RenderType;
  /** 传递给表单控件的属性，类型由 render 决定 */
-  componentProps?: FormOptionProperty<O, C, FORM_ITEM_RENDER_TYPE_MAP[R] | ((formValues: Store) => FORM_ITEM_RENDER_TYPE_MAP[R])>;
+  componentProps?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, FORM_ITEM_RENDER_TYPE_MAP[RenderType] | ((formValues: Values) => FORM_ITEM_RENDER_TYPE_MAP[RenderType])>;
  /** 选项数据（用于 select、radio、checkbox） */
-  items?: FormOptionProperty<O, C, R extends "select" | "radio" | "checkbox" ? OptionItem[] : never>;
+  items?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, RenderType extends "select" | "radio" | "checkbox" ? OptionItem[] : never>;
  /** 字段键配置 */
-  itemsField?: FormOptionProperty<O, C, R extends "select" | "radio" | "checkbox" ? ItemsFieldConfig : never>;
+  itemsField?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, RenderType extends "select" | "radio" | "checkbox" ? ItemsFieldConfig : never>;
  /** checkbox 的栅格数量，如果不传入不使用栅格，传入才使用 */
-  checkboxCol?: FormOptionProperty<O, C, R extends "checkbox" ? number : never>;
+  checkboxCol?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, RenderType extends "checkbox" ? number : never>;
  /** Form.List 独有的属性 */
-  formListUniqueProps?: FormOptionProperty<O, C, R extends "formList" ? FormListUniqueProps | ((formValues: Store) => FormListUniqueProps) : never>;
+  formListUniqueProps?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, RenderType extends "formList" ? FormListUniqueProps | ((formValues: Values) => FormListUniqueProps) : never>;
 };

 /**
 * 不写 render 或 render 为 input 时的表单项（默认按输入框）
 */
-export type FormOptionDefault<O extends boolean = false, C extends boolean = false> = FormOptionBase<O, C> & {
+export type FormOptionDefault<Values = any, IsOnlyForLabel extends boolean = false, IsCustomizeRender extends boolean = false> = FormOptionBase<Values, IsOnlyForLabel, IsCustomizeRender> & {
  /** 渲染类型，默认 input */
  render?: "input" | undefined;
  /** 传递给 Input 的属性 */
-  componentProps?: FORM_ITEM_RENDER_TYPE_MAP["input"] | ((formValues: Store) => FORM_ITEM_RENDER_TYPE_MAP["input"]);
+  componentProps?: FORM_ITEM_RENDER_TYPE_MAP["input"] | ((formValues: Values) => FORM_ITEM_RENDER_TYPE_MAP["input"]);
  /** 选项数据（用于 select、radio、checkbox），input 时不需要 */
  items?: never;
  /** 字段键配置，input 时不需要 */
@ -157,7 +154,7 @@ export type FormOptionDefault<O extends boolean = false, C extends boolean = fal
 /**
 * 自定义渲染时的表单项（render 为 ReactNode 时使用）
 */
-export type FormOptionCustomRender<O extends boolean = false, C extends boolean = false> = FormOptionBase<O, C> & {
+export type FormOptionCustomRender<Values = any, IsOnlyForLabel extends boolean = false, IsCustomizeRender extends boolean = false> = FormOptionBase<Values, IsOnlyForLabel, IsCustomizeRender> & {
  /** 渲染类型，默认 ReactNode */
  render: ReactNode;
  /** 传递给表单控件的属性，自定义渲染时不需要 */
@ -175,23 +172,23 @@ export type FormOptionCustomRender<O extends boolean = false, C extends boolean
 /**
 * 表单配置项
 */
-export type FormOption
-  = | FormOptionDefault<false, false>
-    | FormOptionDefault<false, true>
-    | FormOptionDefault<true, false>
-    | { [K in keyof FORM_ITEM_RENDER_TYPE_MAP]: FormOptionByRender<K, false, false> }[keyof FORM_ITEM_RENDER_TYPE_MAP]
-    | { [K in keyof FORM_ITEM_RENDER_TYPE_MAP]: FormOptionByRender<K, false, true> }[keyof FORM_ITEM_RENDER_TYPE_MAP]
-    | { [K in keyof FORM_ITEM_RENDER_TYPE_MAP]: FormOptionByRender<K, true, false> }[keyof FORM_ITEM_RENDER_TYPE_MAP]
-    | FormOptionCustomRender<false, false>
-    | FormOptionCustomRender<false, true>
-    | FormOptionCustomRender<true, false>;
+export type FormOption<Values = any>
+  = | FormOptionDefault<Values, false, false>
+    | FormOptionDefault<Values, false, true>
+    | FormOptionDefault<Values, true, false>
+    | { [K in keyof FORM_ITEM_RENDER_TYPE_MAP]: FormOptionByRender<K, Values, false, false> }[keyof FORM_ITEM_RENDER_TYPE_MAP]
+    | { [K in keyof FORM_ITEM_RENDER_TYPE_MAP]: FormOptionByRender<K, Values, false, true> }[keyof FORM_ITEM_RENDER_TYPE_MAP]
+    | { [K in keyof FORM_ITEM_RENDER_TYPE_MAP]: FormOptionByRender<K, Values, true, false> }[keyof FORM_ITEM_RENDER_TYPE_MAP]
+    | FormOptionCustomRender<Values, false, false>
+    | FormOptionCustomRender<Values, false, true>
+    | FormOptionCustomRender<Values, true, false>;

 /**
 * FormItemsRenderer 组件属性
 */
-export interface FormItemsRendererProps {
+export interface FormItemsRendererProps<Values = any> {
  /** 表单配置项数组 */
-  options: FormOption[];
+  options: FormOption<Values>[];
  /** 默认栅格占据列数，默认 12 */
  span?: number;
  /** 是否折叠（仅显示前3项），默认 false */
@ -199,7 +196,7 @@ export interface FormItemsRendererProps {
  /** 自动生成必填规则，默认 true */
  useAutoGenerateRequired?: boolean;
  /** 初始值，用于在表单未初始化时提供默认值 */
-  initialValues?: Store;
+  initialValues?: Values;
  /** 栅格间距，继承自 FormBuilder */
  gutter?: Gutter | [Gutter, Gutter];
  /** label 栅格配置，继承自 FormBuilder */
@ -209,6 +206,6 @@ export interface FormItemsRendererProps {
 /**
 * 表单项渲染器组件
 */
-declare const FormItemsRenderer: FC<FormItemsRendererProps>;
+declare const FormItemsRenderer: <Values = any>(props: FormItemsRendererProps<Values>) => ReactElement;

 export default FormItemsRenderer;
--- a/src/components/FormBuilder/index.d.ts
+++ b/src/components/FormBuilder/index.d.ts
@ -1,3 +1,6 @@
+import type { FormOption } from "./FormItemsRenderer";
 import FormBuilder from "./FormBuilder";

+export type { FormOption };
+
 export default FormBuilder;
--- a/src/components/Search/index.d.ts
+++ b/src/components/Search/index.d.ts
@ -1,22 +1,23 @@
 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";
+import type { ReactElement, ReactNode } from "react";
+import type { FormOption } from "../FormBuilder";
+
+export type { FormOption };

 /**
 * Search 组件属性
 */
-export interface SearchProps extends Omit<FormProps, "form" | "onFinish"> {
+export interface SearchProps<Values = any> extends Omit<FormProps, "form" | "onFinish" | "onReset"> {
  /** 表单配置项数组 */
-  options: FormOption[];
+  options: FormOption<Values>[];
  /** 表单值 */
-  values?: Store;
+  values?: Values;
  /** 搜索和重置都会触发的回调 */
-  onFinish?: (values: Store, type: "submit" | "reset") => void;
+  onFinish?: (values: Values, type: "submit" | "reset") => void;
  /** 搜索回调 */
-  onSubmit?: (values: Store) => void;
+  onSubmit?: (values: Values) => void;
  /** 重置回调 */
-  onReset?: (values: Store) => void;
+  onReset?: (values: Values) => void;
  /** 搜索按钮文本，默认"搜索" */
  searchText?: string;
  /** 重置按钮文本，默认"重置" */
@ -28,16 +29,20 @@ export interface SearchProps extends Omit<FormProps, "form" | "onFinish"> {
  /** 额外的底部按钮组 */
  extraButtons?: ReactNode;
  /** 表单实例（通过 Form.useForm() 创建） */
-  form: FormInstance;
+  form: FormInstance<Values>;
 }

 /**
 * 搜索表单组件
 * 支持自动展开/收起功能，当表单项超过4个时显示展开/收起按钮
 */
-declare const Search: FC<SearchProps> & {
+type SearchComponent = {
  useForm: typeof import("antd").Form.useForm;
  useWatch: typeof import("antd").Form.useWatch;
+} & {
+  <Values = any>(props: SearchProps<Values>): ReactElement;
 };

+declare const Search: SearchComponent;
+
 export default Search;