Naive UI Drawer 抽屉组件完全指南:定位、缩放、多层抽屉与 API 全解析

原创2026-09-20 12:29:351,955 阅读
文章标签:前端UI组件设计系统

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-scrollbar prop 为 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 全表,即可在项目中稳定落地单层、多层、可拖拽、局部挂载等各类抽屉交互。

登录后查看全文
naive-ui