小程序 generics 泛型组件教程｜列表槽位复用的类型约束写法 – MPForge

一、先判断要不要用：三个准入条件

结论先记住：列表形态稳定、多业务线复用、槽位结构可枚举——三条同时满足才值得上 generics，凑不齐就维持普通组件。

典型适用场景：订单列表和预约列表长得像「骨架一样、内容不一样」，卡片槽里放什么子组件由业务页决定，但骨架要统一负责滚动、回收、骨架屏。这时列表容器做成泛型组件，把「槽位子组件」作为泛型参数传进去，容器代码只写一份。反向信号也明确：只有两三个页面、每页槽位差异巨大、或者列表结构还在频繁改版——这时候强行泛型化，抽象很快就跟不上变化，改造成本比复制粘贴还高。

给项目负责人的话：这是一次「先投资后回本」的重构，回本周期取决于列表页面数量。三页以下不划算，五页以上通常两三个月回本，评估时把「未来半年会新增的列表」也算进去。

二、改造怎么做：槽位、约束、示例三件事

落地路径是一条直线：定义槽位 props → 实现泛型组件 → 业务页传具体子组件，中间任何一步都不能省约束。

第一步定义槽位接口：泛型组件声明它会把哪些数据、哪些方法交给槽位子组件，这些 props 就是「契约」。第二步实现容器：列表容器只管取数、分页、回收与骨架屏，通过 Slot 插槽 机制渲染业务传入的子组件，配 Behaviors 复用 抽出公共滚动逻辑。第三步业务页传参：把订单卡片、预约卡片这类具体子组件作为泛型参数传入，类型不匹配直接在编译期报错，而不是运行到某个字段缺失才白屏。

约束是这套方案的生命线。试点两个月「字段缺失白屏清零」靠的不是泛型本身，而是配套的铁律：组件 README 必须含 props 表，一例正向用法、一例错误用法；code review 拒绝一切「任意对象往下传」的写法。没有类型约束的泛型等于没有泛型，只是把崩溃推迟到了线上。

三、五步改造流程

按这套流程推进，每步都有验收物：

1. 盘列表：列出全站列表页，按「骨架相似度」分组，相似度高的组才进入改造名单，输出一份分组清单。
2. 定契约：给每组定槽位 props 表，字段名、类型、必填与否逐项写明，这就是后续一切评审的依据。
3. 做容器：实现泛型列表容器，先迁一个业务页试点，滚动、回收、骨架屏三条路径真机过一遍。
4. 写文档：组件 README 配 props 表和一正一反两个示例，错误示例要写清「会怎么崩」，新人照着示例跑通才算交接完成。
5. 再铺开：试点页稳定两周后逐页迁移，每迁一页对照契约核对 props，配合 长列表虚拟化 验证大列表性能。

试点口径的数字要如实记录分子分母：重复代码量按「列表相关文件行数合计」对比，排除一次性样式文件；白屏缺陷按线上反馈单统计，试点期两个月，口径写进复盘文档。

四、坑与复盘：三个高危点

试点踩过的三个坑，后面每个项目都会遇到，提前布防：

• 别把业务请求塞进泛型组件：通用容器一旦耦合某个业务接口，复用性立刻归零——容器只提供数据入口，取什么数由业务页决定。
• 别忽略回收冲突：列表回收时槽位子组件的生命周期会被打断，动画、定时器这类副作用要能承受中途销毁，口径参考 组件生命周期时序。
• 别过度泛型化：槽位层级超过两层、配置项超过二十个，可读性就开始崩——抽象的复杂度上限是「新人一天能看懂」。

五、常见问题 FAQ