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.
Modal 对话框
在页面上方弹出一个带遮罩的窗口,用来确认操作、展示详情或填写一小段表单,不离开当前页面。只是确认一句话时用 Popconfirm 更轻;内容较多、需要从屏幕一侧滑出时用 Drawer。
引入
import { NsModal } from '@ns/ui'
基础用法
用 v-model 控制显示,title 是标题,内容放在默认插槽里。点右上角的 ×、点对话框外面或按 Esc 都可以关闭。
<script setup lang="ts">
import { ref } from 'vue'
import { NsModal, NsButton } from '@ns/ui'
const visible = ref(false)
</script>
<template>
<NsButton type="primary" @click="visible = true">打开对话框</NsButton>
<NsModal v-model="visible" title="提示">
<p>这是对话框的内容。</p>
</NsModal>
</template>
底部按钮
操作按钮放在 footer 插槽里,靠右排列。没有写 footer 插槽时不显示底部区域。
<script setup lang="ts">
import { ref } from 'vue'
import { NsModal, NsButton, NsMessage } from '@ns/ui'
const visible = ref(false)
const submit = () => {
visible.value = false
NsMessage.success('已提交')
}
</script>
<template>
<NsButton type="primary" @click="visible = true">打开对话框</NsButton>
<NsModal v-model="visible" title="确认操作" width="420px">
<p>确定要提交这份表单吗?</p>
<template #footer>
<NsButton @click="visible = false">取消</NsButton>
<NsButton type="primary" @click="submit">确定</NsButton>
</template>
</NsModal>
</template>
宽度
width 默认 50%,可以传数字(按 px 处理)或带单位的字符串。视口比较窄时,对话框最宽占视口的 90%。点下面的按钮看不同宽度:
<script setup lang="ts">
import { ref } from 'vue'
import { NsModal, NsButton, NsSpace } from '@ns/ui'
const visible = ref(false)
const width = ref<string | number>('50%')
const open = (value: string | number) => {
width.value = value
visible.value = true
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="open('30%')">30%</NsButton>
<NsButton @click="open('50%')">50%(默认)</NsButton>
<NsButton @click="open('80%')">80%</NsButton>
<NsButton @click="open(360)">数字 360(按 px)</NsButton>
<NsButton @click="open('600px')">600px</NsButton>
</NsSpace>
<NsModal v-model="visible" :title="`width:${width}`" :width="width">
<p>对话框的宽度由 width 决定,窄屏下最宽占视口的 90%。</p>
</NsModal>
</template>
位置
top 是对话框离视口顶部的距离,默认 15vh,同样可以传数字(按 px 处理)或带单位的字符串。center 让对话框在视口里垂直居中,这时 top 不起作用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsModal, NsButton, NsSpace } from '@ns/ui'
const visible = ref(false)
const top = ref<string | number>('15vh')
const center = ref(false)
const open = (value: string | number, isCenter = false) => {
top.value = value
center.value = isCenter
visible.value = true
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="open('15vh')">离顶部 15vh(默认)</NsButton>
<NsButton @click="open(40)">离顶部 40(按 px)</NsButton>
<NsButton @click="open('30vh')">离顶部 30vh</NsButton>
<NsButton @click="open('15vh', true)">垂直居中(center)</NsButton>
</NsSpace>
<NsModal
v-model="visible"
:title="center ? '垂直居中(center)' : `top:${top}`"
width="420px"
:top="top"
:center="center"
>
<p>对话框的内容。</p>
</NsModal>
</template>
全屏
fullscreen 让对话框占满整个视口,width、top、center 都不起作用。内容多了在内容区里滚动,头部和底部固定。
<script setup lang="ts">
import { ref } from 'vue'
import { NsModal, NsButton } from '@ns/ui'
const visible = ref(false)
</script>
<template>
<NsButton type="primary" @click="visible = true">打开全屏对话框</NsButton>
<NsModal v-model="visible" title="全屏对话框" fullscreen>
<p v-for="i in 30" :key="i">第 {{ i }} 行内容</p>
<template #footer>
<NsButton type="primary" @click="visible = false">关闭</NsButton>
</template>
</NsModal>
</template>
拖动标题栏
加上 draggable 后,按住标题栏可以拖动对话框,标题栏上的光标是移动的样子,拖动时不会选中文字。
- 拖不出视口:对话框放得下时整个留在视口里,拖到边上就停住;比视口还高时,至少标题栏留在视口里,随时能拖回来。
- 按在右上角的关闭按钮上不会开始拖动,点击照常关闭;
header插槽里的按钮、链接、输入框也一样。 - 全屏(
fullscreen)时不能拖,退出全屏后回到拖动后的位置。 - 关闭后再打开,回到原来的位置。
下面第一个按钮打开普通的可拖动对话框,第二个打开比视口还高的,可以在底部切换全屏:
<script setup lang="ts">
import { ref } from 'vue'
import { NsModal, NsButton, NsSpace } from '@ns/ui'
const visible = ref(false)
const tall = ref(false)
const fullscreen = ref(false)
const openTall = () => {
fullscreen.value = false
tall.value = true
}
</script>
<template>
<NsSpace wrap>
<NsButton type="primary" @click="visible = true">打开可拖动的对话框</NsButton>
<NsButton @click="openTall">打开很高的对话框</NsButton>
</NsSpace>
<NsModal v-model="visible" title="按住标题栏拖动" width="420px" draggable>
<p>拖到视口边上会停住,不会拖出去。</p>
<p>关掉再打开,对话框回到原来的位置。</p>
<template #footer>
<NsButton type="primary" @click="visible = false">知道了</NsButton>
</template>
</NsModal>
<NsModal v-model="tall" title="很高的对话框" width="480px" draggable :fullscreen="fullscreen">
<p v-for="i in 40" :key="i">第 {{ i }} 行内容</p>
<template #footer>
<NsButton @click="fullscreen = !fullscreen">
{{ fullscreen ? '退出全屏(可以拖)' : '全屏(不能拖)' }}
</NsButton>
<NsButton type="primary" @click="tall = false">关闭</NsButton>
</template>
</NsModal>
</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 { NsModal, NsButton, 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>
<NsModal
v-model="visible"
:title="title"
width="420px"
: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>
</NsModal>
</template>
关闭前确认
传了 before-close 以后,点 ×、点遮罩、按 Esc 时不会直接关闭,而是先调用这个函数,只有在里面调用了 done() 才关闭。可以用来提示“还有内容没保存”,或者等一个异步请求结束。
下面没勾选“我已保存”时,点 ×、点遮罩或按 Esc 会先弹出确认框;底部的按钮直接改 v-model,不经过 before-close。
<script setup lang="ts">
import { ref } from 'vue'
import { NsModal, NsButton, NsCheckbox, NsMessageBox } from '@ns/ui'
const visible = ref(false)
const saved = ref(false)
const open = () => {
saved.value = false
visible.value = true
}
const beforeClose = (done: () => void) => {
if (saved.value) {
done()
return
}
NsMessageBox.confirm('还没有保存,确定要关闭吗?', '提示', { type: 'warning' })
.then(() => done())
.catch(() => {})
}
</script>
<template>
<NsButton type="primary" @click="open">编辑资料</NsButton>
<NsModal v-model="visible" title="编辑资料" width="420px" :before-close="beforeClose">
<NsCheckbox v-model="saved">我已保存</NsCheckbox>
<template #footer>
<NsButton @click="visible = false">直接关闭</NsButton>
</template>
</NsModal>
</template>
自定义头部
header 插槽替换标题,右上角的关闭按钮还在。
<script setup lang="ts">
import { ref } from 'vue'
import { NsModal, NsButton, NsIcon, NsSpace } from '@ns/ui'
const visible = ref(false)
</script>
<template>
<NsButton type="primary" @click="visible = true">打开对话框</NsButton>
<NsModal v-model="visible" width="460px">
<template #header>
<NsSpace align="center">
<NsIcon name="user" />
<strong>自定义头部</strong>
<span class="subtitle">副标题</span>
</NsSpace>
</template>
<p>内容</p>
</NsModal>
</template>
<style scoped>
.subtitle {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
关闭后保留或销毁内容
对话框第一次打开时才渲染里面的内容。默认关闭后只是隐藏,输入框里填的内容、滚动位置、子组件的状态都还在;加上 destroy-on-close 后,关闭动画结束时销毁内容,下次打开重新渲染。
在两个对话框的输入框里各输入几个字,关掉再打开对比:
<script setup lang="ts">
import { ref } from 'vue'
import { NsModal, NsButton, NsSpace } from '@ns/ui'
const keep = ref(false)
const destroy = ref(false)
</script>
<template>
<NsSpace wrap>
<NsButton @click="keep = true">默认:关闭后保留</NsButton>
<NsButton @click="destroy = true">destroy-on-close:关闭后销毁</NsButton>
</NsSpace>
<NsModal v-model="keep" title="关闭后保留" width="420px">
<input class="demo-input" placeholder="输入的内容再打开时还在" />
</NsModal>
<NsModal v-model="destroy" title="关闭后销毁" width="420px" destroy-on-close>
<input class="demo-input" placeholder="每次打开都是空的" />
</NsModal>
</template>
<style scoped>
.demo-input {
box-sizing: border-box;
width: 100%;
height: var(--ns-component-size);
padding: 0 var(--ns-spacing-3);
color: var(--ns-text-color);
background: var(--ns-bg-color);
border: var(--ns-border-width) var(--ns-border-style) var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
</style>
遮罩和页面滚动
modal 设为 false 时不显示半透明的遮罩。对话框以外的页面仍然不能操作,点对话框外面仍然会关闭(除非把 close-on-click-modal 关掉)。
lock-scroll 默认是 true,打开期间页面不能滚动;设为 false 后,打开对话框时仍然可以滚动页面。
<script setup lang="ts">
import { ref } from 'vue'
import { NsModal, NsButton, NsSpace } from '@ns/ui'
const noMask = ref(false)
const noLock = ref(false)
</script>
<template>
<NsSpace wrap>
<NsButton @click="noMask = true">不显示遮罩(modal=false)</NsButton>
<NsButton @click="noLock = true">不锁定滚动(lock-scroll=false)</NsButton>
</NsSpace>
<NsModal v-model="noMask" title="没有遮罩" :modal="false">
<p>没有半透明的遮罩,点对话框外面照样会关闭。</p>
</NsModal>
<NsModal v-model="noLock" title="不锁定页面滚动" :lock-scroll="false">
<p>打开期间后面的页面仍然可以滚动。</p>
</NsModal>
</template>
多个对话框叠加
对话框里可以再打开对话框。按 Esc 只关闭最后打开的那一个;页面滚动要等所有对话框都关掉才恢复。
多个对话框的层级相同,谁在 DOM 里靠后谁在上面,所以要把后打开的那个写在模板里靠后的位置。先打开的那个加了 append-to-body 时,后打开的也要加。
<script setup lang="ts">
import { ref } from 'vue'
import { NsModal, NsButton } from '@ns/ui'
const first = ref(false)
const second = ref(false)
</script>
<template>
<NsButton type="primary" @click="first = true">打开第一层</NsButton>
<NsModal v-model="first" title="第一层">
<NsButton @click="second = true">打开第二层</NsButton>
</NsModal>
<NsModal v-model="second" title="第二层" width="360px" top="25vh">
<p>按 Esc 只关闭这一层。</p>
</NsModal>
</template>
挂到 body 下
默认对话框渲染在组件所在的位置。祖先元素有 transform、filter、overflow: hidden 之类的样式时,对话框可能被裁掉或者定位不对,这时加 append-to-body 把它挂到 body 下。
<script setup lang="ts">
import { ref } from 'vue'
import { NsModal, NsButton } from '@ns/ui'
const visible = ref(false)
</script>
<template>
<NsButton type="primary" @click="visible = true">打开对话框</NsButton>
<div style="transform: translateZ(0); overflow: hidden;">
<NsModal v-model="visible" title="挂在 body 下" append-to-body>
<p>不受祖先元素样式的影响。</p>
</NsModal>
</div>
</template>
事件
打开时依次触发 open(开始打开)、opened(打开动画结束);关闭时依次触发 close(开始关闭)、closed(关闭动画结束)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsModal, NsButton, NsMessage } from '@ns/ui'
const visible = ref(false)
const onOpen = () => {
NsMessage.info('open:开始打开')
}
const onOpened = () => {
NsMessage.info('opened:打开动画结束')
}
const onClose = () => {
NsMessage.info('close:开始关闭')
}
const onClosed = () => {
NsMessage.info('closed:关闭动画结束')
}
</script>
<template>
<NsButton type="primary" @click="visible = true">打开对话框</NsButton>
<NsModal
v-model="visible"
title="事件"
@open="onOpen"
@opened="onOpened"
@close="onClose"
@closed="onClosed"
>
<p>内容</p>
</NsModal>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | boolean | false | 是否显示,支持 v-model |
| title | string | '' | 标题。也可以用 header 插槽 |
| width | string | number | '50%' | 对话框宽度,数字按 px 处理。最宽占视口的 90% |
| top | string | number | '15vh' | 对话框离视口顶部的距离,数字按 px 处理。center、fullscreen 时不起作用 |
| center | boolean | false | 是否在视口里垂直居中 |
| fullscreen | boolean | false | 是否全屏 |
| modal | boolean | true | 是否显示遮罩 |
| appendToBody | boolean | false | 是否把对话框挂到 body 下 |
| lockScroll | boolean | true | 打开时是否锁定页面滚动 |
| closeOnClickModal | boolean | true | 点对话框外面是否关闭 |
| closeOnPressEscape | boolean | true | 按 Esc 是否关闭 |
| showClose | boolean | true | 是否显示右上角的关闭按钮 |
| beforeClose | (done: () => void) => void | - | 关闭前的回调,调用 done() 才关闭 |
| destroyOnClose | boolean | false | 关闭后是否销毁里面的内容 |
| draggable | boolean | false | 是否可以按住标题栏拖动。拖不出视口,全屏时不能拖,关闭后再打开回到原位置 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: boolean) | 用户关闭对话框(点 ×、点外面、按 Esc)时触发,值是 false |
| open | - | v-model 的值从 false 变成 true、对话框开始打开时触发 |
| opened | - | 打开动画结束时触发 |
| close | - | 对话框开始关闭时触发。用户关闭和外部把 v-model 改成 false 都会触发,每次关闭只触发一次 |
| closed | - | 关闭动画结束时触发 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 对话框的内容 |
| header | - | 头部内容,替换 title。关闭按钮不受影响 |
| footer | - | 底部内容,一般放操作按钮。不写时不显示底部 |
类型
import type { ModalProps } from '@ns/ui'
注意事项
before-close只拦截用户的关闭操作(点 ×、点外面、按 Esc)。你自己把v-model的值改成false时不会调用它。- 对话框一挂载就是打开状态(
v-model的初始值是true)时,不触发open,opened仍会在动画结束后触发。 - 打开时焦点会移进对话框,按 Tab 只在对话框里面循环;关闭后焦点回到打开之前所在的元素(一般是打开它的那个按钮)。
- 锁定页面滚动是通过给
body设置overflow: hidden实现的,并且会补上滚动条的宽度,页面不会左右跳一下。全部对话框、抽屉都关闭后恢复成原来的值。页面不是在body上滚动(而是在某个容器里滚动)时,锁定不起作用。 - 在对话框里按下鼠标、拖到外面才松开(例如拖选输入框里的文字)不会关闭对话框。
- 对话框里的 Popover、Dropdown、Popconfirm 显示着的时候按 Esc,只收起这些浮层,再按一次才关闭对话框。
- 写在
NsModal上的class、style和其他没有声明的属性会加到对话框最外层的元素(.ns-modal)上。 - 对话框、抽屉的层级都是
z-index: 2000,叠放顺序由 DOM 顺序决定,和打开的先后无关。 - 对话框比视口高时,整个对话框在遮罩上面上下滚动;全屏时只有内容区滚动。
draggable拖动时用相对定位的left、top移动.ns-modal__container,不要在这个元素上自己写left、top。拖动的范围按开始拖动时的视口大小算,拖完以后再缩小浏览器窗口,对话框可能有一部分到了视口外面,按住标题栏往回拖即可。- 拖动只能用鼠标、触摸或笔按住标题栏,没有键盘操作。
优化点
- [ ]
modal为false时让对话框以外的页面可以操作(现在只是不显示遮罩,和 Drawer 的行为不一致) - [ ] 多个对话框按打开的先后顺序叠放,不依赖 DOM 顺序
- [ ]
before-close支持返回boolean或Promise<boolean>,和 Drawer 保持一致 - [x] 支持拖动标题栏移动对话框