用法

import { AlertDialog } from "@heroui/react";

组件结构

import {AlertDialog, Button} from "@heroui/react";

export default () => (
  <AlertDialog>
    <Button>Open Alert Dialog</Button>
    <AlertDialog.Backdrop>
      <AlertDialog.Container>
        <AlertDialog.Dialog>
          <AlertDialog.CloseTrigger /> {/* Optional: Close button */}
          <AlertDialog.Header>
            <AlertDialog.Icon /> {/* Optional: Status icon */}
            <AlertDialog.Heading />
          </AlertDialog.Header>
          <AlertDialog.Body />
          <AlertDialog.Footer />
        </AlertDialog.Dialog>
      </AlertDialog.Container>
    </AlertDialog.Backdrop>
  </AlertDialog>
);

示例

状态类型

弹出位置

尺寸

受控模式

配合 React.useState()

使用 React 的 useState 管理对话框开关，适合简单场景。

状态：关闭

配合 useOverlayState()

使用 useOverlayState 获得更简洁的 API，内置 open()、close()、toggle() 等方法。

状态：关闭

自定义图标

自定义触发器

删除条目

永久移除此条目

遮罩变体

自定义遮罩

关闭行为

isDismissable

控制是否允许通过点击遮罩关闭对话框。警告框通常需要明确操作，因此默认为 false。对重要性较低的确认，可设为 true。

isKeyboardDismissDisabled

控制是否允许通过 ESC 关闭。警告框通常需要明确操作，因此默认为 true（禁用 ESC）。设为 false 时将允许 ESC 关闭。

关闭方式

使用 `slot="close"`

最简单的关闭方式：在对话框内的任意 Button 上添加 slot="close"，点击后会自动关闭对话框。

使用 Dialog 的 render props

通过 Dialog 的 render props 获取 close 方法，从而完全控制关闭时机与方式，便于在关闭前加入校验等自定义逻辑。

自定义动画

自定义 Portal

将警告对话框渲染到自定义容器，而不是 document.body

为容器应用 transform: translateZ(0) 可创建新的层叠上下文。

自定义样式

Tailwind CSS

全局 CSS

若要自定义 AlertDialog 组件类，可使用 @layer components 指令。

了解更多。

@layer components {
  .alert-dialog__backdrop {
    @apply bg-gradient-to-br from-black/60 to-black/80;
  }

  .alert-dialog__dialog {
    @apply rounded-2xl border border-red-500/20 shadow-2xl;
  }

  .alert-dialog__header {
    @apply gap-4;
  }

  .alert-dialog__icon {
    @apply size-16;
  }

  .alert-dialog__close-trigger {
    @apply rounded-full bg-white/10 hover:bg-white/20;
  }
}

样式参考

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

AlertDialog 组件使用以下 CSS 类（查看源码样式）：

基础类

.alert-dialog__trigger - 打开警告对话框的触发元素
.alert-dialog__backdrop - 对话框背后的遮罩层
.alert-dialog__container - 支持 placement 的定位包裹层
.alert-dialog__dialog - 对话框内容容器
.alert-dialog__header - 图标与标题的头部区域
.alert-dialog__heading - 标题文本样式
.alert-dialog__body - 主内容区域
.alert-dialog__footer - 操作按钮的底部区域
.alert-dialog__icon - 带状态色的图标容器
.alert-dialog__close-trigger - 关闭按钮元素

遮罩变体

.alert-dialog__backdrop--opaque - 不透明彩色遮罩（默认）
.alert-dialog__backdrop--blur - 带玻璃效果的模糊遮罩
.alert-dialog__backdrop--transparent - 透明遮罩（无覆盖层）

状态变体（图标）

.alert-dialog__icon--default - 默认灰色状态
.alert-dialog__icon--accent - 强调蓝色状态
.alert-dialog__icon--success - 成功绿色状态
.alert-dialog__icon--warning - 警告橙色状态
.alert-dialog__icon--danger - 危险红色状态

交互状态

该组件支持以下交互状态：

Focus：:focus-visible 或 [data-focus-visible="true"] — 应用于 trigger、dialog 和 close 按钮
Hover：:hover 或 [data-hovered="true"] — 应用于 close 按钮悬停时
Active：:active 或 [data-pressed="true"] — 应用于 close 按钮按下时
Entering：[data-entering] — 对话框打开动画期间
Exiting：[data-exiting] — 对话框关闭动画期间
Placement：[data-placement="*"] — 根据对话框位置应用（auto、top、center、bottom）

API 参考

AlertDialog

Prop	类型	默认值	描述
`children`	`ReactNode`	-	触发器与容器元素

AlertDialog.Trigger

Prop	类型	默认值	描述
`children`	`ReactNode`	-	自定义触发器内容
`className`	`string`	-	CSS 类

AlertDialog.Backdrop

Prop	类型	默认值	描述
`variant`	`"opaque" \| "blur" \| "transparent"`	`"opaque"`	遮罩覆盖层样式
`isDismissable`	`boolean`	`false`	点击遮罩是否关闭
`isKeyboardDismissDisabled`	`boolean`	`true`	是否禁用 ESC 键关闭
`isOpen`	`boolean`	-	受控的打开状态
`onOpenChange`	`(isOpen: boolean) => void`	-	打开状态变化处理函数
`className`	`string \| (values) => string`	-	遮罩 CSS 类
`UNSTABLE_portalContainer`	`HTMLElement`	-	自定义 portal 容器

AlertDialog.Container

Prop	类型	默认值	描述
`placement`	`"auto" \| "center" \| "top" \| "bottom"`	`"auto"`	对话框在屏幕上的位置
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "cover"`	`"md"`	Alert Dialog 尺寸变体
`className`	`string \| (values) => string`	-	容器 CSS 类

AlertDialog.Dialog

Prop	类型	默认值	描述
`children`	`ReactNode \| ({close}) => ReactNode`	-	内容或渲染函数
`className`	`string`	-	CSS 类
`role`	`string`	`"alertdialog"`	ARIA role
`aria-label`	`string`	-	无障碍标签
`aria-labelledby`	`string`	-	标签元素的 ID
`aria-describedby`	`string`	-	描述元素的 ID

AlertDialog.Header

Prop	类型	默认值	描述
`children`	`ReactNode`	-	头部内容（通常为 Icon 和 Heading）
`className`	`string`	-	CSS 类

AlertDialog.Heading

Prop	类型	默认值	描述
`children`	`ReactNode`	-	标题文本
`className`	`string`	-	CSS 类

AlertDialog.Body

Prop	类型	默认值	描述
`children`	`ReactNode`	-	正文内容
`className`	`string`	-	CSS 类

AlertDialog.Footer

Prop	类型	默认值	描述
`children`	`ReactNode`	-	底部内容（通常为操作按钮）
`className`	`string`	-	CSS 类

AlertDialog.Icon

Prop	类型	默认值	描述
`children`	`ReactNode`	-	自定义图标元素
`status`	`"default" \| "accent" \| "success" \| "warning" \| "danger"`	`"danger"`	状态颜色变体
`className`	`string`	-	CSS 类

AlertDialog.CloseTrigger

Prop	类型	默认值	描述
`children`	`ReactNode`	-	自定义关闭按钮
`className`	`string \| (values) => string`	-	CSS 类

useOverlayState Hook

import {useOverlayState} from "@heroui/react";

const state = useOverlayState({
  defaultOpen: false,
  onOpenChange: (isOpen) => console.log(isOpen),
});

state.isOpen; // Current state
state.open(); // Open dialog
state.close(); // Close dialog
state.toggle(); // Toggle state
state.setOpen(); // Set state directly