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" 并在完成后移除,为读屏器提供加载状态。
加载态切换
防闪烁延迟 delay
delay(毫秒):loading 变为 true 后延迟展示骨架,延迟窗口内骨架与内容都不渲染——请求在窗口内完成时骨架完全不出现(快速请求不闪骨架)。
防闪烁延迟(delay=500ms)
列表份数 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 | 整组骨架重复份数(列表场景),缺省 1 | string | 1 |
delay | 防闪烁延迟(毫秒):loading 变 true 后延迟展示骨架;窗口内加载完成则骨架不出现;窗口内骨架与内容都不渲染 | string | — |
effect | 动效:sheen(流光)/ pulse(呼吸)/ none(静态,缺省);优先级高于 active(active 保留为 sheen 快捷开关) | string | — |
loading | 受控开关:true(缺省)渲染骨架,"false" 渲染默认插槽的真实内容 | string | true |
rows | 段落行数 | string | 3 |
title | 是否显示标题占位(title 为存在性开关,值本身不渲染;读取后即从宿主移除,不残留原生悬浮提示) | string | — |
widths | 逗号分隔的逐行宽度(如 100%,80%,45%),内联覆盖 text 行默认宽 | string | — |
插槽
| 名称 | 说明 |
|---|---|
| 默认 | 真实内容出口:loading="false" 时渲染(骨架与内容常驻 shadow DOM,按 loading 切换 hidden) |
CSS 变量
| CSS 变量 | 默认值 |
|---|---|
--oas-skeleton-color | var(--oas-color-bg-hover) |
--oas-skeleton-duration | 1.5s |
--oas-skeleton-sheen | var(--oas-color-border) |