ProComponents, templates & AI tooling
HeroUI
27.7k
快速开始
组件
发布说明
迁移

AlertDialog 警告对话框

用于关键确认的模态对话框，需要用户关注并执行明确操作。

StorybookReact Aria源代码样式源代码

引入

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

用法

"use client";

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

export function Default() {

组件结构

导入 AlertDialog 组件后，可通过点语法访问各个子部分。

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>
);

状态

"use client";

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

export function Statuses() {

位置

"use client";

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

const PLACEMENT_LABELS = {

背景变体

"use client";

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

const VARIANT_LABELS = {

尺寸

"use client";

import {Rocket} from "@gravity-ui/icons";
import {AlertDialog, Button} from "@heroui/react";

自定义图标

"use client";

import {LockOpen} from "@gravity-ui/icons";
import {AlertDialog, Button} from "@heroui/react";

自定义背景

"use client";

import {TriangleExclamation} from "@gravity-ui/icons";
import {AlertDialog, Button} from "@heroui/react";

关闭行为

isDismissable

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

isKeyboardDismissDisabled

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

"use client";

import {CircleInfo} from "@gravity-ui/icons";
import {AlertDialog, Button} from "@heroui/react";

关闭方式

使用 slot="close"

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

使用 Dialog 的 render props

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

"use client";

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

export function CloseMethods() {

受控状态

配合 React.useState()

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

状态： 关闭

配合 useOverlayState()

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

状态： 关闭

"use client";

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

自定义触发器

"use client";

import {TrashBin} from "@gravity-ui/icons";
import {AlertDialog, Button} from "@heroui/react";

自定义动画

"use client";

import {ArrowUpFromLine, Sparkles} from "@gravity-ui/icons";
import {AlertDialog, Button} from "@heroui/react";
import React from "react";

自定义 Portal

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

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

"use client";

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

样式

传入 Tailwind CSS 类

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

function CustomAlertDialog() {
  return (
    <AlertDialog>
      <Button variant="danger">Delete</Button>
      <AlertDialog.Backdrop className="bg-red-950/90">
        <AlertDialog.Container className="items-start pt-20">
          <AlertDialog.Dialog className="border-2 border-red-500 sm:max-w-[400px]">
            <AlertDialog.CloseTrigger />
            <AlertDialog.Header>
              <AlertDialog.Icon status="danger" />
              <AlertDialog.Heading>Custom Styled Alert</AlertDialog.Heading>
            </AlertDialog.Header>
            <AlertDialog.Body>
              <p>This alert dialog has custom styling applied via Tailwind classes</p>
            </AlertDialog.Body>
            <AlertDialog.Footer>
              <Button slot="close" variant="tertiary">
                Cancel
              </Button>
              <Button slot="close" variant="danger">
                Delete
              </Button>
            </AlertDialog.Footer>
          </AlertDialog.Dialog>
        </AlertDialog.Container>
      </AlertDialog.Backdrop>
    </AlertDialog>
  );
}

自定义组件类

要自定义 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 - 支持位置配置的包裹层
  • .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-visible 或 [data-focus-visible="true"] — 应用于触发器、对话框与关闭按钮
  • 悬停：:hover 或 [data-hovered="true"] — 应用于关闭按钮悬停时
  • 激活：:active 或 [data-pressed="true"] — 应用于关闭按钮按下时
  • 进入：[data-entering] — 应用于对话框打开动画期间
  • 离开：[data-exiting] — 应用于对话框关闭动画期间
  • 位置：[data-placement="*"] — 根据对话框位置应用（auto、top、center、bottom）

API 参考

AlertDialog

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

AlertDialog.Trigger

Prop类型默认值描述
childrenReactNode-自定义触发器内容
classNamestring-CSS 类

AlertDialog.Backdrop

Prop类型默认值描述
variant"opaque" | "blur" | "transparent""opaque"背景遮罩样式
isDismissablebooleanfalse点击背景是否关闭
isKeyboardDismissDisabledbooleantrue是否禁用 ESC 关闭
isOpenboolean-受控的打开状态
onOpenChange(isOpen: boolean) => void-打开状态变化的事件处理函数
classNamestring | (values) => string-背景的 CSS 类
UNSTABLE_portalContainerHTMLElement-自定义 portal 容器

AlertDialog.Container

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

AlertDialog.Dialog

Prop类型默认值描述
childrenReactNode | ({close}) => ReactNode-内容或渲染函数
classNamestring-CSS 类
rolestring"alertdialog"ARIA role
aria-labelstring-无障碍标签
aria-labelledbystring-标签元素的 id
aria-describedbystring-描述元素的 id

AlertDialog.Header

Prop类型默认值描述
childrenReactNode-头部内容（通常为 Icon 与 Heading）
classNamestring-CSS 类

AlertDialog.Heading

Prop类型默认值描述
childrenReactNode-标题文本
classNamestring-CSS 类

AlertDialog.Body

Prop类型默认值描述
childrenReactNode-正文内容
classNamestring-CSS 类

AlertDialog.Footer

Prop类型默认值描述
childrenReactNode-底部内容（通常为操作按钮）
classNamestring-CSS 类

AlertDialog.Icon

Prop类型默认值描述
childrenReactNode-自定义图标元素
status"default" | "accent" | "success" | "warning" | "danger""danger"状态颜色变体
classNamestring-CSS 类

AlertDialog.CloseTrigger

Prop类型默认值描述
childrenReactNode-自定义关闭按钮
classNamestring | (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

无障碍

实现 WAI-ARIA AlertDialog 模式：

  • 焦点陷阱：焦点限制在 AlertDialog 内
  • 键盘：ESC 关闭（若启用）、Tab 在可聚焦元素间循环
  • 屏幕阅读器：role="alertdialog" 等合适的 ARIA 属性
  • 滚动锁定：打开时禁用 body 滚动
  • 需要明确操作：默认需要用户明确操作（不通过点击背景/ESC 轻易关闭）

Alert 警告

向用户展示重要消息与通知，并提供状态指示。

Autocomplete 自动完成

自动完成将选择与过滤结合，让用户可以搜索并从选项列表中选择。

本页目录

引入用法组件结构状态位置背景变体尺寸自定义图标自定义背景关闭行为关闭方式受控状态自定义触发器自定义动画自定义 Portal样式传入 Tailwind CSS 类自定义组件类CSS 类基础类背景变体状态变体（图标）交互状态API 参考AlertDialogAlertDialog.TriggerAlertDialog.BackdropAlertDialog.ContainerAlertDialog.DialogAlertDialog.HeaderAlertDialog.HeadingAlertDialog.BodyAlertDialog.FooterAlertDialog.IconAlertDialog.CloseTriggeruseOverlayState Hook无障碍