#浮层表单
ModalForm 和 DrawerForm 是 ProForm 的一个变体,本质上仍然是个表单。所以无法通过 footer 来自定义页脚,如果要定义页脚需要使用 submitter.render 来进行自定义。这两个表单的表现与 ProForm 相同,可以从 ProForm 直接修改而来。
ModalForm 和 DrawerForm 都提供了 trigger 来减少 state 的使用,如果你需要使用 state 来控制可以使用 open 和 onOpenChange 来控制打开与关闭。
#Modal 表单
import { PlusOutlined } from '@ant-design/icons';
import {
ModalForm,
ProForm,
ProFormDateRangePicker,
ProFormSelect,
ProFormText,
} from '@ant-design/pro-components';
import { Button, Form, message } from 'antd';
const waitTime = (time: number = 100) => {
return new Promise((resolve) => {
setTimeout(() => {
resolve(true);
}, time);
});
};
const Demo = () => {
const [form] = Form.useForm<{ name: string; company: string }>();
return (
<ModalForm<{
name: string;
company: string;
}>
name="modal-form-demo"
title="Create New Form"
trigger={
<Button type="primary">
<PlusOutlined />
Create New Form
</Button>
}
form={form}
autoFocusFirstInput
modalProps={{
destroyOnHidden: true,
onCancel: () => {
message.info('已关闭');
},
}}
submitTimeout={2000}
onFinish={async () => {
await waitTime(2000);
message.success('Submission successful');
return true;
}}
>
<ProForm.Group>
<ProFormText
width="md"
name="name"
label="Contract Customer Name"
tooltip="Up to 24 characters"
placeholder="Please enter a name"
/>
<ProFormText
width="md"
name="company"
label="Our Company Name"
placeholder="Please enter a name"
/>
</ProForm.Group>
<ProForm.Group>
<ProFormText
width="md"
name="contract"
label="Contract Name"
placeholder="Please enter a name"
/>
<ProFormDateRangePicker
name="contractTime"
label="Contract Effective Time"
/>
</ProForm.Group>
<ProForm.Group>
<ProFormSelect
request={async () => [
{
value: 'chapter',
label: 'Effective after stamping',
},
]}
width="xs"
name="useMode"
label="Contract Agreed Effective Method"
/>
<ProFormSelect
width="xs"
options={[
{
value: 'time',
label: 'Terminate after performance',
},
]}
name="unusedMode"
label="Contract Agreed Invalid Method"
/>
</ProForm.Group>
<ProFormText width="sm" name="id" label="Main Contract Number" />
<ProFormText
name="project"
disabled
label="Project Name"
initialValue="示例项目"
/>
<ProFormText
width="xs"
name="mangerName"
disabled
label="Business Manager"
initialValue="书琰"
/>
</ModalForm>
);
};
export default () => (
<div style={{ padding: 24 }}>
<Demo />
</div>
);
#Drawer 表单
import { PlusOutlined } from '@ant-design/icons';
import {
DrawerForm,
ProForm,
ProFormDateRangePicker,
ProFormSelect,
ProFormText,
} from '@ant-design/pro-components';
import { Button, Form, message } from 'antd';
const waitTime = (time: number = 100) => {
return new Promise((resolve) => {
setTimeout(() => {
resolve(true);
}, time);
});
};
const Demo = () => {
const [form] = Form.useForm<{ name: string; company: string }>();
return (
<DrawerForm<{
name: string;
company: string;
}>
name="modal-form-drawer-form-demo"
title="Create New Form"
resize={{
maxWidth: typeof window === 'undefined' ? 800 : window.innerWidth * 0.8,
minWidth: 300,
}}
form={form}
trigger={
<Button type="primary">
<PlusOutlined />
Create New Form
</Button>
}
autoFocusFirstInput
drawerProps={{
destroyOnHidden: true,
}}
submitTimeout={2000}
onFinish={async () => {
await waitTime(2000);
message.success('Submission successful');
// Not returning will not close the modal
return true;
}}
>
<ProForm.Group>
<ProFormText
name="name"
width="md"
label="Contract Customer Name"
tooltip="Up to 24 characters"
placeholder="Please enter a name"
/>
<ProFormText
rules={[
{
required: true,
},
]}
width="md"
name="company"
label="Our Company Name"
placeholder="Please enter a name"
/>
</ProForm.Group>
<ProForm.Group>
<ProFormText
width="md"
name="contract"
label="Contract Name"
placeholder="Please enter a name"
/>
<ProFormDateRangePicker
name="contractTime"
label="Contract Effective Time"
/>
</ProForm.Group>
<ProForm.Group>
<ProFormSelect
options={[
{
value: 'chapter',
label: 'Effective after stamping',
},
]}
width="xs"
name="useMode"
label="Contract Agreed Effective Method"
/>
<ProFormSelect
width="xs"
options={[
{
value: 'time',
label: 'Terminate after performance',
},
]}
formItemProps={{
style: {
margin: 0,
},
}}
name="unusedMode"
label="Contract Agreed Invalid Method"
/>
</ProForm.Group>
<ProFormText width="sm" name="id" label="Main Contract Number" />
<ProFormText
name="project"
disabled
label="Project Name"
initialValue="示例项目"
/>
<ProFormText
width="xs"
name="mangerName"
disabled
label="Business Manager"
initialValue="书琰"
/>
</DrawerForm>
);
};
export default () => (
<div style={{ padding: 24 }}>
<Demo />
</div>
);
#嵌套浮层表单
Drawer Forms
import { PlusOutlined } from '@ant-design/icons';
import {
DrawerForm,
ModalForm,
ProForm,
ProFormDateRangePicker,
ProFormSelect,
ProFormText,
} from '@ant-design/pro-components';
import { Button, Space, message } from 'antd';
import { useRef } from 'react';
const waitTime = (time: number = 100) => {
return new Promise((resolve) => {
setTimeout(() => {
resolve(true);
}, time);
});
};
const Demo = () => {
const formRef = useRef();
return (
<div
style={{
height: '325px',
}}
>
<Space>
<DrawerForm<{
name: string;
company: string;
}>
name="modal-form-drawer-form-nested-demo-4"
title="新建表单"
formRef={formRef}
width={600}
trigger={
<Button type="primary">
<PlusOutlined />
新建 Drawer 表单
</Button>
}
drawerProps={{
forceRender: true,
destroyOnHidden: true,
}}
onFinish={async () => {
await waitTime(2000);
message.success('提交成功');
// 不返回不会关闭弹框
return true;
}}
>
<DrawerForm<{
name: string;
company: string;
}>
name="modal-form-drawer-form-nested-demo-3"
title="新建表单"
formRef={formRef}
trigger={
<Button type="primary">
<PlusOutlined />
新建 Drawer 表单
</Button>
}
drawerProps={{
forceRender: true,
destroyOnHidden: true,
}}
onFinish={async () => {
await waitTime(2000);
message.success('提交成功');
// 不返回不会关闭弹框
return true;
}}
>
<ProForm.Group>
<ProFormText
name="name"
width="md"
label="签约客户名称"
tooltip="最长为 24 位"
placeholder="请输入名称"
/>
<ProFormText
width="md"
name="company"
label="我方公司名称"
placeholder="请输入名称"
/>
</ProForm.Group>
<ProForm.Group>
<ProFormText
width="md"
name="contract"
label="合同名称"
placeholder="请输入名称"
/>
<ProFormDateRangePicker
name="contractTime"
label="合同生效时间"
/>
</ProForm.Group>
<ProForm.Group>
<ProFormSelect
options={[
{
value: 'chapter',
label: '盖章后生效',
},
]}
width="xs"
name="useMode"
label="合同约定生效方式"
/>
<ProFormSelect
width="xs"
options={[
{
value: 'time',
label: '履行完终止',
},
]}
name="unusedMode"
label="合同约定失效效方式"
/>
</ProForm.Group>
<ProFormText width="sm" name="id" label="主合同编号" />
<ProFormText
name="project"
disabled
label="项目名称"
initialValue="示例项目"
/>
<ProFormText
width="xs"
name="mangerName"
disabled
label="商务经理"
initialValue="书琰"
/>
</DrawerForm>
</DrawerForm>
<ModalForm<{
name: string;
company: string;
}>
name="modal-form-drawer-form-nested-demo-2"
title="新建表单"
formRef={formRef}
trigger={
<Button type="primary">
<PlusOutlined />
新建 Model 表单
</Button>
}
modalProps={{
forceRender: true,
destroyOnHidden: true,
}}
onFinish={async () => {
await waitTime(2000);
message.success('提交成功');
// 不返回不会关闭弹框
return true;
}}
>
<ModalForm<{
name: string;
company: string;
}>
name="modal-form-drawer-form-nested-demo-1"
title="新建表单"
formRef={formRef}
trigger={
<Button type="primary">
<PlusOutlined />
新建 Model 表单
</Button>
}
modalProps={{
forceRender: true,
destroyOnHidden: true,
}}
onFinish={async () => {
await waitTime(2000);
message.success('提交成功');
// 不返回不会关闭弹框
return true;
}}
>
<ProForm.Group>
<ProFormText
name="name"
width="md"
label="签约客户名称"
tooltip="最长为 24 位"
placeholder="请输入名称"
/>
<ProFormText
width="md"
name="company"
label="我方公司名称"
placeholder="请输入名称"
/>
</ProForm.Group>
<ProForm.Group>
<ProFormText
width="md"
name="contract"
label="合同名称"
placeholder="请输入名称"
/>
<ProFormDateRangePicker
name="contractTime"
label="合同生效时间"
/>
</ProForm.Group>
<ProForm.Group>
<ProFormSelect
options={[
{
value: 'chapter',
label: '盖章后生效',
},
]}
width="xs"
name="useMode"
label="合同约定生效方式"
/>
<ProFormSelect
width="xs"
options={[
{
value: 'time',
label: '履行完终止',
},
]}
name="unusedMode"
label="合同约定失效效方式"
/>
</ProForm.Group>
<ProFormText width="sm" name="id" label="主合同编号" />
<ProFormText
name="project"
disabled
label="项目名称"
initialValue="示例项目"
/>
<ProFormText
width="xs"
name="mangerName"
disabled
label="商务经理"
initialValue="书琰"
/>
</ModalForm>
</ModalForm>
</Space>
</div>
);
};
export default () => (
<div style={{ padding: 24 }}>
<Demo />
</div>
);
#Debug:请求加载中关闭(Modal + Drawer)
Debug: destroyOnHidden + request (Modal & Drawer)
import { DrawerForm, ModalForm, ProFormText } from '@ant-design/pro-components';
import { Button, message } from 'antd';
const wait = (time: number = 300) =>
new Promise((resolve) => setTimeout(resolve, time));
const Demo = () => {
return (
<>
<ModalForm
title="Debug: destroyOnHidden + request"
trigger={<Button type="primary">Open (Debug)</Button>}
modalProps={{ destroyOnHidden: true }}
// Simulate async data loading
request={async () => {
await wait(3000);
return { name: 'loaded' } as any;
}}
onFinish={async () => {
message.success('Submission successful');
return true;
}}
>
<ProFormText
name="name"
label="Name"
placeholder="Close quickly while loading to test"
/>
</ModalForm>
<div style={{ height: 16 }} />
<DrawerForm
title="Debug: destroyOnHidden + request (Drawer)"
trigger={<Button type="primary">Open Drawer (Debug)</Button>}
drawerProps={{ destroyOnHidden: true }}
// Simulate async data loading
request={async () => {
await wait(3000);
return { name: 'loaded' } as any;
}}
onFinish={async () => {
message.success('Submission successful');
return true;
}}
>
<ProFormText
name="name"
label="Name"
placeholder="Close quickly while loading to test"
/>
</DrawerForm>
</>
);
};
export default () => (
<div style={{ padding: 24 }}>
<Demo />
</div>
);
#自定义 Modal 表单按钮
import { ModalForm, ProFormText } from '@ant-design/pro-components';
import { Button, Space, message } from 'antd';
const waitTime = (time: number = 100) => {
return new Promise((resolve) => {
setTimeout(() => {
resolve(true);
}, time);
});
};
const Demo = () => {
return (
<Space>
<ModalForm
title="Create New Form"
trigger={<Button type="primary">Custom Footer Buttons</Button>}
submitter={{
render: (props, defaultDoms) => {
return [
...defaultDoms,
<Button
key="ok"
onClick={() => {
props.submit();
}}
>
ok
</Button>,
];
},
}}
onFinish={async () => {
await waitTime(2000);
message.success('Submission successful');
return true;
}}
>
<ProFormText
width="md"
name="name"
label="Contract Customer Name"
tooltip="Up to 24 characters"
placeholder="Please enter a name"
/>
<ProFormText
width="md"
name="company"
label="Our Company Name"
placeholder="Please enter a name"
/>
</ModalForm>
<ModalForm
title="Create New Form"
trigger={<Button type="primary">Custom Text</Button>}
submitter={{
searchConfig: {
submitText: 'Confirm',
resetText: 'Cancel',
},
}}
onFinish={async () => {
await waitTime(2000);
message.success('Submission successful');
return true;
}}
>
<ProFormText
width="md"
name="name"
label="Contract Customer Name"
tooltip="Up to 24 characters"
placeholder="Please enter a name"
/>
<ProFormText
width="md"
name="company"
label="Our Company Name"
placeholder="Please enter a name"
/>
</ModalForm>
<ModalForm
title="Create New Form"
trigger={<Button type="primary">Hide or Modify Button Style</Button>}
submitter={{
resetButtonProps: {
type: 'dashed',
},
submitButtonProps: {
style: {
display: 'none',
},
},
}}
onFinish={async () => {
await waitTime(2000);
message.success('Submission successful');
return true;
}}
>
<ProFormText
width="md"
name="name"
label="Contract Customer Name"
tooltip="Up to 24 characters"
placeholder="Please enter a name"
/>
<ProFormText
width="md"
name="company"
label="Our Company Name"
placeholder="Please enter a name"
/>
</ModalForm>
<ModalForm
title="Hide Footer"
trigger={<Button type="primary">Hide Footer</Button>}
submitter={false}
>
<ProFormText
width="md"
name="name"
label="Contract Customer Name"
tooltip="Up to 24 characters"
placeholder="Please enter a name"
/>
<ProFormText
width="md"
name="company"
label="Our Company Name"
placeholder="Please enter a name"
/>
</ModalForm>
</Space>
);
};
export default () => (
<div style={{ padding: 24 }}>
<Demo />
</div>
);
#使用 open 和 onOpenChange
import { PlusOutlined } from '@ant-design/icons';
import {
DrawerForm,
ModalForm,
ProForm,
ProFormDateRangePicker,
ProFormSelect,
ProFormText,
} from '@ant-design/pro-components';
import { Button, Space, message } from 'antd';
import { useState } from 'react';
const Demo = () => {
const [modalVisit, setModalVisit] = useState(false);
const [drawerVisit, setDrawerVisit] = useState(false);
return (
<>
<Space>
<Button
type="primary"
onClick={() => {
setModalVisit(true);
}}
>
<PlusOutlined />
Show Modal
</Button>
<Button
type="primary"
onClick={() => {
setDrawerVisit(true);
}}
>
<PlusOutlined />
Show Drawer
</Button>
</Space>
<ModalForm
title="Create New Form"
open={modalVisit}
onFinish={async () => {
message.success('Submission successful');
return true;
}}
onOpenChange={setModalVisit}
>
<ProForm.Group>
<ProFormText
width="md"
name="name"
label="Contract Customer Name"
tooltip="Up to 24 characters"
placeholder="Please enter a name"
/>
<ProFormText
width="md"
name="company"
label="Our Company Name"
placeholder="Please enter a name"
/>
</ProForm.Group>
<ProForm.Group>
<ProFormText
width="md"
name="contract"
label="Contract Name"
placeholder="Please enter a name"
/>
<ProFormDateRangePicker
name="contractTime"
label="Contract Effective Time"
/>
</ProForm.Group>
<ProForm.Group>
<ProFormSelect
options={[
{
value: 'chapter',
label: 'Effective after stamping',
},
]}
width="xs"
name="useMode"
label="Contract Agreed Effective Method"
/>
<ProFormSelect
width="xs"
options={[
{
value: 'time',
label: 'Terminate after performance',
},
]}
name="unusedMode"
label="Contract Agreed Invalid Method"
/>
</ProForm.Group>
<ProFormText width="sm" name="id" label="Main Contract Number" />
<ProFormText
name="project"
disabled
label="Project Name"
initialValue="示例项目"
/>
<ProFormText
width="xs"
name="mangerName"
disabled
label="Business Manager"
initialValue="书琰"
/>
</ModalForm>
<DrawerForm
onOpenChange={setDrawerVisit}
title="Create New Form"
open={drawerVisit}
onFinish={async () => {
message.success('Submission successful');
return true;
}}
>
<ProForm.Group>
<ProFormText
width="md"
name="name"
label="Contract Customer Name"
tooltip="Up to 24 characters"
placeholder="Please enter a name"
/>
<ProFormText
width="md"
name="company"
label="Our Company Name"
placeholder="Please enter a name"
/>
</ProForm.Group>
<ProForm.Group>
<ProFormText
width="md"
name="contract"
label="Contract Name"
placeholder="Please enter a name"
/>
<ProFormDateRangePicker
name="contractTime"
label="Contract Effective Time"
/>
</ProForm.Group>
<ProForm.Group>
<ProFormSelect
options={[
{
value: 'chapter',
label: 'Effective after stamping',
},
]}
width="xs"
name="useMode"
label="Contract Agreed Effective Method"
/>
<ProFormSelect
width="xs"
options={[
{
value: 'time',
label: 'Terminate after performance',
},
]}
name="unusedMode"
label="Contract Agreed Invalid Method"
/>
</ProForm.Group>
<ProFormText width="sm" name="id" label="Main Contract Number" />
<ProFormText
name="project"
disabled
label="Project Name"
initialValue="示例项目"
/>
<ProFormText
width="xs"
name="mangerName"
disabled
label="Business Manager"
initialValue="书琰"
/>
</DrawerForm>
</>
);
};
export default () => (
<div style={{ padding: 24 }}>
<Demo />
</div>
);
#在首次打开前设置表单值
antd Modal 默认懒渲染内容。首次打开前,Form.useForm() 创建的实例还没有连接到
ModalForm 内部的 Form,此时调用 setFieldsValue 会出现
“Instance created by useForm is not connected” 警告。只传 form={form} 不能提前挂载
Form。
如果交互必须先调用 setFieldsValue 再打开弹窗,请设置
modalProps={{ forceRender: true }}。下面的示例可以直接复制验证:
useForm:首次打开前写入值
import { ModalForm, ProForm, ProFormText } from '@ant-design/pro-components';
import { Button, Space, message } from 'antd';
import { useState } from 'react';
type User = {
name: string;
email: string;
};
const users: User[] = [
{ name: 'Alice', email: 'alice@example.com' },
{ name: 'Bob', email: 'bob@example.com' },
];
export default () => {
const [form] = ProForm.useForm<User>();
const [open, setOpen] = useState(false);
const handleEdit = (user: User) => {
// forceRender connects this instance before the first button click.
form.setFieldsValue(user);
setOpen(true);
};
return (
<>
<Space>
{users.map((user) => (
<Button key={user.email} onClick={() => handleEdit(user)}>
Edit {user.name}
</Button>
))}
</Space>
<ModalForm<User>
form={form}
open={open}
onOpenChange={setOpen}
modalProps={{ forceRender: true }}
title="Edit user"
onFinish={async (values) => {
message.success(`Saved ${values.name}`);
return true;
}}
>
<ProFormText name="name" label="Name" rules={[{ required: true }]} />
<ProFormText name="email" label="Email" />
</ModalForm>
</>
);
};
也可以采用以下方式避免过早调用实例:
- 使用
initialValues或request,让数据随 Form 挂载后初始化;编辑不同记录时配合modalProps={{ destroyOnHidden: true }},确保下次打开重新挂载。 - 在
onInit中保存或使用已经连接的表单实例。 - 使用 ModalForm 自带的
trigger时,在onOpenChange(true)中写入值;v3 会等内部 Form 挂载后再触发首次打开回调。
#重置表单
import type { ProFormInstance } from '@ant-design/pro-components';
import { ModalForm, ProFormText } from '@ant-design/pro-components';
import { Button, Space, message } from 'antd';
import { useRef, useState } from 'react';
const waitTime = (time: number = 100) => {
return new Promise((resolve) => {
setTimeout(() => {
resolve(true);
}, time);
});
};
const Demo = () => {
const restFormRef = useRef<ProFormInstance>();
const formRef = useRef<ProFormInstance>();
const [modalVisible, setModalVisible] = useState<boolean>(false);
return (
<Space>
<ModalForm
title="Create New Form"
formRef={restFormRef}
open={modalVisible}
trigger={
<Button
type="primary"
onClick={() => {
setModalVisible(true);
}}
>
Reset via formRef
</Button>
}
onOpenChange={setModalVisible}
submitter={{
searchConfig: {
resetText: 'Reset',
},
resetButtonProps: {
onClick: () => {
restFormRef.current?.resetFields();
// setModalVisible(false);
},
},
}}
onFinish={async () => {
await waitTime(2000);
message.success('Submission successful');
return true;
}}
>
<ProFormText
width="md"
name="name"
label="Contract Customer Name"
tooltip="Up to 24 characters"
placeholder="Please enter a name"
/>
<ProFormText
width="md"
name="company"
label="Our Company Name"
placeholder="Please enter a name"
/>
</ModalForm>
<ModalForm
title="Create New Form"
formRef={formRef}
trigger={<Button type="primary">Reset via custom footer button</Button>}
submitter={{
render: (props, defaultDoms) => {
return [
...defaultDoms,
<Button
key="extra-reset"
onClick={() => {
props.reset();
}}
>
Reset
</Button>,
];
},
}}
onFinish={async () => {
await waitTime(2000);
message.success('Submission successful');
return true;
}}
>
<ProFormText
width="md"
name="name"
label="Contract Customer Name"
tooltip="Up to 24 characters"
placeholder="Please enter a name"
/>
<ProFormText
width="md"
name="company"
label="Our Company Name"
placeholder="Please enter a name"
/>
</ModalForm>
</Space>
);
};
export default () => (
<div style={{ padding: 24 }}>
<Demo />
</div>
);
#API
#ModalForm
ModalForm 组合了 Modal 和 ProForm 可以减少繁琐的状态管理。
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| trigger | 用于触发 Modal 打开的 dom,一般是 Button | JSX.Element | - |
| open | 是否打开 | boolean | - |
| onOpenChange | open 改变时触发 | (open: boolean) => void | - |
| modalProps | Modal 的 props,使用方式与 antd 相同。注意:不支持传入 open,请使用顶层的 open 控制 | Omit<ModalProps, 'open'> | - |
| title | 弹框的标题 | ModalProps['title'] | - |
| width | 弹框的宽度 | ModalProps['width'] | - |
| onFinish | 提交数据时触发,返回真值会关闭弹框;若配置了 destroyOnHidden 还会在关闭后重置表单 | (values: any) => Promise<any> | - |
| submitTimeout | 提交数据时,禁用取消按钮的超时时间(毫秒) | number | - |
| submitter | 提交按钮相关配置,使用方式与 ProForm 相同 | SubmitterProps | false | - |
#DrawerForm
DrawerForm 组合了 Drawer 和 ProForm 可以减少繁琐的状态管理。
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| trigger | 用于触发抽屉打开的 dom,一般是 Button | JSX.Element | - |
| open | 是否打开 | boolean | - |
| onOpenChange | open 改变时触发 | (open: boolean) => void | - |
| drawerProps | Drawer 的 props,使用方式与 antd 相同。注意:不支持传入 open,请使用顶层的 open 控制 | Omit<DrawerProps, 'open'> | - |
| title | 抽屉的标题 | DrawerProps['title'] | - |
| size | 抽屉的尺寸 | DrawerProps['size'] | - |
| width | 抽屉的宽度,已废弃,请使用 size | DrawerProps['size'] | - |
| resizable | 是否使用 antd 原生拖拽调整尺寸(配置 resize 时无效) | DrawerProps['resizable'] | - |
| resize | 是否允许拖拽调整抽屉宽度;为 true 时使用默认配置,也可以传入对象进行配置 | CustomizeResizeType | boolean | false |
| onFinish | 提交数据时触发,返回真值会关闭抽屉;若配置了 destroyOnHidden 还会在关闭后重置表单 | (values: any) => Promise<any> | - |
| submitTimeout | 提交数据时,禁用取消按钮的超时时间(毫秒) | number | - |