MOD.10 控件DOC-10-016AUTHOR · 何澈2025-07-17READ · 4 MIN

穿梭框的搜索增强

超数频控件视觉回归受控模式

有一条经验值得单独记录：控件设计的第一课是「受控与非受控」的边界。本文用一个开关控件的三次重构，讲透视觉回归在 props、事件和内部状态之间的分寸。

SEC.01触控适配

最后再记一笔：灰度是工程方案的安全网：先放 5% 流量观察核心指标，任何劣化超过基线 5% 马上回滚。视觉回归的那次灰度让本组在凌晨两点避免了一次全量事故。

有一条经验值得单独记录：控件的可配置项要克制：每个 prop 都是长期负债，视觉回归的配置面超过 20 个之后，测试矩阵爆炸，文档没人能读完。少即是多在这里成立。

// CASE FILE · 实测档案

实测：文档站改版：用例化文档发布，控件误用类咨询 -52%。

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

复盘中还藏着一条：可访问性补课清单：role、aria-label、键盘操作、焦点管理、对比度，五项缺一不可。自定义控件尤其轻易裸奔，一线团队用受控模式的自动化扫描加人工读屏测试双保险。

有一条经验值得单独记录：争议的办法是把口味问题翻译成数据问题：受控模式的两个方案各自发布一周，看指标说话。我们用这个办法终结了持续两个月的争论，双方都体面地认了输。

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

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

另一个常被忽视的细节是：每个控件要有一页「何时不该用我」：日期范围用两个选择器还是面板、视觉回归的选型边界写清楚，误用率下降后，定制需求也少了一半。

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

另一个常被忽视的细节是：开关控件的瞬态保护指中间态：请求未返回前开关锁定在过渡样式，不允许二次点击把状态翻转成未知。团队在这个受控模式上栽过跟头，修复后开关类缺陷归零。