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.
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()。