Alert 警告提示
在页面里固定显示一条提示,例如操作说明、风险提醒、处理结果。不会自动消失,可以加关闭按钮。
引入
import { NsAlert } from '@ns/ui'
基础用法
title 是标题,type 默认是 'info'。
<script setup lang="ts">
import { NsAlert } from '@ns/ui'
</script>
<template>
<NsAlert title="这是一条提示" />
</template>
类型
type 有 success、warning、info、error、help 五种,颜色和左侧图标跟着变。
<script setup lang="ts">
import { NsAlert, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill>
<NsAlert title="成功提示(success)" type="success" />
<NsAlert title="警告提示(warning)" type="warning" />
<NsAlert title="消息提示(info)" type="info" />
<NsAlert title="错误提示(error)" type="error" />
<NsAlert title="帮助提示(help)" type="help" />
</NsSpace>
</template>
深色效果
effect 默认是 'light'(浅色底、彩色图标)。改成 'dark' 后是实色背景、白色文字,没有边框。五种类型都有深色效果:
<script setup lang="ts">
import { NsAlert, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill>
<NsAlert title="深色的成功提示(success)" type="success" effect="dark" />
<NsAlert title="深色的警告提示(warning)" type="warning" effect="dark" />
<NsAlert title="深色的消息提示(info)" type="info" effect="dark" />
<NsAlert title="深色的错误提示(error)" type="error" effect="dark" />
<NsAlert title="深色的帮助提示(help)" type="help" effect="dark" />
<NsAlert
title="深色效果也能带描述"
description="描述文字同样是白色。"
type="success"
effect="dark"
closable
/>
</NsSpace>
</template>
描述文字
description 显示在标题下面,字号小一号。只有描述、没有标题时,图标和文字垂直居中。
描述内容也可以写在默认插槽或 #description 插槽里,优先级是:#description 插槽 > 默认插槽 > description 属性。也就是说,默认插槽是描述内容的后备,写了 #description 时默认插槽不显示。
<script setup lang="ts">
import { NsAlert, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill>
<NsAlert title="带描述的提示" description="这里是更详细的说明文字。" type="success" />
<NsAlert title="带描述的警告" description="这里是更详细的说明文字。" type="warning" />
<NsAlert title="带描述的错误" description="这里是更详细的说明文字。" type="error" />
<NsAlert description="只有描述、没有标题" />
<NsAlert title="用默认插槽写描述">
<span>描述里可以放<a href="https://example.com" target="_blank">链接</a>等内容。</span>
</NsAlert>
<NsAlert>
<template #title>
<strong>用插槽写的标题</strong>
</template>
<template #description>用插槽写的描述</template>
</NsAlert>
<NsAlert title="两个插槽都写" description="description 属性不显示">
<template #description>#description 插槽优先</template>
默认插槽也不显示
</NsAlert>
</NsSpace>
</template>
可关闭
closable 默认是 false,加上后右侧显示关闭按钮。close-text 把关闭图标换成文字。
点关闭按钮时立即触发 close 事件,提示开始淡出;0.3 秒的淡出结束、元素移除后触发 after-close。淡出期间再点关闭按钮不会重复触发。
关掉以后提示不会再出现,下面用“全部重新显示”换一个 key 重新渲染:
<script setup lang="ts">
import { ref } from 'vue'
import { NsAlert, NsButton, NsSpace } from '@ns/ui'
const log = ref<string[]>([])
const key = ref(0)
const handleClose = (event: MouseEvent) => {
log.value.push(`close(${event.type})`)
}
const handleAfterClose = () => {
log.value.push('after-close:已经从页面上移除')
}
const reset = () => {
key.value++
log.value = []
}
</script>
<template>
<NsSpace :key="key" direction="vertical" fill>
<NsAlert title="可以关闭的提示" closable @close="handleClose" @after-close="handleAfterClose" />
<NsAlert title="关闭按钮显示文字" type="success" closable close-text="知道了" />
<NsAlert
title="带描述的可关闭提示"
description="关闭按钮和标题对齐。"
type="warning"
closable
/>
<NsAlert title="深色的可关闭提示" type="error" effect="dark" closable />
</NsSpace>
<NsSpace wrap style="margin-top: 12px">
<NsButton size="small" @click="reset">全部重新显示</NsButton>
<span>{{ log.length ? log.join(' → ') : '点第一条的关闭按钮看事件' }}</span>
</NsSpace>
</template>
对齐方式
align 设置图标、标题和描述的对齐方式,有 left(默认)、center、right 三种。center 属性是早期的写法,等同于 align="center",两个同时写时以 center 为准。居中时关闭按钮固定在右上角。
<script setup lang="ts">
import { NsAlert, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill>
<NsAlert title="左对齐(left)" description="默认左对齐" />
<NsAlert title="居中(center)" description="align 为 center" align="center" />
<NsAlert title="右对齐(right)" description="align 为 right" align="right" />
<NsAlert title="center 属性" description="等同于 align 为 center" type="success" center />
<NsAlert title="居中且可关闭" description="关闭按钮在右上角" type="warning" center closable />
</NsSpace>
</template>
图标
show-icon默认是true,设为false不显示图标。icon-position是图标的位置,'left'(默认)在内容左侧,'right'在内容右侧。#icon插槽替换默认图标,位置同样由icon-position决定;show-icon为false时插槽也不显示。
<script setup lang="ts">
import { NsAlert, NsIcon, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill>
<NsAlert title="不显示图标" :show-icon="false" />
<NsAlert title="图标在左边(left)" type="success" />
<NsAlert title="图标在右边(right)" type="success" icon-position="right" />
<NsAlert title="自定义图标" type="warning">
<template #icon>
<NsIcon name="star" size="md" />
</template>
</NsAlert>
<NsAlert title="自定义图标放在右边" type="help" icon-position="right">
<template #icon>
<NsIcon name="bell" size="md" />
</template>
</NsAlert>
</NsSpace>
</template>
无边框
border 默认是 true,设为 false 去掉边框。浅色效果的五种类型都可以去掉边框(深色效果本来就没有边框)。
<script setup lang="ts">
import { NsAlert, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill>
<NsAlert title="有边框(默认)" type="info" />
<NsAlert title="没有边框的成功提示" type="success" :border="false" />
<NsAlert title="没有边框的警告提示" type="warning" :border="false" />
<NsAlert title="没有边框的消息提示" type="info" :border="false" />
<NsAlert title="没有边框的错误提示" type="error" :border="false" />
<NsAlert title="没有边框的帮助提示" type="help" :border="false" />
</NsSpace>
</template>
跑马灯
marquee 为 true 时,描述文字排成一行,从右向左循环滚动,每轮 10 秒,长文字也能完整滚过去。标题不滚动。
<script setup lang="ts">
import { NsAlert, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill>
<NsAlert
type="warning"
marquee
description="系统将于今晚 22:00 至 24:00 停机维护,请提前保存工作内容。"
/>
<NsAlert
title="公告"
type="info"
effect="dark"
marquee
description="带标题时只有描述滚动,标题固定在上面。"
/>
</NsSpace>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| title | string | '' | 标题。也可以用 #title 插槽 |
| description | string | '' | 描述文字。#description 插槽和默认插槽都会覆盖它 |
| type | 'success' | 'warning' | 'info' | 'error' | 'help' | 'info' | 类型,决定颜色和图标 |
| effect | 'light' | 'dark' | 'light' | 浅色或深色效果 |
| closable | boolean | false | 是否显示关闭按钮 |
| closeText | string | '' | 关闭按钮的文字,不为空时代替关闭图标 |
| align | 'left' | 'center' | 'right' | 'left' | 对齐方式 |
| center | boolean | false | 是否居中,等同于 align="center",同时写时以它为准 |
| showIcon | boolean | true | 是否显示图标 |
| iconPosition | 'left' | 'right' | 'left' | 图标在内容的左边还是右边 |
| border | boolean | true | 是否显示边框 |
| marquee | boolean | false | 描述文字是否单行循环滚动 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| close | (event: MouseEvent) | 点关闭按钮时立即触发,参数是点击事件 |
| after-close | — | 关闭的淡出动画结束、提示从页面上移除后触发 |
Slots
| 插槽 | 说明 |
|---|---|
| default | 描述内容的后备。写了 #description 插槽时不显示 |
| title | 标题,覆盖 title 属性 |
| description | 描述内容,覆盖默认插槽和 description 属性 |
| icon | 替换默认图标,位置由 iconPosition 决定。showIcon 为 false 时不显示 |
类型
import type {
AlertType,
AlertEffect,
AlertAlign,
AlertIconPosition,
AlertProps,
AlertEmits
} from '@ns/ui'
type AlertType = 'success' | 'warning' | 'info' | 'error' | 'help'
type AlertEffect = 'dark' | 'light'
type AlertAlign = 'left' | 'center' | 'right'
type AlertIconPosition = 'left' | 'right'
interface AlertProps {
title?: string
description?: string
type?: AlertType
closable?: boolean
center?: boolean
showIcon?: boolean
effect?: AlertEffect
closeText?: string
align?: AlertAlign
border?: boolean
marquee?: boolean
iconPosition?: AlertIconPosition
}
interface AlertEmits {
close: [event: MouseEvent]
afterClose: []
}
注意事项
- 关闭后提示由组件自己隐藏,没有
v-model或visible属性,组件也没有暴露方法,不能再让它显示出来。需要重新显示时,用外层的v-if或者改key重新渲染一个。 close在淡出开始时触发,这时提示还在页面上;要在提示移除之后做事(例如调整布局)用after-close。- 关闭按钮是原生
<button>,可以用 Tab 键聚焦,按回车或空格关闭。按钮的aria-label是closeText,没写时是“关闭”。 - 根元素是
role="alert",屏幕阅读器会在提示出现时立即读出来。 marquee只作用于描述,描述为空时没有效果。
优化点
- [x] 需要支持跑马灯效果
- [x] 增加icon插槽,插槽可以在左边或者右边
- [x] 可以没有边框
- [x] 增加alert消失之后的回调函数支持
- [x] center属性改为支持文字靠左,靠右,居中3种模式
- [ ] 支持用
v-model控制显示,关闭后可以再打开 - [ ] 支持自定义跑马灯速度