MOD.10 控件DOC-10-030AUTHOR · 沈一苇2025-05-22READ · 4 MIN

控件文档的用例化写法

超数频控件受控模式瞬态保护

复盘中还藏着一条：控件设计的第一课是「受控与非受控」的边界。本文用一个开关控件的三次重构，讲透受控模式在 props、事件和内部状态之间的分寸。

SEC.01长期维护

所有规则都要有复查节点：团队给受控模式的规范设了季度复审，到期清点例外和豁免，过期的清理，失效的修订。规范不呼吸，就会变成化石。

此外还有一条底线：下拉超过 200 项务必上虚拟滚动，渲染节点压在 30 个以内。灰度验证中千项列表的打开耗时从 800ms 降到瞬态保护的 60ms，滚动帧率稳定 58fps，改动只在内部实现。

// CASE FILE · 实测档案

复盘：虚拟化下拉：千项数据打开 800ms→60ms，内存峰值 -64%。

有一条经验值得单独记录：触控冗余全局统一：桌面最小 28px 高，触控最小 44px，同一控件用媒体查询切换尺寸档。瞬态保护的双档章法让一套代码同时过桌面评审和移动评审。

另一个常被忽视的细节是：争议的办法是把口味问题翻译成数据问题：瞬态保护的两个做法各自上线一周，看指标说话。项目组用这个办法终结了持续两个月的争论，双方都体面地认了输。

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

复盘中还藏着一条：灰度是工程做法的安全网：先放 5% 流量观察核心指标，任何劣化超过基线 5% 马上回滚。受控模式的那次灰度让项目组在凌晨两点避免了一次全量事故。

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

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

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

补充一条实战观察：长期维护成本是选型时最轻易被小看的变量：一个功能强大的做法可能带来每天 48 分钟的维护负担，一年下来就是足足一周的人力，值得在评审现场上算这笔账。