React + Antd+TS 动态表单容器组件技术解析与实现

概述

在现代前端应用中，表单是用户交互的核心部分。本文将深入分析一个基于 React 和 Ant Design 的高级动态表单容器组件，它提供了强大的可配置性、灵活的布局选项和丰富的功能扩展能力。

组件核心特性

1. 高度可配置的表单结构

interface FormContainerProps {formData?: FormValues;          // 表单初始数据formList?: FormItem[];          // 表单配置项数组canCollapse?: boolean;          // 是否可折叠labelWidth?: string | number;   // 标签宽度clearable?: boolean;            // 是否可清空horizontal?: boolean;           // 是否水平布局defaultShow?: number;           // 默认显示表单项数量onReset?: (data: FormValues) => void;      // 重置回调onSearch?: (values: FormValues) => void;   // 搜索回调// ... 其他配置项
}

2. 多样化的表单项类型支持

组件支持多种表单项类型，包括：

文本输入框 (input)
选择器 (select)
级联选择器 (cascader)
日期范围选择器 (daterange)
数值范围输入 (range)
自定义插槽 (slot)

实现细节解析

智能标签宽度计算

const computedLabelWidth = useMemo(() => {if (labelWidth) return labelWidth;if (!formList.length) return '100px';// 根据最长标签文本自动计算合适宽度const maxLength = Math.max(...formList.map(item => item.label?.length || 0));if (maxLength <= 4) return '80px';if (maxLength <= 6) return '110px';if (maxLength < 10) return '120px';return '100px';
}, [formList, labelWidth]);

动态表单渲染机制

const renderFormItem = useCallback((item: FormItem) => {const commonProps = {placeholder: item.placeholder,allowClear: clearable || item.clearable,style: { width: item.width || 240 },disabled: disabled || item.disabled,'aria-label': item.label};switch (item.type) {case 'input':return <Input {...commonProps} />;case 'select':return (<Select{...commonProps}mode={item.multiple ? 'multiple' : undefined}onChange={(value) => handleSelectChange(value, item)}>{/* 选项渲染 */}</Select>);// 其他类型处理...case 'slot':// 插槽机制实现自定义内容return Children.toArray(children).find((child): child is ReactElement => isValidElement(child) && child.props?.slot === `${item.prop}_slot`);}
}, [dependencies]);

折叠功能实现

// 折叠状态管理
const [isCollapse, setIsCollapse] = React.useState(false);// 折叠样式计算
const collapseStyle = useMemo(() => {if (isCollapse || !canCollapse) return {};return {height: `${48 * Math.max(1, defaultShow)}px`,overflow: 'hidden'};
}, [isCollapse, defaultShow, canCollapse]);// 折叠切换
const toggleCollapse = useCallback(() => {setIsCollapse(prev => !prev);
}, []);

表单实例暴露与回调处理

// 暴露form实例给父组件
useImperativeHandle(ref, () => form, [form]);// 表单值变化处理
const handleValuesChange = useCallback((changedValues: FormValues, allValues: FormValues) => {onFormDataChange?.(allValues);
}, [onFormDataChange]);// 搜索提交
const handleSearch = useCallback(async () => {try {const values = await form.validateFields();onSearch?.(values);} catch (error) {console.error('Form validation failed:', error);}
}, [form, onSearch]);

使用示例

import React, { useRef } from 'react';
import FormContainer from '/@/components/searchForm/index';
import { FormInstance } from 'antd';const ExampleComponent: React.FC = () => {const formRef = useRef<FormInstance>(null);const formList = [{label: '姓名',prop: 'name',type: 'input',placeholder: '请输入姓名'},{label: '性别',prop: 'gender',type: 'select',options: [{ label: '男', value: 'male' },{ label: '女', value: 'female' }]},{label: '日期范围',prop: 'dateRange',type: 'daterange'},{label: "责任人",type: "select",prop: "personId",placeholder: "请选择",options: [],},{label: "部门",type: "input",prop: "organizeList",checkStrictly: true,placeholder: "级联多选",options: [],},{label: "标签",type: "select",prop: "userTagIdList",multiple: true,collapsetags: true,collapseTagsTooltip: true,placeholder: "请选择",options: [],},];const handleSearch = (formData: any) => {console.log('查询参数:', formData);};const handleReset = (formData: any) => {console.log('重置表单:', formData);};return (<FormContainerref={formRef}formList={formList}onSearch={handleSearch}onReset={handleReset}/>);
};export default ExampleComponent;

组件完整代码实现

import React, { useMemo, useCallback,useImperativeHandle,forwardRef,ReactElement,cloneElement,isValidElement,Children
} from 'react';
import {Form,Input,Select,Cascader,DatePicker,Button,Space,FormInstance,FormProps
} from 'antd';
import { UpOutlined, DownOutlined 
} from '@ant-design/icons';
import { FormContainerProps, FormItem, FormValues } from './types';
import './index.css';const { RangePicker } = DatePicker;
const { Option } = Select;const FormContainer = forwardRef<FormInstance, FormContainerProps>((props, ref) => {const {formData = {},formList = [],canCollapse = true,labelWidth,clearable = false,horizontal = true,defaultShow = 1,onReset,onSearch,onSelectChange,onCascaderChange,onFormDataChange,children,loading = false,disabled = false} = props;const [form] = Form.useForm();const [isCollapse, setIsCollapse] = React.useState(false);// 暴露form实例给父组件useImperativeHandle(ref, () => form, [form]);// 计算标签宽度const computedLabelWidth = useMemo(() => {if (labelWidth) return labelWidth;if (!formList.length) return '100px';const maxLength = Math.max(...formList.map(item => item.label?.length || 0));if (maxLength <= 4) return '80px';if (maxLength <= 6) return '110px';if (maxLength < 10) return '120px';return '100px';}, [formList, labelWidth]);// 折叠样式const collapseStyle = useMemo(() => {if (isCollapse || !canCollapse) return {};return {height: `${48 * Math.max(1, defaultShow)}px`,overflow: 'hidden'};}, [isCollapse, defaultShow, canCollapse]);// 表单值变化处理const handleValuesChange = useCallback((changedValues: FormValues, allValues: FormValues) => {onFormDataChange?.(allValues);}, [onFormDataChange]);// 选择器变化事件const handleSelectChange = useCallback((value: unknown, item: FormItem) => {const currentValues = form.getFieldsValue();onSelectChange?.(item, currentValues);}, [form, onSelectChange]);// 级联选择变化事件const handleCascaderChange = useCallback((value: unknown, item: FormItem) => {const currentValues = form.getFieldsValue();onCascaderChange?.(item, currentValues);}, [form, onCascaderChange]);// 重置表单const handleReset = useCallback(() => {try {form.resetFields();const resetData = form.getFieldsValue();onReset?.(resetData);} catch (error) {console.error('Form reset failed:', error);}}, [form, onReset]);// 查询提交const handleSearch = useCallback(async () => {try {const values = await form.validateFields();onSearch?.(values);} catch (error) {console.error('Form validation failed:', error);}}, [form, onSearch]);// 切换折叠状态const toggleCollapse = useCallback(() => {setIsCollapse(prev => !prev);}, []);// 通用属性const getCommonProps = useCallback((item: FormItem) => ({placeholder: item.placeholder,allowClear: clearable || item.clearable,style: { width: item.width || 240 },disabled: disabled || item.disabled,'aria-label': item.label}), [clearable, disabled]);// 渲染表单项const renderFormItem = useCallback((item: FormItem) => {const commonProps = getCommonProps(item);switch (item.type) {case 'input':return (<Input{...commonProps}type={item.inputType || 'text'}maxLength={item.maxLength}/>);case 'select':return (<Select{...commonProps}mode={item.multiple ? 'multiple' : undefined}maxTagCount={item.collapseTags ? 1 : undefined}showSearch={item.filterable}optionFilterProp="children"onChange={(value) => handleSelectChange(value, item)}notFoundContent={loading ? '加载中...' : '暂无数据'}>{item.options?.map((option, idx) => {const value = option.value ?? option.itemValue ?? option.id;const label = option.label ?? option.itemText;return (<Option key={`${value}-${idx}`} value={value}>{label}</Option>);})}</Select>);case 'cascader':return (<Cascader{...commonProps}options={item.options || []}fieldNames={item.props}multiple={item.multiple}showArrowchangeOnSelect={!item.showAllLevels}maxTagCount={item.collapseTags ? 1 : undefined}showSearch={item.filterable}onChange={(value) => handleCascaderChange(value, item)}notFoundContent={loading ? '加载中...' : '暂无数据'}/>);case 'daterange':return (<RangePicker{...commonProps}format={item.format || 'YYYY-MM-DD'}placeholder={item.placeholder ? [item.placeholder, item.placeholder] : ['开始时间', '结束时间']}/>);case 'range':return (<Space><Input{...commonProps}style={{ width: item.width || 110 }}type={item.inputType || 'text'}min={item.min}addonAfter={item.unit}aria-label={`${item.label}最小值`}/><span aria-hidden="true">-</span><Input{...commonProps}style={{ width: item.width || 110 }}type={item.inputType || 'text'}min={item.min}addonAfter={item.unit}aria-label={`${item.label}最大值`}/></Space>);case 'slot':const slot = Children.toArray(children).find((child): child is ReactElement => isValidElement(child) && child.props?.slot === `${item.prop}_slot`);return slot ? cloneElement(slot, { data: form.getFieldsValue(),disabled: disabled || item.disabled }) : null;default:console.warn(`Unknown form item type: ${item.type}`);return null;}}, [getCommonProps, loading, children, form, handleSelectChange, handleCascaderChange]);// 表单配置const formLayout: FormProps = useMemo(() => ({layout: 'inline',labelAlign: 'right',labelWrap: true,style: collapseStyle,form,initialValues: formData,onValuesChange: handleValuesChange,disabled: disabled || loading}), [collapseStyle, form, formData, handleValuesChange, disabled, loading]);// 是否显示折叠按钮const shouldShowCollapseButton = useMemo(() => canCollapse && formList.length > defaultShow, [canCollapse, formList.length, defaultShow]);// 渲染的表单项列表const renderedFormItems = useMemo(() => formList.map((item, index) => {if (!item.prop || !item.type) {console.warn(`Form item at index ${index} missing required prop or type`);return null;}return (<Form.Itemkey={`${item.prop}-${index}`}label={`${item.label || ''}：`}name={item.prop}rules={item.rules}labelCol={{ style: { width: computedLabelWidth } }}>{renderFormItem(item)}</Form.Item>);}), [formList, computedLabelWidth, renderFormItem]);return (<div className="search-form-container"role="search"aria-label="搜索表单"><div className="search-form-layout"><div className="form-content"><Form {...formLayout}>{renderedFormItems}</Form></div><div className="form-actions"><Space><Button type="primary" onClick={handleSearch}loading={loading}aria-label="搜索">搜索</Button><Button onClick={handleReset}disabled={loading}aria-label="重置">重置</Button>{shouldShowCollapseButton && (<Button type="link" onClick={toggleCollapse}icon={isCollapse ? <UpOutlined /> : <DownOutlined />}aria-label={isCollapse ? '收起' : '展开'}aria-expanded={isCollapse}>{isCollapse ? '收起' : '展开'}</Button>)}</Space></div></div>{children}</div>);
});FormContainer.displayName = 'FormContainer';export default FormContainer;

import { Rule } from 'antd/es/form';
import { ReactNode } from 'react';export type FormValues = Record<string, unknown>;export interface OptionItem {label?: string;value?: string | number;itemText?: string;itemValue?: string | number;id?: string | number;
}export interface FormItem {label: string;prop: string;type: 'input' | 'select' | 'cascader' | 'daterange' | 'range' | 'slot';placeholder?: string;width?: string | number;clearable?: boolean;disabled?: boolean;multiple?: boolean;collapseTags?: boolean;filterable?: boolean;options?: OptionItem[];props?: Record<string, string>;showAllLevels?: boolean;dateObj?: boolean;time?: string;format?: string;start?: string;end?: string;unit?: string;min?: number;maxLength?: number;inputType?: 'text' | 'number' | 'password' | 'email' | 'tel' | 'url';formatter?: (value: string) => string;rules?: Rule[];
}export interface FormContainerProps {formData?: FormValues;formList: FormItem[];canCollapse?: boolean;labelWidth?: string;clearable?: boolean;horizontal?: boolean;defaultShow?: number;loading?: boolean;disabled?: boolean;onReset?: (form: FormValues) => void;onSearch?: (form: FormValues) => void;onSelectChange?: (item: FormItem, form: FormValues) => void;onCascaderChange?: (item: FormItem, form: FormValues) => void;onFormDataChange?: (form: FormValues) => void;children?: ReactNode;
}

.search-form-container {width: 100%;border-bottom: 1px solid #ebeef5;margin-bottom: 24px;padding-bottom: 8px;
}.search-form-layout {display: flex;justify-content: space-between;align-items: flex-start;gap: 16px;
}.form-content {flex: 1;min-width: 0;
}.form-content .ant-form-item {display: inline-block;margin-right: 16px;margin-bottom: 16px;vertical-align: top;
}.form-actions {flex-shrink: 0;padding-top: 4px;
}@media (max-width: 768px) {.search-form-layout {flex-direction: column;align-items: stretch;}.form-content .ant-form-item {display: block;width: 100%;margin-right: 0;}.form-actions {align-self: flex-end;}
}