Drawer 抽屉

用法

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

组件结构

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

export default () => (
  <Drawer>
    <Button>Open Drawer</Button>
    <Drawer.Backdrop>
      <Drawer.Content>
        <Drawer.Dialog>
          <Drawer.Handle /> {/* Optional: Drag handle */}
          <Drawer.CloseTrigger /> {/* Optional: Close button */}
          <Drawer.Header>
            <Drawer.Heading />
          </Drawer.Header>
          <Drawer.Body />
          <Drawer.Footer />
        </Drawer.Dialog>
      </Drawer.Content>
    </Drawer.Backdrop>
  </Drawer>
);

示例

弹出位置

不可关闭

在 Drawer.Backdrop 上设置 isDismissable={false} 可阻止点击外部或拖拽关闭。用户必须通过抽屉内的操作按钮交互。

可滚动内容

Drawer.Body 通过原生滚动自动处理溢出。拖拽关闭在 body 区域被排除，以避免与滚动冲突。

受控模式

搭配表单

导航抽屉

遮罩变体

自定义样式

Tailwind CSS

全局 CSS

可使用 @layer components 指令自定义 Drawer 组件类。

了解更多。

@layer components {
  .drawer__backdrop {
    @apply bg-gradient-to-br from-black/50 to-black/70;
  }

  .drawer__dialog {
    @apply rounded-2xl border border-white/10 shadow-2xl;
  }

  .drawer__header {
    @apply text-center;
  }

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

样式参考

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

CSS 类

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

基础类

• .drawer__trigger - 打开抽屉的触发元素
• .drawer__backdrop - 抽屉背后的遮罩层
• .drawer__content - 抽屉面板的定位包裹层
• .drawer__dialog - 抽屉面板本身
• .drawer__header - 标题区域
• .drawer__heading - 主标题文本
• .drawer__body - 主可滚动内容区域
• .drawer__footer - 操作按钮区域
• .drawer__handle - 视觉拖拽手柄指示器
• .drawer__close-trigger - 关闭按钮元素

遮罩变体

• .drawer__backdrop--opaque - 不透明彩色遮罩（默认）
• .drawer__backdrop--blur - 模糊遮罩，玻璃效果
• .drawer__backdrop--transparent - 透明遮罩（无覆盖层）

位置变体

• .drawer__content--bottom - 从底部边缘滑入（默认）
• .drawer__content--top - 从顶部边缘滑入
• .drawer__content--left - 从左侧边缘滑入
• .drawer__content--right - 从右侧边缘滑入

对话框变体

• .drawer__dialog--top - 从顶部边缘滑入
• .drawer__dialog--bottom - 从底部边缘滑入
• .drawer__dialog--left - 从左侧边缘滑入
• .drawer__dialog--right - 从右侧边缘滑入

交互状态

组件支持以下交互状态：

• Focus：:focus-visible 或 [data-focus-visible="true"] - 应用于触发器与关闭按钮
• Hover：:hover 或 [data-hovered="true"] - 悬停时应用于关闭按钮
• Active：:active 或 [data-pressed="true"] - 按下时应用于触发器与关闭按钮
• Entering：[data-entering] - 抽屉打开动画期间
• Exiting：[data-exiting] - 抽屉关闭动画期间
• Placement：[data-placement="*"] - 根据抽屉位置（top、bottom、left、right）应用

API 参考

Drawer

Drawer.Trigger

Drawer.Backdrop

Drawer.Content

Drawer.Dialog

Drawer.Header

Drawer.Heading

Drawer.Body

Drawer.Footer

Drawer.Handle

Drawer.CloseTrigger

useOverlayState Hook

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

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

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

无障碍

实现 WAI-ARIA Dialog 模式：

• 焦点陷阱：打开时焦点锁定在抽屉内
• 键盘：ESC 关闭（可关闭时），Tab 循环元素
• 屏幕阅读器：通过 React Aria 提供正确的 ARIA 属性
• 滚动锁定：打开时禁用 body 滚动
• 拖拽关闭：在 handle、header 和 footer 区域支持指针拖拽手势

相关组件