Naive UI Drawer 抽屉组件完全指南:从 Props 到源码实现
Naive UI Drawer 抽屉组件完全指南:从 Props 到源码实现
抽屉(Drawer)是 Naive UI 中与 Modal(对话框)并列的浮层型组件,它从屏幕边缘滑出,常用于承载详情、编辑表单等次级任务。本文以 Drawer 官方中文文档为骨架,结合源码仓库中 Drawer.tsx、DrawerContent.tsx 及全部中文演示用例,系统讲解 n-drawer 与 n-drawer-content 的用法、全部 Props/Slots、主题定制与底层实现原理,帮助你写出可运行、可维护的抽屉交互。
一、Drawer 与 Modal 的定位差异
官方文档开门见山:「我感觉和 Modal 功能差不太多,位置有点差别。」这句话点明了 Drawer 的本质——它和 Modal 一样属于受控的浮层容器,但展示形式截然不同:
- Modal 从屏幕中央弹出,强调「阻断式确认」,适合必须用户回应的场景;
- Drawer 从
top/right/bottom/left四个边缘滑入,默认从右侧(placement默认值为'right'),适合「展示详情 + 就地编辑」这类不需要完全打断主流程的旁路任务。
从源码看,二者在实现上共享了大量基础设施:Drawer 复用了 vdirs 的 zindexable 指令管理层级(Drawer.tsx),使用 VLazyTeleport 进行懒加载传送(Drawer.tsx),并通过 Transition 实现出现/消失动画(Drawer.tsx)。
二、使用前的关键提示
在动手写代码之前,先记住官方文档中唯一的一则警示(index.demo-entry.md):
如果你需要使用
n-drawer-content,n-drawer的native-scrollbar需要保持为true。
这源于组件体系的分工:n-drawer 负责外层容器与滚动策略,n-drawer-content 内部也维护着独立的 native-scrollbar 选项(默认 true)。从 DrawerContent.tsx 可以看到,n-drawer-content 在 native-scrollbar 为 false 时会降级为 NScrollbar 内部滚动组件,此时若外层抽屉再关闭原生滚动,两层滚动策略叠加会产生不可预期的滚动行为。因此最简单稳妥的实践是:外层 n-drawer 保持原生滚动,把自定义滚动需求放在 n-drawer-content 上控制。
三、基础用法:四个方向 + 受控显示
抽屉是典型的受控组件,通过 show / 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')">上</n-button>
<n-button @click="activate('right')">右</n-button>
<n-button @click="activate('bottom')">下</n-button>
<n-button @click="activate('left')">左</n-button>
</n-button-group>
<n-drawer v-model:show="active" :width="502" :placement="placement">
<n-drawer-content title="斯通纳">
《斯通纳》是美国作家约翰·威廉姆斯在 1965 年出版的小说。
</n-drawer-content>
</n-drawer>
</template>
几个要点:
- 组件对:
n-drawer与n-drawer-content必须搭配使用。从源码看,n-drawer-content通过inject(drawerInjectionKey)获取父级上下文,若被放在n-drawer之外,会直接抛出'n-drawer-content' must be placed inside 'n-drawer'.的运行时错误(DrawerContent.tsx)。 - 类型导出:
placement的类型DrawerPlacement可直接从naive-ui导入,可选值为'top' | 'right' | 'bottom' | 'left'。 - 尺寸语义:
width只在left/right方向生效,height只在top/bottom方向生效。该逻辑在源码中由styleWidthRef/styleHeightRef计算属性实现——按placement决定注入width还是height(Drawer.tsx)。
四、多抽屉叠加:嵌套与层级
抽屉天然支持多层叠加。多个抽屉演示展示了「抽屉里再开抽屉」的经典场景:
<template>
<n-button @click="doShowOuter">来一个!</n-button>
<n-drawer v-model:show="showOuter" :width="502">
<n-drawer-content title="斯通纳">
《斯通纳》是美国作家约翰·威廉姆斯在 1965 年出版的小说。
<template #footer>
<n-button @click="doShowInner">再来一个!</n-button>
</template>
</n-drawer-content>
<!-- 内层抽屉嵌套在外层抽屉内部 -->
<n-drawer v-model:show="showInner" :width="251">
<n-drawer-content title="斯通纳">
《斯通纳》是美国作家约翰·威廉姆斯在 1965 年出版的小说。
</n-drawer-content>
</n-drawer>
</n-drawer>
</template>
实现原理上,抽屉容器的层级依赖 zindexable 指令动态计算(Drawer.tsx),每个打开状态的抽屉会自动叠加上层 z-index,无需手动干预。多个抽屉各自维护独立的 show 状态,互不干扰。
五、可关闭:closable 与关闭交互
抽屉默认不显示右上角的关闭按钮(n-drawer-content 的 closable 默认值为 false),需要显式开启。可关闭演示:
<n-drawer v-model:show="show" :width="502">
<n-drawer-content title="斯通纳" closable>
《斯通纳》是美国作家约翰·威廉姆斯在 1965 年出版的小说。
</n-drawer-content>
</n-drawer>
从源码看,关闭按钮的渲染条件是「有 header 插槽、有 title、或 closable 为真」三者之一(DrawerContent.tsx)。点击关闭按钮会调用从父级注入的 doUpdateShow(false)(DrawerContent.tsx),进而触发 on-update:show 事件。
除了按钮,抽屉还支持三种关闭途径(Drawer.tsx):
| 交互 | 触发条件 | 关联 Props |
|---|---|---|
| 点击遮罩 | mask-closable 为 true(默认) |
on-mask-click |
| 按下 Esc | close-on-esc 为 true(默认),且焦点在抽屉内 |
on-esc |
| 点击关闭按钮 | n-drawer-content 的 closable 为 true |
无 |
六、显示在指定区域:to + trap-focus + block-scroll
默认情况下抽屉渲染到 body 下(to 默认值 'body'),但你可以通过 to 把它挂载到页面任意容器中。显示在指定区域演示:
<div id="drawer-target" style="position: relative; width: 100%; height: 300px; overflow: hidden">
显示区域
</div>
<n-drawer
v-model:show="active"
:width="200"
:height="200"
:placement="placement"
:trap-focus="false"
:block-scroll="false"
to="#drawer-target"
>
<n-drawer-content title="斯通纳">
《斯通纳》是美国作家约翰·威廉姆斯在 1965 年出版的小说。
</n-drawer-content>
</n-drawer>
官方文档特别强调:使用 to 自定义显示区域时,记得同时设置 :trap-focus="false" 和 :block-scroll="false"。原因是:
trap-focus(默认true)会把焦点锁定在抽屉内部,若不关闭,抽屉外的内容将无法被聚焦;block-scroll(默认true)会在打开时禁用 body 滚动,若不关闭,即使抽屉只占局部区域,整个页面依然无法滚动。
源码中 to 支持 string | HTMLElement,由 VLazyTeleport 完成懒加载传送(Drawer.tsx),选择器字符串会解析为对应 DOM 节点。
七、自定义头部与底部:插槽体系
n-drawer-content 提供了 header 与 footer 两个插槽,配合 title 属性即可自由排版。自定义头部和底部演示:
<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.tsx 中的 DrawerContentSlots 定义):
| 插槽 | 参数 | 说明 |
|---|---|---|
default |
() |
抽屉主体的内容 |
header |
() |
抽屉主体 header 的内容(优先级高于 title 属性) |
footer |
() |
抽屉主体 footer 的内容 |
注意渲染细节:header 区域只有在「header 插槽、title 属性、closable」三者至少满足其一时才渲染(DrawerContent.tsx),footer 区域则仅在提供 footer 插槽时渲染(DrawerContent.tsx),因此没有头部/底部内容的抽屉会非常干净。
八、滚动内容与原生滚动条
当抽屉内容较长时,滚动是刚需。滚动内容演示展示了标准写法:把 native-scrollbar 设为 false 交由 Naive UI 的自定义 Scrollbar 接管:
<n-drawer v-model:show="show" :width="480">
<n-drawer-content title="Stoner" :native-scrollbar="false">
<!-- 长文本内容 -->
</n-drawer-content>
</n-drawer>
从源码看,n-drawer-content 的 native-scrollbar 为 true(默认)时,主体渲染为普通的 div 结构(drawer-body + drawer-body-content-wrapper 双层);为 false 时则替换为 NScrollbar 组件,并透传 scrollbar-props、body-content-class、body-content-style(DrawerContent.tsx)。Scrollbar 的完整 Props 可参考 Scrollbar 官方文档。
九、可调整宽高的抽屉:resizable
从 2.31.0 版本起,抽屉支持拖拽调整尺寸。可调整宽高演示给出关键配置:
<n-drawer
v-model:show="active"
:default-width="502"
:placement="placement"
resizable
>
<n-drawer-content title="斯通纳">
《斯通纳》是美国作家约翰·威廉姆斯在 1965 年出版的小说。
</n-drawer-content>
</n-drawer>
官方文档明确提示:使用 resizable 时要配合 default-width 或 default-height。原因可以从源码找到:default-width / default-height 的默认值为 251,它们作为内部 uncontrolledWidthRef / uncontrolledHeightRef 的初始值,与受控的 width / height 通过 useMergedState 合并(Drawer.tsx)。拖拽过程中 doUpdateWidth / doUpdateHeight 会同时更新内部状态并触发 on-update:width / on-update:height 事件(Drawer.tsx),实现「非受控也能记住最新尺寸」的体验。
配套的边界控制属性:
| 属性 | 默认值 | 说明 | 版本 |
|---|---|---|---|
min-width / min-height |
undefined |
拖动时的最小宽/高 | 2.35.0 |
max-width / max-height |
undefined |
拖动时的最大宽/高 | 2.35.0 |
十、Drawer Props 全表(含默认值)
以下完整继承自官方文档(index.demo-entry.md),并在源码 Drawer.tsx 中得到逐一印证:
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
auto-focus |
boolean |
true |
是否自动聚焦 Drawer 第一个可聚焦的元素 | 2.24.2 |
block-scroll |
boolean |
true |
是否在打开时禁用 body 滚动 | 2.28.3 |
close-on-esc |
boolean |
true |
是否在按下 Esc 键时关闭 Drawer | 2.24.2 |
content-class |
string |
undefined |
抽屉可滚动内容节点的类名 | 2.37.0 |
content-style |
string | Object |
undefined |
抽屉可滚动内容节点的样式 | — |
default-width |
number | string |
251 |
抽屉的默认宽度,在位置是 left 和 right 时生效 |
2.31.0 |
default-height |
number | string |
251 |
抽屉的默认高度,在位置是 top 和 bottom 时生效 |
2.31.0 |
display-directive |
'if' | 'show' |
'if' |
控制内容是否渲染的指令,'if' 对应 v-if,'show' 对应 v-show |
— |
height |
number | string |
undefined |
抽屉的高度,在位置是 top 和 bottom 时生效 |
— |
mask-closable |
boolean |
true |
点击遮罩时是否发出 update:show 事件 |
— |
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 |
native-scrollbar |
boolean |
true |
是否使用原生滚动 | — |
placement |
'top' | 'right' | 'bottom' | 'left' |
'right' |
抽屉展示的位置 | — |
resizable |
boolean |
false |
抽屉是否可以调整宽度、高度 | 2.31.0 |
scrollbar-props |
ScrollbarProps |
undefined |
属性参考 Scrollbar props | — |
show |
boolean |
false |
是否展示抽屉 | — |
show-mask |
boolean | 'transparent' |
true |
是否显示遮罩;设为 'transparent' 展示透明遮罩,设为 false 会禁用 trap-focus |
2.28.3 |
to |
string | HTMLElement |
'body' |
抽屉出现的区域 | — |
trap-focus |
boolean |
true |
是否将焦点锁定在 Drawer 内部 | 2.24.2 |
width |
number | string |
undefined |
抽屉的宽度,在位置是 left 和 right 时生效 |
— |
z-index |
number |
undefined |
抽屉的 z-index | 2.24.0 |
on-after-enter |
() => void |
undefined |
Drawer 出现后的回调 | 2.28.0 |
on-after-leave |
() => void |
undefined |
Drawer 关闭后的回调 | 2.28.0 |
on-esc |
() => void |
undefined |
焦点在 Drawer 内部时按下 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 |
几个需要额外解读的属性:
show-mask:三态属性。true显示遮罩;'transparent'显示透明遮罩(点击仍可关闭,但视觉上不遮挡背景);false完全隐藏遮罩,此时按文档说明会禁用trap-focus(因为没有遮罩承接点击关闭与焦点管理)。源码中'transparent'会追加drawer-mask--invisible类(Drawer.tsx)。display-directive:'if'走v-if语义(彻底销毁/创建 DOM),'show'走v-show语义(保留 DOM 仅切换显隐)。后者在需要保持抽屉内部状态(如表单输入)时更友好。z-index:不设置时由zindexable指令根据当前打开浮层自动计算,设置了则优先使用指定值。
十一、DrawerContent Props 全表
n-drawer-content 是抽屉的「骨架三件套」:header(标题区)、body(内容区)、footer(底部区),对应的 Props 完整继承自官方文档(index.demo-entry.md),与源码 DrawerContent.tsx 完全一致:
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
body-class |
string |
undefined |
主体 body 的类名 | 2.37.0 |
body-style |
string | Object |
undefined |
主体 body 的样式 | — |
body-content-class |
string |
undefined |
主体可滚动内容节点的类名 | 2.37.0 |
body-content-style |
string | Object |
undefined |
主体可滚动内容节点的样式 | — |
closable |
boolean |
false |
是否可关闭(显示右上角关闭按钮) | — |
footer-class |
string |
undefined |
主体 footer 的类名 | 2.37.0 |
footer-style |
string | Object |
undefined |
主体 footer 的样式 | — |
header-class |
string |
undefined |
主体 header 的类名 | 2.37.0 |
header-style |
string | Object |
undefined |
主体 header 的样式 | — |
native-scrollbar |
boolean |
true |
主体部分是否使用原生滚动条 | — |
scrollbar-props |
ScrollbarProps |
undefined |
属性参考 Scrollbar props | — |
title |
string |
undefined |
主体的标题 | — |
title 直接渲染在 header 主区域并带有 aria-level="1" 的标题语义(DrawerContent.tsx),配合 role="heading" 保证了基础的无障碍可读性。
十二、主题定制:从 CSS 变量到 Theme Overrides
抽屉与 Naive UI 其他组件一样支持两层主题定制。主题变量定义在 light.ts,常用可覆盖项如下:
| 变量 | 默认值(light) | 作用 |
|---|---|---|
bodyPadding |
16px 24px |
内容区内边距 |
headerPadding |
16px 24px |
头部区内边距 |
footerPadding |
16px 24px |
底部区内边距 |
color |
modalColor(跟随主题) |
抽屉背景色 |
textColor |
textColor2 |
正文文本色 |
titleTextColor |
textColor1 |
标题文本色 |
titleFontSize |
18px |
标题字号 |
titleFontWeight |
fontWeightStrong |
标题字重 |
boxShadow |
boxShadow3 |
抽屉投影 |
borderRadius |
主题圆角 | 抽屉圆角 |
headerBorderBottom |
1px solid ${dividerColor} |
头部下边框 |
footerBorderTop |
1px solid ${dividerColor} |
底部上边框 |
resizableTriggerColorHover |
primaryColorHover |
拖拽手柄 hover 颜色 |
主题通过 useTheme 挂载(Drawer.tsx),并在 index.cssr.ts 中映射为 --n-* CSS 变量,例如 --n-header-padding、--n-color、--n-box-shadow(Drawer.tsx)。这意味着除了官方 Theme Overrides,你还可以直接用 style 覆盖抽屉容器上的 --n-* 变量做局部微调。暗色主题由 dark.ts 基于同一变量体系派生,深浅色切换无需额外处理。
十三、无障碍与焦点管理
Drawer 在无障碍方面内置了完整支持,这正是「a11y-debug」演示存在的意义:
auto-focus(默认true):打开后自动聚焦第一个可聚焦元素;trap-focus(默认true):将 Tab 焦点循环锁定在抽屉内部,避免焦点逃逸到背景页面;close-on-esc(默认true)+on-esc:键盘用户可随时按 Esc 关闭,并可通过on-esc钩子介入;on-after-enter/on-after-leave:动画结束后的生命周期回调,适合做焦点归位或数据刷新等收尾逻辑。
源码中 Esc 处理还特别排除了输入法组词状态(useIsComposing,见 Drawer.tsx),避免中文输入法选词时误关抽屉——这是实际项目中很容易踩的坑,Naive UI 已内置规避。
十四、已废弃的旧属性
从源码 Drawer.tsx 可以看到一组带 @deprecated 标记的兼容属性,开发时请优先使用新写法:
| 旧属性 | 替代写法 |
|---|---|
drawer-style |
直接使用 style |
drawer-class |
直接使用 class |
target |
to |
on-show |
on-update:show |
on-hide |
on-update:show |
在开发环境下,一旦使用这些旧属性,控制台会输出一次性的 warnOnce 弃用警告(Drawer.tsx),帮助平滑迁移。
十五、测试与验证
仓库为 Drawer 提供了完整的测试保障(Drawer.spec.tsx),覆盖显示状态切换、placement 方向渲染等核心行为;同时 server.spec.tsx 专门验证 SSR(服务端渲染)场景下的稳定性——抽屉这类依赖浏览器 DOM 与传送(teleport)的组件,在服务端环境最容易出问题,该测试保证了它同样适用于 Nuxt 等 SSR 框架。
总结
Drawer 在 Naive UI 中是「与 Modal 互补」的浮层组件:默认从右侧滑入、受控显隐、支持四方向与多抽屉嵌套;n-drawer 负责容器、遮罩、焦点与尺寸控制,n-drawer-content 负责 header / body / footer 三区结构与滚动策略,二者通过注入机制(drawerInjectionKey)协作。配合 resizable 拖拽、to 局部挂载、native-scrollbar 切换与 --n-* 主题变量,可以覆盖从轻量详情到复杂编辑面板的绝大多数旁路任务场景。文中所有 Props 均可在 官方中文文档 与 Drawer.tsx 中交叉核验,直接按第十节、第十一节表格组合使用即可投入生产。