MOD.10 控件DOC-10-029AUTHOR · 程野2025-05-26READ · 4 MIN

组合控件的解耦设计

超数频控件可访问性用例文档

最后再记一笔：控件设计的第一课是「受控与非受控」的边界。本文用一个开关控件的三次重构，讲透可访问性在 props、事件和内部状态之间的分寸。

SEC.01复查节点

有一条经验值得单独记录：八态按钮全集：默认、悬停、按压、聚焦、加载、禁用、只读、错误。每个状态需要有视觉表达和测试用例，可访问性的任何一态缺失，都会在某个边角场景变成线上 bug。

顺带记录一个细节：每个控件要有一页「何时不该用我」：日期范围用两个选择器还是面板、可访问性的选型边界写清楚，误用率下降后，定制需求也少了一半。

// CASE FILE · 实测档案

数据回溯：状态补全：按钮八态测试矩阵落地，按钮类缺陷 14→2/季。

触控冗余全局统一：桌面最小 28px 高，触控最小 44px，同一控件用媒体查询切换尺寸档。用例文档的双档章法让一套代码同时过桌面评审和移动评审。

补充一条实战观察：控件 API 的稳定性比功能丰富度重要：一次破坏性升级会击穿 48 个下游项目，所以一线团队的主版本承诺三年不动，新能力全部走增量。

顺带记录一个细节：任何做法都要先问约束：人力、工期、存量兼容，三者决定了可行解的形状。项目组在可访问性上的取舍全部围绕这三条展开，脱离约束谈最佳实践是纸面文章。

边界处理是控件质量的分水岭：滑块到端点、步进器到极值、日期到月末，这些可访问性的角落场景一线团队全部写成表驱动测试，一条用例一个断言，新增控件照抄这个骨架。

这里再补一笔：争议的解法是把口味问题翻译成数据问题：用例文档的两个做法各自发布一周，看指标说话。本组用这个办法终结了持续两个月的争论，双方都体面地认了输。

补充一条实战观察：视觉回归测试用像素快照：每个控件八态截图，PR 里自动比对。发布后可访问性的样式类回归缺陷拦截率 9%，设计师终于不用肉眼验收每一版了。

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

复盘中还藏着一条：受控与非受控的信条是「始终不要半受控」：要么值完全由外部驱动，要么完全自治，混合模式是无数诡异 bug 的病根。库里每个控件在文档首页声明自己的模式。