> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/drawer.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# Drawer 抽屉

从页面边缘展开内容，查看详情或完成操作。


## 基础用法

通过 `onClose` 响应关闭请求并更新 `open`。没有 `title` 时，使用 `aria-label` 提供名称。


查看详情

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/drawer/basic.tsx"
import { Button, Drawer, Paragraph } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DrawerBasic() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button onClick={() => setOpen(true)}>查看详情</Button>
      <Drawer open={open} title="文档详情" onClose={() => setOpen(false)}>
        <Paragraph>此文档由设计团队维护，最近更新于本周。</Paragraph>
      </Drawer>
    </>
  );
}
```

展开代码


## 示例

### 展开方向

左右方向使用 `width`，上下方向使用 `height`。


左侧右侧顶部底部

placement.tsx

复制代码

```tsx lineNumbers file="../../src/examples/drawer/placement.tsx"
import { Button, Drawer, type DrawerProps, Paragraph, Space } from '@ifhover/leaf-ui';
import { useState } from 'react';

const placements = [
  { value: 'left', label: '左侧' },
  { value: 'right', label: '右侧' },
  { value: 'top', label: '顶部' },
  { value: 'bottom', label: '底部' },
] as const;

export function DrawerPlacement() {
  const [open, setOpen] = useState(false);
  const [placement, setPlacement] = useState<DrawerProps['placement']>('right');
  return (
    <>
      <Space wrap>
        {placements.map((item) => (
          <Button
            key={item.value}
            onClick={() => {
              setPlacement(item.value);
              setOpen(true);
            }}
          >
            {item.label}
          </Button>
        ))}
      </Space>
      <Drawer open={open} placement={placement} title="文档详情" onClose={() => setOpen(false)}>
        <Paragraph>从选定的页面边缘展开详情。</Paragraph>
      </Drawer>
    </>
  );
}
```

展开代码

### 底部提交

通过按钮的 `form` 属性关联抽屉内的表单，保留原生校验；提交与关闭都由应用处理。


编辑名称

sections.tsx

复制代码

```tsx lineNumbers file="../../src/examples/drawer/sections.tsx"
import { Button, Drawer, Form, FormField, Input, Space } from '@ifhover/leaf-ui';
import { useId, useState } from 'react';

export function DrawerSections() {
  const [open, setOpen] = useState(false);
  const formId = useId();
  return (
    <>
      <Button onClick={() => setOpen(true)}>编辑名称</Button>
      <Drawer
        open={open}
        title="编辑名称"
        onClose={() => setOpen(false)}
        footer={
          <Space wrap>
            <Button onClick={() => setOpen(false)}>取消</Button>
            <Button variant="solid" type="submit" form={formId}>
              保存
            </Button>
          </Space>
        }
      >
        <Form
          id={formId}
          layout="vertical"
          onSubmit={(event) => {
            event.preventDefault();
            setOpen(false);
          }}
        >
          <FormField label="名称" required>
            <Input name="name" defaultValue="Leaf UI" />
          </FormField>
        </Form>
      </Drawer>
    </>
  );
}
```

展开代码

### 调整尺寸

[](#)
启用 `resizable` 后，可拖动边缘，或聚焦分隔条后使用方向键调整。`minSize` 与 `maxSize` 限制 `onResize` 返回的调整值，实际可见尺寸仍受视口限制；修改 `width` 或 `height` 会重置手动调整值。


调整抽屉宽度

resize.tsx

复制代码

```tsx lineNumbers file="../../src/examples/drawer/resize.tsx"
import { Button, Drawer, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DrawerResize() {
  const [open, setOpen] = useState(false);
  const [size, setSize] = useState<number>();
  return (
    <>
      <Button onClick={() => setOpen(true)}>调整抽屉宽度</Button>
      <Drawer
        open={open}
        title="调整宽度"
        onClose={() => setOpen(false)}
        resizable
        minSize={260}
        maxSize={640}
        onResize={setSize}
      >
        <Text tone="muted" role="status">
          {size == null ? '尚未调整尺寸' : `调整值：${size}px`}
        </Text>
      </Drawer>
    </>
  );
}
```

展开代码

### 嵌套推移

在子抽屉上设置 `push`，打开时推移最近的父弹层；`true` 对应 40px，也可直接传入距离。Escape 仅关闭最上层抽屉，关闭后焦点回到对应触发按钮。父抽屉关闭时同时重置子抽屉的 `open`，避免下次打开时子层仍展开。


打开第一层

nested.tsx

复制代码

```tsx lineNumbers file="../../src/examples/drawer/nested.tsx"
import { Button, Drawer, Paragraph } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DrawerNested() {
  const [open, setOpen] = useState(false);
  const [childOpen, setChildOpen] = useState(false);
  const closeParent = () => {
    setChildOpen(false);
    setOpen(false);
  };
  return (
    <>
      <Button onClick={() => setOpen(true)}>打开第一层</Button>
      <Drawer open={open} title="第一层抽屉" onClose={closeParent}>
        <Button onClick={() => setChildOpen(true)}>打开第二层</Button>
        <Drawer
          open={childOpen}
          title="第二层抽屉"
          width={300}
          push
          onClose={() => setChildOpen(false)}
        >
          <Paragraph>这里是第二层抽屉的内容。</Paragraph>
        </Drawer>
      </Drawer>
    </>
  );
}
```

展开代码

### 标签页抽屉

通过 `tabs` 在标题下方或顶部嵌入线形标签页。标签栏固定在正文滚动区上方，即使 `divided={false}`（默认值）也会保留标签栏底部分割线；若仅将标签栏用于切换状态并把内容写在 Drawer 的 `children` 中，可省略各项的 `children`。


查看详情

tabs.tsx

复制代码

```tsx lineNumbers file="../../src/examples/drawer/tabs.tsx"
import { Button, Drawer, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DrawerTabs() {
  const [open, setOpen] = useState(false);
  const [view, setView] = useState('overview');
  return (
    <>
      <Button onClick={() => setOpen(true)}>查看详情</Button>
      <Drawer
        open={open}
        title="任务详情"
        onClose={() => setOpen(false)}
        tabs={{
          activeKey: view,
          onChange: setView,
          items: [
            { key: 'overview', label: '概览' },
            { key: 'logs', label: '运行日志' },
          ],
        }}
      >
        <Text>
          {view === 'overview'
            ? '省略标签项 children 时，可将标签栏作为正文状态切换器使用。'
            : '正在展示运行日志视图，标签栏底部分割线始终保留。'}
        </Text>
      </Drawer>
    </>
  );
}
```

展开代码

内容保留与焦点配置参见 [Modal 的进阶用法](https://ifhover.github.io/leaf-ui/components/modal.md#%E8%BF%9B%E9%98%B6%E7%94%A8%E6%B3%95)。


## API

### Drawer API

抽屉的受控打开状态、展开方向、内容区域与关闭行为配置。

| 属性               | 类型                                                                         | 默认值       | 说明                                        |
| ---------------- | -------------------------------------------------------------------------- | --------- | ----------------------------------------- |
| `open`           | `boolean`                                                                  | 必填        | 受控的打开状态，应用负责更新。                           |
| `title`          | `ReactNode`                                                                | —         | 抽屉标题。                                     |
| `description`    | `ReactNode`                                                                | —         | 补充说明。                                     |
| `tabs`           | [`DrawerTabsProps`](#drawertabs-api)                                       | —         | 内嵌标签页；无标题时替代标题栏，有标题时位于其下方；底部分割线始终保留。      |
| `onClose`        | `() => void`                                                               | —         | 请求关闭，由应用更新 open                           |
| `placement`      | `'left' \| 'right' \| 'top' \| 'bottom'`                                   | `'right'` | 展开方向                                      |
| `width`          | `number \| string`                                                         | `380`     | 左右抽屉宽度                                    |
| `height`         | `number \| string`                                                         | `300`     | 上下抽屉高度                                    |
| `footer`         | `ReactNode`                                                                | —         | 底部内容                                      |
| `extra`          | `ReactNode`                                                                | —         | 标题旁的操作内容                                  |
| `icon`           | `ReactNode`                                                                | —         | 标题左侧的装饰图标。                                |
| `divided`        | `boolean`                                                                  | `false`   | 用浅分隔线划分标题、内容和底部操作区。                       |
| `closable`       | `boolean`                                                                  | `true`    | 显示关闭按钮。                                   |
| `maskClosable`   | `boolean`                                                                  | `true`    | 点击遮罩时请求关闭。                                |
| `keyboard`       | `boolean`                                                                  | `true`    | 允许按 Escape 请求关闭。                          |
| `initialFocus`   | `RefObject<HTMLElement \| null> \| (() => HTMLElement \| null)`            | —         | 指定打开后的初始焦点。                               |
| `returnFocus`    | `boolean \| RefObject<HTMLElement \| null> \| (() => HTMLElement \| null)` | —         | 关闭后返回原焦点；也可指定目标或设为 false。                 |
| `resizable`      | `boolean`                                                                  | `false`   | 允许拖动和使用方向键调整大小。                           |
| `minSize`        | `number`                                                                   | `240`     | 最小尺寸，单位为像素。                               |
| `maxSize`        | `number`                                                                   | `900`     | 最大尺寸，单位为像素。                               |
| `onResize`       | `(size: number) => void`                                                   | —         | 用户拖动或键盘调整时返回新尺寸；width 或 height 改变会重置手动尺寸。 |
| `push`           | `boolean \| number`                                                        | `false`   | 推动最近的父弹层；true 使用 40px，数字指定距离。             |
| `afterClose`     | `() => void`                                                               | —         | 关闭过渡结束后触发                                 |
| `destroyOnClose` | `boolean`                                                                  | `false`   | 关闭后卸载内容；preserve 优先，forceRender 会保持挂载。    |
| `preserve`       | `boolean`                                                                  | —         | 指定是否保留内容，优先于 destroyOnClose；不重置组件外的受控状态。  |
| `forceRender`    | `boolean`                                                                  | `false`   | 打开前也挂载内容，关闭时保持隐藏。                         |
| `container`      | `Element \| DocumentFragment \| (() => Element \| DocumentFragment)`       | —         | 指定 Portal 挂载目标，也可返回 ShadowRoot。           |

### DrawerTabs API

内嵌标签页的可用属性见 [Tabs API
](tabs.html#tabs-api)（新标签页打开）。Drawer 固定使用 `type="line"`
 与 `placement="top"`
，标签栏固定在正文滚动区上方，底部分割线不受 `divided={false}`
 影响；`items`
 为空时恢复普通抽屉。
```ts
type DrawerTabsProps = Omit<TabsProps, 'type' | 'placement' | 'children'>;
```
