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

# Drawer

反馈`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

在不离开当前页面的情况下打开侧边任务面板。

## 何时使用

检查、编辑或辅助工作流需要保留当前页面上下文时使用 Drawer。

**推荐**

- 提供清晰标题和可预测的关闭入口。
- 破坏性操作应保留独立确认步骤。

**避免**

- 不要在同一工作流中连续堆叠多个 Drawer。

## 代码演示


### 基础用法
```tsx preview
import { Button, Drawer } from '@rockshin/tao-ui';
import { useState } from 'react';

function DrawerExample() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Open drawer
      </Button>
      <Drawer
        open={open}
        onClose={() => setOpen(false)}
        title="Project settings"
      >
        Update settings without leaving the current page.
      </Drawer>
    </>
  );
}

export default DrawerExample;
```

### 位置与尺寸
```tsx preview
import { Button, Drawer, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';

function DrawerPlacement() {
  const [placement, setPlacement] = useState<'right' | 'bottom' | null>(null);

  return (
    <>
      <Stack direction="horizontal" gap="md">
        <Button variant="secondary" onClick={() => setPlacement('right')}>
          Right
        </Button>
        <Button variant="secondary" onClick={() => setPlacement('bottom')}>
          Bottom
        </Button>
      </Stack>
      <Drawer
        open={placement !== null}
        placement={placement || 'right'}
        size={placement === 'bottom' ? 'large' : 'default'}
        title="Placement demo"
        onClose={() => setPlacement(null)}
      >
        Drawer content follows the selected edge.
      </Drawer>
    </>
  );
}

export default DrawerPlacement;
```

### 页脚与额外操作
```tsx preview
import { Button, Drawer, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';

function DrawerFooter() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Edit settings
      </Button>
      <Drawer
        open={open}
        title="Settings"
        extra={
          <Button size="small" variant="ghost">
            Help
          </Button>
        }
        footer={
          <Stack direction="horizontal" gap="sm">
            <Button variant="ghost" onClick={() => setOpen(false)}>
              Cancel
            </Button>
            <Button onClick={() => setOpen(false)}>Save</Button>
          </Stack>
        }
        onClose={() => setOpen(false)}
      >
        Drawer footer actions stay attached to the workflow.
      </Drawer>
    </>
  );
}

export default DrawerFooter;
```

### 可调整尺寸的抽屉
```tsx preview
import { Button, Drawer } from '@rockshin/tao-ui';
import { useState } from 'react';

function ResizableDrawer() {
  const [open, setOpen] = useState(false);
  const [width, setWidth] = useState<number | null>(null);

  return (
    <>
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Open resizable drawer
      </Button>
      <Drawer
        open={open}
        title="Resizable"
        resizable={{ onResize: (size) => setWidth(Math.round(size)) }}
        onClose={() => setOpen(false)}
      >
        Current width: {width === null ? 'default' : width + 'px'}
      </Drawer>
    </>
  );
}

export default ResizableDrawer;
```

### 标题操作与固定页脚
使用 `extra` 与 `footer` 放置操作，内容滚动时操作区保持可见。
```tsx preview
import { Button, Drawer, FormField, Input, Stack } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function DrawerWithFooterAndExtra() {
  function Demo() {
    const [open, setOpen] = useState(false);
    return (
      <>
        <Button variant="secondary" onClick={() => setOpen(true)}>
          Open
        </Button>
        <Drawer
          open={open}
          onClose={() => setOpen(false)}
          title="Edit Profile"
          extra={
            <Button variant="ghost" onClick={() => setOpen(false)}>
              Reset
            </Button>
          }
          footer={
            <>
              <Button variant="secondary" onClick={() => setOpen(false)}>
                Cancel
              </Button>
              <Button variant="primary" onClick={() => setOpen(false)}>
                Save
              </Button>
            </>
          }
        >
          <Stack gap="md">
            <FormField label="Name">
              <Input placeholder="Your name" />
            </FormField>
            <FormField label="Bio">
              <Input placeholder="Short bio" />
            </FormField>
          </Stack>
        </Drawer>
      </>
    );
  }
  return <Demo />;
}
```

### 预设与自定义尺寸
`size` 提供预设，`width` 或 `height` 可指定应用所需的尺寸。
```tsx preview
import { Button, Drawer, Stack } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function DrawerSizes() {
  function Demo() {
    const [size, setSize] = useState<'default' | 'large' | null>(null);
    return (
      <Stack direction="horizontal" gap="md">
        <Button variant="secondary" onClick={() => setSize('default')}>
          default (378)
        </Button>
        <Button variant="secondary" onClick={() => setSize('large')}>
          large (736)
        </Button>
        <Drawer
          open={size != null}
          onClose={() => setSize(null)}
          title={`Size: ${size}`}
          size={size ?? 'default'}
        >
          <p style={{ color: 'var(--tao-color-text-secondary)' }}>
            Preset width via the `size` prop.
          </p>
        </Drawer>
      </Stack>
    );
  }
  return <Demo />;
}
```

### 遮罩与关闭方式
分别控制遮罩、点击遮罩关闭和关闭按钮，始终提供明确的退出路径。
```tsx preview
import { Button, Drawer } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function DrawerNoMaskClosableConfig() {
  function Demo() {
    const [open, setOpen] = useState(false);
    return (
      <>
        <Button variant="secondary" onClick={() => setOpen(true)}>
          Open (mask click won't close)
        </Button>
        <Drawer
          open={open}
          onClose={() => setOpen(false)}
          title="Locked"
          maskClosable={false}
          keyboard={false}
          footer={
            <Button variant="primary" onClick={() => setOpen(false)}>
              Done
            </Button>
          }
        >
          <p style={{ color: 'var(--tao-color-text-secondary)' }}>
            Mask click and Esc are disabled — close via the × or the footer
            button.
          </p>
        </Drawer>
      </>
    );
  }
  return <Demo />;
}
```

### 拖动调整抽屉
`resizable` 允许拖动边缘调整尺寸，适合需要临时扩大工作区域的详情面板。
```tsx preview
import { Button, Drawer } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function DrawerResizable() {
  function Demo() {
    const [open, setOpen] = useState(false);
    const [size, setSize] = useState<number | null>(null);
    return (
      <>
        <Button variant="secondary" onClick={() => setOpen(true)}>
          Open resizable
        </Button>
        <Drawer
          open={open}
          onClose={() => setOpen(false)}
          title="Drag the left edge"
          resizable={{ onResize: (s) => setSize(Math.round(s)) }}
        >
          <p style={{ color: 'var(--tao-color-text-secondary)' }}>
            Grab the inner edge and drag to resize. Current width:{' '}
            {size != null ? `${size}px` : 'default'}
          </p>
        </Drawer>
      </>
    );
  }
  return <Demo />;
}
```

## API


### [#](#drawer)Drawer



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| extra | Extra content rendered on the trailing side of the header. | `ReactNode` | `-` |
| footer | Footer content; renders a bordered footer area when provided. | `ReactNode` | `-` |
| size | Preset drawer size: `default` (378) / `large` (736). `width`/`height` override it. | `DrawerSize | undefined` | `-` |
| closable | Show the close (×) button. Defaults to true. | `boolean | undefined` | `true` |
| closeIcon | Custom close icon. | `ReactNode` | `-` |
| maskClosable | Close when clicking the mask. Defaults to true. | `boolean | undefined` | `true` |
| mask | Render the mask/overlay. Defaults to true. | `boolean | undefined` | `true` |
| keyboard | Close on Esc key. Defaults to true. | `boolean | undefined` | `true` |
| resizable | Allow resizing by dragging the inner edge. Pass an object for resize callbacks. | `boolean | DrawerResizableConfig | undefined` | `-` |
| afterOpenChange | Called after open transitions in either direction. | `((open: boolean) => void) | undefined` | `-` |
| afterClose | Called after the drawer has fully closed. | `(() => void) | undefined` | `-` |
| destroyOnHidden | Unmount children when closed. Defaults to `true`.
Set `false` to keep children mounted while releasing modal interaction locks when hidden. | `boolean | undefined` | `true` |

