青梧 UI

商品卡片骨架

自动测量 DOM 生成精准骨架，无需手写第二套布局。点击按钮切换加载/完成态，骨架与真实内容像素级对齐。

加载中...
import { AutoSkeleton } from "@qingwu-ui/skeleton";
import "@qingwu-ui/skeleton/style.css";

useEffect(() => {
  const el = document.getElementById("card")!;
  el.innerHTML = cardHTML;
  const sk = new AutoSkeleton(el, { loading: true });
  // 数据加载完成后
  sk.update({ loading: false });
  return () => sk.destroy();
}, []);

表单骨架

表单含输入框、下拉选择、文本域等多种控件。骨架自动识别各类元素，精确匹配每个控件的尺寸和位置。

import { AutoSkeleton } from "@qingwu-ui/skeleton";

useEffect(() => {
  const el = document.getElementById("form")!;
  el.innerHTML = formHTML;
  const sk = new AutoSkeleton(el, { loading: true });
  return () => sk.destroy();
}, []);

// 数据就绪
sk.update({ loading: false });

过渡动画

骨架与真实内容之间的平滑切换。退出时骨架覆盖层逐渐透明，内容文字同步恢复可见，300ms 过渡动画。

// 退出时给覆盖层添加 .is-exiting 类触发 CSS 过渡
const overlay = sk.overlay;
overlay?.classList.add("is-exiting");
setTimeout(() => sk.update({ loading: false }), 250);

动画样式按容器

每个容器独立的流光颜色、时长、时序函数，互不覆盖。红色 600ms linear 快扫、蓝色 2600ms ease-out 缓扫、紫色默认配置。

600ms · linear
2600ms · ease-out
1500ms · ease-in-out
import { AutoSkeleton } from "@qingwu-ui/skeleton";

const sk = new AutoSkeleton(el, {
  loading: true,
  shimmerColor: "#ffb3b3",
  backgroundColor: "#f5a3a3",
  duration: 600,
  timingFunction: "linear",
});
// 多个容器并存：各自动画样式独立生效

SSR 骨架（无 JS 预览）

完整管线演示：渲染真实卡片 → extractElementInfo 测量 → renderSkeletonSnapshot 生成纯 CSS 骨架。骨架几何来自真实测量，与内容像素级对齐（同一测量引擎，按构造相等）。

import { extractElementInfo, renderSkeletonSnapshot } from "@qingwu-ui/skeleton";

// 构建时：渲染真实页面后测量
const snapshot = extractElementInfo(document.querySelector(".card")!);

const html = renderSkeletonSnapshot(snapshot, {
  width: snapshot[0].x + snapshot[0].width,
  shimmerColor: "#f0f0f0",
  backgroundColor: "#e0e0e0",
  duration: 1500,
});
// 返回完整 CSS 骨架 HTML 字符串

配置项（AutoSkeletonOptions）

属性说明类型默认值
loading是否处于加载态boolean必填
shimmerColor流光颜色string"#f0f0f0"
backgroundColor骨架块背景色string"#e0e0e0"
duration流光动画时长 (ms)number1500
timingFunction动画时序函数（CSS animation-timing-function），如 linear / ease-out / cubic-bezierstring"ease-in-out"
staggerDelay错峰步进 (ms)：动画块按文档序递增负 delay 形成级联流水感；0 关闭错峰number80
zIndex覆盖层 z-index（portal 挂载于 body）；页面 sticky 头部需显示在骨架之上时调低number9999
fallbackBorderRadius默认圆角 (px)，用于 borderRadius 为 0 的元素number-
reducedMotion禁用动画（不传时自动检测 prefers-reduced-motion）booleanauto
maxElements骨架最大元素数量（性能保护）number500

静态骨架（RenderSkeletonSnapshotOptions）

属性说明类型默认值
width容器宽度 (px)number必填
height容器高度 (px)，未提供时按块几何自动计算number-
shimmerColor流光颜色（与 AutoSkeleton 同名配置一致）string"#f0f0f0"
backgroundColor骨架块背景色（与 AutoSkeleton 同名配置一致）string"#e0e0e0"
duration流光动画时长 (ms，与 AutoSkeleton 同名配置一致)number1500
timingFunction动画时序函数（与 AutoSkeleton 同名配置一致）string"ease-in-out"
staggerDelay错峰步进 (ms，与 AutoSkeleton 同名配置一致)number80
reducedMotion禁用动画（与 AutoSkeleton 同名配置一致）booleanauto
maxBlocks最大骨架块数（性能保护，超出截断）number200

函数与实例方法

属性说明类型默认值
new AutoSkeleton(el, options)构造：原地测量 DOM 生成骨架覆盖层(el: HTMLElement, options) => AutoSkeleton-
sk.update({ loading })切换加载态（数据就绪后移除骨架）(opts: Partial<AutoSkeletonOptions>) => void-
sk.overlay骨架覆盖层 DOM（可手动加 .is-exiting 触发退出动画）HTMLElement-
sk.destroy()销毁实例，移除覆盖层与监听器() => void-
extractElementInfo(root)测量 DOM 结构，返回骨架块快照（SSR 管线第一步）(root: HTMLElement) => SkeletonElement[]-
renderSkeletonSnapshot(snapshot, options)将测量快照渲染为纯 CSS 静态骨架 HTML（SSR 管线第二步）(snapshot, options) => string-
isLeafElement / structureSignature叶子元素判定 / DOM 结构签名（测试与比对用）(el) => boolean / (el) => string-