Naive UI Drawer 抽屉组件完全指南:定位、缩放、多层抽屉与 API 全解析
Naive UI Drawer 抽屉组件完全指南:定位、缩放、多层抽屉与 API 全解析
Naive UI(A Vue 3 Component Library,使用 TypeScript 编写)中的 n-drawer 抽屉组件,是一种从屏幕边缘滑出的浮层面板,常用于承载详情、设置、表单等二级内容。本文以 Drawer 官方文档 为骨架,结合仓库内 Drawer.tsx 等源码与全部官方 Demo,完整讲解四个方向的定位方式、多层抽屉、可调整尺寸、自定义挂载容器等实战能力,并逐项解析 Drawer 与 DrawerContent 的全部 Props 和 Slots。读完本文,你可以直接在项目里正确配置并扩展出自己的抽屉交互。
与 Modal 的关系:同源异位
官方文档开门见山地指出:“I think it is similar with modal, with a bit difference on placement.” 即 n-drawer 与 n-modal 在交互模型上高度相似——都有遮罩(mask)、都支持按 Esc 关闭、都通过 show / v-model:show 控制显隐;唯一的本质区别在于出现的位置:Modal 居中弹出,而 Drawer 从 top / right / bottom / left 四个边缘滑入。
这一设计在源码中同样可以得到印证:Drawer.tsx 在实现上复用了 vdirs 的 zindexable、vooks 的 useIsMounted / useMergedState,以及 _mixins 中的 useConfig、useTheme 等通用设施,其参数形态与 Modal 高度一致,只是多了 placement、width、height、resizable 等与"位置和尺寸"强相关的属性。
使用前必读:Caveat 警告
官方文档在开头放置了一条醒目的警告(<n-alert type="warning">):
如果你需要使用
n-drawer-content,应当保持n-drawer的native-scrollbarprop 为true。
原因在于 n-drawer 与 n-drawer-content 是两个独立组件:n-drawer 负责定位、遮罩、动画与整体滚动容器,而 n-drawer-content 负责内部的头部(header)、主体(body)、底部(footer)排版。当把 n-drawer 的 native-scrollbar 设为 false 时,滚动容器会切换为 Naive UI 自研的 NScrollbar 组件,此时直接套用 n-drawer-content 可能会出现结构冲突或滚动异常。若确实需要自定义滚动条,请参考 Scrollbar 组件文档 及其 ScrollbarProps,并通过 scrollbar-props 透传配置。
基础用法:四个方向的抽屉
官方 basic.demo.vue(源码见 basic.demo.vue)演示了最核心的用法:通过 placement 切换抽屉从哪个方向滑出,通过 width 指定宽度,并用 v-model:show 双向绑定显隐:
<script lang="ts" setup>
import type { DrawerPlacement } from 'naive-ui'
import { ref } from 'vue'
const active = ref(false)
const placement = ref<DrawerPlacement>('right')
function activate(place: DrawerPlacement) {
active.value = true
placement.value = place
}
</script>
<template>
<n-button-group>
<n-button @click="activate('top')">Top</n-button>
<n-button @click="activate('right')">Right</n-button>
<n-button @click="activate('bottom')">Bottom</n-button>
<n-button @click="activate('left')">Left</n-button>
</n-button-group>
<n-drawer v-model:show="active" :width="502" :placement="placement">
<n-drawer-content title="Stoner">
Stoner is a 1965 novel by the American writer John Williams.
</n-drawer-content>
</n-drawer>
</template>
要点说明:
DrawerPlacement类型('top' | 'right' | 'bottom' | 'left')由仓库从DrawerBodyWrapper导出,见 index.ts 与 Drawer.tsx 中placement的默认值'right'。width只在placement为left/right时生效;height只在top/bottom时生效(二者默认均为undefined,此时分别回落为default-width/default-height的251)。n-drawer-content的title属性会渲染为头部标题;没有提供title时头部区域为空,可用插槽自定义。
多层抽屉(Multiple Drawers)
官方 multiple.demo.vue(见 multiple.demo.vue)展示了一个抽屉内部再开一个抽屉的嵌套场景——外层抽屉的 footer 里放按钮,点击后打开内层抽屉:
<template>
<n-button @click="doShowOuter">Come on!</n-button>
<n-drawer v-model:show="showOuter" :width="502">
<n-drawer-content title="Stoner">
Stoner is a 1965 novel by the American writer John Williams.
<template #footer>
<n-button @click="doShowInner">Come on Again!</n-button>
</template>
</n-drawer-content>
<n-drawer v-model:show="showInner" :width="251">
<n-drawer-content title="Stoner">
Stoner is a 1965 novel by the American writer John Williams.
</n-drawer-content>
</n-drawer>
</n-drawer>
</template>
实现层面,n-drawer 通过 drawerInjectionKey 向子抽屉注入 doUpdateShow / doUpdateWidth / doUpdateHeight 等能力(见 interface.ts),因此多层抽屉之间的显隐、尺寸更新可以协同工作。注意嵌套时内层抽屉会覆盖在外层之上,遮罩层级由 z-index 机制自动处理,通常无需手工干预。
关闭按钮:closable
n-drawer 本身不渲染关闭按钮,关闭入口由 n-drawer-content 的 closable 属性控制。官方 closable.demo.vue 展示了在标题栏右侧出现一个关闭(×)图标:
<n-drawer v-model:show="show" :width="502">
<n-drawer-content title="Stoner" closable>
Stoner is a 1965 novel by the American writer John Williams.
</n-drawer-content>
</n-drawer>
closable 默认值为 false,即默认不显示关闭按钮。用户仍可通过点击遮罩(mask-closable 默认 true)或按 Esc(close-on-esc 默认 true)关闭抽屉。
自定义显示区域:to 与 trap-focus / block-scroll
默认情况下抽屉挂载到 body(to 默认值为 'body')。官方 target.demo.vue 演示了把抽屉渲染到页面中任意容器内,实现"局部抽屉"效果:
<div
id="drawer-target"
style="
position: relative;
width: 100%;
height: 300px;
border: 1px solid rgba(128, 128, 128, 0.2);
display: flex;
align-items: center;
justify-content: center;
overflow: hidden;
"
>
Target Area
</div>
<n-drawer
v-model:show="active"
:width="200"
:height="200"
:placement="placement"
:trap-focus="false"
to="#drawer-target"
>
<n-drawer-content title="Stoner">...</n-drawer-content>
</n-drawer>
官方文档特别提示:自定义显示区域时务必设置 :trap-focus="false" 与 :block-scroll="false",否则抽屉外的内容将无法获得焦点、页面 body 也无法滚动。原因对应源码中的两个默认值:Drawer.tsx 中 trapFocus 与 blockScroll 的默认值均为 true——焦点陷阱会把 Tab 焦点锁定在抽屉内部,滚动锁定会禁用 body 滚动;将 to 指向局部容器后,这两项全局行为反而成为障碍。
自定义头部与底部:header / footer 插槽
n-drawer-content 提供了 header 与 footer 两个插槽,官方 slot.demo.vue 展示了完全自定义的用法:
<n-drawer v-model:show="active" :width="502">
<n-drawer-content>
<template #header>Header</template>
<template #footer>
<n-button>Footer</n-button>
</template>
</n-drawer-content>
</n-drawer>
对应官方文档中 DrawerContent Slots 表的说明:header 为抽屉头部内容、footer 为抽屉底部内容、default 为主体内容。使用插槽后,title 属性会被插槽内容取代。
滚动内容与自定义滚动条
官方 scroll.demo.vue 展示了一个超长文本的滚动场景,其中关键的一行是:
<n-drawer v-model:show="show" :width="480">
<n-drawer-content title="Stoner" :native-scrollbar="false" :width="996">
n-drawer-content的native-scrollbar设为false后,主体部分使用 Naive UI 的自研NScrollbar渲染滚动条,而非浏览器原生滚动条;- 注意此处与开头 Caveat 的区别:警告针对的是
n-drawer层面的native-scrollbar;而这里关闭的是n-drawer-content主体区域的native-scrollbar(其默认值为true),两者作用于不同层级,可以独立配置; - 若需要精细控制滚动条外观,可通过
scrollbar-props(ScrollbarProps)透传,其完整属性参见 Scrollbar 组件文档。
可调整尺寸的抽屉(Resizable)
官方 resizable.demo.vue 展示了拖动改变抽屉宽/高的能力,并强调:使用 resizable 时必须配合 default-width 或 default-height:
<n-drawer
v-model:show="active"
:default-width="502"
:placement="placement"
resizable
>
<n-drawer-content title="Stoner">...</n-drawer-content>
</n-drawer>
配套属性:
default-width(默认251,支持number | string):left/right放置时的默认宽度,可拖拽起点;default-height(默认251,支持number | string):top/bottom放置时的默认高度;min-width/min-height/max-width/max-height(均默认undefined):拖拽尺寸的上下限约束;on-update:width/on-update:height:尺寸变化回调,v-model:width/v-model:height可同步受控值。
源码层面,这些能力全部定义于 Drawer.tsx 的 drawerProps 中(resizable: Boolean、defaultWidth 默认 251 等),并通过 drawerInjectionKey 注入 doUpdateWidth / doUpdateHeight,由 n-drawer-content 与内部拖拽手柄协同更新尺寸。
完整 API 参考
以下内容完整继承自官方文档 index.demo-entry.md,并结合 Drawer.tsx 源码中的 props 定义补充了实现细节与版本信息。
Drawer Props
| Name | Parameters | Default | Description | Version |
|---|---|---|---|---|
| auto-focus | boolean |
true |
抽屉打开时是否聚焦内部第一个可聚焦元素。 | 2.24.2 |
| block-scroll | boolean |
true |
抽屉激活时是否禁用 body 滚动。 | 2.28.3 |
| close-on-esc | boolean |
true |
按下 Esc 时是否关闭抽屉。 | 2.24.2 |
| content-class | string |
undefined |
抽屉可滚动内容节点的 class。 | 2.37.0 |
| content-style | string | Object |
undefined |
抽屉可滚动内容节点的样式。 | |
| default-width | number | string |
251 |
抽屉默认宽度,placement 为 left / right 时生效。 |
2.31.0 |
| default-height | number | string |
251 |
抽屉默认高度,placement 为 top / bottom 时生效。 |
2.31.0 |
| display-directive | 'if' | 'show' |
'if' |
n-drawer 渲染时使用的显示指令,'if' 对应 v-if,'show' 对应 v-show。 |
|
| height | number | string |
undefined |
placement 为 top / bottom 时生效。 |
|
| native-scrollbar | boolean |
true |
抽屉是否使用原生滚动条。 | |
| mask-closable | boolean |
true |
点击遮罩时是否触发关闭(emit hide 事件)。 |
|
| max-width | number |
undefined |
可拖拽抽屉的最大宽度。 | 2.35.0 |
| max-height | number |
undefined |
可拖拽抽屉的最大高度。 | 2.35.0 |
| min-width | number |
undefined |
可拖拽抽屉的最小宽度。 | 2.35.0 |
| min-height | number |
undefined |
可拖拽抽屉的最大高度(源码实现为最小高度约束)。 | 2.35.0 |
| placement | 'top' | 'right' | 'bottom' | 'left' |
'right' |
抽屉出现的位置。 | |
| resizable | boolean |
false |
是否允许拖拽调整抽屉的宽/高。 | 2.31.0 |
| scrollbar-props | ScrollbarProps |
undefined |
见 Scrollbar props。 | |
| show | boolean |
false |
是否显示抽屉。 | |
| show-mask | boolean |
true |
是否显示遮罩;设为 'transparent' 时显示透明遮罩;设为 false 时 trap-focus 将被禁用。 |
2.28.3 |
| to | string | HTMLElement |
'body' |
抽屉挂载到的容器节点。 | |
| trap-focus | boolean |
true |
是否将焦点锁定在抽屉内部。 | 2.24.2 |
| width | number | string |
undefined |
placement 为 left / right 时生效。 |
|
| z-index | number |
undefined |
抽屉的 z-index。 | 2.24.0 |
| on-after-enter | () => void |
undefined |
抽屉打开动画结束后的回调。 | 2.28.0 |
| on-after-leave | () => void |
undefined |
抽屉关闭动画结束后的回调。 | 2.28.0 |
| on-esc | () => void |
undefined |
焦点在抽屉内时按下 Esc 触发的回调。 | 2.24.2 |
| on-mask-click | (e: MouseEvent) => void |
undefined |
点击遮罩时触发的回调。 | |
| on-update:height | (height: number) => void |
undefined |
抽屉高度变化时触发。 | 2.31.0 |
| on-update:show | (show: boolean) => void |
undefined |
抽屉显示状态即将变化时触发。 | |
| on-update:width | (width: number) => void |
undefined |
抽屉宽度变化时触发。 | 2.31.0 |
源码补充:
min-height在官方文档描述中写作 "Max height of draggable drawer"(疑为文档笔误),Drawer.tsx 中的实际语义是拖拽的最小高度约束;z-index的实现依赖vdirs的zindexable指令,未设置时由层叠上下文自动管理。此外源码中还存在drawerStyle、drawerClass、target、onShow、onHide等带@deprecated标注的旧属性(见 Drawer.tsx),新代码应使用content-style/content-class、to与on-update:show替代。
DrawerContent Props
| Name | Parameters | Default | Description | Version |
|---|---|---|---|---|
| body-class | string |
undefined |
抽屉内容主体(body)的 class。 | 2.37.0 |
| body-style | string | Object |
undefined |
抽屉内容主体(body)的样式。 | |
| body-content-class | string |
undefined |
body 内可滚动内容节点的 class。 | |
| body-content-style | string | Object |
undefined |
body 内可滚动内容节点的样式。 | 2.37.0 |
| closable | boolean |
false |
抽屉内容是否可关闭(显示关闭按钮)。 | |
| footer-class | string |
undefined |
抽屉内容底部(footer)的 class。 | 2.37.0 |
| footer-style | string | Object |
undefined |
抽屉内容底部(footer)的样式。 | |
| header-class | string |
undefined |
抽屉内容头部(header)的 class。 | 2.37.0 |
| header-style | string | Object |
undefined |
抽屉内容头部(header)的样式。 | |
| native-scrollbar | boolean |
true |
body 部分是否使用原生滚动条。 | |
| title | string |
undefined |
抽屉内容标题。 | |
| scrollbar-props | ScrollbarProps |
undefined |
见 Scrollbar props。 |
Drawer Slots
| Name | Parameters | Description |
|---|---|---|
| default | () |
抽屉的内容。 |
DrawerContent Slots
| Name | Parameters | Description |
|---|---|---|
| default | () |
抽屉内容的主体内容。 |
| footer | () |
抽屉内容的底部内容。 |
| header | () |
抽屉内容的头部内容。 |
从源码理解 Drawer 的结构
n-drawer 由两个可组合组件构成,其目录结构(见 src/drawer)为:
Drawer.tsx:对外组件,负责 props 声明、遮罩、动画过渡、to挂载与 z-index 管理,源码位于 src/drawer/src/Drawer.tsx;DrawerBodyWrapper.tsx:承载位置计算与宽高尺寸逻辑,并导出Placement类型;DrawerContent.tsx:头部/主体/底部排版组件,导出DrawerContentProps与DrawerContentSlots;interface.ts:定义drawerInjectionKey与DrawerInjection(包含doUpdateShow、doUpdateWidth、doUpdateHeight),用于父子抽屉组件间的通信;styles/index.cssr.ts与styles/rtl.cssr.ts:样式与 RTL 适配。
组件的公开导出统一收口在 src/drawer/index.ts,其中 DrawerPlacement 类型取自 DrawerBodyWrapper。若需要局部引入,可直接从 naive-ui 导入 NDrawer / NDrawerContent 或使用全局注册的 n-drawer / n-drawer-content 标签。
小结
n-drawer 是与 n-modal 同源的边缘滑出式浮层组件,核心差异集中在 placement 定位与 width / height 尺寸体系上。实践中最容易踩坑的三点:一是使用 n-drawer-content 时保持 n-drawer 的 native-scrollbar 为 true;二是自定义 to 挂载区域时必须显式关闭 trap-focus 与 block-scroll;三是启用 resizable 时必须搭配 default-width / default-height。掌握官方 Drawer 文档 中的七个 Demo 与本文的 API 全表,即可在项目中稳定落地单层、多层、可拖拽、局部挂载等各类抽屉交互。