Shimmer From Structure是一个结构感知的骨架屏（Skeleton Loader）开源库，它会在运行时自动镜像你的真实 UI 结构，生成与组件尺寸完全一致的 shimmer 加载动画。无论你是用 React、Vue、Svelte、Angular 还是 SolidJS，只需一行安装命令 + 一个<Shimmer>组件，就能实现零维护、零布局重复的骨架屏方案。

为什么选择 Shimmer From Structure？

传统骨架屏库让你头疼的三件事，它全部帮你解决：

它的核心亮点：

• 🎯五大框架全支持：React、Vue 3、Svelte 5、Angular 19、SolidJS
• 📏像素级还原：自动读取每个元素的真实尺寸和 CSSborder-radius（圆形头像自动变圆形骨架块）
• 🎨保留容器背景：加载时卡片背景、边框依然可见，体验更自然
• 🧩支持动态数据：通过templateProps注入模拟数据，列表、卡片都能正确测量
• ⚡极致轻量：核心包@shimmer-from-structure/core仅 1.44 kB

一键安装步骤

根据你的框架，安装对应的适配器包即可（yarn / pnpm / bun 同理）：

# React npm install @shimmer-from-structure/react # Vue 3 npm install @shimmer-from-structure/vue # Svelte 5 npm install @shimmer-from-structure/svelte # Angular 19+ npm install @shimmer-from-structure/angular # SolidJS npm install @shimmer-from-structure/solid

💡 React 用户也可以直接安装主包npm install shimmer-from-structure，向后兼容。

各框架的版本要求：React ≥ 18、Vue ≥ 3.3、Svelte ≥ 5、Angular ≥ 19、SolidJS ≥ 1.9。

React 骨架屏：3 行代码接入

导入Shimmer组件，把你的内容包进去，通过loading属性控制即可：

import { Shimmer } from '@shimmer-from-structure/react'; function UserCard() { return ( <Shimmer loading={isLoading}> <div className="card"> <img src="avatar.jpg" className="avatar" /> <h2>John Doe</h2> <p>Software Engineer</p> </div> </Shimmer> ); }

loading={true}时，组件照常渲染但文字透明，库会同步测量所有叶子元素的尺寸并生成对应的 shimmer 骨架块；数据加载完成后切回false，骨架屏即刻切换为真实内容，且不会发生任何布局跳动。React 适配器的核心实现可以查看 Shimmer.tsx。

Vue、Svelte、Angular、SolidJS 快速用法

Vue 3

<script setup> import { ref } from 'vue'; import { Shimmer } from '@shimmer-from-structure/vue'; const isLoading = ref(true); </script> <template> <Shimmer :loading="isLoading"> <div class="card"> <img src="avatar.jpg" class="avatar" /> <h2>John Doe</h2> <p>Software Engineer</p> </div> </Shimmer> </template>

Svelte

<script> import { Shimmer } from '@shimmer-from-structure/svelte'; let isLoading = $state(true); </script> <Shimmer loading={isLoading}> <div class="card"> <img src="avatar.jpg" class="avatar" /> <h2>John Doe</h2> <p>Software Engineer</p> </div> </Shimmer>

Angular

import { Component, signal } from '@angular/core'; import { ShimmerComponent } from '@shimmer-from-structure/angular'; @Component({ selector: 'app-user-card', standalone: true, imports: [ShimmerComponent], template: ` <shimmer [loading]="isLoading()"> <div class="card"> <img src="avatar.jpg" class="avatar" /> <h2>John Doe</h2> <p>Software Engineer</p> </div> </shimmer> `, }) export class UserCardComponent { isLoading = signal(true); }

SolidJS

import { createSignal } from 'solid-js'; import { Shimmer } from '@shimmer-from-structure/solid'; function UserCard() { const [isLoading] = createSignal(true); return ( <Shimmer loading={isLoading()}> <div className="card"> <img src="avatar.jpg" className="avatar" /> <h2>John Doe</h2> <p>Software Engineer</p> </div> </Shimmer> ); }

五种框架的写法高度一致：包一层、传 loading、完事。完整可运行的示例项目位于 examples/ 目录，包含react-example、vue-example、svelte-example、angular-example、solid-example五个子项目。

动态数据：templateProps 用法

当你的组件依赖 props 渲染（例如用户数据还没返回），直接包一层会因数据为空而测不到结构。这时用templateProps注入一份模拟数据即可：

const userTemplate = { name: 'Loading...', role: 'Loading role...', avatar: 'placeholder.jpg', }; <Shimmer loading={loading} templateProps={{ user: userTemplate }}> <UserCard user={user || userTemplate} /> </Shimmer>

加载期间，templateProps会被自动展开到第一个子组件上，让组件先用模拟数据渲染，骨架屏据此测出与真实数据等长、等结构的布局。小技巧：模板数组的长度尽量和真实数据一致，骨架效果最自然。

常用 Props 速查表

<Shimmer loading={isLoading} shimmerColor="rgba(255, 255, 255, 0.2)" duration={2} fallbackBorderRadius={8} > <MyComponent user={user} /> </Shimmer>

🎨全局统一主题：每个框架都提供 Provider 机制（React/Solid 用ShimmerProvider，Vue 用provideShimmerConfig，Angular 用provideShimmerConfig注入，Svelte 用setShimmerConfig），一次配置整站生效，单个组件仍可局部覆盖。

它是怎么工作的？

整个流程只有 5 步，全部在浏览器端完成：

1. 可见容器渲染：loading={true}时，内容照常渲染，但文字变透明、容器背景保留
2. 模板数据注入：提供templateProps时展开到首个子组件
3. 同步测量 DOM：通过getBoundingClientRect()读取每个叶子元素的位置与尺寸
4. 圆角检测：自动读取计算后的border-radius
5. 生成 shimmer 块：绝对定位覆盖 + 平滑渐变动画

测量逻辑集中在框架无关的 packages/core/ 中，例如 extractElementInfo.ts 负责元素信息提取。由于测量只在loading变为true时触发一次，且使用原生浏览器 API，性能开销极低。

最佳实践清单

• ✅分区分包：Dashboard 每个区块各自用一个<Shimmer>，实现独立加载状态，避免"全有或全无"
• ✅标题宽度：<h1>、<p>默认占满容器宽度，想让骨架贴合文字宽度，给标题加width: fit-content
• ✅异步组件：图表等异步内容请给容器显式宽高，否则测不到尺寸
• ⚠️已知限制：display: none的零尺寸元素和 SVG 内部路径不会被捕获

下一步

• 快速上手文档：docs/app/docs/getting-started/page.tsx
• 完整安装说明（含包体积对比）：docs/app/docs/installation/page.tsx
• 更多实战示例：docs/app/docs/examples/page.tsx
• 项目总览与 Roadmap：README.md

5 分钟走完安装、接入、动态数据三步，你的骨架屏维护成本从此归零 🚀