Modal#
反馈
@rockshin/tao-ui在受保护的焦点上下文中展示需要用户处理的对话框。
#何时使用
任务需要中断当前流程、确认重要决策或集中完成短任务时使用 Modal。
推荐
- 标题说明用户需要完成的任务。
- 确认按钮文案使用具体动作。
- 异步确认期间展示 loading。
避免
- 不需要中断或焦点保护的内容不要放进 Modal。
#代码演示
#基础用法
TSX
import { Button, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';
function ModalExample() {
const [open, setOpen] = useState(false);
return (
<>
<Button variant="secondary" onClick={() => setOpen(true)}>
Open modal
</Button>
<Modal
open={open}
title="Archive project?"
onClose={() => setOpen(false)}
onOk={() => setOpen(false)}
>
You can restore the project later.
</Modal>
</>
);
}
export default ModalExample;#确认加载状态
TSX
import { Button, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';
function LoadingModal() {
const [open, setOpen] = useState(false);
const [loading, setLoading] = useState(false);
function confirm() {
setLoading(true);
window.setTimeout(() => {
setLoading(false);
setOpen(false);
}, 1200);
}
return (
<>
<Button variant="secondary" onClick={() => setOpen(true)}>
Publish
</Button>
<Modal
open={open}
title="Publish changes?"
confirmLoading={loading}
onOk={confirm}
onClose={() => setOpen(false)}
>
The production site will update immediately.
</Modal>
</>
);
}
export default LoadingModal;#自定义与无页脚
TSX
import { Button, Modal, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
function ModalFooters() {
const [mode, setMode] = useState<'custom' | 'none' | null>(null);
return (
<>
<Stack direction="horizontal" gap="md">
<Button variant="secondary" onClick={() => setMode('custom')}>
Custom footer
</Button>
<Button variant="secondary" onClick={() => setMode('none')}>
No footer
</Button>
</Stack>
<Modal
open={mode !== null}
title={mode === 'custom' ? 'Custom footer' : 'Informational modal'}
footer={
mode === 'custom' ? (
<Button onClick={() => setMode(null)}>Done</Button>
) : null
}
onClose={() => setMode(null)}
>
Footer content is optional and can be replaced.
</Modal>
</>
);
}
export default ModalFooters;#命令式对话框
TSX
import { Button, Modal, Stack } from '@rockshin/tao-ui';
function ImperativeModals() {
return (
<Stack direction="horizontal" gap="md">
<Button
variant="secondary"
onClick={() =>
Modal.info({ title: 'Information', content: 'Your export is ready.' })
}
>
Info
</Button>
<Button
variant="secondary"
onClick={() =>
Modal.success({ title: 'Saved', content: 'Changes were saved.' })
}
>
Success
</Button>
<Button
variant="destructive"
onClick={() =>
Modal.confirm({
title: 'Delete project?',
content: 'This cannot be undone.',
})
}
>
Confirm
</Button>
</Stack>
);
}
export default ImperativeModals;#异步确认
用本地延迟模拟提交,confirmLoading 在等待期间提供加载状态并避免重复确认。
TSX
import { Button, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ModalConfirmLoading() {
function Demo() {
const [open, setOpen] = useState(false);
const [loading, setLoading] = useState(false);
return (
<>
<Button variant="secondary" onClick={() => setOpen(true)}>
Open Confirm
</Button>
<Modal
open={open}
title="Delete item?"
confirmLoading={loading}
okText="Delete"
onClose={() => setOpen(false)}
onOk={() => {
setLoading(true);
setTimeout(() => {
setLoading(false);
setOpen(false);
}, 1500);
}}
>
<p>This action cannot be undone.</p>
</Modal>
</>
);
}
return <Demo />;
}#自定义页脚
footer 替换默认操作区,用于多步骤或特殊提交场景。
TSX
import { Button, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ModalCustomFooter() {
function Demo() {
const [open, setOpen] = useState(false);
return (
<>
<Button variant="secondary" onClick={() => setOpen(true)}>
Open
</Button>
<Modal
open={open}
title="Custom footer"
width={420}
onClose={() => setOpen(false)}
footer={
<Button variant="primary" onClick={() => setOpen(false)}>
Got it
</Button>
}
>
<p>Single-action footer.</p>
</Modal>
</>
);
}
return <Demo />;
}#扩展默认按钮
通过页脚渲染函数保留默认按钮能力,同时增加附加操作。
TSX
import { Button, Modal, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ModalFooterRenderFn() {
function Demo() {
const [open, setOpen] = useState(false);
return (
<>
<Button variant="secondary" onClick={() => setOpen(true)}>
Open
</Button>
<Modal
open={open}
title="Compose around defaults"
onClose={() => setOpen(false)}
onOk={() => setOpen(false)}
footer={(origin, { CancelBtn }) => (
<Stack direction="horizontal" gap="sm" style={{ width: '100%' }}>
<Button variant="ghost" onClick={() => setOpen(false)}>
Read later
</Button>
<span style={{ flex: 1 }} />
<CancelBtn />
{origin}
</Stack>
)}
>
<p>
The render-prop footer receives the default node plus{' '}
<code>OkBtn</code> / <code>CancelBtn</code> so you can keep defaults
and add your own.
</p>
</Modal>
</>
);
}
return <Demo />;
}#确认与取消按钮属性
分别配置按钮文案和属性,让危险操作或暂不可用状态更明确。
TSX
import { Button, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ModalButtonProps() {
function Demo() {
const [open, setOpen] = useState(false);
return (
<>
<Button variant="secondary" onClick={() => setOpen(true)}>
Open
</Button>
<Modal
open={open}
title="Delete item?"
okText="Delete"
okButtonProps={{ variant: 'destructive' }}
cancelButtonProps={{ variant: 'ghost' }}
onClose={() => setOpen(false)}
onOk={() => setOpen(false)}
>
<p>OK is a destructive button via okButtonProps.</p>
</Modal>
</>
);
}
return <Demo />;
}#保留关闭前的内容
关闭时保留子组件,可让再次打开后继续编辑;试着输入后关闭再打开。
TSX
import { Button, FormField, Input, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ModalKeepAlive() {
function Demo() {
const [open, setOpen] = useState(false);
return (
<>
<Button variant="secondary" onClick={() => setOpen(true)}>
Open (state preserved across reopen)
</Button>
<Modal
open={open}
title="destroyOnHidden = false"
destroyOnHidden={false}
onClose={() => setOpen(false)}
onOk={() => setOpen(false)}
>
<FormField label="Type, close, reopen — text stays">
<Input placeholder="I survive close" />
</FormField>
</Modal>
</>
);
}
return <Demo />;
}#命令式确认
Modal.confirm 创建一次性确认;示例使用本地延迟模拟异步操作。
TSX
import { Button, Modal, Stack } from '@rockshin/tao-ui';
export default function ModalImperativeConfirm() {
return (
<Stack direction="horizontal" gap="sm">
<Button
variant="destructive"
onClick={() =>
Modal.confirm({
title: 'Delete item?',
content: 'This action cannot be undone.',
okText: 'Delete',
okButtonProps: { variant: 'destructive' },
onOk: () => new Promise((res) => setTimeout(res, 1200)),
})
}
>
confirm (async OK)
</Button>
<Button
variant="secondary"
onClick={() => Modal.info({ title: 'Info', content: 'FYI.' })}
>
info
</Button>
<Button
variant="secondary"
onClick={() => Modal.success({ title: 'Saved!' })}
>
success
</Button>
<Button
variant="secondary"
onClick={() => Modal.error({ title: 'Something broke' })}
>
error
</Button>
<Button
variant="secondary"
onClick={() =>
Modal.warning({ title: 'Heads up', content: 'Check your input.' })
}
>
warning
</Button>
</Stack>
);
}#在上下文中使用确认
Modal.useModal 返回实例与上下文节点,在应用 Provider 范围内渲染该节点。
TSX
import { Button, Modal } from '@rockshin/tao-ui';
export default function ModalUseModalHook() {
function Demo() {
const [modal, contextHolder] = Modal.useModal();
return (
<>
<Button
variant="secondary"
onClick={() =>
modal.confirm({
title: 'Context-aware confirm',
content: 'Inherits TaoProvider config & theme.',
})
}
>
useModal confirm
</Button>
{contextHolder}
</>
);
}
return <Demo />;
}#响应式弹窗宽度
通过断点宽度配置让弹窗适应屏幕,内容保持自然换行。
TSX
import { Button, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ModalResponsiveWidth() {
function Demo() {
const [open, setOpen] = useState(false);
return (
<>
<Button variant="secondary" onClick={() => setOpen(true)}>
Open Responsive Modal
</Button>
<Modal
open={open}
title="Responsive Width"
width={{ xs: 'calc(100vw - 32px)', md: 640, xl: 800 }}
onClose={() => setOpen(false)}
onOk={() => setOpen(false)}
>
Resize the viewport: full-width on phones, 640px from md up, 800px
from xl up.
</Modal>
</>
);
}
return <Demo />;
}#API
#Modal
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| footer | Footer content.
- undefined renders default OK/Cancel buttons
- null renders no footer
- a function receives (originNode, { OkBtn, CancelBtn }) to compose around the defaults | ReactNode | ModalFooterRender | - |
| okButtonProps | Extra props forwarded to the default OK button. | ButtonProps | undefined | - |
| cancelButtonProps | Extra props forwarded to the default Cancel button. | ButtonProps | undefined | - |
| width | Dialog width. Accepts a breakpoint map, e.g.
width={{ xs: '100%', md: 640 }} — the largest matching breakpoint wins,
falling back to the 520px default when no entry matches. | string | number | Partial<Record<TaoBreakpoint, string | number>> | undefined | 520 |
| centered | Vertically center the dialog. Defaults to true. | boolean | undefined | true |
| closable | Show the close (×) button. Defaults to true. | boolean | (AriaAttributes & { disabled?: boolean | undefined; closeIcon?: ReactNode; onClose?: (() => void) | undefined; afterClose?: (() => void) | undefined; }) | undefined | true |
| maskClosable | Close when clicking the mask/overlay. Defaults to true. | boolean | undefined | true |
| keyboard | Close on Esc key. Defaults to true. | boolean | undefined | true |
| getContainer | Portal destination. false renders the dialog in place. | string | false | HTMLElement | (() => HTMLElement) | undefined | - |
| afterClose | Called after the modal has fully closed (open transitions true → false). | (() => void) | undefined | - |
| destroyOnHidden | Unmount children when closed. Defaults to true.
Set false to keep children mounted while releasing modal interaction locks when hidden. | boolean | undefined | true |