Skeleton 骨架屏
数据加载期间,在内容的位置显示灰色的占位图形,加载完成后换成真实内容。
引入
import { NsSkeleton, NsSkeletonItem } from '@ns/ui'
基础用法
不写插槽时显示默认布局:一个圆形头像、一行标题和若干行段落。
<template>
<NsSkeleton />
</template>
包裹真实内容
把真实内容放进默认插槽,用 loading 控制:加载中显示骨架,加载完成显示真实内容。点“重新加载”模拟一次 2 秒的请求,也可以直接用开关切换。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSkeleton, NsSpace, NsSwitch } from '@ns/ui'
const loading = ref(true)
const reload = () => {
loading.value = true
// 用定时器模拟请求
setTimeout(() => {
loading.value = false
}, 2000)
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap align="center">
<NsSwitch v-model="loading" />
<span>loading:{{ loading }}</span>
<NsButton size="small" :disabled="loading" @click="reload">重新加载</NsButton>
</NsSpace>
<NsSkeleton :loading="loading">
<div>
<h4>文章标题</h4>
<p>文章内容……</p>
</div>
</NsSkeleton>
</NsSpace>
</template>
段落行数和动画
rows 设置默认布局里段落的行数,默认 3 行,最后一行短一些;animated 控制闪光动画,默认开启,设为 false 时是静止的灰色块。
<template>
<NsSpace direction="vertical" fill>
<NsSkeleton :rows="1" />
<NsSkeleton :rows="5" />
<NsSkeleton :animated="false" />
</NsSpace>
</template>
用下面的控件调整行数、开关动画:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsInputNumber, NsSkeleton, NsSpace } from '@ns/ui'
const rows = ref(3)
const animated = ref(true)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap align="center">
<span>rows</span>
<NsInputNumber v-model="rows" :min="1" :max="8" size="small" />
<NsCheckbox v-model="animated">animated</NsCheckbox>
</NsSpace>
<NsSkeleton :rows="rows" :animated="animated" />
</NsSpace>
</template>
自定义模板
用 template 插槽替换默认布局,里面用 NsSkeletonItem 拼出和真实内容相近的形状。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSkeleton, NsSkeletonItem, NsSpace, NsSwitch } from '@ns/ui'
const loading = ref(true)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace align="center">
<NsSwitch v-model="loading" />
<span>加载中</span>
</NsSpace>
<NsSkeleton :loading="loading">
<template #template>
<div style="display: flex; gap: 16px">
<NsSkeletonItem variant="circle" :size="48" />
<div style="flex: 1">
<NsSkeletonItem variant="text" width="40%" />
<NsSkeletonItem variant="text" />
</div>
</div>
</template>
<div>真实内容</div>
</NsSkeleton>
</NsSpace>
</template>
多个
count 把默认布局或 template 插槽重复多次,适合列表。
<template>
<NsSkeleton :count="3" />
</template>
和 template 插槽一起用时,每一份都是插槽里的内容。写在 NsSkeleton 上的 style、class 加在骨架容器上,可以用来排版,例如把 3 张卡片排成一行:
<template>
<NsSkeleton
:count="3"
style="display: grid; grid-template-columns: repeat(auto-fill, minmax(160px, 1fr)); gap: 16px"
>
<template #template>
<div>
<NsSkeletonItem variant="image" :height="100" />
<NsSkeletonItem variant="text" width="70%" style="margin-top: 12px" />
<NsSkeletonItem variant="text" width="40%" style="margin-top: 8px" />
</div>
</template>
</NsSkeleton>
</template>
延迟显示
throttle 设置延迟多少毫秒后才显示骨架屏,延迟期间显示默认插槽的内容。加载很快完成时,骨架屏不会一闪而过。
下面的 throttle 是 500ms:“快速加载”只用 200ms,骨架屏不会出现;“慢速加载”用 2 秒,500ms 后出现骨架屏。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSkeleton, NsSpace } from '@ns/ui'
const loading = ref(false)
// 发起请求时把 loading 设为 true,请求结束设为 false,这里用定时器模拟
const load = (ms: number) => {
loading.value = true
setTimeout(() => {
loading.value = false
}, ms)
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton :disabled="loading" @click="load(200)">快速加载</NsButton>
<NsButton :disabled="loading" @click="load(2000)">慢速加载</NsButton>
</NsSpace>
<NsSkeleton :loading="loading" :throttle="500">
<div>真实内容</div>
</NsSkeleton>
</NsSpace>
</template>
SkeletonItem 的形状
NsSkeletonItem 可以单独使用,variant 有 text(默认)、circle、rect、image 四种。不传尺寸时的默认尺寸:
| variant | 默认尺寸 |
|---|---|
| text | 宽 100%、高 16px,4px 圆角 |
| circle | 40px × 40px,圆形 |
| rect | 宽 100%、高 16px,6px 圆角 |
| image | 宽 100%、高 120px,6px 圆角,中间有图标 |
下面每一行是一种形状,都用默认尺寸:
<template>
<NsSpace direction="vertical" fill>
<div class="row">
<span class="row-label">text</span>
<NsSkeletonItem variant="text" />
</div>
<div class="row">
<span class="row-label">circle</span>
<NsSkeletonItem variant="circle" />
</div>
<div class="row">
<span class="row-label">rect</span>
<NsSkeletonItem variant="rect" />
</div>
<div class="row">
<span class="row-label">image</span>
<NsSkeletonItem variant="image" />
</div>
</NsSpace>
</template>
<style scoped>
.row {
display: flex;
align-items: center;
gap: var(--ns-spacing-3);
}
.row-label {
flex-shrink: 0;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
单独使用的 NsSkeletonItem 没有闪光动画;放在 NsSkeleton 的 template 插槽里时,跟随 NsSkeleton 的 animated。
SkeletonItem 的尺寸
width、height 分别设置宽高,size 同时设置宽高(优先于 width、height)。数字按 px 处理,字符串原样使用。
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap align="center">
<NsSkeletonItem variant="text" :width="200" />
<NsSkeletonItem variant="circle" :size="64" />
<NsSkeletonItem variant="circle" size="2em" />
<NsSkeletonItem variant="rect" :width="120" :height="60" />
<!-- size 优先:显示成 48px × 48px,width、height 不生效 -->
<NsSkeletonItem variant="rect" :size="48" :width="200" :height="20" />
</NsSpace>
<NsSkeletonItem variant="image" width="100%" :height="160" />
</NsSpace>
</template>
NsSkeleton Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| loading | boolean | true | 是否处于加载中;为 false 时显示默认插槽的内容 |
| animated | boolean | true | 是否显示闪光动画 |
| count | number | 1 | 默认布局或 template 插槽重复的次数 |
| rows | number | 3 | 默认布局里段落的行数 |
| throttle | number | 0 | 延迟多少毫秒后显示骨架屏,延迟期间显示默认插槽的内容 |
NsSkeletonItem Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| variant | 'text' | 'circle' | 'rect' | 'image' | 'text' | 形状 |
| width | string | number | - | 宽度,数字按 px 处理 |
| height | string | number | - | 高度,数字按 px 处理 |
| size | string | number | - | 同时设置宽高,优先于 width、height |
NsSkeleton Slots
| 插槽 | 说明 |
|---|---|
| default | 真实内容,loading 为 false 时(以及延迟期间)显示 |
| template | 加载中时替换默认布局,按 count 重复 |
类型
import type { SkeletonProps, SkeletonItemProps, SkeletonItemVariant } from '@ns/ui'
type SkeletonItemVariant = 'text' | 'circle' | 'rect' | 'image'
interface SkeletonProps {
loading?: boolean
animated?: boolean
count?: number
rows?: number
throttle?: number
}
interface SkeletonItemProps {
variant?: SkeletonItemVariant
width?: string | number
height?: string | number
size?: string | number
}
注意事项
- 写在
NsSkeleton上的class、id、style等属性只加到骨架容器.ns-skeleton上;loading为false时不会透传到真实内容上,真实内容的样式请写在插槽里的元素上。 - 加载中只有一个
.ns-skeleton容器,count个布局都在里面;容器带aria-busy="true"。 - 骨架的颜色可以用 CSS 变量覆盖:
--ns-skeleton-color是底色,--ns-skeleton-to-color是闪光的高亮色。 - 默认布局固定带一个圆形头像;不需要头像时用
template插槽自己拼。
优化点
- [ ] 支持更丰富的骨架布局模板(可配置是否显示头像、标题宽度等)
- [x] 支持骨架渐变动画(
animated) - [ ] 支持响应式骨架布局