# Dialog

模态对话框组件，支持声明式 `<Dialog>` 和命令式 `confirm()` / `alert()` 两种调用方式。

## 适用场景

- 需要用户确认操作（confirm）
- 需要展示警告或通知（alert）
- 需要用户填写信息的浮层表单
- 复杂自定义内容的模态窗口（使用 DialogHead / DialogBody / DialogFoot 子组件）

## Props

### Dialog Props

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| className | `string` | `""` | 否 | 自定义 class |
| size | `"sm" \| "md"` | `-` | 否 | 尺寸，默认读取 ConfigContext `baseSize` |
| width | `number \| "sm" \| "md" \| "xs" \| "lg" \| "xl"` | `"md"` | 否 | 宽度 |
| headline | `ReactNode` | `-` | 否 | 标题 |
| headDivide | `boolean` | `false` | 否 | 是否在标题区加分隔线 |
| confirmLabel | `string` | `-` | 否 | 自定义确认按钮文本 |
| confirmDisabled | `boolean` | `-` | 否 | 禁用确认按钮 |
| cancelLabel | `string` | `-` | 否 | 自定义取消按钮文本 |
| actions | `ReactNode` | `-` | 否 | 自定义操作区 |
| maskCancel | `boolean` | `false` | 否 | 点击蒙层是否触发取消/关闭 |
| actionsAlign | `"right" \| "center" \| "left"` | `-` | 否 | 操作按钮位置，默认读取 ConfigContext `dialogActionsAlign` |
| withCloseX | `boolean` | `true` | 否 | 是否显示右上角关闭叉 |
| withCancel | `boolean` | `true` | 否 | 是否有取消按钮（及关闭叉），设为 false 为纯 alert 确认场景 |
| visible | `boolean` | `-` | 否 | 是否显示 |
| destroyOnHide | `boolean` | `-` | 否 | 隐藏时是否销毁内容 |
| disablePortal | `boolean` | `-` | 否 | 禁用 popup portal，维持 children 在父节点 DOM 层级 |
| portalContainer | `HTMLElement \| (() => HTMLElement)` | `-` | 否 | 指定 popup portal 挂载容器，默认为 document.body |
| onConfirm | `DialogAction` | `-` | 否 | 点击确认的回调 |
| onCancel | `DialogAction` | `-` | 否 | 点击取消/关闭的回调 |

### DialogBody / DialogHead / DialogFoot Props

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| className | `string` | `""` | 否 | 自定义 class |

### DialogConfirm Props

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| className | `string` | `""` | 否 | 自定义 class |
| headline | `ReactNode` | `"--"` | 否 | 标题 |
| content | `ReactNode` | `"--"` | 否 | 内容 |
| loadingDelay | `number` | `-` | 否 | loading 图标延迟响应时间（ms），0 为立即显示 |
| size | `"sm" \| "md"` | `-` | 否 | 尺寸 |
| width | `number \| "sm" \| "md" \| "xs" \| "lg" \| "xl"` | `-` | 否 | 宽度 |
| confirmLabel | `string` | `-` | 否 | 自定义确认按钮文本 |
| cancelLabel | `string` | `-` | 否 | 自定义取消按钮文本 |
| withCancel | `boolean` | `-` | 否 | 是否有取消按钮 |
| onConfirm | `DialogAction` | `-` | 否 | 点击确认的回调 |
| onCancel | `DialogAction` | `-` | 否 | 点击取消/关闭的回调 |
| type | `"info" \| "success" \| "warning" \| "error"` | `"warning"` | 否 | 类型 |
| icon | `boolean \| SvgFC` | `true` | 否 | icon；false 不显示，true 使用 theme icon，传 SvgFC 自定义 |

### confirm() Props

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| headline | `Required<ReactNode>` | `-` | 是 | 标题 |
| content | `Required<ReactNode>` | `-` | 是 | 内容 |
| className | `string` | `-` | 否 | 自定义 class |
| loadingDelay | `number` | `-` | 否 | loading 延迟（ms） |
| size | `"sm" \| "md"` | `-` | 否 | 尺寸 |
| width | `number \| "sm" \| "md" \| "xs" \| "lg" \| "xl"` | `-` | 否 | 宽度 |
| confirmLabel | `string` | `-` | 否 | 自定义确认按钮文本 |
| cancelLabel | `string` | `-` | 否 | 自定义取消按钮文本 |
| withCancel | `boolean` | `-` | 否 | 是否有取消按钮 |
| onConfirm | `DialogAction` | `-` | 否 | 点击确认的回调 |
| onCancel | `DialogAction` | `-` | 否 | 点击取消/关闭的回调 |
| type | `"info" \| "success" \| "warning" \| "error"` | `-` | 否 | 类型 |
| icon | `boolean \| SvgFC` | `-` | 否 | icon 配置 |

### alert() Props

与 `confirm()` Props 相同，区别仅在于 `alert()` 默认不显示取消按钮（纯确认场景）。

## 典型用法

### 基础对话框

```tsx
import { useState } from 'react'
import { Button } from '@befe/brick-comp-button'
import { Dialog } from '@befe/brick-comp-dialog'

function Demo() {
    const [visible, setVisible] = useState(false)

    return (
        <>
            <Button onClick={() => setVisible(true)} type={'important'}>打开</Button>
            <Dialog
                headline={'弹窗标题'}
                visible={visible}
                onConfirm={() => setVisible(false)}
                onCancel={() => setVisible(false)}
            >
                <p>弹窗内容</p>
            </Dialog>
        </>
    )
}
```

### 命令式 confirm

```tsx
import { confirm } from '@befe/brick-comp-dialog'

confirm({
    headline: '请确认',
    content: '修改后无法撤销，是否继续？',
    onConfirm: () => { console.log('confirmed') },
    onCancel: () => { console.log('cancelled') },
})

// 快捷类型方法
confirm.info('通知', '内容')
confirm.warning('警告', '内容')
confirm.error('错误', '内容')
confirm.success('成功', '内容')
```

### 命令式 alert（纯确认，无取消）

```tsx
import { alert } from '@befe/brick-comp-dialog'

alert({ headline: '警告', content: '操作不可逆' })
alert.success('成功', '提交完成')
```

### 自定义结构（DialogHead / DialogBody / DialogFoot）

```tsx
import { Dialog, DialogHead, DialogBody, DialogFoot } from '@befe/brick-comp-dialog'

<Dialog visible={visible} onCancel={close}>
    <DialogHead>
        <Icon svg={SvgLocation} />
        <span>自定义标题</span>
    </DialogHead>
    <DialogBody>
        <p>自定义内容</p>
    </DialogBody>
    <DialogFoot>
        <Button type={'intensive'} onClick={close}>操作</Button>
    </DialogFoot>
</Dialog>
```

### 样式隔离场景下使用 createConfirm

```tsx
import { createConfirm, createAlert } from '@befe/brick'

const confirm = createConfirm({ wrapClassName: 'my-scope' })
const alert = createAlert({ wrapClassName: 'my-scope' })
```

## 注意事项

- `confirm()` / `alert()` 是在独立 React root 中渲染的，无法访问当前页面的 ConfigProvider 配置（如 `wrapClassName`），需要用 `createConfirm(configContext)` / `createAlert(configContext)` 重新创建实例
- `actionsAlign` 建议通过 ConfigProvider 的 `theme/dialogActionsAlign` 全局配置，而不是逐个组件设置
- 使用 `portalContainer` 实现局部模态时，须为容器设置 `position: relative`（或其他非 static 值）
- 破坏性变更（2021）：`actionsAlign` 默认值由 `'center'` 改为 `'right'`；`DialogConfirm` 的 `props.message` 已改名为 `props.content` 且为必填