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.
Spin 加载中
在一块区域上显示转圈的加载图标。可以单独放在页面上,也可以包住一段内容,加载时在内容上盖一层半透明遮罩。
引入
import { NsSpin } from '@ns/ui'
基础用法
不写内容时,NsSpin 只显示一个转圈图标,是行内块元素。spinning 默认是 true,改成 false 时整个组件不渲染。
<script setup lang="ts">
import { NsSpin } from '@ns/ui'
</script>
<template>
<NsSpin />
</template>
用开关切换 spinning:关掉时图标直接消失,两边的文字会靠拢,不留占位。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsSpin, NsSwitch } from '@ns/ui'
const spinning = ref(true)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace align="center">
<NsSwitch v-model="spinning" />
<span>spinning:{{ spinning }}</span>
</NsSpace>
<div>前面的文字<NsSpin :spinning="spinning" size="small" />后面的文字</div>
</NsSpace>
</template>
尺寸
size 有 small、default、large 三种,图标分别是 16、24、32 像素,提示文字分别是 12、14、16 像素。根元素带 ns-spin--small、ns-spin--default 或 ns-spin--large 类名,用 indicator 插槽时可以按根元素的尺寸类写样式,例如 .ns-spin--large .my-indicator { font-size: 32px; }(见“自定义图标”)。
<script setup lang="ts">
import { NsSpin, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace wrap size="large" align="center">
<NsSpin size="small" />
<NsSpin />
<NsSpin size="large" />
</NsSpace>
<NsSpace wrap size="large" align="end">
<NsSpin size="small" tip="small" />
<NsSpin tip="default" />
<NsSpin size="large" tip="large" />
</NsSpace>
</NsSpace>
</template>
提示文字
tip 显示在图标下方。
<script setup lang="ts">
import { NsSpin } from '@ns/ui'
</script>
<template>
<NsSpin tip="加载中..." />
</template>
包裹内容
把内容放进默认插槽后,NsSpin 变成块级元素。spinning 为 true 时在内容上面盖一层半透明遮罩,图标和文字显示在遮罩中间:内容还能隐约看到,但鼠标点不到。spinning 为 false 时只显示内容。遮罩出现和消失时有 0.3 秒的淡入淡出。
切换加载状态的按钮要放在 NsSpin 外面,放在里面的话加载时会被遮罩挡住。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsSpin } from '@ns/ui'
const spinning = ref(true)
</script>
<template>
<NsSpace direction="vertical" fill>
<div>
<NsButton @click="spinning = !spinning">切换加载状态</NsButton>
</div>
<NsSpin :spinning="spinning" tip="正在加载...">
<div style="padding: 24px">被 Spin 包裹的内容区域</div>
</NsSpin>
</NsSpace>
</template>
包裹内容时 size 同样生效,遮罩里的图标和文字跟着变大变小:
<template>
<NsSpace direction="vertical" fill>
<NsSpin size="small" tip="small">
<div class="block">内容区域</div>
</NsSpin>
<NsSpin tip="default">
<div class="block">内容区域</div>
</NsSpin>
<NsSpin size="large" tip="large">
<div class="block">内容区域</div>
</NsSpin>
</NsSpace>
</template>
<style scoped>
.block {
padding: var(--ns-spacing-6);
border: var(--ns-border-width) var(--ns-border-style) var(--ns-border-color-light);
border-radius: var(--ns-border-radius);
}
</style>
模拟加载数据
点“刷新”后加载 1.5 秒,期间内容盖上遮罩,刷新按钮也显示加载中,加载完换成新数据。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsSpin } from '@ns/ui'
const loading = ref(false)
const updatedAt = ref('尚未刷新')
const visits = ref(1280)
const refresh = () => {
loading.value = true
// 用定时器模拟请求
setTimeout(() => {
visits.value += Math.floor(Math.random() * 100)
updatedAt.value = new Date().toLocaleTimeString()
loading.value = false
}, 1500)
}
</script>
<template>
<NsSpace direction="vertical" fill>
<div>
<NsButton type="primary" icon="refresh" :loading="loading" @click="refresh">刷新</NsButton>
</div>
<NsSpin :spinning="loading" tip="数据加载中...">
<div class="panel">
<div class="panel__value">{{ visits }}</div>
<div class="panel__label">今日访问量(更新于 {{ updatedAt }})</div>
</div>
</NsSpin>
</NsSpace>
</template>
<style scoped>
.panel {
padding: var(--ns-spacing-6);
text-align: center;
background-color: var(--ns-fill-color-light);
border-radius: var(--ns-border-radius);
}
.panel__value {
font-size: var(--ns-font-size-3xl);
font-weight: var(--ns-font-weight-semibold);
color: var(--ns-text-color);
}
.panel__label {
margin-top: var(--ns-spacing-2);
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
延迟显示
delay 是 spinning 变成 true 之后再等多少毫秒才显示。等待期间 spinning 又变回 false 的话,图标和遮罩不会出现。加载很快时用它避免遮罩闪一下。spinning 变成 false 时立即隐藏,不受 delay 影响。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsSpin } from '@ns/ui'
const spinning = ref(false)
const load = (ms: number) => {
spinning.value = true
window.setTimeout(() => (spinning.value = false), ms)
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<!-- 加载 200ms,短于 delay,遮罩不会出现 -->
<NsButton @click="load(200)">快速加载</NsButton>
<!-- 加载 2 秒,500ms 后出现遮罩 -->
<NsButton @click="load(2000)">慢速加载</NsButton>
</NsSpace>
<NsSpin :spinning="spinning" :delay="500">
<div style="padding: 24px">delay 为 500ms</div>
</NsSpin>
</NsSpace>
</template>
自定义图标
indicator 插槽替换默认的转圈图标。插槽里的内容不会自动旋转,需要旋转时自己加,例如 NsIcon 的 spin。
<script setup lang="ts">
import { NsIcon, NsSpin } from '@ns/ui'
</script>
<template>
<NsSpin tip="刷新中">
<template #indicator>
<NsIcon name="refresh" spin size="xl" />
</template>
</NsSpin>
</template>
插槽内容的大小和颜色不随 size 变,要分尺寸时按根元素的尺寸类(ns-spin--small / default / large)写样式:
<template>
<NsSpace wrap size="large" align="end">
<NsSpin size="small" tip="small">
<template #indicator>
<NsIcon name="refresh" spin class="my-indicator" />
</template>
</NsSpin>
<NsSpin tip="default">
<template #indicator>
<NsIcon name="refresh" spin class="my-indicator" />
</template>
</NsSpin>
<NsSpin size="large" tip="large">
<template #indicator>
<NsIcon name="refresh" spin class="my-indicator" />
</template>
</NsSpin>
</NsSpace>
</template>
<style scoped>
.my-indicator {
color: var(--ns-color-primary);
}
.ns-spin--small .my-indicator {
font-size: 16px;
}
.ns-spin--default .my-indicator {
font-size: 24px;
}
.ns-spin--large .my-indicator {
font-size: 32px;
}
</style>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| spinning | boolean | true | 是否处于加载中 |
| size | 'large' | 'default' | 'small' | — | 图标和提示文字的尺寸。不写时跟随 NsConfigProvider 的 size,都没有时是 'default' |
| tip | string | — | 图标下方的提示文字 |
| delay | number | 0 | spinning 变成 true 后延迟多少毫秒再显示,为 0 时立即显示 |
Slots
| 插槽 | 说明 |
|---|---|
| default | 被包裹的内容。有内容时加载状态显示为盖在内容上的半透明遮罩 |
| indicator | 替换默认的转圈图标 |
类型
import type { SpinSize, SpinProps } from '@ns/ui'
type SpinSize = 'large' | 'default' | 'small'
interface SpinProps {
size?: SpinSize
spinning?: boolean
tip?: string
delay?: number
}
注意事项
- 组件没有事件,也没有暴露方法,加载状态只由
spinning控制。 - 不写
size时跟随NsConfigProvider的size;不跟随NsForm的尺寸(加载中不是表单控件)。 - 不包裹内容时,
spinning为false就什么都不渲染,不会留出占位。 - 包裹内容时,遮罩只盖住
NsSpin自己这一块,页面其他地方照常能点。遮罩的z-index是 10,内容里有层级更高的定位元素时会盖在遮罩上面。 - 遮罩只挡鼠标。内容里的按钮、输入框仍然能用 Tab 键聚焦、用键盘操作,加载期间不允许提交时要自己禁用它们。
- 无障碍:加载中时包裹层带
aria-busy="true",图标和文字所在的元素是role="status",屏幕阅读器会读出提示文字。