skeletonizer

skeletonizer

在线 demo：https://icodejoo.github.io/codejoo/skeletonizer/（各效果、档位、深色、fit 等可交互切换）

English docs: README.md。

给 AI 编码助手：精简用法见 llms.md（随 npm 包发布），接入方式见给 AI 编码助手。

Web 版骨架屏方案：照 Flutter skeletonizer 的路子，真实 DOM + mock 数据 + 纯 CSS，不用手画占位形状。

受 Flutter 的 skeletonizer 启发，解决 vue-skeletor / react-content-loader 里手写占位的痛点 —— 改个 UI 就得重新设计骨架，特别折腾。这套方案照常渲染真实组件，喂进 mock 数据，你用 skz-text / skz-bone / skz-leaf 标出哪些元素是骨头，CSS 按实际布局把它们画出来。

包提供两个构建，二选一（各自自包含，同一页面不要同时引）：

• 完整版（默认）：import "skeletonizer" 一行搞定（样式 + 运行时 + 全局 skz）。功能齐全：继承防火墙（长列表）、SVG 方案与老浏览器降级、四种文字模式、懒渲染，规模上限高得多。
• lite：import "skeletonizer/lite"。包最小、规则最简单，面向现代浏览器里的中小骨架（单个根约 2000 元素以内）。

两者怎么选，看下面的对比表。0.3.0 起入口就只有这两个加框架适配层；从 0.2.x 升级见升级到 0.3.0。

骨头由你自己标（0.2.0 起的默认）：没标的内容原样显示。给无法改标记的第三方组件，可以开一块 skz-auto 区域，区域内退回按标签推导。从 0.1.x 升级见升级到 0.2.0。

目录

• 怎么工作
• 完整版还是 lite：并列对比表
• 快速开始：完整版和 lite 各一行引入，外加怎么标记骨头
• 选择入口：各文件的内容与体积
• 升级到 0.3.0 · 升级到 0.2.0
• 功能总表：效果 / 入口 / 选项 / 自动机制 / 标记 / 主题变量 / API 的作用、用法、限制，每项标明属于 lite 还是完整版
• 标记与属性参考：元素标记 / 根属性 / 运行时属性，以及它们在各文字模式、入口、动画效果、浏览器档位下的表现
• 类型：EnableOptions、各联合类型、类型怎么随版本变宽、适配层类型、SkzBox 类
• 方案怎么选：按场景的建议
• 方案对比：性能、颜色、兼容性实测（含 lite 的规模上限）
• 各方案详解：fade / solid、global、svg、标记与 skz-auto、懒渲染
• Bone 工具 · 主题
• 浏览器支持与降级 · 已知限制与使用约束
• 在框架里怎么用 · 给 AI 编码助手 · 开发与实验存档

怎么工作

三个部分组成：

1. 真实 DOM 渲染：用你平常的 JSX / Vue 模板写组件，只是喂进 mock 数据而不是真实数据。
2. Mock 数据：用 Bone 工具生成文字、图片等占位内容，都是确定性的（SSR 友好，不用 Math.random）。
3. 你标记，CSS 来画：用裸属性 skz-text（文字）、skz-bone（图片、头像、按钮、色块）、skz-leaf（把一棵子树合成一块骨头）、skz-ignore（保持原样）说明哪些元素是骨头，没标的内容原样显示。无法改标记的第三方组件放进 skz-auto 区域，区域内才按标签名和内容推导（见标记骨头）。

骨架样式是纯 CSS，不用 UA 嗅探，也不用 JS 闸门：CSS 可以完全脱离 JS 运行，只靠根上的 skz 属性开关（JS 只负责切开关、写根属性）。两种用法的渐进方式不同：

• lite：目标线是 Chrome 119+ / Safari 16.4+ / Firefox 128+（@property、相对颜色、:has()、text-decoration-thickness、background-clip: text 都具备）。过线的浏览器走“现代档”（一个 @supports：skz-text 文字条用 round / clip 画法，另有控件整块、图标识别和 skz-auto 区域里的其他推导），pulse / shimmer 由根上的一个 CSS 动画驱动。低于线的浏览器只有第 0 档（按标签铺静态色块，仅 skz-auto 区域）、skz-bone / skz-leaf 标记和 fade，skz-text 文字条需要达到现代档；没有逐档渐进。
• 完整版：三层渐进（第 0 档 → 第 1 档 → 第 2 档），从 Chrome 88 到最新的都有对应效果，外加老浏览器的 SVG 动画降级。各档的推导只在 skz-auto 区域里生效，skz-text 标记由第 1 / 2 档负责。

完整版还是 lite

体积口径：pnpm build 产物按 gzip -9 -n 逐文件压缩（1 KB = 1024 字节）；每个 JS 文件都自包含，所以"JS"就是那一个文件。明细在选择入口。

一句话挑：默认就是完整版；包体最敏感、骨架又小，换 skeletonizer/lite。留在（或换到）完整版的理由：

• 单个根超过约 2000 元素，还要 pulse / shimmer（lite 没有继承防火墙；桌面 CPU 上实测到约 4000 元素还是 60 帧，慢设备要少得多，数据见 lite 的规模上限）；
• 浏览器门槛以下的用户也要有动画（完整版有 SVG 降级）；
• 需要 underline / leaf 文字、懒渲染；
• 没有列表结构的大骨架（大表单、长详情页）要 shimmer：svg 方案。

skeletonizer 和 skeletonizer/lite 不要在同一页面同时引：各自带一份 core，扩展注册表和全局 skz 会分家（后加载的占全局 skz）。

快速开始

1. 安装

pnpm add skeletonizer

2. 完整版（默认）：一行引入

import "skeletonizer"; // 样式（full.css）+ 运行时 + 全局 skz，一行搞定

之后在任何地方都可以直接用全局 skz（不用再 import）：

const off = skz.enable(document.querySelector("#card")!, { effect: "shimmer" });
const user = { name: skz.bone.text(8), bio: skz.bone.lines(2) };
// 数据到了：
off();

也可以具名导入，类型提示更完整（skz 的成员见全局变量 skz）：

import { enable, Bone } from "skeletonizer";

import skz from "skeletonizer" 拿到的就是全局上的那个 skz 对象（skeletonizer 与 skeletonizer/lite 成员相同）；全局名字被别人占用时，默认导入照样可用。

完整版已经内置 global、svg 两个方案，没有别的要引、要挑的；方案在运行时用 engine 选项选。

单独引 skeletonizer/full.css 的场景：入口在打包器里自带样式，下面几种情况要自己引：

• SSR 首屏：服务端渲染的 HTML 里直接写 <link rel="stylesheet" href="…/skeletonizer/full.css">，根上写 skz，首屏就是骨架，JS 起来后 enable() 接管（幂等）。服务端跑 JS 的注意事项见 SSR 与 Node。
• 无打包器：<link> 引 full.css + import map，见无打包器。
• CDN：同上，URL 换成 CDN 地址。

3. lite：更小的构建

import "skeletonizer/lite"; // 样式（lite.css）+ core 运行时 + 全局 skz

第 2 步里的用法（skz、具名导入、import skz from "skeletonizer/lite"、单独引 skeletonizer/lite.css）全部同样适用。lite 没有的东西见完整版还是 lite。skeletonizer 和 skeletonizer/lite 不要同时引。

4. 开启骨架

import { enable, Bone } from "skeletonizer"; // lite 写 "skeletonizer/lite"

const off = enable(document.querySelector("#card")!, { effect: "shimmer" });
// 数据到了：
off();

enable() 的选项（"版本"列：两者 = lite 和完整版都有；仅完整版 = lite 里传了会被忽略）：

fit 的 CSS 已包含在 lite.css / full.css 里，无需另引。

重复调用 enable() 是安全的：按本次参数重新同步属性（没传的会被清掉），并重新扫描列表项、忽略区和主题变量。

5. 标记骨头

没标记的内容原样显示。在根里用裸属性标出哪些元素是骨头：

<!-- 根是你调用 enable() 的元素 / 包住内容的 <SkzBox>，由它们写上 skz -->
<div class="card">
  <img skz-bone src="https://raw.githubusercontent.com/icodejoo/codejoo/HEAD/…" width="48" height="48" />
  <h3><span skz-text>昵称</span></h3>
  <p><span skz-text>一段会折成好几行的简介文字。</span></p>
  <div skz-leaf class="stats"><b>128</b> 篇 · <b>3.2k</b> 关注</div>
  <button skz-bone>关注</button>
  <a skz-ignore href="https://github.com/icodejoo/codejoo/blob/HEAD/cancel">取消</a>
</div>

完整的属性清单（元素标记、根属性、库自己写的运行时属性）以及它们在各文字模式 / 入口 / 动画效果 / 档位下的表现，见标记与属性参考。

skz-text / skz-bone / skz-leaf 在根下任何位置都生效，不管在不在 skz-auto 区域里；写在根自身上不会被读取。文字条的外观跟随根上的 skz-text-mode（即 text 选项）：默认 round，见文字骨头模式。

skz-auto 区域：在根或根内任意元素上写裸属性 skz-auto，按标签的自动推导只作用于这棵子树：文字标签（p span h1~h6 a li 等）、媒体与控件（img video canvas svg input button 等）、空的 <i> 和类名带 icon 的空元素。局限：规则基于标签白名单，CSS 又选不到文本节点，所以 直接写在 div、自定义元素、code 里的裸文字不在范围内（round / clip 下不可见），要包进 p / span 或自己标 skz-text；块级文字标签在 round 下是整块圆角矩形；用 div 做的头像 / 色块（空元素）不会被识别，要加 skz-bone。

6. 喂 mock 数据，照常渲染

const user = loading ? { name: Bone.text(8), bio: Bone.lines(2), avatar: Bone.image(48, 48) } : data;

框架适配

适配层走子路径导出，框架本身是可选 peer 依赖。适配层只是薄薄一层胶水（每个 gzip 约 0.5–0.9 KB），不含 core 代码：它们通过私有全局键 globalThis[Symbol.for("skeletonizer")] 找到 enable / disable，这个键由 skeletonizer（完整版）或 skeletonizer/lite 在导入时挂上。所以应用入口要导入且只导入其中一个、一次（样式也随它带上）；适配层本身不带样式、不挂全局。两个都没导入时，开发模式下 console.warn 一次（"No implementation found"），适配层的调用什么也不做。适配层的选项类型以 skeletonizer/lite 为底，项目里导入了 skeletonizer 就跟着变宽（见类型）：lite 下写完整版选项是类型错误，完整版下运行时才真正生效。

// Vue 3：指令 / 组件 / 组合式 / 插件
import { vSkeleton, SkzBox, useSkeleton, SkzPlugin } from "skeletonizer/vue";
// <div v-skeleton="{ loading, effect: 'shimmer' }">…</div>   或   <SkzBox :loading="loading" effect="shimmer">…</SkzBox>

// React：Hook / 组件
import { SkzBox, useSkeleton } from "skeletonizer/react";
// <SkzBox loading={loading} effect="shimmer">…</SkzBox>

// Svelte：action
import { skeleton } from "skeletonizer/svelte";
// <div use:skeleton={{ loading, effect: 'shimmer' }}>…</div>

// Solid：指令 / 组件（适配层不用 JSX，无需编译插件）
import { skeleton, SkzBox } from "skeletonizer/solid";
// <div use:skeleton={{ loading: loading(), effect: 'shimmer' }}>…</div>   or   <SkzBox loading={loading()} effect="shimmer">…</SkzBox>
// skeleton 只出现在 `use:` 里时，TypeScript 会把这个 import 当成未使用删掉：加一行 `void skeleton;` 保住它

// Angular：没有适配层，自己写个十来行的指令调用 enable / disable，或用 <skz-box>，见下文「在框架里怎么用 → Angular」

<skz-box> 自定义元素 / 纯 HTML

import "skeletonizer"; // 或 "skeletonizer/lite"：提供 enable / disable，<skz-box> 只是转发给它
import { defineSkzBox } from "skeletonizer/element"; // 导入没有副作用，需要手动注册
defineSkzBox();

<skz-box loading effect="shimmer"><div class="card" skz>…</div></skz-box>

<!-- 宿主上的 loading 是开关；skz 落在它的【第一个元素子节点】（骨架根）上，宿主自己不带 skz；JS 里用 el.loading = true/false 切换 -->
<!-- SSR / 无 JS：直接在子根上写 skz，如 <skz-box loading><div skz>…</div></skz-box>；CSS（标记，以及 `skz-auto` 里的推导）不用 JS 就生效，JS 起来后 enable 是幂等的 -->
<!-- 不用 JS：直接写根属性（lite：拿不到 inert 交互锁；完整版另拿不到防火墙和运行时 SVG） -->
<div skz skz-effect="shimmer">…</div>

<skz-box> 在独立入口 skeletonizer/element（只有胶水，不含 core 代码、不带 CSS；和适配层一样经私有全局键取 enable / disable，所以应用入口要导入一次 skeletonizer 或 skeletonizer/lite，否则开发模式警告一次）。它只认宿主自己的 loading（以及 effect / text / fallback / engine / fit）属性；lite 下 text / engine / fallback 被忽略。它不带 MutationObserver：框架把第一个子节点替换掉之后，由你自己处理，比如把 loading 关一下再开，新子根才会生效、旧子根被解除。宿主被移动到别的父节点后加载态会自然保持。

编辑器代码提示（skz-* 属性）

手写的属性（skz、skz-text、skz-bone、skz-leaf、skz-host、skz-ignore、skz-auto、skz-effect、skz-text-mode、skz-shimmer-mode、skz-cv）有补全、取值提示和文档链接：

• WebStorm / JetBrains 系：不用配。包里声明了 "web-types": "./web-types.json"，node_modules 里有 skeletonizer 就自动识别。

• VS Code：在 .vscode/settings.json 加一行：

  { "html.customData": ["./node_modules/skeletonizer/html-custom-data.json"] }
  

• JSX / 模板里的 TypeScript：导入任一适配层（skeletonizer/react、/solid、/svelte、/vue）就生效，零配置。适配层把共享类型 SkzHtmlAttributes（从 skeletonizer/lite 导出）并进框架的 HTMLAttributes，所以 skz-effect="nope" 会报类型错。裸属性在 React / Vue 里类型是 ""（React 对未知属性传 true 会丢掉属性），在 Solid / Svelte 里是 "" 或 true（它们的裸写法传的是 true）；不收 false，因为 Vue / Solid 会把它渲染成 ="false"，照样命中 [skz-bone]。TSX 对没声明的带连字符属性不做检查，所以只导入 lite 时 skz-cv / skz-shimmer-mode 只是没有补全，不会报错。

数据都来自同一份清单 src/attributes.ts；web-types.json 与 html-custom-data.json 由 pnpm build（或 pnpm gen:editor）生成并提交入库，测试保证清单、生成物、TS 类型与 README 属性表四处一致。

SSR 与 Node

0.3.0 起每个 JS 入口开头都带 CSS 导入（import "./full.css" / import "./lite.css"），所以 skeletonizer 和 skeletonizer/lite 在没有打包器的纯 Node 里不能直接 import（Node 不认识 .css）。SSR 框架的服务端代码都经过打包器，CSS 导入由它处理，但很多框架默认把 node_modules 里的包外置、直接交给 Node：要让它们把本包打进去（Vite / Nuxt / SvelteKit：ssr.noExternal: ["skeletonizer"]；Next.js：transpilePackages: ["skeletonizer"]）。全局 skz 在服务端同样会挂。完全没有打包器时，给 Node 配一个把 .css 当空模块的加载钩子，或者不要把骨架代码带进服务端包。框架适配层（skeletonizer/vue / /react / /svelte / /solid）没有 CSS 导入，Node 里 import 没问题，只是没导入过实现时开发模式会警告。

全局变量 skz

导入 skeletonizer 或 skeletonizer/lite，就会把 skz 挂到 globalThis 上，免 import 直接用。同一个 API 对象还总是会挂在私有键 globalThis[Symbol.for("skeletonizer")] 上（适配层读的就是它；公开名字 skz 被别人占用时它照样可用）：

• SSR 里也会挂：Node 里 import 同样往 globalThis 上写；不用它的话没副作用。
• 已经存在的 skz 不覆盖：别人已经占用了全局名 skz（不是我们挂的）时，保持原样，开发模式下 console.warn 一次，提示改用 import；我们自己挂的会直接刷新（多份拷贝、热更新都不报警）。生产构建里警告连同文案会被你的打包器折叠掉（见开发模式警告）。
• 不冻结对象，完整版要往上补属性；适配层（/vue /react /svelte）不挂。
• 类型：导入任一入口后，全局 skz 带类型（SkzGlobal），不需要自己声明。

无打包器：浏览器直接用（import map）

不用打包器时，JS 入口不能直接 import（开头是 CSS 导入）：CSS 另用 <link> 引，模块用一份去掉那一行的拷贝，或者让你自己的构建脚本去掉它。最稳的做法是加一个很小的构建步骤；临时页面也可以把文件取下来、删掉第一条 import "./full.css"; 语句再自己托管。exports 指向的文件：

CSS 文件：dist/full.css、dist/lite.css。每个 .mjs 都自包含（没有共享块），要托管的就这一个文件。

<link rel="stylesheet" href="/vendor/skeletonizer/full.css" />

<script type="importmap">
  { "imports": { "skeletonizer": "/vendor/skeletonizer/full.mjs" } }
</script>

<script type="module">
  import { enable, Bone } from "skeletonizer"; // 去掉第一行（CSS 导入）的 full.mjs；导入时也会挂全局 skz

  const off = enable(document.querySelector("#card"), { effect: "shimmer" });
  // 数据到了：off();
</script>

• import map 要放在第一个 module 脚本之前；full.mjs 和 lite.mjs 千万不要同时引。
• 浏览器会因为第一行去把 ./full.css 当模块加载而报错，所以这种用法必须去掉那一行（打包器则会把它变成样式表链接）。

选择入口

整个包就是下面这些文件（dist/）。体积是 pnpm build 产物的 gzip -9 -n（1 KB = 1024 字节）；每个 JS 文件都自包含，没有共享块，也没有带哈希的文件。

每个 .mjs 旁边有对应的 .d.mts（full.d.mts、lite.d.mts ……）。lite.d.mts 是类型底座；full.d.mts 从它再导出并用 declare module "skeletonizer/lite" 把它变宽；适配层的类型从 skeletonizer/lite 引。

// 完整版（默认）：全部功能，一行
import "skeletonizer";

// lite：更小的构建，两者同一页面只能引一个
import "skeletonizer/lite";

// 配适配层：先导入一个实现（一次），再用适配层
import "skeletonizer";
import { SkzBox } from "skeletonizer/vue";

• 完整版里，方案（global 防火墙 / svg）在运行时用 enable(el, { engine }) 选，不再有分方案的入口。
• explicit 没有了：lite.css 已经包含它的全部内容（见升级到 0.3.0）。

升级到 0.3.0

0.3.0 把 dist/ 里的 37 个文件合并成两个自包含的构建加适配层。破坏性改动如下（完整的变更记录在 CHANGELOG）：

1. 默认入口现在是完整版。 import "skeletonizer" 带来完整版运行时和 full.css；原来的 core 是 skeletonizer/lite。
2. 所有旧子路径删除：./full、./explicit、./global、./svg、./all（及各自的 /js）和 CSS 子路径 ./core.css、./base.css、./explicit.css、./global.css、./svg.css、./sweep.css、./all.css、./style.css。CSS 子路径只剩 ./full.css 和 ./lite.css。
3. 每个 JS 文件自包含，开头带自己的 CSS 导入；node 条件和纯 JS 的 *-js 构建都没有了。没有打包器的纯 Node 不能再直接 import skeletonizer / skeletonizer/lite（见 SSR 与 Node）。
4. skeletonizer 和 skeletonizer/lite 不要在同一页面同时引，各自带一份 core。
5. 适配层不再打包 core。 它们从 globalThis[Symbol.for("skeletonizer")] 取 API；应用入口要导入一次 skeletonizer 或 skeletonizer/lite，否则开发模式警告、适配层什么也不做。适配层的选项类型以 skeletonizer/lite 为底，项目里导入 skeletonizer 后变宽。
6. explicit 删除。 只认标记本来就是默认行为（推导要 skz-auto），explicit.css 是 lite.css 的子集；它带的懒渲染规则只对完整版 JS 有意义，完整版里本来就有。
7. 类型：增强目标从 declare module "skeletonizer" 改成 declare module "skeletonizer/lite"；自己对 "skeletonizer" 做过类型增强的代码，改成增强 "skeletonizer/lite"。

升级到 0.2.0

本节里的入口和文件名是 0.2.x 的旧名字，与今天名字的对应关系见升级到 0.3.0。

0.2.0 把默认从"按标签推导骨头"改成"你自己标"。破坏性改动如下（完整的变更记录在 CHANGELOG）：

1. 默认改为显式标记。 没有任何标记、也不在 skz-auto 区域里的内容原样显示。文字用 skz-text（块元素里包一层 <span> 再打），图片 / 头像 / 按钮 / 色块用 skz-bone，要合并的容器用 skz-leaf。无法改标记的第三方组件，在根或根内任意元素上写裸属性 skz-auto：原来的推导规则（第 0 档、图标、控件、leaf 模式）现在只作用于该子树。见标记骨头。
2. 根上的 skz-text 属性改名为 skz-text-mode（取值 round / clip / underline / leaf）。text 选项不变，只是写到新属性；手写根属性的要同步改名。skz-text 现在是元素级标记。
3. 新的默认文字模式 round。 文字条变成带圆角的背景盒（见文字骨头模式）。要回到原来的外观，根上写 skz-text-mode="clip"（完整版 text: "clip"）。lite 与 explicit.css 手写 round / clip 也认。
4. 移除 skz-has-ignore，忽略区只靠 skz-ignore、纯 CSS 生效，enable() 不再为它写任何属性。「含忽略区的祖先关下划线」的修正规则也一并去掉：忽略区放在 skz-text 元素或 skz-auto 区域内时，它的文字显示在骨头条之上；想要干净的忽略区，写成兄弟元素：<span skz-text>价格</span> <span skz-ignore>实时</span>。
5. explicit.css / skeletonizer/explicit 的含义变成「不含 skz-auto 推导规则」，同样支持 skz-text（round / clip）、skz-bone、skz-leaf、skz-ignore。lite.css 与 base.css = 标记 + 门控在 skz-auto 上的推导。
6. 浏览器门槛：推导和标记规则用了 :is() / :where()（Chrome 88+ / Safari 14+ / Firefox 84+；标记规则里的 :not() 用了选择器列表）。CSS 按这条线降级（chrome88 / firefox84 / safari14），JS 产物是 ES2015，不带 polyfill。

CSS 不再依赖 JS：手写根属性 skz 就能得到正确渲染（交互锁、懒渲染暂停、防火墙、运行时 SVG 属于性能 / 降级路径，不影响正确性）。

从 0.1.0 之前的布局迁移

0.1.0 之前的预览布局（一个入口包含全部）早已不存在，迁移说明保留在 CHANGELOG（0.1.0）里。那里提到的入口名（skeletonizer/full 等）后来又改过，当前名称以升级到 0.3.0为准。

功能总表

所有选项、属性、变量、入口和 API 的作用 / 最短用法 / 限制都在这张表里，「版本」列标明每项属于 lite 还是完整版（两者 = 都有；仅完整版 = lite 里没有；仅 lite = 只有 lite 才有的东西）；总表放不下的细节见各方案详解和已知限制与使用约束；标记和属性的完整枚举（含各模式 / 入口 / 档位下的表现）见标记与属性参考。表里的性能数字（帧率 / 每帧样式重算 / 开启耗时，"4000 / 16000 元素"）统一取文字模式 clip（0.2.0 之前的默认）下的数据（出自方案对比的 clip 补测与落地复测），新默认 round 没有逐表重测（原型实测 GPU 约为 clip 的一半）；只有原矩阵测过、没为 clip 重测的，数字旁标了"underline 时测得"。桌面 Chrome、单次正向测量，差距在 2 倍以内的别当真。