Drawer 抽屉
从屏幕侧边滑入的浮层,承载较多详情或表单。相比 Modal,Drawer 不打断当前页面纵深,更适合"补充信息"场景。
基本使用
通过 v-model:visible 控制开合;默认从右侧滑入。
四个方向
placement 可选 right / left / top / bottom。
自定义尺寸
size 接受数字(px)或字符串(带单位)。横向 placement 控制 width,纵向控制 height。
自定义底部按钮
带操作的抽屉常需要底部按钮区。用 #footer slot 自定义即可。
关闭行为
mask-closable 控制点遮罩关;close-on-esc 控制 Esc 键关;都设为 false 时只能用 × 或外部代码关。
销毁内部 DOM
destroy-on-close 让抽屉关闭后清空内部内容(重置内嵌组件状态)。
API
Props
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| visible | boolean | false | 是否显示(支持 v-model:visible) |
| title | string | '' | 标题 |
| placement | DrawerPlacement | 'right' | 弹出方向:left / right / top / bottom |
| size | number | string | 378 | 横向时为宽,纵向时为高(数字按 px,字符串按原值) |
| closable | boolean | { closeIcon?: VNode | string; disabled?: boolean; ariaLabel?: string } | true | 关闭按钮配置;对象形支持自定义图标 / 禁用 / aria-label |
| maskClosable | boolean | true | 点遮罩是否关闭 |
| closeOnEsc | boolean | true | Esc 键是否关闭 |
| mask | boolean | true | 是否显示遮罩 |
| loading | boolean | false | 加载状态:渲染 3 行骨架占位 + aria-busy="true",body 区被替换 |
| footer | string | VNode | null | undefined | -- | 底部内容(null 隐藏;string/VNode 直接渲染;undefined 启用 slot) |
| destroyOnClose | boolean | false | 关闭后销毁内部 DOM |
| keepAlive | boolean | false | 即使未打开也保留 DOM(与 destroyOnClose 互斥) |
| focusTriggerAfterClose | boolean | true | 关闭后聚焦回打开前的触发元素 |
| push | boolean | { distance?: number } | false | 嵌套抽屉时让位距离;父抽屉设 push=false 表示不让位 |
| zIndex | number | 1000 | 层级 |
| appendToBody | boolean | true | 是否把浮层 Teleport 到 document.body |
Events
| 事件名 | 回调签名 | 触发时机 |
|---|---|---|
| update:visible | (visible: boolean) | 显示状态变化(v-model:visible) |
| after-open-change | (open: boolean) | 打开 / 关闭动画完成后触发(immediate watch,首次 false) |
| open | () | 开启动画开始 |
| opened | () | 开启动画结束 |
| close | () | 关闭被触发 |
| closed | () | 关闭动画结束 |
Slots
| 名称 | 说明 |
|---|---|
| default | 抽屉主体内容 |
| title | 自定义标题(覆盖 title 属性) |
| footer | 自定义底部内容(优先级高于 footer prop) |
| extra | 标题右侧操作区(与 title 同行,inline-flex) |
| close-icon | 自定义关闭图标(优先级高于 closable.closeIcon) |