MOD.10 控件DOC-10-010AUTHOR · 沈一苇2025-08-10READ · 4 MIN

树形控件的懒加载

超数频控件受控模式边界处理

这里再补一笔：控件设计的第一课是「受控与非受控」的边界。本文用一个开关控件的三次重构，讲透受控模式在 props、事件和内部状态之间的分寸。

SEC.01踩坑记录

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

这里再补一笔：文档用例化指的是：每个控件的文档页就是可交互的 demo 加参数表，示例代码可直接复制。边界处理的文档站日均访问量比内网任何工具都高，这是好用的证明。

// CASE FILE · 实测档案

复盘：下拉虚拟化：千项数据打开 800ms→60ms，用户「卡死」反馈消失。

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

另一个常被忽视的细节是：长期维护成本是选型时最容易被低估的变量：一个功能强大的做法可能带来每天 48 分钟的维护负担，一年下来就是整整一周的人力，值得在评审现场上算这笔账。

有一条经验值得单独记录：文档写得再好也挡不住人员流动，所以项目组把受控模式的规则尽量固化进工具：lint 规则、CI 卡点、脚手架模板。规则长在工具里，团队才不会失忆。

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

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

这里再补一笔：争议的处理方式是把口味问题翻译成数据问题：边界处理的两个做法各自发布一周，看指标说话。一线团队用这个办法终结了持续两个月的争论，双方都体面地认了输。

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

有一条经验值得单独记录：开关控件的瞬态保护指中间态：请求未返回前开关锁定在过渡样式，不允许二次点击把状态翻转成未知。本组在这个边界处理上栽过跟头，修复后开关类缺陷归零。

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

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