LoadingBar 顶部加载条
页面最顶部的一条细进度条,切换路由、提交请求时告诉用户“正在加载”。用函数调用,不用在模板里写组件。
引入
ts
import { NsLoadingBar } from '@ns/ui'
基础用法
NsLoadingBar.start():加载条从页面顶部出现,自动缓慢前进,越接近终点越慢,不会走到头。NsLoadingBar.finish():走满,再淡出。NsLoadingBar.error():变成危险色,走满,再淡出。
没点“开始”直接点“完成”或“出错”也可以,加载条从 0 走满再淡出。
vue
<script setup lang="ts">
import { onBeforeUnmount } from 'vue'
import { NsButton, NsLoadingBar, NsSpace } from '@ns/ui'
// 离开这个页面时加载条还在走,就直接移除
onBeforeUnmount(() => NsLoadingBar.destroy())
</script>
<template>
<NsSpace wrap>
<NsButton type="primary" @click="NsLoadingBar.start()">开始(start)</NsButton>
<NsButton type="success" @click="NsLoadingBar.finish()">完成(finish)</NsButton>
<NsButton type="danger" @click="NsLoadingBar.error()">出错(error)</NsButton>
</NsSpace>
</template>
重复调用
页面上同一时间只有一条加载条:
- 已经在加载中时再调用
start不做任何事,进度不会倒退,也不会多出一条。 - 已经在走满、淡出时调用
start,加载条从头开始。 - 已经在走满、淡出时调用
finish不做任何事;调用error只把颜色换成出错色。
vue
<script setup lang="ts">
import { onBeforeUnmount } from 'vue'
import { NsButton, NsLoadingBar, NsSpace } from '@ns/ui'
let timers: ReturnType<typeof setTimeout>[] = []
const cancel = () => {
timers.forEach(clearTimeout)
timers = []
NsLoadingBar.destroy()
}
// 安排几个延时调用;再点一次时先取消上一次没执行的
const schedule = (steps: [number, () => void][]) => {
cancel()
timers = steps.map(([delay, fn]) => setTimeout(fn, delay))
}
// 离开这个页面时取消还没执行的调用
onBeforeUnmount(cancel)
// 连着调用 3 次 start,仍然只有一条,2 秒后完成
const startThreeTimes = () => {
schedule([[2000, NsLoadingBar.finish]])
NsLoadingBar.start()
NsLoadingBar.start()
NsLoadingBar.start()
}
// 1 秒后完成,淡出时再 start,加载条从头开始,3 秒后再完成
const restart = () => {
schedule([
[1000, NsLoadingBar.finish],
[1400, () => NsLoadingBar.start()],
[3000, NsLoadingBar.finish]
])
NsLoadingBar.start()
}
// 完成后马上出错:颜色换成危险色,照常淡出
const finishThenError = () => {
schedule([
[1000, NsLoadingBar.finish],
[1100, NsLoadingBar.error]
])
NsLoadingBar.start()
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="startThreeTimes">连着调用 3 次 start</NsButton>
<NsButton @click="restart">淡出时重新 start</NsButton>
<NsButton @click="finishThenError">finish 后马上 error</NsButton>
</NsSpace>
</template>
颜色和高度
start 可以传配置,只对这一轮生效:
color:进度条颜色,默认主题主色。可以写任意 CSS 颜色,也可以写var(--ns-color-success)这样的主题变量,跟着配色和暗色主题变。errorColor:调用error后的颜色,默认主题危险色。height:高度,数字按 px,字符串原样使用,默认2。
每个按钮开始后 1.5 秒完成,errorColor 一行 1.5 秒后出错:
vue
<script setup lang="ts">
import { NsButton, NsLoadingBar, NsSpace } from '@ns/ui'
import type { LoadingBarOptions } from '@ns/ui'
let timer: ReturnType<typeof setTimeout> | undefined
const play = (options: LoadingBarOptions, end: 'finish' | 'error' = 'finish') => {
// 上一次还没结束时先移除,新的配置才能马上看到
clearTimeout(timer)
NsLoadingBar.destroy()
NsLoadingBar.start(options)
timer = setTimeout(() => NsLoadingBar[end](), 1500)
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">color</span>
<NsButton @click="play({})">默认主色</NsButton>
<NsButton @click="play({ color: 'var(--ns-color-success)' })">成功色</NsButton>
<NsButton @click="play({ color: 'var(--ns-color-warning)' })">警告色</NsButton>
<NsButton @click="play({ color: '#722ed1' })">#722ed1</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">errorColor</span>
<NsButton @click="play({}, 'error')">默认危险色</NsButton>
<NsButton @click="play({ errorColor: 'var(--ns-color-warning)' }, 'error')">警告色</NsButton>
<NsButton @click="play({ errorColor: '#eb2f96' }, 'error')">#eb2f96</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">height</span>
<NsButton @click="play({})">默认 2</NsButton>
<NsButton @click="play({ height: 4 })">4</NsButton>
<NsButton @click="play({ height: 6 })">6</NsButton>
<NsButton @click="play({ height: '0.5rem' })">'0.5rem'</NsButton>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 80px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
全局配置
NsLoadingBar.config(options) 设置之后每一轮的默认配置,配置项和 start 的一样,和已有的配置合并。某一项传 undefined 恢复成默认值。start 传的配置优先于它。正在显示的加载条不受影响,下一次 start 才用上。一般在应用入口调用一次。
vue
<script setup lang="ts">
import { onBeforeUnmount, ref } from 'vue'
import { NsButton, NsLoadingBar, NsSpace } from '@ns/ui'
const current = ref('默认')
let timer: ReturnType<typeof setTimeout> | undefined
const setPurple = () => {
NsLoadingBar.config({ color: '#722ed1', height: 4 })
current.value = '紫色、高 4px'
}
const setDefault = () => {
NsLoadingBar.config({ color: undefined, height: undefined })
current.value = '默认'
}
const play = (color?: string) => {
clearTimeout(timer)
NsLoadingBar.destroy()
NsLoadingBar.start(color ? { color } : undefined)
timer = setTimeout(() => NsLoadingBar.finish(), 1500)
}
// config 是全局的,离开这个页面时恢复默认,不影响别的页面
onBeforeUnmount(setDefault)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsButton @click="setPurple">config:紫色、高 4px</NsButton>
<NsButton @click="setDefault">config:恢复默认</NsButton>
<span>当前默认配置:{{ current }}</span>
</NsSpace>
<NsSpace wrap>
<NsButton type="primary" @click="play()">start()</NsButton>
<NsButton type="primary" plain @click="play('var(--ns-color-success)')">
start({ color: 成功色 })
</NsButton>
</NsSpace>
</NsSpace>
</template>
模拟请求
请求开始时 start,成功时 finish,失败时 error。下面用 setTimeout 模拟一个 1.5 秒的请求:
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsLoadingBar, NsMessage, NsSpace } from '@ns/ui'
const loading = ref(false)
// 模拟请求:1.5 秒后按 ok 成功或失败
const fakeRequest = (ok: boolean) =>
new Promise<void>((resolve, reject) => {
setTimeout(() => (ok ? resolve() : reject(new Error('网络异常'))), 1500)
})
const submit = async (ok: boolean) => {
loading.value = true
NsLoadingBar.start()
try {
await fakeRequest(ok)
NsLoadingBar.finish()
NsMessage.success('提交成功')
} catch {
NsLoadingBar.error()
NsMessage.error('提交失败,请稍后再试')
} finally {
loading.value = false
}
}
</script>
<template>
<NsSpace wrap>
<NsButton type="primary" :loading="loading" @click="submit(true)">提交(会成功)</NsButton>
<NsButton :loading="loading" @click="submit(false)">提交(会失败)</NsButton>
</NsSpace>
</template>
多个请求同时进行
第一个结束的请求调用 finish 时,加载条就走满了。要等所有请求都结束,自己记一下进行中的个数:从 0 变成 1 时 start,回到 0 时 finish。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsLoadingBar, NsSpace } from '@ns/ui'
const pending = ref(0)
// 模拟一个请求,duration 毫秒后结束
const request = (duration: number) => {
if (pending.value === 0) NsLoadingBar.start()
pending.value++
setTimeout(() => {
pending.value--
if (pending.value === 0) NsLoadingBar.finish()
}, duration)
}
const sendThree = () => {
request(600)
request(1200)
request(2400)
}
</script>
<template>
<NsSpace align="center">
<NsButton type="primary" @click="sendThree">同时发 3 个请求</NsButton>
<span>进行中的请求:{{ pending }} 个</span>
</NsSpace>
</template>
配合 vue-router
在路由的 beforeEach 里 start,afterEach 里 finish,onError 里 error:
ts
import {
createRouter,
createWebHistory,
isNavigationFailure,
NavigationFailureType
} from 'vue-router'
import { NsLoadingBar } from '@ns/ui'
import routes from './routes'
const router = createRouter({
history: createWebHistory(),
routes
})
// 开始跳转。被重定向时会再进来一次,加载条已经在走,不会重新开始
router.beforeEach(() => {
NsLoadingBar.start()
})
router.afterEach((to, from, failure) => {
// 跳到当前页面(duplicated)时没有经过 beforeEach;被新的跳转取消(cancelled)时,
// 新的那次结束会 finish。这两种情况不用管,否则会多显示一次走满
if (
isNavigationFailure(failure, NavigationFailureType.duplicated | NavigationFailureType.cancelled)
) {
return
}
NsLoadingBar.finish()
})
// 守卫里抛了错、路由组件加载失败时,afterEach 不会调用,在这里显示出错
router.onError(() => {
NsLoadingBar.error()
})
export default router
服务端渲染时这些调用不做任何事,不需要另外判断。
方法
| 方法 | 说明 |
|---|---|
NsLoadingBar.start(options?) | 开始加载。已经在加载中时不做任何事(也不应用新的配置);正在走满、淡出时从头开始。options 只对这一轮生效,优先于 config |
NsLoadingBar.finish() | 加载完成:走满再淡出。没有 start 过时从 0 走满再淡出;已经在走满、淡出时不做任何事 |
NsLoadingBar.error() | 加载出错:变成出错色,走满再淡出。没有 start 过时也能调用;已经在走满、淡出时只换颜色 |
NsLoadingBar.config(options) | 设置之后每一轮的默认配置,和已有的合并,某一项传 undefined 恢复默认。正在显示的加载条不受影响 |
NsLoadingBar.destroy() | 立即移除加载条,不播放动画,清掉所有计时器。没有加载条时不做任何事 |
这些方法都没有返回值,也不依赖 this,可以解构出来用。
配置项
start 和 config 的参数:
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| color | string | --ns-color-primary | 进度条颜色。任意 CSS 颜色,也可以写 var(--ns-color-success) 这样的主题变量 |
| errorColor | string | --ns-color-danger | 调用 error 后的颜色 |
| height | number | string | 2 | 高度,数字按 px,字符串原样使用(如 '0.25rem')。不大于 0 的数字不生效 |
| zIndex | number | 10000 | 层级 |
类型
ts
import type { LoadingBarOptions, LoadingBarApi } from '@ns/ui'
interface LoadingBarOptions {
color?: string
errorColor?: string
height?: number | string
zIndex?: number
}
interface LoadingBarApi {
start: (options?: LoadingBarOptions) => void
finish: () => void
error: () => void
config: (options: LoadingBarOptions) => void
destroy: () => void
}
注意事项
- 页面上同一时间最多一条加载条。它是单独创建的 Vue 应用,挂在
body下的.ns-loading-bar-container里,淡出结束后自动移除,下一次调用时再创建。 - 自动前进只会无限接近 95%,不会走到头。一直不调用
finish或error,加载条会一直停在顶部,请求失败的分支也要记得调用error。 - 加载中再
start不会应用新的配置。想马上换配置,先destroy()再start(options)。 - 默认颜色是主题主色和危险色,跟着配色和暗色主题变。
color、errorColor写成var(--ns-color-xxx)也会跟着变,写死的颜色不会。 - 层级默认
10000,在对话框、抽屉、下拉面板(从 2000 起)和消息提示(9999)之上。它不读NsConfigProvider的zIndex(单独创建的应用读不到),需要时用zIndex配置。 - 加载条设置了
pointer-events: none,不挡住页面的点击。 - 根元素是
role="progressbar",带aria-valuemin="0"、aria-valuemax="100"、aria-valuenow(当前进度取整)和aria-label="加载进度"。它不能聚焦,也没有键盘操作。 - 系统设置了“减少动态效果”时,去掉前进和淡出的过渡动画,计时不变。
- 服务端渲染时没有
window、document,start、finish、error、destroy都不做任何事,在路由守卫里调用也安全。 - 应用卸载(例如微前端的子应用卸载)时加载条不会自动消失,要调用
NsLoadingBar.destroy()。