FxSkeleton 骨架屏

在数据加载过程中显示占位骨架，避免页面空白或布局抖动，提供流畅的视觉过渡体验。

包含 FxSkeleton（容器）与 FxSkeletonItem（骨架单元）两个组件。

基础用法

默认展示 3 行段落骨架。

<template>
  <FxSkeleton />
  <br />
  <FxSkeleton style="--fx-skeleton-circle-size: 100px">
    <template #template>
      <FxSkeletonItem variant="circle" />
    </template>
  </FxSkeleton>
</template>

可配置行数

通过 rows 控制每组骨架的行数，实际渲染行数 = rows + 1（首行宽 33%，其余 61%）。

<template>
  <FxSkeleton :rows="5" />
</template>

动画

设置 animated 开启动画效果，骨架会出现 shimmer 流光动画。

<template>
  <FxSkeleton :rows="5" animated />
</template>

自定义模板

通过 template 插槽自定义骨架结构，配合 FxSkeletonItem 的不同 variant 组合出任意布局。建议骨架布局与真实 DOM 结构尽量接近，避免高度差引起的布局跳动。

<template>
  <FxSkeleton style="width: 240px">
    <template #template>
      <FxSkeletonItem variant="image" style="width: 240px; height: 240px" />
      <div style="padding: 14px">
        <FxSkeletonItem variant="p" style="width: 50%" />
        <div
          style="
            display: flex;
            align-items: center;
            justify-content: space-between;
          "
        >
          <FxSkeletonItem variant="text" style="margin-right: 16px" />
          <FxSkeletonItem variant="text" style="width: 30%" />
        </div>
      </div>
    </template>
  </FxSkeleton>
</template>

加载状态

loading 控制是否显示骨架屏：true 显示骨架，false 显示 default 插槽中的真实内容。

<template>
  <div style="display: flex; flex-direction: column; align-items: flex-start; gap: 8px">
    <div>
      <label style="margin-right: 16px">切换加载状态</label>
      <FxSwitch v-model="loading" />
    </div>
    <FxSkeleton style="width: 240px" :loading="loading" animated>
      <template #template>
        <FxSkeletonItem variant="image" style="width: 240px; height: 240px" />
        <div style="padding: 14px">
          <FxSkeletonItem variant="h3" style="width: 50%" />
          <div
            style="
              display: flex;
              align-items: center;
              justify-content: space-between;
              margin-top: 16px;
              height: 16px;
            "
          >
            <FxSkeletonItem variant="text" style="margin-right: 16px" />
            <FxSkeletonItem variant="text" style="width: 30%" />
          </div>
        </div>
      </template>
      <template #default>
        <FxCard :body-style="{ padding: '0px' }">
          <img
            src="https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png"
            style="width: 100%; border: none; border-radius: 0; margin-top: 0"
          />
          <div style="padding: 14px">
            <span>美味汉堡</span>
            <div style="display: flex; justify-content: space-between; align-items: center; margin-top: 13px">
              <span style="font-size: 13px; color: var(--fx-text-color-secondary)">{{ currentDate }}</span>
              <FxBtn size="small">操作按钮</FxBtn>
            </div>
          </div>
        </FxCard>
      </template>
    </FxSkeleton>
  </div>
</template>

<script lang="ts" setup>
import { ref } from "vue"

const loading = ref(true)
const currentDate = new Date().toDateString()
</script>

列表数据渲染

配合 count 可批量渲染多组骨架，常用于列表数据加载场景。不推荐渲染过多骨架，会影响性能与销毁耗时。

<template>
  <div style="display: flex; flex-direction: column; gap: 8px; width: 100%">
    <div>
      <FxBtn @click="setLoading">点击重新加载</FxBtn>
    </div>
    <FxSkeleton
      style="display: flex; gap: 8px"
      :loading="loading"
      animated
      :count="3"
    >
      <template #template>
        <div style="flex: 1">
          <FxSkeletonItem variant="image" style="height: 240px" />
          <div style="padding: 14px">
            <FxSkeletonItem variant="h3" style="width: 50%" />
            <div
              style="
                display: flex;
                align-items: center;
                justify-content: space-between;
                margin-top: 16px;
                height: 16px;
              "
            >
              <FxSkeletonItem variant="text" style="margin-right: 16px" />
              <FxSkeletonItem variant="text" style="width: 30%" />
            </div>
          </div>
        </div>
      </template>
      <template #default>
        <div style="display: flex; gap: 8px">
          <FxCard
            v-for="item in lists"
            :key="item.name"
            style="flex: 1"
            :body-style="{ padding: '0px' }"
          >
            <img
              :src="item.imgUrl"
              style="max-width: 100%; border: none; border-radius: 0; margin-top: 0"
            />
            <div style="padding: 14px">
              <span>{{ item.name }}</span>
              <div style="display: flex; justify-content: space-between; align-items: center; margin-top: 13px">
                <span style="font-size: 13px; color: var(--fx-text-color-secondary)">{{ currentDate }}</span>
                <FxBtn size="small">操作按钮</FxBtn>
              </div>
            </div>
          </FxCard>
        </div>
      </template>
    </FxSkeleton>
  </div>
</template>

<script lang="ts" setup>
import { onMounted, ref } from "vue"

interface ListItem {
  imgUrl: string
  name: string
}

const loading = ref(true)
const lists = ref<ListItem[]>([])
const currentDate = new Date().toDateString()

const setLoading = () => {
  loading.value = true
  setTimeout(() => {
    loading.value = false
  }, 2000)
}

onMounted(() => {
  loading.value = false
  lists.value = [
    {
      imgUrl:
        "https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg",
      name: "Deer",
    },
    {
      imgUrl:
        "https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg",
      name: "Horse",
    },
    {
      imgUrl:
        "https://fuss10.elemecdn.com/0/6f/e35ff375812e6b0020b6b4e8f9583jpeg.jpeg",
      name: "Mountain Lion",
    },
  ]
})
</script>

避免渲染抖动

当接口响应很快时，骨架屏刚渲染就被销毁，会产生闪烁。使用 throttle 延迟骨架屏显示来避免。

TIP

throttle 支持两种值：number（等同于 { leading: xxx }，控制骨架屏显示的节流）和 object（{ leading?: number, trailing?: number, initVal?: boolean }）。

<template>
  <div style="display: flex; flex-direction: column; align-items: flex-start; gap: 8px">
    <div>
      <label style="margin-right: 16px">切换加载状态</label>
      <FxSwitch v-model="loading" />
    </div>
    <FxSkeleton
      style="width: 240px"
      :loading="loading"
      animated
      :throttle="500"
    >
      <template #template>
        <FxSkeletonItem variant="image" style="width: 240px; height: 265px" />
        <div style="padding: 14px">
          <FxSkeletonItem variant="h3" style="width: 50%" />
          <div
            style="
              display: flex;
              align-items: center;
              justify-content: space-between;
              margin-top: 16px;
              height: 16px;
            "
          >
            <FxSkeletonItem variant="text" style="margin-right: 16px" />
            <FxSkeletonItem variant="text" style="width: 30%" />
          </div>
        </div>
      </template>
      <template #default>
        <FxCard :body-style="{ padding: '0px' }">
          <img
            src="https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png"
            style="width: 100%; border: none; border-radius: 0; margin-top: 0"
          />
          <div style="padding: 14px">
            <span>美味汉堡</span>
            <div style="display: flex; justify-content: space-between; align-items: center; margin-top: 13px">
              <span style="font-size: 13px; color: var(--fx-text-color-secondary)">{{ currentDate }}</span>
              <FxBtn size="small">操作按钮</FxBtn>
            </div>
          </div>
        </FxCard>
      </template>
    </FxSkeleton>
  </div>
</template>

<script lang="ts" setup>
import { ref } from "vue"

const loading = ref(false)
const currentDate = new Date().toDateString()
</script>

初始渲染即显示

当 loading 初始值为 true 时，可设 throttle: { initVal: true, leading: xxx } 控制初始骨架屏立即显示，不受节流延迟影响。

<template>
  <div style="display: flex; flex-direction: column; align-items: flex-start; gap: 8px">
    <div>
      <label style="margin-right: 16px">切换加载状态</label>
      <FxSwitch v-model="loading" />
    </div>
    <FxSkeleton
      style="width: 240px"
      :loading="loading"
      animated
      :throttle="{ leading: 500, initVal: true }"
    >
      <template #template>
        <FxSkeletonItem variant="image" style="width: 240px; height: 265px" />
        <div style="padding: 14px">
          <FxSkeletonItem variant="h3" style="width: 50%" />
          <div
            style="
              display: flex;
              align-items: center;
              justify-content: space-between;
              margin-top: 16px;
              height: 16px;
            "
          >
            <FxSkeletonItem variant="text" style="margin-right: 16px" />
            <FxSkeletonItem variant="text" style="width: 30%" />
          </div>
        </div>
      </template>
      <template #default>
        <FxCard :body-style="{ padding: '0px' }">
          <img
            src="https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png"
            style="width: 100%; border: none; border-radius: 0; margin-top: 0"
          />
          <div style="padding: 14px">
            <span>美味汉堡</span>
            <div style="display: flex; justify-content: space-between; align-items: center; margin-top: 13px">
              <span style="font-size: 13px; color: var(--fx-text-color-secondary)">{{ currentDate }}</span>
              <FxBtn size="small">操作按钮</FxBtn>
            </div>
          </div>
        </FxCard>
      </template>
    </FxSkeleton>
  </div>
</template>

<script lang="ts" setup>
import { ref } from "vue"

const loading = ref(true)
const currentDate = new Date().toDateString()
</script>

显示/隐藏平滑过渡

设置 throttle: { leading: xxx, trailing: xxx } 同时控制骨架屏的显示与隐藏延迟，使加载切换更平滑。

<template>
  <div style="display: flex; flex-direction: column; align-items: flex-start; gap: 8px">
    <div>
      <label style="margin-right: 16px">切换加载状态</label>
      <FxSwitch v-model="loading" />
    </div>
    <FxSkeleton
      style="width: 240px"
      :loading="loading"
      animated
      :throttle="{ leading: 500, trailing: 500, initVal: true }"
    >
      <template #template>
        <FxSkeletonItem variant="image" style="width: 240px; height: 265px" />
        <div style="padding: 14px">
          <FxSkeletonItem variant="h3" style="width: 50%" />
          <div
            style="
              display: flex;
              align-items: center;
              justify-content: space-between;
              margin-top: 16px;
              height: 16px;
            "
          >
            <FxSkeletonItem variant="text" style="margin-right: 16px" />
            <FxSkeletonItem variant="text" style="width: 30%" />
          </div>
        </div>
      </template>
      <template #default>
        <FxCard :body-style="{ padding: '0px' }">
          <img
            src="https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png"
            style="width: 100%; border: none; border-radius: 0; margin-top: 0"
          />
          <div style="padding: 14px">
            <span>美味汉堡</span>
            <div style="display: flex; justify-content: space-between; align-items: center; margin-top: 13px">
              <span style="font-size: 13px; color: var(--fx-text-color-secondary)">{{ currentDate }}</span>
              <FxBtn size="small">操作按钮</FxBtn>
            </div>
          </div>
        </FxCard>
      </template>
    </FxSkeleton>
  </div>
</template>

<script lang="ts" setup>
import { ref } from "vue"

const loading = ref(false)
const currentDate = new Date().toDateString()
</script>

FxSkeleton API

Attributes

属性	说明	类型	默认值
animated	是否开启动画	boolean	false
count	渲染多少组骨架	number	1
loading	是否加载中（false 时显示真实 DOM）	boolean	true
rows	每组骨架的行数（仅未传 template 插槽时生效）	number	3
throttle	渲染延迟（ms）。数字等同于 { leading: xxx }，也可设 { leading, trailing, initVal }	number | { leading?: number, trailing?: number, initVal?: boolean }	0

Slots

名称	说明	作用域
default	加载完成后显示的真实 DOM	$attrs
template	自定义骨架模板	{ key: number }

Exposes

名称	说明	类型
uiLoading	含节流延迟后的实际 loading 状态	Ref<boolean>

FxSkeletonItem API

FxSkeletonItem 自带变体样式，可脱离 FxSkeleton 独立使用（常用于自定义骨架结构）。

Attributes

| 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | | variant | 当前渲染的骨架类型 | 'p' \| 'text' \| 'h1' \| 'h3' \| 'h5' \| 'caption' \| 'button' \| 'image' \| 'circle' \| 'rect' | text |

variant 说明

类型	形态	默认尺寸
p	段落行	宽 100%，高 16px
text	文本行	宽 100%，高 13px
h1	一级标题	宽 50%，高 20px，上边距 16px
h3	三级标题	宽 50%，高 18px，上边距 16px
h5	五级标题	宽 50%，高 16px
caption	说明文字	宽 50%，高 12px
button	按钮	宽 64px，高 40px
image	图片占位	宽自适应，居中显示图标（22% SVG）
circle	圆形（头像）	由 --fx-skeleton-circle-size 控制，默认 48px
rect	矩形	宽 100%，高 16px（继承 item 默认值）

CSS 变量

变量	说明	默认值
--fx-skeleton-color	骨架底色	var(--color-fill-light)
--fx-skeleton-to-color	动画高亮色	var(--color-fill-darker)
--fx-skeleton-circle-size	圆形变体尺寸	48px

局部引入

import { FxSkeleton, FxSkeletonItem } from "@fx/components"