Drawer 抽屉 · Oink UI

同一张悬浮卡片

Dialog、Drawer、Sheet、Panel 不是四套东西，而是同一张悬浮卡片（FloatingCard）在不同位置、不同尺寸下的用法：一张圆角卡片，和视口四周留一圈缝，从停靠的那一侧滑入。没有阴影，模态时靠遮罩压暗背景，非模态时靠描边和页面分开。遮罩、焦点圈、滚动锁、Esc、进退场都在 FloatingCard 里，只此一份；卡片里面统一用 FloatingHeader / FloatingBody / FloatingFooter 三个结构件来搭。

组件	停靠位置	模态	用在哪
Dialog	居中	模态	确认、简短的表单
Drawer 本页	贴着四边之一	模态	详情、较长的表单、导航
Sheet	贴着底边	模态	手机上代替对话框和抽屉
Panel	贴着四边之一	非模态	检查器、筛选面板

结构件

抽屉本身只是一张贴边的卡片，里面用 FloatingHeader（标题、说明、关闭按钮）、FloatingBody（可滚动的内容区）、FloatingFooter（一排按钮）来搭。头尾固定，内容超出时只有中间滚动。

四个方向

placement 决定从哪一侧滑入，默认 right。进退场和所有悬浮卡片共用：303ms 用 spring-soft 落位（不冲出边距），160ms ease-in 退场。

尺寸

size 是主轴尺寸。左右抽屉是宽度：sm 280、md 360（默认）、lg 480；上下抽屉是高度：sm 240、md 360、lg 520。也可以给数字（px）或 CSS 长度。

头部图标与撑满的按钮

FloatingHeader 的 icon 在标题左边放一个色块图标；FloatingFooter 的 align 控制按钮的排法（end、start、between、stretch）。

关闭方式

默认 Esc、点遮罩、头部的关闭按钮都能关。dismissible={false} 时前两种失效，头部的关闭按钮也随之消失，只能走你提供的按钮。dragToDismiss 让头部变成拖拽把手，朝停靠的那一侧拖出去关闭。

接口

Drawer

属性	类型	默认值	说明
`placement`	`'left' \| 'right' \| 'top' \| 'bottom'`	`'right'`	从哪一侧滑入。
`size`	`'sm' \| 'md' \| 'lg' \| number \| string`	`'md'`	主轴尺寸。左右是宽度 280 / 360 / 480；上下是高度 240 / 360 / 520。
`modal`	`boolean`	`true`	模态：带遮罩、锁滚动、圈住焦点。需要非模态时优先用 Panel。
`stretch`	`boolean`	`true`	是否在另一个方向上撑满；false 则按内容大小并居中。
`dragToDismiss`	`boolean`	`false`	按住头部（或抓手）朝停靠的那一侧拖拽关闭。需要 dismissible。
`role`	`'dialog' \| 'alertdialog' \| 'complementary' \| 'region'`	`'dialog'`	语义角色。
`open / defaultOpen`	`boolean`	`false`	开合，受控 / 非受控。
`onOpenChange`	`(open: boolean) => void`	—	开合变化时（Esc、点遮罩、关闭按钮、拖拽关闭都会触发）。
`dismissible`	`boolean`	`true`	允许 Esc 和点遮罩关闭。
`gap`	`number`	`12（窄屏 8）`	卡片到视口边缘的间隙（px）。
`initialFocus`	`RefObject<HTMLElement>`	—	模态时打开后焦点落在哪。默认是卡片里带 data-autofocus 的元素，没有就落在卡片本身。
`restoreFocus`	`boolean`	`true`	关闭后把焦点还给打开前的元素。
`container`	`HTMLElement \| null`	—	渲染到哪个容器，默认 body。
`onExited`	`() => void`	—	退场动画结束、节点卸载后。
`aria-label / aria-labelledby / aria-describedby`	`string`	—	不传时自动接上 FloatingHeader 的标题和说明。

FloatingHeader

属性	类型	默认值	说明
`title`	`ReactNode`	—	标题。自动成为卡片的 aria-labelledby。
`description`	`ReactNode`	—	标题下面的一行说明。自动成为卡片的 aria-describedby。
`icon`	`ReactNode`	—	标题左边的图标位（40×40 的色块）。
`level`	`1 \| 2 \| 3 \| 4 \| 5 \| 6`	`2`	标题的层级。
`closable`	`boolean`	—	是否带关闭按钮。默认跟随卡片的 dismissible。
`closeLabel`	`string`	`'关闭'`	关闭按钮的读屏名称。
`onClose`	`() => void`	—	点关闭按钮时；不传则请求卡片关闭。
`children`	`ReactNode`	—	放在关闭按钮前面的额外操作。

FloatingBody / FloatingFooter

属性	类型	默认值	说明
`padded`	`boolean`	`true`	是否带内边距。内容自己通栏（列表、表格）时关掉。
`align`	`'start' \| 'end' \| 'between' \| 'stretch'`	`'end'`	按钮的排法：靠左、靠右、两端、等分撑满。