front_library
/
zy-react-library
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

master
LiuJiaNan 2026-04-21 16:08:44 +08:00
parent 5d29fa6ea0
commit fb42f2299b
4 changed files with 74 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
src/components/FormBuilder/FormBuilder.d.ts vendored
View File

@ -1,17 +1,16 @@
import type { FormInstance, FormProps } from "antd/es/form"; import type { FormInstance, FormProps } from "antd/es/form";
import type { Gutter } from "antd/es/grid/row"; import type { Gutter } from "antd/es/grid/row";
import type { Store } from "rc-field-form/lib/interface"; import type { ReactElement, ReactNode } from "react";
import type { FC, ReactNode } from "react";
import type { FormOption } from "./FormItemsRenderer"; import type { FormOption } from "./FormItemsRenderer";
/** /**
* FormBuilder 组件属性 * 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 */ /** 栅格间距，默认 24 */
gutter?: Gutter | [Gutter, Gutter]; gutter?: Gutter | [Gutter, Gutter];
/** 占据栅格列数，默认 12 */ /** 占据栅格列数，默认 12 */
@ -35,15 +34,21 @@ export interface FormBuilderProps extends Omit<FormProps, "form"> {
/** 是否处于加载状态，默认 false */ /** 是否处于加载状态，默认 false */
loading?: boolean; loading?: boolean;
/** 表单实例（通过 Form.useForm() 创建） */ /** 表单实例（通过 Form.useForm() 创建） */
form: FormInstance; form: FormInstance<Values>;
/** 表单提交时的回调函数 */
onFinish?: (values: Values) => void;
} }
/** /**
* 表单构建器组件 * 表单构建器组件
*/ */
declare const FormBuilder: FC<FormBuilderProps> & { type FormBuilderComponent = {
useForm: typeof import("antd").Form.useForm; useForm: typeof import("antd").Form.useForm;
useWatch: typeof import("antd").Form.useWatch; useWatch: typeof import("antd").Form.useWatch;
} & {
<Values = any>(props: FormBuilderProps<Values>): ReactElement;
}; };
declare const FormBuilder: FormBuilderComponent;
export default FormBuilder; export default FormBuilder;

89
src/components/FormBuilder/FormItemsRenderer.d.ts vendored
View File

@ -2,13 +2,10 @@ import type { ColProps } from "antd/es/col";
import type { FormItemProps, Rule } from "antd/es/form"; import type { FormItemProps, Rule } from "antd/es/form";
import type { FormListFieldData } from "antd/es/form/FormList"; import type { FormListFieldData } from "antd/es/form/FormList";
import type { Gutter } from "antd/es/grid/row"; import type { Gutter } from "antd/es/grid/row";
import type { Store } from "rc-field-form/lib/interface"; import type { NamePath, Store } from "rc-field-form/lib/interface";
import type { FC, ReactNode } from "react"; import type { ReactElement, ReactNode } from "react";
import type { FORM_ITEM_RENDER_TYPE_MAP } from "../../enum/formItemRender"; 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，则不需要 */ /** React 需要的 key，如果传递了唯一的 name，则不需要 */
key?: string; key?: string;
/** 表单项字段名 */ /** 表单项字段名 */
name?: FormFieldName; name?: NamePath<Values>;
/** 表单项标签 */ /** 表单项标签 */
label?: ReactNode; label?: ReactNode;
/** 占据栅格列数，默认 12 */ /** 占据栅格列数，默认 12 */
span?: WhenTrue<O, number | string>; span?: WhenTrue<IsOnlyForLabel, number | string>;
/** 是否必填，默认 true，支持函数动态计算 */ /** 是否必填，默认 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 组合 */ /** 占位符文本，默认会根据传入的 render 类型自动判断（请选择、请输入）和 label 组合 */
placeholder?: FormOptionProperty<O, C, ReactNode>; placeholder?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, ReactNode>;
/** 提示信息，传入将在 label 右侧生成图标展示 tooltip */ /** 提示信息，传入将在 label 右侧生成图标展示 tooltip */
tip?: FormOptionProperty<O, C, ReactNode>; tip?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, ReactNode>;
/** 是否隐藏，默认 false，支持函数动态计算 */ /** 是否隐藏，默认 false，支持函数动态计算 */
hidden?: WhenTrue<O, boolean | ((formValues: Store) => boolean)>; hidden?: WhenTrue<IsOnlyForLabel, boolean | ((formValues: Values) => boolean)>;
/** 是否自定义渲染，完全交给外部控制渲染，默认 false */ /** 是否自定义渲染，完全交给外部控制渲染，默认 false */
customizeRender?: C; customizeRender?: IsCustomizeRender;
/** 传递给 Form.Item 的属性，支持函数动态计算 */ /** 传递给 Form.Item 的属性，支持函数动态计算 */
formItemProps?: FormOptionProperty<O, C, FormItemProps | ((formValues: Store) => FormItemProps)>; formItemProps?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, FormItemProps | ((formValues: Values) => FormItemProps)>;
/** label 栅格配置，默认直接使用外层的 labelCol，如果 span 等于 24，是外层的 labelCol.span 一半 */ /** label 栅格配置，默认直接使用外层的 labelCol，如果 span 等于 24，是外层的 labelCol.span 一半 */
labelCol?: FormOptionProperty<O, C, ColProps>; labelCol?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, ColProps>;
/** wrapper 栅格配置，默认 24 - labelCol.span */ /** 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 */ /** 是否仅用于保存标签，不渲染到页面上，只在表单中保存数据，默认 false */
onlyForLabel?: O; onlyForLabel?: IsOnlyForLabel;
} }
/** /**
* 按 render 类型区分的表单项 * 按 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 会按该类型推导） */ /** 渲染类型（写字面量时 componentProps 会按该类型推导） */
render: R; render: RenderType;
/** 传递给表单控件的属性，类型由 render 决定 */ /** 传递给表单控件的属性，类型由 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） */ /** 选项数据（用于 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 的栅格数量，如果不传入不使用栅格，传入才使用 */ /** checkbox 的栅格数量，如果不传入不使用栅格，传入才使用 */
checkboxCol?: FormOptionProperty<O, C, R extends "checkbox" ? number : never>; checkboxCol?: FormOptionProperty<IsOnlyForLabel, IsCustomizeRender, RenderType extends "checkbox" ? number : never>;
/** Form.List 独有的属性 */ /** 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 时的表单项（默认按输入框） * 不写 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 */ /** 渲染类型，默认 input */
render?: "input" | undefined; render?: "input" | undefined;
/** 传递给 Input 的属性 */ /** 传递给 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 时不需要 */ /** 选项数据（用于 select、radio、checkbox），input 时不需要 */
items?: never; items?: never;
/** 字段键配置，input 时不需要 */ /** 字段键配置，input 时不需要 */
@ -157,7 +154,7 @@ export type FormOptionDefault<O extends boolean = false, C extends boolean = fal
/** /**
* 自定义渲染时的表单项（render 为 ReactNode 时使用） * 自定义渲染时的表单项（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 */ /** 渲染类型，默认 ReactNode */
render: ReactNode; render: ReactNode;
/** 传递给表单控件的属性，自定义渲染时不需要 */ /** 传递给表单控件的属性，自定义渲染时不需要 */
@ -175,23 +172,23 @@ export type FormOptionCustomRender<O extends boolean = false, C extends boolean
/** /**
* 表单配置项 * 表单配置项
*/ */
export type FormOption export type FormOption<Values = any>
= | FormOptionDefault<false, false> = | FormOptionDefault<Values, false, false>
| FormOptionDefault<false, true> | FormOptionDefault<Values, false, true>
| FormOptionDefault<true, false> | FormOptionDefault<Values, 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, Values, 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, Values, 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] | { [K in keyof FORM_ITEM_RENDER_TYPE_MAP]: FormOptionByRender<K, Values, true, false> }[keyof FORM_ITEM_RENDER_TYPE_MAP]
| FormOptionCustomRender<false, false> | FormOptionCustomRender<Values, false, false>
| FormOptionCustomRender<false, true> | FormOptionCustomRender<Values, false, true>
| FormOptionCustomRender<true, false>; | FormOptionCustomRender<Values, true, false>;
/** /**
* FormItemsRenderer 组件属性 * FormItemsRenderer 组件属性
*/ */
export interface FormItemsRendererProps { export interface FormItemsRendererProps<Values = any> {
/** 表单配置项数组 */ /** 表单配置项数组 */
options: FormOption[]; options: FormOption<Values>[];
/** 默认栅格占据列数，默认 12 */ /** 默认栅格占据列数，默认 12 */
span?: number; span?: number;
/** 是否折叠（仅显示前3项），默认 false */ /** 是否折叠（仅显示前3项），默认 false */
@ -199,7 +196,7 @@ export interface FormItemsRendererProps {
/** 自动生成必填规则，默认 true */ /** 自动生成必填规则，默认 true */
useAutoGenerateRequired?: boolean; useAutoGenerateRequired?: boolean;
/** 初始值，用于在表单未初始化时提供默认值 */ /** 初始值，用于在表单未初始化时提供默认值 */
initialValues?: Store; initialValues?: Values;
/** 栅格间距，继承自 FormBuilder */ /** 栅格间距，继承自 FormBuilder */
gutter?: Gutter | [Gutter, Gutter]; gutter?: Gutter | [Gutter, Gutter];
/** label 栅格配置，继承自 FormBuilder */ /** 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; export default FormItemsRenderer;

3
src/components/FormBuilder/index.d.ts vendored
View File

@ -1,3 +1,6 @@
import type { FormOption } from "./FormItemsRenderer";
import FormBuilder from "./FormBuilder"; import FormBuilder from "./FormBuilder";
export type { FormOption };
export default FormBuilder; export default FormBuilder;

27
src/components/Search/index.d.ts vendored
View File

@ -1,22 +1,23 @@
import type { FormInstance, FormProps } from "antd/es/form"; import type { FormInstance, FormProps } from "antd/es/form";
import type { Store } from "rc-field-form/lib/interface"; import type { ReactElement, ReactNode } from "react";
import type { FC, ReactNode } from "react"; import type { FormOption } from "../FormBuilder";
import type { FormOption } from "../FormBuilder/FormItemsRenderer";
export type { FormOption };
/** /**
* Search 组件属性 * 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; searchText?: string;
/** 重置按钮文本，默认"重置" */ /** 重置按钮文本，默认"重置" */
@ -28,16 +29,20 @@ export interface SearchProps extends Omit<FormProps, "form" | "onFinish"> {
/** 额外的底部按钮组 */ /** 额外的底部按钮组 */
extraButtons?: ReactNode; extraButtons?: ReactNode;
/** 表单实例（通过 Form.useForm() 创建） */ /** 表单实例（通过 Form.useForm() 创建） */
form: FormInstance; form: FormInstance<Values>;
} }
/** /**
* 搜索表单组件 * 搜索表单组件
* 支持自动展开/收起功能，当表单项超过4个时显示展开/收起按钮 * 支持自动展开/收起功能，当表单项超过4个时显示展开/收起按钮
*/ */
declare const Search: FC<SearchProps> & { type SearchComponent = {
useForm: typeof import("antd").Form.useForm; useForm: typeof import("antd").Form.useForm;
useWatch: typeof import("antd").Form.useWatch; useWatch: typeof import("antd").Form.useWatch;
} & {
<Values = any>(props: SearchProps<Values>): ReactElement;
}; };
declare const Search: SearchComponent;
export default Search; export default Search;