跳到主要内容

Skeleton 多块能力收进 items prop（DES-127）

版本： 0.2.0 · 类型： ✨ 新功能

DES-127（sub issue of DES-124 Skeleton）

延续 WEB-889（[Skeleton] 圆角/颜色挂 token + 卡片级扫光）

问题​

昨天（2026-06-16）落地的卡片级连续扫光以独立组件 SkeletonGroup 承载，调用方需要同时引入并嵌套 Skeleton + SkeletonGroup 两个组件。SkeletonGroup 尚无任何业务方使用，趁早把「多块连续扫光」能力收进 Skeleton 自身的 items prop，减少对外 API 数量与嵌套心智。

改动文件​

  • src/components/Skeleton/Skeleton.tsx
  • src/components/Skeleton/SkeletonGroup.tsx（删除）
  • src/components/Skeleton/skeleton-group-context.ts（删除）
  • src/components/Skeleton/index.ts
  • src/components/index.ts
  • src/components/ui/skeleton.tsx（注释）
  • src/components/Skeleton/__tests__/Skeleton.test.tsx
  • scripts/a11y/a11y-audit-config.ts
  • packages/design-site/docs/components/atomic/progress-indicators/skeleton.mdx
  • packages/design-site/i18n/zh-CN/.../skeleton.mdx
  • packages/design-site/src/theme/ReactLiveScope/index.tsx

改动内容​

  • Skeleton 新增 items?: SkeletonItem[] prop（SkeletonItem = { className?: string; key?: Key }）：
    • 不传 items → 单块骨架，行为与之前完全一致。
    • 传 items → 外层 div 充当整张「画布」，按 items 渲染多块，一道光跨块连续扫过（块间空隙不扫）；块的排布由 Skeleton 自身 className（flex / grid / gap）控制。
  • 删除 SkeletonGroup 组件与 SkeletonGroupContext，移除 SkeletonGroup / SkeletonGroupProps 导出；新增 SkeletonItem 类型导出。
  • 把原 SkeletonGroup 的几何测量逻辑（ResizeObserver + MutationObserver + applyShimmerGeometry）收进 Skeleton：items 模式下外层画布测量子块偏移，单块模式按自身尺寸测量。
  • 文档站三处 demo（卡片级扫光 / 文本行 / 卡片）改为 Skeleton items 用法；Props 表移除 SkeletonGroup Props 段，补 items / SkeletonItem 说明。
  • a11y 离线审计补一条 Skeleton (items) 多块 fixture（此前仅注册单块）。
  • 单测同步重写：移除 SkeletonGroup 测试块，补 items 多块行为（按 item 渲染、className 透传、画布不带骨架视觉、空数组、ref）与「装饰性骨架置于 role="status" 加载容器」的 axe 断言。

备注​

  • 扫光几何 CSS 变量与单例 <style> 注入（skeleton-shimmer.ts）保持不变，仅测量入口从 SkeletonGroup 迁移到 Skeleton。
  • 单块/多块共用同一段 useEffect：单块不挂 MutationObserver（无子节点增删），多块才监听子块增删并补观察新节点。

2026-06-17 Skeleton 新增 direction 与 item.children 嵌套布局（同日追加）​

改动内容​

  • Skeleton 新增 direction?: 'horizontal' | 'vertical'（默认 vertical，仅 items 模式生效）：自动给画布加 flex flex-row/flex-col，gap / align 等细节仍交给 className（用 mergeClass 合并，className 可覆盖，如改用 grid）。
  • SkeletonItem 新增 children?: SkeletonItem[] 与 direction?：叶子 item（无 children）渲染一个骨架块；带 children 的 item 不画骨架块、改作子容器，按自身 direction（默认 vertical）递归排布子节点。用于「头像在左 + 右侧上下两行」这类混合布局。
  • 渲染改为递归 renderItem；几何测量逻辑无需改动——仍用 querySelectorAll(SKELETON_SELECTOR) 抓画布内所有叶子骨架块，嵌套结构天然兼容，一道光跨所有叶子块连续扫过。
  • 新增 SkeletonDirection 类型导出。
  • 文档站补 direction 说明与「嵌套布局（头像 + 两行）」demo；Props 表补 direction 与 SkeletonItem.children/direction。
  • a11y 离线审计的 Skeleton (items) fixture 改为嵌套结构（horizontal 画布 + vertical 子容器）。
  • 单测补 direction 默认/水平/className 覆盖、嵌套 children（叶子块计数、分支作子容器、子容器 direction 默认值）共 7 条。

2026-06-17 修复单块模式吞掉 children + 移除 SkeletonGroup 决策说明（同日追加，review 跟进）​

问题​

  • 重构后 Skeleton 把 children 从 props 解构出来，单块模式 return <SkeletonUI ... /> 却没把 children 传回。SkeletonProps 仍继承 HTMLAttributes<HTMLDivElement>（类型层面允许传 children），导致 <Skeleton>content</Skeleton> 这类旧写法的子节点被静默丢弃——行为回退。

改动文件​

  • src/components/Skeleton/Skeleton.tsx
  • src/components/Skeleton/__tests__/Skeleton.test.tsx

改动内容​

  • 单块模式补回 {children}，作为底层 div 子节点渲染，恢复重构前行为。
  • 单测补一条「单块模式 children 透传」断言，防止再次回退。

关于移除 SkeletonGroup 不走 deprecated 流程的说明​

review 提出「SkeletonGroup 已从 @plaud/design 顶层导出，属公开 API，移除应保留一版 deprecated 兼容包装」。结合本仓库事实，本次确认直接移除、不保留兼容层，依据：

  • SkeletonGroup 于 2026-06-16 落地，存活不到 24 小时，全仓 grep 零业务引用。
  • @plaud/design 是 monorepo 内部源码包（消费方直接走 src/index.ts），不存在未知外部消费方的发布契约。
  • 因此将其归类为「未发布能力的内部调整」，不计为破坏性变更，无需 deprecated 包装与 major bump。