xiaoye-components

Appearance

Skeleton 骨架屏 ​

xy-skeleton 用于承接"结构已知、内容未到"的加载占位，适合列表页、卡片区和详情块这类中后台场景。

基础骨架 ​

最简单的用法是直接渲染默认骨架模板，让页面先把版式站稳，再等待真实数据回填。

状态切换与模板 ​

页面层通常会用 loading 控制骨架和真实内容切换；当默认骨架不够贴合页面结构时，再用 template 自定义占位布局。

loading = true

状态衔接 ​

真实页面里，Skeleton 往往不是终点。接口返回后，常见的下一个状态是"真实内容 / 空结果 / 失败反馈"三者之一。

动画与重复行数 ​

animated 适合强调"正在加载中"，rows 和 count 则更适合批量列表或多块卡片一起占位。

卡片区加载animated
双列摘要卡占位count = 2

变体组合 ​

xy-skeleton-item 适合手动拼装头像、标题、段落、图片和按钮区域，让骨架结构更贴近真实界面。

文本层级

适合拼标题、说明、段落和列表行里最常见的文本骨架。

h1大标题
h3区块标题
text正文文本
caption辅助说明
p整段占位
形状与媒体

适合头像、卡片封面、图片区和操作按钮一类更具结构感的占位。

circle头像 / 状态点
rect卡片封面
image图片占位
button操作按钮

何时使用 ​

  • 列表页、控制台概览、详情抽屉等已知结构但未知内容的加载过程。
  • 需要让页面先稳定布局，避免数据返回前大面积闪动。
  • 希望用户一眼看出"这里会加载出什么结构"，而不是只看到一个通用 loading 图标。

何时不使用 ​

  • 加载时间极短（< 300ms）时，骨架屏闪烁反而影响体验，优先使用 xy-loading。
  • 页面结构完全未知时，骨架屏无法提供有意义的占位，应使用通用加载指示器。
  • 需要展示加载进度百分比时，优先使用 xy-progress。
  • 需要全屏遮罩加载时，优先使用 v-loading 指令。

最佳实践 ​

页面级骨架屏组合 ​

中后台常见布局是顶部统计卡片 + 下方列表，建议用 xy-skeleton-item 手动拼装贴近真实结构的骨架：

vue
<xy-skeleton :loading="loading">
  <template #template>
    <div style="display: grid; grid-template-columns: repeat(4, 1fr); gap: 16px; margin-bottom: 24px;">
      <xy-skeleton-item variant="rect" style="height: 80px" />
      <xy-skeleton-item variant="rect" style="height: 80px" />
      <xy-skeleton-item variant="rect" style="height: 80px" />
      <xy-skeleton-item variant="rect" style="height: 80px" />
    </div>
    <xy-skeleton-item variant="rect" style="height: 300px" />
  </template>
  <real-page-content />
</xy-skeleton>

状态衔接 ​

页面层维护真实 loading 状态，Skeleton 只负责承接占位反馈，不承担请求逻辑。结构简单时优先用默认模板；只有当页面骨架明显异于默认段落结构时，再上 template 或 xy-skeleton-item。

API ​

Skeleton Attributes ​

属性说明类型默认值
animated是否启用骨架动画booleanfalse
count重复渲染多少组骨架模板number1
rows默认模板下的段落行数number3
loading是否展示骨架，占位结束后渲染默认插槽booleantrue
throttle骨架切换节流配置，支持数字或对象写法SkeletonThrottle0

Skeleton Slots ​

插槽说明
template自定义骨架模板；当你已经知道页面结构时，用它替换默认段落骨架
defaultloading = false 时渲染真实内容

Skeleton Exposes ​

暴露项说明类型
uiLoading节流后的最终加载态SkeletonInstance["uiLoading"]

SkeletonItem Attributes ​

属性说明类型默认值
variant骨架单元类型SkeletonItemVariant'text'