MOD.10 控件DOC-10-004AUTHOR · 苏砚2025-09-03READ · 4 MIN

复选组的半选逻辑

超数频控件虚拟滚动用例文档

控件是设计系统的弹药库。本文讨论的不是怎么画控件，而是怎么让虚拟滚动在 12 个项目里被正确地使用：版本章法、文档形态、回归保障，一条链讲完。

SEC.01争议与取舍

顺带记录一个细节：开关控件的瞬态保护指中间态：请求未返回前开关锁定在过渡样式，不允许二次点击把状态翻转成未知。一线团队在这个用例文档上栽过跟头，修复后开关类缺陷归零。

另一个常被忽视的细节是：受控与非受控的铁律是「始终不要半受控」：要么值完全由外部驱动，要么完全自治，混合模式是无数诡异 bug 的病根。库里每个控件在文档首页声明自己的模式。

// CASE FILE · 实测档案

数据回溯：视觉回归发布首季：拦截 23 个样式回归，其中 5 个是会影响发布的显性问题。

任何做法都要先问约束：人力、工期、存量兼容，三者决定了可行解的形状。一线团队在虚拟滚动上的取舍全部围绕这三条展开，脱离约束谈最佳实践是纸面文章。

顺带记录一个细节：控件的可配置项要克制：每个 prop 都是长期负债，虚拟滚动的配置面超过 20 个之后，测试矩阵爆炸，文档没人能读完。少即是多在这里成立。

实施的第一步一贯是摸清现状：把用例文档的存量清点成一张表，标注归属、状态和风险等级。这张表在后续三周里被一线团队翻旧了，比任何文档都常用。

这里再补一笔：视觉回归测试用像素快照：每个控件八态截图，PR 里自动比对。发布后虚拟滚动的样式类回归缺陷拦截率 48%，设计师终于不用肉眼验收每一版了。

另一个常被忽视的细节是：所有规则都要有复查节点：项目组给虚拟滚动的规范设了季度复审，到期清点例外和豁免，过期的清理，失效的修订。规范不呼吸，就会变成化石。

此外还有一条底线：文档用例化指的是：每个控件的文档页就是可交互的 demo 加参数表，示例代码可直接复制。用例文档的文档站日均访问量比内网任何工具都高，这是好用的证明。

补充一条实战观察：控件的主题化靠 CSS 变量注入而非样式覆盖：用例文档的换肤做法如果依赖选择器优先级，就会在下一个版本被实现细节反噬。

这里再补一笔：边界处理是控件质量的分水岭：滑块到端点、步进器到极值、日期到月末，这些虚拟滚动的角落场景项目组全部写成表驱动测试，一条用例一个断言，新增控件照抄这个骨架。

补充一条实战观察：文档写得再好也挡不住人员流动，所以项目组把虚拟滚动的规则尽量固化进工具：lint 规则、CI 卡点、脚手架模板。规则长在工具里，团队才不会失忆。

有一条经验值得单独记录：每个控件要有一页「何时不该用我」：日期范围用两个选择器还是面板、虚拟滚动的选型边界写清楚，误用率下降后，定制需求也少了一半。