# CommonDialog - 常规弹窗

## 说明

最常用的通用弹窗，固定展示标题和底部按钮，正文等内容通过 `children` 自定义传入。基于 `BaseDialog` 实现，遮罩、弹入/弹出动画、按钮布局、键盘避让等行为与其他 HyperOS 弹窗一致。

与 `MessageDialog` 的区别：`CommonDialog` 不内置正文文案和 checkbox，需要纯文本消息时建议直接用 `MessageDialog`；需要在标题与按钮之间放置自定义内容时用 `CommonDialog`。

下表中标注「继承自 BaseDialog」的属性为 Dialog 体系公共属性。

## 属性

| 属性 | 说明 | 类型 | 默认值 | 必填 |
|------|------|------|--------|------|
| **visible** | 是否显示弹窗 | `boolean` | - | 是 |
| **title** | 标题文案（继承自 BaseDialog） | `string` | `'文本类弹窗'` | 否 |
| **children** | 标题与按钮之间的自定义内容（正文需自行传入） | `ReactNode` | - | 否 |
| **buttons** | 底部按钮，1~3 个，数量越界则不渲染按钮组（继承自 BaseDialog） | `AbstractDialogButtonType[]` | `[取消, 确定]` | 否 |
| **titleIcon** | 标题上方图标（继承自 BaseDialog） | `ReactNode` | - | 否 |
| **titleIconStyle** | 标题图标容器样式，可覆盖 width/height（取值钳制在 32~120）（继承自 BaseDialog） | `StyleProp<ViewStyle>` | `80×80` | 否 |
| **colorDepth** | 弹窗底色深度（继承自 BaseDialog） | `'base' \| 'low'` | `'base'` | 否 |
| **canDismiss** | 点击遮罩是否可关闭（继承自 BaseDialog） | `boolean` | `true` | 否 |
| **cancelable** | 返回键及无 callback 按钮是否可关闭弹窗（继承自 BaseDialog） | `boolean` | `true` | 否 |
| **hasShade** | 是否显示半透明遮罩背景（继承自 BaseDialog） | `boolean` | `true` | 否 |
| **onDismiss** | 非点击按钮方式（遮罩、返回键）关闭时回调（继承自 BaseDialog） | `() => void` | - | 否 |
| **onModalShow** | 弹窗显示时回调（继承自 BaseDialog） | `() => void` | - | 否 |
| **onModalHide** | 弹窗隐藏时回调（继承自 BaseDialog） | `() => void` | - | 否 |
| **accessible** | 无障碍：是否启用（继承自 BaseDialog） | `boolean` | `true` | 否 |
| **accessibilityLabel** | 无障碍标签（继承自 BaseDialog） | `string` | - | 否 |
| **layerDismissAccessibilityHint** | 遮罩可点击区域的无障碍标签（继承自 BaseDialog） | `string` | - | 否 |

### buttons 项（AbstractDialogButtonType）

| 字段 | 说明 | 类型 | 必填 |
|------|------|------|------|
| **title** | 按钮文案，缺省时首个为「取消」、其余为「确定」 | `string` | 否 |
| **type** | 按钮类型 | `'primary' \| 'warning' \| 'normal'` | 否 |
| **colorType** | 按钮色系（仅 primary 系生效） | `ColorType` | 否 |
| **disabled** | 是否禁用 | `boolean` | 否 |
| **callback** | 点击回调；不传时点击按钮会按 `cancelable` 决定是否关闭弹窗 | `(...args: any[]) => any` | 否 |
| **accessibilityHint** | 按钮无障碍提示 | `string` | 否 |

## 使用示例

```tsx
import { CommonDialog } from 'miot/ui/hyperOSUI';
import { Text } from 'react-native';

<CommonDialog
  visible={visible}
  title="提示"
  buttons={[
    { title: '取消', callback: () => setVisible(false) },
    { title: '确定', type: 'primary', colorType: 'blue', callback: onConfirm },
  ]}
  onDismiss={() => setVisible(false)}
>
  <Text style={{ paddingHorizontal: 28, textAlign: 'center' }}>这里是自定义内容</Text>
</CommonDialog>
```

## 注意事项

- 按钮数量必须为 1~3 个，否则按钮组不渲染（控制台会打印 `只允许设置1～3个按钮` 警告）。
- 1~2 个按钮横向排列，3 个按钮纵向排列。
- `title` 未传时默认显示 `文本类弹窗`，正式场景请显式传入标题。
- 标题与底部按钮始终展示，无法隐藏；如需无标题/无按钮的完全自定义内容，请使用 `CustomDialog` 或 `ActionCustomDialog`。
- 正文多行滚动、居中/自然对齐等能力不在本组件内置，请使用 `MessageDialog`。

## 修改记录

| 日期 | 版本 | 修改内容 | 修改原因 | 关联 |
|------|------|----------|----------|------|
| 2026-04-06 | v1.18.5-alpha.0 | 组件更名为 CommonDialog，调用方需同步更新引用名 | — | fc8dee02 |
| 2025-12-16 | v1.18.0 | 统一底部按钮命名与字体规格 | — | 06098f07 |