> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt.

# Modal

反馈`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

在受保护的焦点上下文中展示需要用户处理的对话框。

## 何时使用

任务需要中断当前流程、确认重要决策或集中完成短任务时使用 Modal。

**推荐**

- 标题说明用户需要完成的任务。
- 确认按钮文案使用具体动作。
- 异步确认期间展示 loading。

**避免**

- 不需要中断或焦点保护的内容不要放进 Modal。

## 代码演示


### 基础用法
```tsx preview
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 preview
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 preview
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 preview
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 preview
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 preview
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 preview
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 preview
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 preview
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 preview
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 preview
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 preview="iframe-follow"
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)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` |

