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.
Message 消息提示
在窗口顶部居中弹出一条简短的反馈,例如“保存成功”,几秒后自动消失。用函数调用,不用在模板里写组件。
引入
import { NsMessage } from '@ns/ui'
基础用法
传一段文字就能弹出消息,默认是 info 类型,3 秒后自动关闭。
<script setup lang="ts">
import { NsButton, NsMessage } from '@ns/ui'
const show = () => {
NsMessage('这是一条消息提示')
}
</script>
<template>
<NsButton @click="show">显示消息</NsButton>
</template>
不同类型
有 success、warning、info、error 四种类型,颜色和图标不同。可以用对应的快捷方法,也可以在配置里写 type。
<script setup lang="ts">
import { NsButton, NsMessage, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">快捷方法</span>
<NsButton type="success" @click="NsMessage.success('保存成功')">成功(success)</NsButton>
<NsButton type="warning" @click="NsMessage.warning('库存不足')">警告(warning)</NsButton>
<NsButton type="info" @click="NsMessage.info('已复制到剪贴板')">信息(info)</NsButton>
<NsButton type="danger" @click="NsMessage.error('网络异常,请稍后再试')">
错误(error)
</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">配置 type</span>
<NsButton @click="NsMessage({ message: '保存成功', type: 'success' })">success</NsButton>
<NsButton @click="NsMessage({ message: '库存不足', type: 'warning' })">warning</NsButton>
<NsButton @click="NsMessage({ message: '已复制到剪贴板', type: 'info' })">info</NsButton>
<NsButton @click="NsMessage({ message: '网络异常,请稍后再试', type: 'error' })">
error
</NsButton>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 72px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
快捷方法也能传配置对象,这时 type 以方法名为准,配置里的 type 不生效:
import { NsMessage } from '@ns/ui'
// 弹出的是 success 类型
NsMessage.success({ message: '保存成功', type: 'error', showClose: true })
可关闭
showClose 为 true 时右侧显示关闭按钮,点了立即关闭。每种类型都可以加。
<script setup lang="ts">
import { NsButton, NsMessage, NsSpace } from '@ns/ui'
import type { MessageType } from '@ns/ui'
const show = (type: MessageType) => {
NsMessage({ message: `可以手动关闭的 ${type} 消息`, type, showClose: true })
}
</script>
<template>
<NsSpace wrap>
<NsButton type="success" @click="show('success')">成功(success)</NsButton>
<NsButton type="warning" @click="show('warning')">警告(warning)</NsButton>
<NsButton type="info" @click="show('info')">信息(info)</NsButton>
<NsButton type="danger" @click="show('error')">错误(error)</NsButton>
</NsSpace>
</template>
文字居中
center 为 true 时图标和文字在消息框里居中。消息框宽度在 280 到 480 像素之间,文字短时才看得出居中的效果。
<script setup lang="ts">
import { NsButton, NsMessage, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap>
<NsButton @click="NsMessage({ message: '默认靠左' })">默认</NsButton>
<NsButton @click="NsMessage({ message: '居中的文字', center: true })">居中(center)</NsButton>
<NsButton
@click="
NsMessage({ message: '居中且可关闭', type: 'success', center: true, showClose: true })
"
>
居中且可关闭
</NsButton>
</NsSpace>
</template>
显示时长和手动关闭
duration 是显示多少毫秒后自动关闭,默认 3000,为 0 时不自动关闭。鼠标移到消息上时暂停计时,移开后重新计时。
<script setup lang="ts">
import { NsButton, NsMessage, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap>
<NsButton @click="NsMessage({ message: '1 秒后关闭', duration: 1000 })">1 秒</NsButton>
<NsButton @click="NsMessage({ message: '3 秒后关闭' })">3 秒(默认)</NsButton>
<NsButton @click="NsMessage({ message: '10 秒后关闭', duration: 10000 })">10 秒</NsButton>
<NsButton
@click="NsMessage({ message: '不会自动关闭,点 × 关闭', duration: 0, showClose: true })"
>
不自动关闭(0)
</NsButton>
</NsSpace>
</template>
每次调用都返回一个 MessageInstance,调用它的 close() 可以随时关闭这条消息。
<script setup lang="ts">
import { NsButton, NsMessage, NsSpace } from '@ns/ui'
import type { MessageInstance } from '@ns/ui'
let instance: MessageInstance | null = null
const open = () => {
instance = NsMessage({ message: '不会自动关闭,点按钮关闭', duration: 0 })
}
const close = () => {
instance?.close()
instance = null
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="open">打开</NsButton>
<NsButton @click="close">关闭</NsButton>
</NsSpace>
</template>
多条消息和 offset
连续弹出多条时,后弹出的排在前一条下面。offset 是这条消息和上一条之间的距离,排在第一条时是和窗口顶部的距离,默认 20(像素)。有一条关闭后,下面的消息依次上移补位。
<script setup lang="ts">
import { NsButton, NsMessage, NsSpace } from '@ns/ui'
const showThree = () => {
NsMessage({ message: '第 1 条', duration: 2000 })
NsMessage({ message: '第 2 条,2 秒后先关闭', type: 'success', duration: 2000 })
NsMessage({ message: '第 3 条,4 秒后关闭,会往上补位', type: 'warning', duration: 4000 })
}
const showOffset = () => {
NsMessage({ message: '第 1 条,离窗口顶部 20px' })
NsMessage({ message: '第 2 条,离上一条 80px', offset: 80 })
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="showThree">连续弹出 3 条</NsButton>
<NsButton @click="showOffset">第二条 offset 80</NsButton>
</NsSpace>
</template>
内容传 VNode
message 除了字符串,还可以传用 h() 创建的 VNode,用来显示加粗、链接等内容。字符串按纯文本显示,不会解析 HTML,写在字符串里的标签会原样显示出来。
<script setup lang="ts">
import { h } from 'vue'
import { NsButton, NsMessage, NsSpace } from '@ns/ui'
const showVNode = () => {
NsMessage({
message: h('span', ['订单 ', h('b', '20260101001'), ' 已提交'])
})
}
const showString = () => {
NsMessage({ message: '订单 <b>20260101001</b> 已提交' })
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="showVNode">VNode:加粗订单号</NsButton>
<NsButton @click="showString">字符串:标签原样显示</NsButton>
</NsSpace>
</template>
关闭回调
onClose 在消息关闭、淡出动画结束后调用一次。自动关闭、点关闭按钮、调用 close() 或 closeAll() 都会调用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsMessage } from '@ns/ui'
const status = ref('还没有打开消息')
const open = () => {
status.value = '消息显示中...'
NsMessage({
message: '1 秒后关闭',
duration: 1000,
showClose: true,
onClose: () => {
status.value = `onClose 已调用(${new Date().toLocaleTimeString()})`
}
})
}
</script>
<template>
<NsButton @click="open">打开消息</NsButton>
<p style="margin-top: 12px">{{ status }}</p>
</template>
关闭全部
NsMessage.closeAll() 关闭当前所有消息,每条都有正常的淡出动画,也会调用各自的 onClose。
<script setup lang="ts">
import { NsButton, NsMessage, NsSpace } from '@ns/ui'
const openMany = () => {
NsMessage.success({ message: '第 1 条', duration: 0 })
NsMessage.warning({ message: '第 2 条', duration: 0 })
NsMessage.error({ message: '第 3 条', duration: 0 })
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="openMany">弹出 3 条不会自动关闭的消息</NsButton>
<NsButton type="primary" @click="NsMessage.closeAll()">关闭全部</NsButton>
</NsSpace>
</template>
调用方式
| 写法 | 说明 |
|---|---|
NsMessage(options: MessageOptions) | 按配置弹出一条消息 |
NsMessage(message: string) | 弹出一条 info 类型的消息,其他都用默认值 |
NsMessage.success(message | options) | 弹出 success 类型的消息 |
NsMessage.warning(message | options) | 弹出 warning 类型的消息 |
NsMessage.info(message | options) | 弹出 info 类型的消息 |
NsMessage.error(message | options) | 弹出 error 类型的消息 |
NsMessage.closeAll() | 关闭当前所有消息,没有返回值 |
除了 closeAll,其他写法都返回这条消息的 MessageInstance。
配置项
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| message | string | VNode | '' | 消息内容。字符串按纯文本显示 |
| type | 'success' | 'warning' | 'info' | 'error' | 'info' | 类型,决定颜色和图标 |
| duration | number | 3000 | 显示多少毫秒后自动关闭,为 0 时不自动关闭 |
| showClose | boolean | false | 是否显示关闭按钮 |
| center | boolean | false | 图标和文字是否居中 |
| offset | number | 20 | 和上一条消息的距离(像素),排在第一条时是和窗口顶部的距离 |
| onClose | () => void | — | 关闭的淡出动画结束后调用 |
返回值
MessageInstance:
| 属性 | 类型 | 说明 |
|---|---|---|
| id | string | 这条消息的编号 |
| vm | HTMLElement | 消息的 DOM 元素 |
| props | MessageProps | 这条消息最终使用的配置(没传的项是默认值) |
| close | () => void | 关闭这条消息,有淡出动画。已经在关闭的消息再调用不做任何事 |
类型
import type { MessageType, MessageProps, MessageOptions, MessageInstance, MessageFn } from '@ns/ui'
import type { VNode } from 'vue'
type MessageType = 'success' | 'warning' | 'info' | 'error'
interface MessageProps {
message: string | VNode
type?: MessageType
duration?: number
showClose?: boolean
center?: boolean
offset?: number
onClose?: () => void
}
interface MessageOptions extends Omit<MessageProps, 'message'> {
message?: string | VNode
}
interface MessageInstance {
id: string
vm: HTMLElement
props: MessageProps
close: () => void
}
interface MessageFn {
(options: MessageOptions): MessageInstance
(message: string): MessageInstance
success: (message: string | MessageOptions) => MessageInstance
warning: (message: string | MessageOptions) => MessageInstance
info: (message: string | MessageOptions) => MessageInstance
error: (message: string | MessageOptions) => MessageInstance
closeAll: () => void
}
另外导出了消息本身的组件 NsMessageComponent,NsMessage 内部用它渲染,一般不需要直接用。
注意事项
- 每条消息都是单独创建的 Vue 应用,挂在
body下的.ns-message-container里。message传的 VNode 拿不到当前应用的全局组件、provide和插件,VNode 里用到的组件要直接 import。 - 消息的
z-index固定是 9999,盖在对话框和消息弹框上面,不读NsConfigProvider的zIndex(消息是单独创建的应用,读不到它)。 - 宽度在 280 到 480 像素之间,文字太长时换行。
- 消息的根元素是
role="alert",屏幕阅读器会读出内容。关闭按钮是原生<button>,可以用 Tab 键聚焦,按回车或空格关闭。 - 只有
NsMessage.closeAll()能一次关掉所有消息;关单条要保存调用时返回的实例。
优化点
- [ ] 支持合并内容相同的消息(如
grouping),连续点击时不弹一串 - [ ] 支持限制同时显示的条数
- [ ] 支持自定义图标