phantom-ui是一款结构感知的骨架屏（skeleton loader）组件：一个 Web Component，适配 React、Vue、Svelte、Angular、Solid、Qwik、HTMX 等所有框架。它通过在运行时测量你的真实 DOM，自动生成位置与尺寸完全吻合的 shimmer 占位块，免去手工维护"第二套"骨架组件的烦恼。

自从1.0.0版本起（当前已迭代到 1.6.1），phantom-ui 严格遵循语义化版本（SemVer），并首次对公共 API 稳定性做出正式承诺。本文带你快速看懂这份承诺的边界、版本升级规则，以及一份可以直接照做的升级安全清单。

一、1.0 稳定性承诺：骨架屏组件的 6 类"冻结"内容

按照官方 API 稳定性文档，以下 6 类内容属于公共 API。只要不升大版本（2.0.0），它们不会发生破坏性变更：

💡一句话理解：只要版本号还在1.x区间，你今天写好的骨架屏用法，明天升级后依然能工作。

二、边界之外：哪些细节"允许"变化

稳定性承诺并非"什么都不动"。官方明确列出了不受保障的部分，理解它们能避免误判 bug：

• 📐shimmer 块的精确像素输出—— DOM 测量是启发式的，未来可能优化，占位块的像素位置允许微调；
• 🏷️Shadow DOM 内部类名—— 组件内部样式实现随时可重构，请勿依赖内部类名选择器；
• 📦Custom Elements Manifest 的结构—— custom-elements.json 供 IDE 补全和工具链消费，其字段结构不承诺稳定；
• ⚠️未文档化的边缘场景行为—— 官方未写进文档的行为，不构成 API 契约。

组件的核心测量逻辑位于 src/phantom-ui.ts，渲染管线详见工作原理文档。

三、版本升级规则：Patch、Minor、Major 分别能期待什么

phantom-ui 的版本号遵循严格的三级策略：

换句话说：1.x内的任何升级都是安全的，包括从当前版本继续小步前进；只有看到2.0.0时才需要预留迁移时间。

四、骨架屏组件升级安全清单（Checklist）✅

升级 phantom-ui 之前，花 1 分钟过一遍这张清单：

• 确认目标版本号：Patch / Minor 直接升级；Major 先阅读 changelog 的迁移说明；
• 只使用文档化 API：检查项目内是否引用了 Shadow DOM 内部类名、依赖了占位块的精确像素位置——这两类都不在保障范围；
• 核对属性与 data 属性：确保使用的属性都在属性参考和数据属性参考中列出；
• 检查 SSR 集成：如果你用 Next.js / Nuxt / SvelteKit 等框架，确认布局文件中的import "@aejkatappaja/phantom-ui/ssr.css"导入路径未变（该路径属于稳定承诺）；
• 验证 JSX 类型声明：React / Solid / Qwik 项目确认 phantom-ui.d.ts 使用的类型导出（PhantomUiAttributes/SolidPhantomUiAttributes）名称未变；
• 跑一遍回归用例：升级后重点观察首屏骨架生成、loading移除后的内容显现、以及overlay刷新模式；
• 锁定依赖策略：生产环境建议使用^1.0.0之类的范围，避免意外引入 2.x。

📌 示例项目可参考 examples/ 目录下的 React、Vue、Angular、Solid、Qwik 多框架接入方式，它们是升级后回归验证的良好参照。

五、升级后出现异常？这样处理

官方给出了非常明确的保障条款：如果某个版本破坏了一份此处文档化承诺，却没有升大版本号，那就是 bug，会以回归（regression）对待。

遇到疑似破坏性变更时：

1. 先对照本文第一节的 6 类承诺项，确认受影响内容确实在保障范围内；
2. 收集版本对比信息（升级前后的版本号、受影响的属性或类型）；
3. 向项目提交 issue 反馈，标题注明"疑似违反 1.0 API 稳定性承诺"。

六、延伸阅读

总结：phantom-ui 从 1.0 起把"骨架屏组件升级不用怕"写进了版本策略——标签名、属性、CSS 变量、类型声明、SSR 路径与 CLI 六类 API 全部冻结在1.x区间内。对照本文的升级安全清单逐项打勾，你就可以放心地随版本演进，享受每次 Minor 更新带来的新能力。