Drawer 抽屉
有时 Dialog 并不能完全满足我们的需求,比如你有一个复杂的表单,或者你需要展示类似服务条款之类的内容,Drawer 拥有与 Dialog 几乎相同的 API,但它带来了不同的用户体验。
提示
由于所有组件都原生支持 v-model,因此 visible.sync 已被废弃,请使用 v-model="visibilityBinding" 来控制当前抽屉的可见性。
基础用法
从多个方向呼出一个临时抽屉
你必须像 Dialog 一样为 Drawer 设置 model-value,它是 boolean 类型,用来控制 Drawer 本身的可见性。Drawer 分为三个部分:title、body 和 footer。title 是一个具名插槽,你也可以通过名为 title 的属性来设置标题,默认为空字符串。body 部分是 Drawer 的主体区域,包含用户定义的内容。打开时,Drawer 默认从**右侧向左**展开,其大小为浏览器窗口的 **30%**。你可以通过设置 direction 和 size 属性来更改这一默认行为。此示例还演示了如何使用 before-close API,有关更多详细信息,请查看属性部分。
不显示标题
当你不再需要标题时,可以将其从抽屉中移除。
将 withHeader 属性设置为 **false**,即可从抽屉中移除标题,从而使抽屉在屏幕上拥有更多空间。如果你希望符合无障碍标准,请务必设置 title 属性。
自定义内容
与 Dialog 一样,Drawer 也可用于显示多种多样的交互内容。
自定义页头
header 插槽可用于自定义标题显示的区域。为了保持无障碍访问,在使用此插槽的同时,请另外使用 title 属性,或者使用 titleId 插槽属性来指定哪个元素应被作为抽屉标题朗读。
可伸缩抽屉 2.11.0
尝试拖动边缘部分。
将 resizable 设置为 true 即可进行伸缩。
多层嵌套
你也可以像 Dialog 一样拥有多层嵌套的 Drawer。
如果你需要在不同层级使用多个 Drawer,则必须将 append-to-body 属性设置为 **true**。
遮罩层
将 modal 设置为 false 将隐藏抽屉的遮罩(叠加层)。
从版本 2.11.7 开始,增加了 modal-penetrable 属性,可以使遮罩层可穿透。
提示
Drawer 内部的内容应该是懒加载的,这意味着 Drawer 内部的内容不会影响初始渲染性能,因此任何 DOM 操作都应通过 ref 或在触发 open 事件后执行。
提示
Drawer 提供了一个名为 destroy-on-close 的 API,它是一个标志变量,指示在 Drawer 关闭后是否应销毁其中的子内容。当你需要每次打开 Drawer 时都调用 mounted 生命周期钩子时,可以使用此 API。
API
属性
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 是否显示抽屉 | boolean | false |
| 插入至 body | 控制 Drawer 是否应插入至 DocumentBody 元素中,嵌套的 Drawer 必须将此参数分配为 **true** | boolean | false |
| 插入至 2.8.0 | Drawer 附加到的元素。将覆盖 append-to-body | CSSSelector / HTMLElement | body |
| 锁定滚动 | 显示 Drawer 时是否禁用 body 的滚动 | boolean | true |
| 关闭前的回调 | 如果设置,关闭流程将被中止 | Function | — |
| 点击遮罩关闭 | 是否可以通过点击遮罩层关闭 Drawer | boolean | true |
| close-on-press-escape | 指示是否可以通过按 ESC 键关闭 Drawer | boolean | true |
| 延迟打开 | 打开前的延迟时间(毫秒) | number | 0 |
| 延迟关闭 | 关闭前的延迟时间(毫秒) | number | 0 |
| 关闭时销毁 | 指示 Drawer 关闭后是否应销毁子元素 | boolean | false |
| 遮罩层 | 是否显示遮罩层 | boolean | true |
| 遮罩穿透 2.11.7 | 遮罩是否可穿透。modal 属性必须为 false。 | boolean | false |
| direction | Drawer 打开的方向 | 枚举 | 从右到左 (rtl) |
| 可伸缩 2.11.0 | 启用 Drawer 的可伸缩功能 | boolean | false |
| show-close | 是否在 Drawer 右上角显示关闭按钮 | boolean | true |
| size | Drawer 的大小。如果 Drawer 是水平模式,它会影响 width 属性;否则会影响 height 属性。当 size 为 number 类型时,它以像素为单位描述大小;当 size 为 string 类型时,它应与 x% 记法一起使用,否则将被解释为像素单位。 | number / string | 30% |
| title | Drawer 的标题,也可以通过具名插槽设置,详细描述可以在插槽表格中找到 | string | — |
| 带页头 | 控制页头部分是否存在的标志,默认为 true。当 withHeader 设置为 false 时,title 属性和 title 插槽都将失效 | boolean | true |
| 遮罩层类名 | 遮罩层的额外类名 | string | — |
| 页头类名 2.9.3 | 页头包装器的自定义类名 | string | — |
| 主体类名 2.9.3 | 主体包装器的自定义类名 | string | — |
| 页脚类名 2.9.3 | 页脚包装器的自定义类名 | string | — |
| z-index | 设置 z-index | number | — |
| 页头 ARIA 层级 a11y | 页头的 aria-level 属性 | string | 2 |
| 自定义类名 已废弃 | Drawer 的额外类名 | string | — |
警告
custom-class 已 **废弃**,并将于 2.3.0 中 **移除**,请使用 class。
事件
| 名称 | 描述 | 类型 |
|---|---|---|
| open | Drawer 打开动画开始前触发 | Function |
| 已打开 | Drawer 打开动画结束后触发 | Function |
| 关闭 | Drawer 关闭动画开始前触发 | Function |
| 已关闭 | Drawer 关闭动画结束后触发 | Function |
| 打开自动聚焦 | Drawer 打开且内容聚焦后触发 | Function |
| 关闭自动聚焦 | Drawer 关闭且内容聚焦后触发 | Function |
| 开始伸缩 2.11.8 | 开始伸缩时触发(启用 resizable 时) | Function |
| 伸缩中 2.11.8 | 伸缩过程中触发(启用 resizable 时) | Function |
| 结束伸缩 2.11.8 | 结束伸缩时触发(启用 resizable 时) | Function |
插槽
| 名称 | 描述 |
|---|---|
| default | Drawer 的内容 |
| header | Drawer 页头部分;替换此处会移除标题,但不会移除关闭按钮。 |
| footer | Drawer 页脚部分 |
| 标题 已废弃 | 功能与 header 插槽相同。请改用 header。 |
警告
title 已 **废弃**,并将于 3.0.0 中 **移除**,请使用 header。
暴露
| 名称 | 描述 |
|---|---|
| handleClose | 为了关闭 Drawer,此方法将调用 before-close。 |