Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Drawer 抽屉
从屏幕一侧滑出的面板,用来放详情、表单、设置这类内容比较多、又不想跳转页面的东西。内容很少、只是确认一下时用 Modal。
引入
import { NsDrawer } from '@ns/ui'
基础用法
用 v-model 控制显示,title 是标题,内容放在默认插槽里。默认从右侧滑出,点右上角的 ×、点遮罩或按 Esc 都可以关闭。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDrawer, NsButton } from '@ns/ui'
const visible = ref(false)
</script>
<template>
<NsButton type="primary" @click="visible = true">打开抽屉</NsButton>
<NsDrawer v-model="visible" title="抽屉标题">
<p>这是抽屉的内容。</p>
</NsDrawer>
</template>
方向
direction 决定从哪一侧滑出:rtl 右侧(默认)、ltr 左侧、ttb 顶部、btt 底部。点下面的按钮从对应的一侧打开:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsDrawer, NsSpace } from '@ns/ui'
import type { DrawerDirection } from '@ns/ui'
const visible = ref(false)
const direction = ref<DrawerDirection>('rtl')
const open = (value: DrawerDirection) => {
direction.value = value
visible.value = true
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="open('rtl')">右侧(rtl,默认)</NsButton>
<NsButton @click="open('ltr')">左侧(ltr)</NsButton>
<NsButton @click="open('ttb')">顶部(ttb)</NsButton>
<NsButton @click="open('btt')">底部(btt)</NsButton>
</NsSpace>
<NsDrawer v-model="visible" :title="`direction:${direction}`" :direction="direction">
<p>从 {{ direction }} 方向滑出。</p>
</NsDrawer>
</template>
尺寸
size 默认 30%。左右方向的抽屉是宽度,上下方向的抽屉是高度。可以传数字(按 px 处理)或带单位的字符串。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsDrawer, NsSpace } from '@ns/ui'
import type { DrawerDirection } from '@ns/ui'
const visible = ref(false)
const size = ref<string | number>('30%')
const direction = ref<DrawerDirection>('rtl')
const open = (value: string | number, dir: DrawerDirection = 'rtl') => {
size.value = value
direction.value = dir
visible.value = true
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">宽度</span>
<NsButton @click="open(240)">数字 240(按 px)</NsButton>
<NsButton @click="open('30%')">30%(默认)</NsButton>
<NsButton @click="open('50%')">50%</NsButton>
<NsButton @click="open('480px')">480px</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">高度</span>
<NsButton @click="open(200, 'btt')">底部 200px</NsButton>
<NsButton @click="open('30%', 'btt')">底部 30%(默认)</NsButton>
<NsButton @click="open('50%', 'ttb')">顶部 50%</NsButton>
</NsSpace>
</NsSpace>
<NsDrawer v-model="visible" :title="`size:${size}`" :size="size" :direction="direction">
<p>左右方向的 size 是宽度,上下方向的 size 是高度。</p>
</NsDrawer>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 40px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
底部按钮
footer 插槽的内容固定在抽屉底部,靠右排列。内容区比较长时只有内容区滚动,头部和底部不动。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsDrawer, NsMessage } from '@ns/ui'
const visible = ref(false)
const save = () => {
visible.value = false
NsMessage.success('已保存')
}
</script>
<template>
<NsButton @click="visible = true">编辑资料</NsButton>
<NsDrawer v-model="visible" title="编辑资料" size="360px">
<p v-for="i in 30" :key="i">第 {{ i }} 行表单内容</p>
<template #footer>
<NsButton @click="visible = false">取消</NsButton>
<NsButton type="primary" @click="save">保存</NsButton>
</template>
</NsDrawer>
</template>
自定义头部和不显示头部
header 插槽替换标题,右上角的关闭按钮还在。with-header 设为 false 时整个头部(标题和关闭按钮)都不显示。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsDrawer, NsIcon, NsSpace } from '@ns/ui'
const a = ref(false)
const b = ref(false)
</script>
<template>
<NsSpace wrap>
<NsButton @click="a = true">自定义头部</NsButton>
<NsButton @click="b = true">不显示头部(with-header=false)</NsButton>
</NsSpace>
<NsDrawer v-model="a" size="360px">
<template #header>
<NsSpace align="center">
<NsIcon name="setting" />
<strong>自定义头部</strong>
</NsSpace>
</template>
<p>内容</p>
</NsDrawer>
<NsDrawer v-model="b" :with-header="false" size="320px">
<p>没有头部,自己放一个关闭按钮。</p>
<NsButton @click="b = false">关闭</NsButton>
</NsDrawer>
</template>
不显示遮罩
modal 设为 false 时不显示遮罩,抽屉以外的页面可以照常点击。这时点页面不会关闭抽屉,用 × 或 Esc 关闭。
页面滚动默认还是锁定的,要让页面能滚动,再加上 :lock-scroll="false"。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsDrawer, NsSpace } from '@ns/ui'
const visible = ref(false)
const count = ref(0)
</script>
<template>
<NsSpace wrap>
<NsButton @click="visible = true">打开没有遮罩的抽屉</NsButton>
<NsButton @click="count++">抽屉打开时也能点({{ count }})</NsButton>
</NsSpace>
<NsDrawer v-model="visible" title="没有遮罩" size="320px" :modal="false" :lock-scroll="false">
<p>可以一边看抽屉,一边操作页面。</p>
</NsDrawer>
</template>
限制关闭方式
三个开关分别控制三种关闭方式,默认都是开的:
close-on-click-modal:点遮罩关闭。close-on-press-escape:按 Esc 关闭。show-close:显示右上角的关闭按钮。
三个都关掉以后,只能由你自己把 v-model 的值改成 false 来关闭。下面每个按钮关掉其中一种,最后一个三种都关掉:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsDrawer, NsSpace } from '@ns/ui'
const visible = ref(false)
const title = ref('')
const options = reactive({
closeOnClickModal: true,
closeOnPressEscape: true,
showClose: true
})
const open = (label: string, next: Partial<typeof options>) => {
Object.assign(options, { closeOnClickModal: true, closeOnPressEscape: true, showClose: true })
Object.assign(options, next)
title.value = label
visible.value = true
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="open('点遮罩不关闭', { closeOnClickModal: false })">
点遮罩不关闭(close-on-click-modal)
</NsButton>
<NsButton @click="open('按 Esc 不关闭', { closeOnPressEscape: false })">
按 Esc 不关闭(close-on-press-escape)
</NsButton>
<NsButton @click="open('没有关闭按钮', { showClose: false })">
不显示关闭按钮(show-close)
</NsButton>
<NsButton
type="primary"
@click="
open('只能点下面的按钮关闭', {
closeOnClickModal: false,
closeOnPressEscape: false,
showClose: false
})
"
>
三个都关掉
</NsButton>
</NsSpace>
<NsDrawer
v-model="visible"
:title="title"
:close-on-click-modal="options.closeOnClickModal"
:close-on-press-escape="options.closeOnPressEscape"
:show-close="options.showClose"
>
<p>点遮罩:{{ options.closeOnClickModal ? '关闭' : '不关闭' }}</p>
<p>按 Esc:{{ options.closeOnPressEscape ? '关闭' : '不关闭' }}</p>
<p>右上角的关闭按钮:{{ options.showClose ? '显示' : '不显示' }}</p>
<template #footer>
<NsButton type="primary" @click="visible = false">我知道了</NsButton>
</template>
</NsDrawer>
</template>
关闭前确认
传了 before-close 以后,点 ×、点遮罩、按 Esc 时先调用这个函数,由它决定关不关。有三种写法,下面每个按钮用一种:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsCheckbox, NsDrawer, NsMessage, NsSpace } from '@ns/ui'
type Mode = 'done' | 'return' | 'promise'
const visible = ref(false)
const saved = ref(false)
const mode = ref<Mode>('done')
// 写法一:声明 done 参数,调用 done() 才关闭
const byDone = (done: () => void) => {
if (saved.value) done()
else NsMessage.warning('先勾选“我已保存”')
}
// 写法二:不要参数,返回 true 关闭、返回 false 不关闭
const byReturn = () => {
if (!saved.value) NsMessage.warning('先勾选“我已保存”')
return saved.value
}
// 写法三:返回 Promise,等异步操作(这里用定时器模拟保存)结束再决定
const byPromise = () =>
new Promise<boolean>((resolve) => {
NsMessage.info('正在保存,1 秒后关闭')
setTimeout(() => resolve(true), 1000)
})
const handlers = { done: byDone, return: byReturn, promise: byPromise }
const titles = {
done: '写法一:调用 done()',
return: '写法二:返回布尔值',
promise: '写法三:返回 Promise'
}
const open = (value: Mode) => {
mode.value = value
saved.value = false
visible.value = true
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="open('done')">调用 done()</NsButton>
<NsButton @click="open('return')">返回布尔值</NsButton>
<NsButton @click="open('promise')">返回 Promise</NsButton>
</NsSpace>
<NsDrawer v-model="visible" :title="titles[mode]" :before-close="handlers[mode]">
<NsCheckbox v-if="mode !== 'promise'" v-model="saved">我已保存</NsCheckbox>
<p v-else>点 × 或按 Esc,1 秒后才关闭。</p>
</NsDrawer>
</template>
具体规则:
- 返回
true(或 Promise 的结果是true):关闭。 - 返回
false:不关闭。 - 没有返回值:函数声明了
done参数的,等它调用done();没有声明参数的,直接关闭。 - 函数抛出错误,或返回的 Promise 被拒绝:不关闭。
多层叠加
抽屉里可以再打开抽屉或对话框。按 Esc 只关闭最后打开的那一个;页面滚动要等全部关掉才恢复。
抽屉和对话框的层级相同,谁在 DOM 里靠后谁在上面,所以要把后打开的那个写在模板里靠后的位置。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsDrawer, NsModal, NsSpace } from '@ns/ui'
const outer = ref(false)
const inner = ref(false)
const dialog = ref(false)
</script>
<template>
<NsButton @click="outer = true">打开第一层抽屉</NsButton>
<NsDrawer v-model="outer" title="第一层抽屉" size="480px">
<NsSpace wrap>
<NsButton @click="inner = true">打开第二层抽屉</NsButton>
<NsButton @click="dialog = true">打开对话框</NsButton>
</NsSpace>
</NsDrawer>
<NsDrawer v-model="inner" title="第二层抽屉" size="300px">
<p>按 Esc 只关闭这一层。</p>
</NsDrawer>
<NsModal v-model="dialog" title="抽屉上面的对话框" width="360px">
<p>对话框显示在抽屉上面。</p>
</NsModal>
</template>
挂到 body 下
默认抽屉渲染在组件所在的位置。祖先元素有 transform、filter、overflow: hidden 之类的样式时,抽屉可能被限制在祖先元素里,这时加 append-to-body 把它挂到 body 下。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsDrawer } from '@ns/ui'
const visible = ref(false)
</script>
<template>
<div style="transform: translateX(0);">
<NsButton @click="visible = true">打开抽屉</NsButton>
<NsDrawer v-model="visible" title="挂在 body 下" append-to-body>
<p>不受祖先元素样式的影响。</p>
</NsDrawer>
</div>
</template>
事件
v-model 的值变成 true 时触发 open;关闭时触发 close,不管是用户点 ×、点遮罩、按 Esc,还是外部把 v-model 改成 false,每次关闭只触发一次。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsDrawer, NsMessage } from '@ns/ui'
const visible = ref(false)
const onOpen = () => {
NsMessage.info('open:开始打开')
}
const onClose = () => {
NsMessage.info('close:开始关闭')
}
</script>
<template>
<NsButton @click="visible = true">打开抽屉</NsButton>
<NsDrawer v-model="visible" title="事件" @open="onOpen" @close="onClose">
<p>点 ×、点遮罩、按 Esc 或下面的按钮关闭,都会触发 close。</p>
<NsButton @click="visible = false">改 v-model 关闭</NsButton>
</NsDrawer>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | boolean | false | 是否显示,支持 v-model |
| title | string | '' | 标题。也可以用 header 插槽 |
| direction | 'rtl' | 'ltr' | 'ttb' | 'btt' | 'rtl' | 从哪一侧滑出:rtl 右侧、ltr 左侧、ttb 顶部、btt 底部 |
| size | string | number | '30%' | 抽屉尺寸:左右方向是宽度,上下方向是高度。数字按 px 处理 |
| modal | boolean | true | 是否显示遮罩。为 false 时抽屉以外的页面可以操作 |
| appendToBody | boolean | false | 是否把抽屉挂到 body 下 |
| lockScroll | boolean | true | 打开时是否锁定页面滚动 |
| closeOnClickModal | boolean | true | 点遮罩是否关闭 |
| closeOnPressEscape | boolean | true | 按 Esc 是否关闭 |
| showClose | boolean | true | 是否显示右上角的关闭按钮 |
| beforeClose | (done: () => void) => boolean | Promise<boolean> | void | - | 关闭前的回调,规则见“关闭前确认” |
| withHeader | boolean | true | 是否显示头部(标题和关闭按钮) |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: boolean) | 用户关闭抽屉(点 ×、点遮罩、按 Esc)时触发,值是 false |
| open | - | v-model 的值从 false 变成 true 时触发 |
| close | - | 抽屉关闭时触发。用户关闭和外部把 v-model 改成 false 都会触发,每次关闭只触发一次 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 抽屉的内容 |
| header | - | 头部内容,替换 title。关闭按钮不受影响 |
| footer | - | 底部内容,一般放操作按钮。不写时不显示底部 |
类型
import type { DrawerDirection, DrawerProps } from '@ns/ui'
type DrawerDirection = 'rtl' | 'ltr' | 'ttb' | 'btt'
注意事项
- 抽屉关闭后里面的内容会被销毁,下次打开重新渲染。要保留输入的内容,把数据放在抽屉外面的变量里。
before-close只拦截用户的关闭操作(点 ×、点遮罩、按 Esc)。你自己把v-model的值改成false时不会调用它。- 抽屉一挂载就是打开状态(
v-model的初始值是true)时,不触发open。 - 打开时焦点会移进抽屉,按 Tab 只在抽屉里面循环;关闭后焦点回到打开之前所在的元素(一般是打开它的那个按钮)。
modal为false时页面仍可操作:Tab 可以从抽屉走到页面上,抽屉也不声明aria-modal。 - 锁定页面滚动是通过给
body设置overflow: hidden实现的,并且会补上滚动条的宽度,页面不会左右跳一下。全部抽屉、对话框都关闭后恢复成原来的值。页面不是在body上滚动(而是在某个容器里滚动)时,锁定不起作用。 - 抽屉里的 Popover、Dropdown、Popconfirm 显示着的时候按 Esc,只收起这些浮层,再按一次才关闭抽屉。
- 写在
NsDrawer上的class、style和其他没有声明的属性会加到抽屉最外层的元素(.ns-drawer)上。 - 抽屉的宽度、高度不会超过视口。
优化点
- [ ] 增加
opened、closed事件(动画结束时触发),和 Modal 保持一致 - [ ] 增加
destroyOnClose之类的开关,支持关闭后保留里面的内容(现在关闭就销毁,和 Modal 的默认行为相反) - [ ] 多个抽屉、对话框按打开的先后顺序叠放,不依赖 DOM 顺序
- [ ]
modal为false时默认不锁定页面滚动 - [ ] 支持拖动边缘调整抽屉尺寸