Naive UI Drawer 抽屉组件完全指南:从 Props 到源码实现

原创2026-09-20 21:38:102,230 阅读
文章标签:前端UI组件设计系统

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>

几个要点:

  1. 组件对:n-drawer 与 n-drawer-content 必须搭配使用。从源码看,n-drawer-content 通过 inject(drawerInjectionKey) 获取父级上下文,若被放在 n-drawer 之外,会直接抛出 'n-drawer-content' must be placed inside 'n-drawer'. 的运行时错误(DrawerContent.tsx)。
  2. 类型导出:placement 的类型 DrawerPlacement 可直接从 naive-ui 导入,可选值为 'top' | 'right' | 'bottom' | 'left'。
  3. 尺寸语义: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 中交叉核验,直接按第十节、第十一节表格组合使用即可投入生产。

登录后查看全文
naive-ui