AntD React TS可复用表单多字段提交失败：handleFinish未触发

问题描述 #

基于Ant Design + React TypeScript封装了可复用表单组件ReusableForm和表单项组件ReusableFormField，单个表单项时表单验证、提交功能正常；但添加多个字段后，表单提交时ReusableForm的handleFinish函数完全不触发，无法完成提交流程。

相关代码 #

ReusableForm组件

import { Form, FormInstance } from 'antd';

interface FormPropsType<T> {
    children: React.ReactNode;
    onFinish: (data: T) => void;
    layout?: 'horizontal' | 'vertical' | 'inline';
    form?: FormInstance<T>;
}
const ReusableForm = <T,>({ children, onFinish, layout, form }: FormPropsType<T>) => {
    const handleFinish = (formData: T) => {
        onFinish(formData);
        console.log('finish called!!!');
        formInstance.resetFields();
    };

    const [formInstance] = Form.useForm<T>(form);

    return (
        <Form form={formInstance} onFinish={handleFinish} layout={layout} requiredMark="optional">
            {children}
        </Form>
    );
};

export default ReusableForm;

ReusableFormField组件

import { Col, Form, Input, Row } from 'antd';
import { Rule } from 'antd/lib/form';

interface FormFieldProps<T> {
    name: string | string[];
    label?: string;
    rules?: Rule[];
    value?: string | number | readonly string[];
    onChange?: (value: T[keyof T]) => void;
    placeholder?: string;
}

const ReusableFormField = <T,>({ name, label, rules, value, onChange, placeholder }: FormFieldProps<T>) => {
    return (
        <Row gutter={16}>
            <Col style={{ width: '100%', display: 'flex' }}>
                <Form.Item name={name} label={label} rules={rules} style={{ width: '100%' }}>
                    <Input value={value} onChange={(e) => onChange?.(e.target.value as T[keyof T])} placeholder={placeholder} />
                </Form.Item>
            </Col>
        </Row>
    );
};

export default ReusableFormField;

业务组件UsersComponent

import React, { FC, useState } from 'react';

import ReusableTable from './ReusableDatatable';
import ReusableForm from './ReusableForm';
import ReusableFormField from './ReusableInput';
import ReusableModal from './ReusableModal';
import { handleEdit } from './tableHandlers';

const UsersComponent: FC = () => {
    const [isModalVisible, setIsModalVisible] = useState(false);

    const handleCreateUser = () => {
        setIsModalVisible(true);
    };
    const handleModalClose = () => {
        setIsModalVisible(false);
    };
    const columns = [
        { title: 'Name', dataIndex: 'name', key: 'name' },
        { title: 'Age', dataIndex: 'age', key: 'age' },
        { title: 'Email', dataIndex: 'email', key: 'email' },
    ];

    const data = [
        { key: '1', name: 'John Doe', age: 30, email: 'john@example.com' },
        { key: '2', name: 'Jane Doe', age: 25, email: 'jane@example.com' },
    ];

    const onFinish = (values: any) => {
        console.log(values);
        // handleModalClose();
    };

    return (
        <>
            <ReusableTable
                columns={columns}
                data={data}
                onEdit={(record) => {
                    handleEdit('user', record);
                }}
                createButton={{ text: 'Create User', action: handleCreateUser }}
            />
            <ReusableModal open={isModalVisible} title="Create User" onClose={handleModalClose}>
                <ReusableForm onFinish={onFinish} layout="horizontal">
                    <ReusableFormField name="category" label="Category" rules={[{ required: true, message: 'Please enter the category' }]} />
                    <ReusableFormField name="username" label="Username" rules={[{ required: true, message: 'username field can not be empty' }]} />
                </ReusableForm>
            </ReusableModal>
        </>
    );
};

export default UsersComponent;

问题根源 #

核心问题出在ReusableFormField组件中：手动给Input绑定了value和onChange，导致AntD Form失去了对该表单项的状态控制权，表单项变成非受控组件。

• 单个字段时，即使是非受控状态，只要该字段通过验证，Form会尝试触发提交；
• 多个非受控字段时，AntD Form无法同步所有字段的状态，内部验证流程中断，直接阻止onFinish函数触发。

修复方案 #

方案1：移除手动控制，让AntD Form完全管理状态（推荐） #

删除Input上的value和onChange，改用AntD Form提供的Form.useWatch监听字段变化，确保Form能完全控制表单项状态：

import { Col, Form, Input, Row } from 'antd';
import { Rule } from 'antd/lib/form';
import React from 'react';

interface FormFieldProps<T> {
    name: string | string[];
    label?: string;
    rules?: Rule[];
    placeholder?: string;
    // 新增字段变化回调，替代原onChange
    onValueChange?: (value: T[keyof T]) => void;
}

const ReusableFormField = <T,>({ name, label, rules, placeholder, onValueChange }: FormFieldProps<T>) => {
    // 使用Form.useWatch监听字段值变化
    const value = Form.useWatch(name);

    // 监听值变化并触发回调
    React.useEffect(() => {
        onValueChange?.(value as T[keyof T]);
    }, [value, onValueChange]);

    return (
        <Row gutter={16}>
            <Col style={{ width: '100%', display: 'flex' }}>
                <Form.Item name={name} label={label} rules={rules} style={{ width: '100%' }}>
                    <Input placeholder={placeholder} />
                </Form.Item>
            </Col>
        </Row>
    );
};

export default ReusableFormField;

方案2：手动控制状态时同步Form实例（仅适用于特殊业务场景） #

如果必须手动管理字段值，需要通过Form实例的setFieldsValue同步状态，确保Form能识别字段更新：

import { Col, Form, Input, Row } from 'antd';
import { Rule, FormInstance } from 'antd/lib/form';
import React from 'react';

interface FormFieldProps<T> {
    name: string | string[];
    label?: string;
    rules?: Rule[];
    value?: string | number | readonly string[];
    onChange?: (value: T[keyof T]) => void;
    placeholder?: string;
    // 必须传入Form实例
    form: FormInstance<T>;
}

const ReusableFormField = <T,>({ name, label, rules, value, onChange, placeholder, form }: FormFieldProps<T>) => {
    const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
        const inputValue = e.target.value as T[keyof T];
        // 同步值到Form实例
        form.setFieldsValue({ [name as string]: inputValue });
        onChange?.(inputValue);
    };

    // 初始化时同步初始值
    React.useEffect(() => {
        if (value !== undefined) {
            form.setFieldsValue({ [name as string]: value });
        }
    }, [value, form, name]);

    return (
        <Row gutter={16}>
            <Col style={{ width: '100%', display: 'flex' }}>
                <Form.Item name={name} label={label} rules={rules} style={{ width: '100%' }}>
                    <Input value={value} onChange={handleInputChange} placeholder={placeholder} />
                </Form.Item>
            </Col>
        </Row>
    );
};

export default ReusableFormField;

使用时需要从ReusableForm传递Form实例到子组件，或在业务组件中通过Form.useForm获取实例后传入。

额外优化 #

在ReusableForm的handleFinish中，建议先确保onFinish执行成功后再调用resetFields，避免验证失败时误重置字段：

const handleFinish = async (formData: T) => {
    try {
        await onFinish(formData);
        console.log('finish called!!!');
        formInstance.resetFields();
    } catch (error) {
        // 处理提交失败逻辑
        console.error('Submit failed:', error);
    }
};

内容的提问来源于stack exchange，提问作者user23519065