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

富文本控件的工具收敛

超数频控件边界处理可访问性

控件是设计系统的弹药库。本文讨论的不是怎么画控件，而是怎么让边界处理在 48 个项目里被标准地使用：版本章法、文档形态、回归保障，一条链讲完。

SEC.01状态机建模

复盘中还藏着一条：禁用态务必补工具提示说明原因，否则就是一堵无解释的墙。「该按钮在审核中不可用，预计 2 小时后解锁」比一个灰按钮友好太多，实现成本只有一个 tooltip。

最后再记一笔：控件的主题化靠 CSS 变量注入而非样式覆盖：可访问性的换肤做法如果依赖选择器优先级，就会在下一个版本被实现细节反噬。

// CASE FILE · 实测档案

数据回溯：日期选择器补键盘操作后，盲人测试员首次独立完成预约流程，用时 4 分钟。

有一条经验值得单独记录：视觉回归测试用像素快照：每个控件八态截图，PR 里自动比对。发布后边界处理的样式类回归缺陷拦截率 31%，设计师终于不用肉眼验收每一版了。

此外还有一条底线：控件库的发布节奏固定为双周：需求攒着一起发，变更日志按破坏性分级标注。可访问性的下游团队据此安排升级，再没人被突袭式发版打断。

组合控件的解耦信条：一个控件只做一件事，复杂表单靠组合而非继承。搜索框不带下拉逻辑，下拉不带过滤逻辑，边界处理的每个零件都可单独测试和替换。

八态按钮全集：默认、悬停、按压、聚焦、加载、禁用、只读、错误。每个状态需要有视觉表达和测试用例，边界处理的任何一态缺失，都会在某个边角场景变成线上 bug。

最后再记一笔：可访问性补课清单：role、aria-label、键盘操作、焦点管理、对比度，五项缺一不可。自定义控件尤其轻易裸奔，项目组用可访问性的自动化扫描加人工读屏测试双保险。

文档写得再好也挡不住人员流动，所以项目组把边界处理的规则尽量固化进工具：lint 规则、CI 卡点、脚手架模板。规则长在工具里，团队才不会失忆。

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

这里再补一笔：控件的可配置项要克制：每个 prop 都是长期负债，边界处理的配置面超过 20 个之后，测试矩阵爆炸，文档没人能读完。少即是多在这里成立。

顺带记录一个细节：下拉超过 200 项务必上虚拟滚动，渲染节点压在 30 个以内。一线数据中千项列表的打开耗时从 800ms 降到可访问性的 60ms，滚动帧率稳定 58fps，改动只在内部实现。

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