Skip to content

Skeleton 骨架屏 ​

加载时的占位骨架:整组段落组合(头像/标题/行)与单形状占位块(oas-skeleton-item)两种用法,支持受控加载切换、三档动效、列表份数、逐行宽度与防闪烁延迟。

基础用法 ​

基础用法

组合 ​

组合

动效 effect ​

effect 三档:sheen(流光扫过)/ pulse(呼吸明暗)/ none(静态,缺省)。active 是流光的布尔快捷开关(兼容保留),effect 优先级高于 active——显式 effect="none" 可以压过 active,非法值回落 active 判定。

动效三档

动画时长与骨架底色/流光高光色可经 CSS 变量穿透定制:--oas-skeleton-duration(动画时长)、--oas-skeleton-color(底色)、--oas-skeleton-sheen(流光高光色)。

加载态切换 loading ​

loading 受控切换骨架与真实内容:loading="true"(或缺省)渲染骨架,loading="false" 渲染默认 slot 里的真实内容。骨架容器内部 aria-hidden="true"(纯装饰,读屏静默);建议宿主在加载区域容器上挂 aria-busy="true" 并在完成后移除,为读屏器提供加载状态。

加载态切换

项目标题
描述文本:数据加载完成后,默认 slot 里的真实内容替换骨架展示。

防闪烁延迟 delay ​

delay(毫秒):loading 变为 true 后延迟展示骨架,延迟窗口内骨架与内容都不渲染——请求在窗口内完成时骨架完全不出现(快速请求不闪骨架)。

防闪烁延迟(delay=500ms)

快速请求(150ms)慢速请求(1.2s)
点击按钮模拟请求
真实内容

列表份数 count ​

count 将整组骨架(头像/标题/行)重复 N 份,适合列表加载占位。

count=3

逐行宽度 widths ​

widths 逗号分隔,按序覆盖每行宽度;未覆盖的行走奇偶交替默认宽(92% / 76%),条目多于行数时多余项忽略。

widths=100%,80%,45%

单形状占位 oas-skeleton-item ​

oas-skeleton-item 渲染单个形状占位块,与整组组合用法互补:多块自由组合出卡片、表格、表单等任意布局。type 七档:text(文本行,缺省)/ title(标题)/ avatar(圆形头像)/ button(按钮同形)/ input(输入框同形)/ image(图片块)/ rect(通用矩形)。

七种类型

width / height 为自由 CSS 值,内联覆盖各 type 的默认尺寸;effect 与 oas-skeleton 语义一致(独立使用时自控,缺省 none)。

自定义尺寸

组合配方 ​

卡片占位(头像 + 标题 + 两行文本):

卡片

表格占位(行 × 列网格):

表格行

表单占位(输入框 ×3 + 提交按钮):

表单

无障碍 ​

骨架与 oas-skeleton-item 均为纯装饰占位:内部元素 aria-hidden="true",不向读屏器暴露内容。宿主侧建议:加载区域容器挂 aria-busy="true"(数据就绪后移除)并提供可读名称(如 role="region" + aria-label),让读屏器感知「区域正在更新」而不是逐块播报骨架。

API ​

oas-skeleton ​

属性 ​

属性说明类型默认值
active是否启用流光动画boolean—
avatar是否显示头像占位boolean—
count整组骨架重复份数(列表场景),缺省 1string1
delay防闪烁延迟(毫秒):loading 变 true 后延迟展示骨架;窗口内加载完成则骨架不出现;窗口内骨架与内容都不渲染string—
effect动效:sheen(流光)/ pulse(呼吸)/ none(静态,缺省);优先级高于 active(active 保留为 sheen 快捷开关)string—
loading受控开关:true(缺省)渲染骨架,"false" 渲染默认插槽的真实内容stringtrue
rows段落行数string3
title是否显示标题占位(title 为存在性开关,值本身不渲染;读取后即从宿主移除,不残留原生悬浮提示)string—
widths逗号分隔的逐行宽度(如 100%,80%,45%),内联覆盖 text 行默认宽string—

插槽 ​

名称说明
默认真实内容出口:loading="false" 时渲染(骨架与内容常驻 shadow DOM,按 loading 切换 hidden)

CSS 变量 ​

CSS 变量默认值
--oas-skeleton-colorvar(--oas-color-bg-hover)
--oas-skeleton-duration1.5s
--oas-skeleton-sheenvar(--oas-color-border)

基于 MIT OR Apache-2.0 双许可发布