Loading 加载
加载数据时在区域或整个窗口上盖一层遮罩,中间显示转圈图标和文字。有三种用法:写成组件、调用 NsLoading.service()、在元素上加 v-loading 指令。
引入
import { NsLoading, vLoading } from '@ns/ui'
NsLoading是组件,同时带有服务方法NsLoading.service(options)。服务方法也单独导出为NsLoadingService,两者是同一个函数。vLoading是指令。全量注册app.use(NsUI)时会自动注册成v-loading;按需引入时的注册方式见下面的“v-loading 指令”一节。
基础用法
组件用法:把 NsLoading 放进要盖住的区域,用 visible 控制显示,可以反复开关,关闭时有 0.3 秒的淡出。
遮罩是 position: absolute,上下左右都是 0,铺满最近的定位父元素。组件不会改父元素的样式,所以父元素要自己写上 position: relative,否则遮罩会铺到更外层的定位元素上。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsLoading } from '@ns/ui'
const loading = ref(false)
</script>
<template>
<div style="margin-bottom: 12px">
<NsButton @click="loading = !loading">{{ loading ? '关闭' : '打开' }}</NsButton>
</div>
<div style="position: relative; height: 120px">
<div style="padding: 16px">内容区域</div>
<NsLoading :visible="loading" />
</div>
</template>
文字、图标和背景
text显示在图标下方。spinner是@ns/icons里的图标名,默认是'loading'。图标会一直旋转;名字写错时用默认的 loading 图标。background是遮罩的背景色。不传时是跟随主题的底色(页面背景色,90% 不透明),暗色主题下也是深色。
<script setup lang="ts">
import { NsLoading } from '@ns/ui'
</script>
<template>
<div class="grid">
<div>
<div class="box"><NsLoading visible /></div>
<p class="caption">默认</p>
</div>
<div>
<div class="box"><NsLoading visible text="加载中" /></div>
<p class="caption">text</p>
</div>
<div>
<div class="box"><NsLoading visible text="刷新中" spinner="refresh" /></div>
<p class="caption">spinner="refresh"</p>
</div>
<div>
<div class="box"><NsLoading visible text="设置中" spinner="setting" /></div>
<p class="caption">spinner="setting"</p>
</div>
<div>
<div class="box"><NsLoading visible text="名字写错" spinner="not-exist" /></div>
<p class="caption">图标名写错时用默认图标</p>
</div>
<div>
<div class="box">
<NsLoading visible text="深色背景" spinner="refresh" background="rgba(0, 0, 0, 0.5)" />
</div>
<p class="caption">background</p>
</div>
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(160px, 1fr));
gap: var(--ns-spacing-3);
}
.box {
position: relative;
height: 120px;
border: var(--ns-border-width) var(--ns-border-style) var(--ns-border-color);
border-radius: var(--ns-border-radius);
overflow: hidden;
}
.caption {
margin: var(--ns-spacing-2) 0 0;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
text-align: center;
}
</style>
全屏
组件加上 fullscreen 后,遮罩改成 position: fixed,铺满整个窗口,和组件写在哪里无关。下面的示例 2 秒后自动关闭。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsLoading } from '@ns/ui'
const loading = ref(false)
const open = () => {
loading.value = true
window.setTimeout(() => (loading.value = false), 2000)
}
</script>
<template>
<NsButton @click="open">全屏加载 2 秒</NsButton>
<NsLoading :visible="loading" fullscreen text="正在加载..." />
</template>
用方法控制
通过组件的 ref 调用 show()、close() 打开、关闭遮罩,visible 读出遮罩当前是否在页面上(淡出的 0.3 秒里仍是 true)。这两个方法不改 visible 属性;只用方法控制时可以不传 visible(默认 false),下面的示例就没有传。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsLoading, NsSpace } from '@ns/ui'
interface LoadingExpose {
show: () => void
close: () => void
visible: boolean
}
const loadingRef = ref<LoadingExpose>()
</script>
<template>
<NsSpace wrap style="margin-bottom: 12px">
<NsButton @click="loadingRef?.show()">show()</NsButton>
<NsButton @click="loadingRef?.close()">close()</NsButton>
<span>visible:{{ loadingRef?.visible ?? false }}</span>
</NsSpace>
<div style="position: relative; height: 120px">
<div style="padding: 16px">内容区域</div>
<NsLoading ref="loadingRef" text="用方法打开的" />
</div>
</template>
服务方式
NsLoading.service(options) 在代码里打开遮罩,返回一个实例,调用它的 close() 关闭。不用在模板里写组件,适合在请求函数、路由守卫里用。
全屏加载
不传 target 时遮罩挂在 document.body 上。要让遮罩固定盖住窗口、页面滚动时不跟着走,传 fullscreen: true。lock: true 会在加载期间锁定页面滚动,关闭后恢复。
下面用定时器模拟一个 2 秒的请求,请求结束后在 finally 里关闭:
<script setup lang="ts">
import { NsButton, NsLoading } from '@ns/ui'
// 模拟一个 2 秒的请求
const fetchData = () => new Promise((resolve) => setTimeout(resolve, 2000))
const load = async () => {
const loading = NsLoading.service({ fullscreen: true, lock: true, text: '正在加载...' })
try {
await fetchData()
} finally {
loading.close()
}
}
</script>
<template>
<NsButton @click="load">全屏加载 2 秒</NsButton>
</template>
局部加载
target 传 DOM 元素或 CSS 选择器,遮罩挂到这个元素里面,铺满它。目标元素是 static 定位时,打开期间临时改成 relative,最后一个挂在它上面的遮罩关闭后还原;打开期间目标元素上还会加上 ns-loading-parent 类。选择器找不到元素时在控制台警告,改为挂到 document.body。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsLoading, NsSpace } from '@ns/ui'
const box = ref<HTMLElement>()
const byElement = () => {
const loading = NsLoading.service({ target: box.value, text: 'target 传元素' })
setTimeout(() => loading.close(), 2000)
}
const bySelector = () => {
const loading = NsLoading.service({
target: '#loading-service-target',
text: 'target 传选择器'
})
setTimeout(() => loading.close(), 2000)
}
</script>
<template>
<NsSpace wrap style="margin-bottom: 12px">
<NsButton @click="byElement">传元素,加载 2 秒</NsButton>
<NsButton @click="bySelector">传选择器,加载 2 秒</NsButton>
</NsSpace>
<div id="loading-service-target" ref="box" class="box">表格区域</div>
</template>
<style scoped>
.box {
height: 120px;
padding: 16px;
border: var(--ns-border-width) var(--ns-border-style) var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
</style>
更新文字
实例的 update() 可以在加载过程中改文字、图标和背景色。
<script setup lang="ts">
import { NsButton, NsLoading } from '@ns/ui'
const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
const run = async () => {
const loading = NsLoading.service({ fullscreen: true, text: '第 1 步:读取数据' })
await wait(1000)
loading.update({ text: '第 2 步:保存', spinner: 'save' })
await wait(1000)
loading.update({ text: '第 3 步:完成', spinner: 'check', background: 'rgba(0, 0, 0, 0.6)' })
await wait(800)
loading.close()
}
</script>
<template>
<NsButton @click="run">分 3 步加载</NsButton>
</template>
全屏单例
全屏的遮罩(fullscreen: true,或者没传 target、挂在 document.body 上)同一时间只有一个。已经有一个打开着(包括正在淡出的)时再调用 NsLoading.service(),拿到的是同一个实例:文字、图标、背景按这次的配置更新,正在进行的关闭会被取消。任何一处调用 close() 都会把它关掉。
挂到其他元素上的遮罩不是单例,每次调用都新建一个,要各自关闭。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsLoading } from '@ns/ui'
const result = ref('')
const run = () => {
const first = NsLoading.service({ fullscreen: true, text: '第一次调用' })
setTimeout(() => {
const second = NsLoading.service({ fullscreen: true, text: '第二次调用:还是同一个遮罩' })
result.value = `两次调用拿到的是同一个实例:${first === second}`
setTimeout(() => second.close(), 1500)
}, 1000)
}
</script>
<template>
<NsButton @click="run">连续调用两次</NsButton>
<p style="margin-top: 12px">{{ result || '点按钮看看' }}</p>
</template>
v-loading 指令
指令的值是布尔值,为 true 时在元素里盖上遮罩,为 false 时淡出后移除。元素是 static 定位时,打开期间临时改成 relative,关闭后还原。
全量注册 app.use(NsUI) 时指令已经注册好了。按需引入时有两种注册方式:
- 全局注册:
app.directive('loading', vLoading)。 - 在
<script setup>里import { vLoading } from '@ns/ui',模板里直接用v-loading。
文字、图标、背景色通过元素上的属性设置,不写时和组件的默认值一样:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, vLoading } from '@ns/ui'
const loading = ref(false)
</script>
<template>
<div style="margin-bottom: 12px">
<NsButton @click="loading = !loading">{{ loading ? '关闭' : '打开' }}</NsButton>
</div>
<div class="grid">
<div v-loading="loading" class="box">不写属性</div>
<div
v-loading="loading"
element-loading-text="拼命加载中"
element-loading-spinner="refresh"
element-loading-background="rgba(0, 0, 0, 0.6)"
class="box"
>
写了文字、图标和背景色
</div>
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
gap: var(--ns-spacing-3);
}
.box {
height: 120px;
padding: 16px;
border: var(--ns-border-width) var(--ns-border-style) var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
</style>
element-loading-text、element-loading-spinner、element-loading-background 在所在组件每次更新时重新读取,绑定的值变了,遮罩上的文字跟着变。element-loading-fullscreen="true" 让遮罩铺满窗口,它只在遮罩创建时读取。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, vLoading } from '@ns/ui'
const loading = ref(false)
const percent = ref(0)
const fullscreen = ref(false)
const start = () => {
percent.value = 0
loading.value = true
const timer = setInterval(() => {
percent.value += 20
if (percent.value >= 100) {
clearInterval(timer)
loading.value = false
}
}, 400)
}
const openFullscreen = () => {
fullscreen.value = true
setTimeout(() => (fullscreen.value = false), 2000)
}
</script>
<template>
<NsSpace wrap style="margin-bottom: 12px">
<NsButton :disabled="loading" @click="start">开始加载</NsButton>
<NsButton @click="openFullscreen">全屏加载 2 秒</NsButton>
</NsSpace>
<div v-loading="loading" :element-loading-text="`已加载 ${percent}%`" class="box">内容区域</div>
<div
v-loading="fullscreen"
element-loading-fullscreen="true"
element-loading-text="全屏加载中,2 秒后关闭"
/>
</template>
<style scoped>
.box {
height: 120px;
padding: 16px;
border: var(--ns-border-width) var(--ns-border-style) var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
</style>
Props
组件用法的属性。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| visible | boolean | false | 是否显示。可以反复开关,关闭时淡出 0.3 秒。只用 show()、close() 控制时可以不传 |
| text | string | — | 图标下方的文字 |
| spinner | string | 'loading' | 图标名,取 @ns/icons 里的图标;写错时用默认的 loading 图标 |
| background | string | — | 遮罩背景色。不传时跟随主题 |
| fullscreen | boolean | false | 为 true 时遮罩 fixed 铺满窗口;为 false 时 absolute 铺满最近的定位父元素 |
组件暴露的方法
通过组件的 ref 调用:
| 名称 | 类型 | 说明 |
|---|---|---|
| show | () => void | 显示遮罩。正在淡出时调用会取消关闭 |
| close | () => void | 淡出后隐藏遮罩。已经隐藏或正在淡出时调用不做任何事 |
| visible | boolean | 遮罩当前是否在页面上(淡出过程中仍是 true),只用来读取 |
show()、close() 不会改 visible 属性。之后 visible 属性再变化时,以属性的新值为准。
NsLoading.service 配置项
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| target | HTMLElement | string | document.body | 遮罩挂到哪个元素上。字符串按 CSS 选择器查找,找不到时警告并改用 document.body |
| text | string | — | 图标下方的文字 |
| spinner | string | 'loading' | 图标名,写错时用默认的 loading 图标 |
| background | string | — | 遮罩背景色。不传时跟随主题 |
| fullscreen | boolean | false | 为 true 时遮罩 fixed 铺满窗口 |
| lock | boolean | false | 加载期间锁定页面滚动,关闭后恢复。只对全屏遮罩(fullscreen: true 或挂在 body 上)生效 |
NsLoading.service 返回值
返回 LoadingInstance:
| 方法 | 类型 | 说明 |
|---|---|---|
| close | () => void | 淡出 0.3 秒后移除遮罩,还原目标元素的定位和页面滚动。重复调用只关一次 |
| update | (options: Partial<LoadingProps>) => void | 更新 text、spinner、background、fullscreen;传 visible: true 可以取消正在进行的关闭 |
v-loading 属性
| 属性 | 说明 |
|---|---|
| element-loading-text | 图标下方的文字。所在组件每次更新时重新读取,改了会跟着变 |
| element-loading-spinner | 图标名,不写时是 'loading'。所在组件每次更新时重新读取 |
| element-loading-background | 遮罩背景色,不写时跟随主题。所在组件每次更新时重新读取 |
| element-loading-fullscreen | 写 "true" 时遮罩 fixed 铺满窗口。只在遮罩创建时读取,之后改了不生效 |
类型
import type {
LoadingOptions,
LoadingInstance,
LoadingProps,
LoadingDirectiveBinding,
LoadingServiceFn
} from '@ns/ui'
interface LoadingOptions {
target?: HTMLElement | string
text?: string
spinner?: string
background?: string
fullscreen?: boolean
lock?: boolean
}
interface LoadingInstance {
close: () => void
update: (options: Partial<LoadingProps>) => void
}
interface LoadingProps {
text?: string
spinner?: string
background?: string
fullscreen?: boolean
visible: boolean
}
interface LoadingDirectiveBinding {
value: boolean
oldValue?: boolean
arg?: string
modifiers?: Record<string, boolean>
}
type LoadingServiceFn = (options: LoadingOptions) => LoadingInstance
另外导出了 NsLoadingComponent,和 NsLoading 是同一个组件。
注意事项
- 全屏 service 是单例,任何一处调用
close()都会把它关掉。多个并发请求共用全屏遮罩时,先结束的那个会把遮罩关掉,后面的请求还没完成。 - 关闭 service 要用
close()。update({ visible: false })只把遮罩隐藏,不会移除,也不会还原目标元素的定位。 update()不能改target和lock,这两项只在打开时生效。- 组件没有插槽,图标只能通过
spinner传图标名。 - 组件用法和指令都不会锁定页面滚动,只有 service 的
lock会。 - 元素卸载时,它上面的
v-loading遮罩立即移除,不等淡出。 - 遮罩的层级:直接在模板里用
<NsLoading>组件时读NsConfigProvider的zIndex,没设时是 2000;v-loading指令和NsLoadingService是单独创建的应用,读不到 ConfigProvider,固定是 2000。层级和对话框相同时,谁盖住谁取决于它们在 DOM 里的先后。 - 无障碍:遮罩是
role="status"、aria-busy="true",屏幕阅读器会读出文字。遮罩只挡鼠标,被盖住的按钮、输入框仍然能用 Tab 键聚焦。
优化点
- [ ]
v-loading支持.fullscreen、.lock修饰符 - [ ]
v-loading支持传对象配置,不用写一组element-loading-*属性 - [ ] 支持用插槽或组件自定义加载图标