sibling-index() 与 sibling-count():在 Modern Web Guidance 中实现动态同级元素样式

原创2026-11-12 17:06:422,324 阅读
文章标签:前端文档AI 技能AI 评测Agent 评测人工智能RAGCLI提示工程

sibling-index() 与 sibling-count():在 Modern Web Guidance 中实现动态同级元素样式

本篇技术指南围绕 Modern Web Guidance 仓库中的 dynamic-sibling-styling 用例,讲清如何用 CSS 原生的 sibling-index() 与 sibling-count() 让列表的配色、扇形排布和环形定位随元素数量自动变化,而不再依赖 :nth-child 循环或 JavaScript 注入内联样式。读完本文,你将掌握三个可直接复用的视觉模式、一套符合仓库强制要求的特性检测降级方案,以及该用例在仓库中如何被 expectations.md 与 grader.ts 自动验证。

用例定位:它解决什么问题

指南文件 guide.md 的定位非常明确:过去要给列表中每个同级元素施加唯一(或递进)的样式,要么写出一长串 :nth-child(n) 规则,要么用 JavaScript 计算后写入内联样式。前者随元素数量变化立刻失效,后者把样式逻辑搬到了脚本层。现代 CSS 把这套算术下沉到了样式表里——sibling-index() 返回当前元素在同级元素中的序号,sibling-count() 返回该组同级元素的总数,二者可以在 calc() 中直接参与运算,因此布局与配色能够随增删元素自动重算。

前置元数据与仓库的校验约束

指南头部声明的 frontmatter 决定了它在整个项目体系中的身份:

name: dynamic-sibling-styling
description: Create dynamic visual spectrums or layout arrangements that automatically adapt to the number of elements in a group.
web-feature-ids:
  - sibling-count
  - trig-functions

这些字段不是装饰。仓库的 guide-validation.ts 会校验三件事:name 必须与所在目录名一致(dynamic-sibling-styling 正好是目录名)、description 不可缺失、web-feature-ids 必须是数组且每个 ID 都要能通过 validateFeature() 的校验。同时 feature-to-groups.gen.json 把 sibling-count 归类到 css 分组,也就是说该用例在生成技能内容时会被归入 CSS 板块。

值得注意的是这里登记了 两个 特性 ID:sibling-count 与 trig-functions。这提示了一个容易踩坑的事实——环形定位依赖的 sin() / cos() 属于独立的特性条目,其浏览器支持节奏与 sibling-index() / sibling-count() 并不必然同步。从仓库结构可以推断:下文给出的 JS 降级只覆盖序号与总数,如果你的目标浏览器同时缺少三角函数,还需要额外的降级策略(例如改用预置的旋转角度表)。

模式一:动态色彩系统

第一个模式把 360° 色相环按同级元素总数均分,再按当前元素序号取色,得到一个与元素数量无关、始终完整铺开的渐变光谱:

.swatch {
  /* 用 360deg 除以同级总数,再乘以当前元素的 1 起始序号,得到该元素的色相 */
  background-color: hsl(
    calc(360deg / sibling-count() * sibling-index()),
    70%,
    50%
  );
}

实现细节值得展开:

  • 运算顺序:calc(360deg / sibling-count() * sibling-index()) 等价于 (360deg / count) * index,即先求“每份色相宽度”,再乘以位置。若元素数为 5,五个元素分别落在 72°、144°、216°、288°、360° 上——第 5 个等于 360°,与 0° 视觉上重合,因此首尾在色环上并非“等距留白”而是首尾相接,这正是完整光谱的预期效果。
  • 单位处理:色相需要角度单位 deg,而 sibling-count() / sibling-index() 返回的是无单位数值,所以必须让 360deg 作为被除数来“带上单位”,不能写成 360 / count。
  • 比例分配:同一组数值还可以用于宽度分配,例如仓库示例中的 width: calc(100% / var(--count)),让每张卡片等分容器宽度。

模式二:对称布局与扇形展开

要做出“以中间元素为轴、向两侧对称张开”的扇形,需要先用总数求出中点,再用序号与中点的差值决定旋转角度:

.card {
  /* 求中心序号:5 个同级元素时为 3 */
  --center: calc((sibling-count() + 1) / 2);

  /* 与中心的距离决定旋转角度:左侧为负、右侧为正,中心元素为 0deg */
  transform: rotate(calc(10deg * (sibling-index() - var(--center))));
}

这里有两个易被忽略的要点:

  1. 中点公式必须是 (count + 1) / 2 而不是 count / 2。因为序号从 1 开始,5 个元素的中点序号是 3;若用 count / 2 会得到 2.5,中心元素不再归零,扇形会整体偏斜。仓库的 grader.ts 甚至用正则 /(?:\+\s*1|1\s*\+)/ 与 /\/\s*2/ 同时匹配文件内容,来确认实现里确实出现了“加一后除以二”的中点计算。
  2. 旋转原点决定观感。参考实现 demo.html 中,.fan-card 额外设置了 transform-origin: bottom center,并把卡片用负外边距叠放(margin-left: -20px),这样旋转是围绕卡片底部中线展开的,形成真正的“手持扇面”而非围绕各自中心乱转。

模式三:环形与复杂定位

把序号换算成圆周角度,再借三角函数求出 x / y 位移,就能让任意数量的元素均匀落在一个圆上,无需为每个位置手写坐标:

.orb {
  /* 该元素在 360deg 圆周上的角度 */
  --angle: calc(360deg / sibling-count() * sibling-index());
  --radius: 150px;

  /* 让所有元素的原始位置都落在父容器中心 */
  position: absolute;
  place-self: center;

  /* 从中心向外偏移到圆周上 */
  transform: translate(
    calc(cos(var(--angle)) * var(--radius)),
    calc(sin(var(--angle)) * var(--radius))
  );
}

三个关键点:

  • 先归零再偏移。position: absolute + place-self: center 把每个元素的初始位置压到父容器中心,随后 translate() 才是纯径向位移。缺少这一步,位移会叠加在各自的正常流位置上,圆会散架。
  • 父容器需提供定位上下文。参考实现里 .circle-container 是 position: relative 的 300×300 正方形,搭配 display: grid; place-items: center,并把 --radius 调到 120px 以留在边框内。
  • 角度用 deg 承载。cos() / sin() 接收角度,所以 360deg / count * index 中的 deg 不可省略;乘出来的位移是无单位的比例系数乘以 --radius 的长度,最终得到合法长度值。

降级策略:特性检测 + 自定义属性双轨

指南在 ## Fallback strategies 之后用 {{ BASELINE_STATUS("sibling-count") }} 宏插入了该特性的 Baseline 状态。这个宏由 macros.ts 实现:构建时调用 getStatusMessage() 从 web-features 与 Browser Compat Data 取状态;当目标为 devsite 且未显式给出 BCD key 时,会改为输出 {{ macros.BaselineStatus(...) }} 交由站点渲染。状态本身随依赖数据更新,因此指南正文不硬编码版本号——这也是撰写同类内容时值得沿用的做法。

在功能未普及的浏览器上,降级链路分成两半:JS 注入变量,CSS 用 @supports 择优覆盖。

第一步:用 CSS.supports() 守卫的 JS 注入

/* MANDATORY: 先检测原生支持,避免无谓的脚本执行 */
if (!CSS.supports('top: calc(sibling-index() * 1px)')) {
  const items = document.querySelectorAll('.item');
  items.forEach((item, index) => {
    /* MANDATORY: 注入的序号必须是 1 起始,与原生函数语义对齐 */
    item.style.setProperty('--sibling-index', index + 1);
    item.style.setProperty('--sibling-count', items.length);
  });
}

指南把这段逻辑中的两个环节都标注为 MANDATORY,原因分别是:

  • CSS.supports() 检测必不可少:不支持时执行 JS 是“补位”,支持时执行则是纯粹的浪费——而且会造成两套数据源并存的混乱。检测表达式选用 top: calc(sibling-index() * 1px) 而不是裸函数名,因为 @supports / CSS.supports() 需要一个完整的声明来判定,把函数嵌进长度计算里才具备可解析性。参考实现 demo.html 使用同一表达式,只是把注入逻辑抽成了 applyFallback(selector) 复用给三组元素。
  • 序号必须是 1 起始:原生 sibling-index() 从 1 计数,若降级用 index(0 起始),同一套 calc() 公式在两种浏览器上会给出不同结果——最直接的表现是第一个元素颜色/角度错位。仓库的评分脚本会显式读取 --sibling-index 并断言其等于 '1'。

第二步:以变量为基线,@supports 内覆盖为原生函数

.item {
  /* 1. 先用变量打底(值来自 JS 降级注入) */
  --index: var(--sibling-index);
  --count: var(--sibling-count);

  /* 2. 用算出的变量写实现相关的样式 */
  background-color: hsl(calc(360deg / var(--count) * var(--index)), 70%, 50%);
}

@supports (top: calc(sibling-index() * 1px)) {
  .item {
    /* 3. 仅在支持时才用原生函数覆盖变量 */
    --index: sibling-index();
    --count: sibling-count();
  }
}

这段模式的价值在于:业务样式只写一次,永远只消费 --index / --count,数据来源由 @supports 在运行时切换。指南同样把“必须包在 @supports 里”标为 MANDATORY,其技术根因是自定义属性的特殊性——--index: sibling-index(); 在解析阶段只是一串待替换的 token,即便函数不被支持,声明本身也未必报错,真正的失效发生在 var() 替换之后。若不加 @supports,旧浏览器会“接受”这条声明却在使用时让整条 background-color 失效,表现为样式全丢。加上 @supports 后,不支持的浏览器会保留变量基线的值,行为可预期。

参考实现里,三组组件(.spectrum-card、.fan-card、.circle-orb)都重复了“基线 + @supports 覆盖”的成对结构,见 demo.html、demo.html、demo.html。

实践补充:让降级更抗破碎

以下两点属于基于 CSS 语义与示例结构的工程建议,而非指南原文断言,落地时值得一并考虑:

  • 给 var() 留兜底值。若 JS 未执行(脚本加载失败、元素后插入),var(--sibling-index) 会因为没有回退值而使整条声明在计算值阶段失效。写成 var(--sibling-index, 1) 与 var(--sibling-count, 1) 至少能退化到“不报错、样式近似”的状态。
  • 动态增删元素后需重跑注入。原生函数由样式引擎自动重算,而 JS 降级是一次性快照;如果列表会在客户端增删,需在变更后重新执行注入。参考实现刻意只用静态列表,因此没有处理这一场景。

可验证性:expectations 与 grader 如何锁定实现质量

该用例不只提供示例,还配套了一套可自动执行的质量门槛,这也是 Modern Web Guidance 区别于普通教程的地方。

expectations.md 用 9 条可观察要求描述了“合格实现”的外观,包括:使用两个原生函数计算视觉属性、提供降级、降级注入 --sibling-index / --sibling-count、用 CSS.supports() 条件执行、注入值 1 起始、CSS 以变量为基线并在 @supports 内覆盖、用总数做比例分配、用总数求对称中点、以及结合三角函数做环形定位。

grader.ts 把这些要求映射为 Playwright 测试,其中几处设计很能说明“为什么这些约束是硬性的”:

测试意图 实现手法 关键行
确认真用了原生函数 对文件内容匹配 sibling-index\s*\( 与 sibling-count\s*\( L35-L38
强制走降级分支 addInitScript 劫持 CSS.supports,凡条件含 sibling-index 一律返回 false L40-L68
校验 1 起始与总数 读取内联 --sibling-index / --sibling-count,断言首项为 '1' 且总数等于元素个数 L60-L63
校验 @supports 确实生效 在支持的浏览器下读取计算后的 --index,断言其包含 sibling-index L82-L91
校验动态自适应 克隆一个 .spectrum-card 追加到父节点,轮询宽度/背景色/transform 是否发生变化 L93-L125
校验中点与三角函数 正则检查“加一除以二”与 sin( / cos( 是否同时出现 L127-L135

其中“克隆节点后样式必须变化”这条最能体现用例的核心意图:它不满足于静态截图正确,而是要求实现真的由数量驱动。写入 width: calc(100% / var(--count)) 的卡片在新增一个同级元素后宽度会被重新分配,背景色相也会重排——这正是 sibling-count() 存在的意义。

反面示例:四种典型失败

negative-demo.html 是一个刻意写坏的对照样本,注释里逐条标出了失败点:

.swatch {
  height: 100px;
  /* 失败:完全没有 sibling-count(),宽度被写死 */
  width: 100px;
  background-color: steelblue;
}
/* 失败:缺少 CSS.supports() 特性检测 */
/* 失败:降级使用 0 起始序号 */
const items = document.querySelectorAll('.swatch');
items.forEach((item, index) => {
  item.style.setProperty('--sibling-index', index);
  item.style.setProperty('--sibling-count', items.length);
});

归纳起来是四类问题:硬编码尺寸导致不随数量变化、固定颜色放弃光谱、无条件执行降级脚本造成重复劳动、0 起始序号与原生语义错位。第四类最隐蔽——页面在旧浏览器上“看起来也有颜色”,只是整条光谱相对原生实现整体偏移了一位。

真实任务形态:从 daily-grind 应用到通用列表

用例的任务描述 tasks/task.md 给出了一个贴近业务的落地场景,其 frontmatter 指定 base_app: daily-grind:

用现代 CSS 为现有 .card 元素追加 .spectrum-card 类并赋予光谱背景色;新增一个含 5 张会员卡的 .fan-container,卡片类为 .fan-card,对称扇形展开;再新增含 6 个咖啡产地徽章的 .circle-container,徽章类为 .circle-orb,环形排列。MANDATORY:所有实现必须是动态的,未来增删元素时能自动适配。

这段任务描述把三个模式串成了同一个页面的三种组件,并且把“动态自适应”写成了硬性要求——它不是可选的优化项,而是验收条件。因此判断一份实现是否合格,标准不是“5 张卡看起来像扇形”,而是“删掉一张后仍然是扇形”。

生态位置:同一组函数在仓库中的其他用法

dynamic-sibling-styling 聚焦视觉与几何,而这两个函数在仓库的其他指南里承担着不同职责,可作为交叉参考:

  • 层级与堆叠:breadcrumbs/guide.md 用 z-index: calc(sibling-count() - sibling-index()) 让越靠前的面包屑层级越高,并用 calc(sibling-count() + 1) 在聚焦时把当前项提到最前,且把规则包在 @supports (corner-shape: bevel) and (z-index: sibling-index()) 中进行能力门控。
  • 循环轮播的“停靠”逻辑:carousel/guide.md 用 order: clamp(0, var(--current) - (sibling-count() - 3), 1) 计算首尾幻灯片的停放位置,并明确要求无支持时退回有限轮播。
  • 动画错峰:dynamic-sibling-animations/guide.md 用 calc(sibling-index() * var(--stagger-time)) 替代成串的 :nth-child 延迟规则。这条路径在源码侧还有配套的静态分析规则 dynamic-sibling-animations.ts,它会检测“3 条及以上连续 :nth-child(N) 且只设置 animation-delay / transition-delay”的模式并给出替换建议,同时明确排除那些同时设置了颜色、位移、--i 等属性的规则——因为那种情况无法简单折叠为单个 calc()。

这些用法共同说明:sibling-index() / sibling-count() 提供的是“位置与总量”这一层基础数据,配色、几何、层级、时序都是在它之上的不同投影。

在项目中取用与自测

如果你想在自己的代码库里套用本用例,可以通过仓库提供的 CLI 直接检索与取回,无需克隆整个仓库:

# 按自然语言检索相关指南
npx modern-web-guidance@latest search "style siblings by index and count"

# 按 ID 取回本用例完整内容
npx modern-web-guidance@latest retrieve "dynamic-sibling-styling"

若要修改或新增同类用例,仓库约定的三件套是 guide.md(面向 Agent 检索的自包含指南)、demo.html(可直接打开的参考实现)、expectations.md(可测试的期望清单),详见 guides/CONTRIBUTING.md。提交前应运行 pnpm test 以触发指南结构与 frontmatter 校验;仓库根目录的 package.json 中 test 脚本会执行 src/**/*.test.ts,其中就包含 guide-validation.test.ts 等结构检查。

要点回顾

  • sibling-index() 为 1 起始的序号,sibling-count() 为同级元素总数,两者可直接在 calc() 中参与角度、长度与比例运算。
  • 光谱用 360deg / count * index 分配色相;对称效果用 (count + 1) / 2 求中点,配合 transform-origin 控制旋转轴;环形布局先 absolute + place-self: center 归零,再用 cos() / sin() 径向偏移。
  • 降级必须满足四条硬约束:CSS.supports() 条件执行、注入 1 起始序号、CSS 以自定义属性为基线、原生覆盖放在 @supports 内。
  • 三角函数属于独立特性条目,原生函数与三角函数的能力检测需要分开考虑。
  • 验收标准是“增删元素后样式自动重算”,静态截图正确并不等于实现合格——仓库的评分脚本正是用克隆节点后比对计算样式的方式来守住这一点。
登录后查看全文
modern-web-guidance-src