SuperAPI AI 工具集

legend-list-best-practices

通用与其它

查看项目

更新于 10-15 23:58

技能介绍

用途:用于实现或审计 @legendapp/list 的使用,涵盖回收(recycling)、测量(measurement)、失效(invalidation)与滚动锚定等主题。技能强调使用 Legend List 特有契约,而不是通用属性调优;对不清晰的 bug 或回归,应先复现并测量再改代码。

主要能力与工作流:区分构建、审计、修复三种模式。构建时先确立 keys、失效、行归属、测量、回收与验证。审计时检查列表与完整行树,按影响与置信度排序报告具体发现,区分已测量问题与风险。修复时先审计并给出排序计划再执行。追溯每个发现到确切的列表、行、状态来源及失效、测量或滚动路径。

身份与失效:使用稳定唯一的 keyExtractor,避免在可重排、前置、删除或回收时使用索引键。data 可为键数组但必须保持数组。替换逻辑数据集时改 dataKey,原地修改同一数组时改 dataVersion,优先不可变更新。仅在语义未变时使用 itemsAreEqual 且需覆盖所有影响渲染或布局的字段。extraData 仅在外部值需使所有已挂载项重估时使用,保持最小且低频。勿用变化的 React key 作为常规更新信号。

属性与行稳定性:审计父组件重渲染时所有非原始类型属性,保持身份稳定。extraData 本身也应稳定(如 useMemo)。不要让列表级属性依赖易变的选择、展开、悬停、输入、播放或筛选状态。返回具名窄属性的行组件,将易变状态放入拥有该状态的行或按项作用域的订阅。若存在广泛失效,可将按键的外部状态或支持选择器的状态库作为架构选项提出,但未经批准不得添加依赖。勿用 :first-child 等 DOM 结构选择器表示数据位置。

测量与布局:estimatedItemSize 与 estimatedListSize 是可选首屏提示,默认估计 100。getFixedItemSize 仅用于真正固定尺寸,动态项返回 undefined。视口尺寸放在 style 的 flex:1,contentContainerStyle 留给内部布局。清缓存前先证明其过期,优先 clearCaches({ mode: "sizes" })。drawDistance 仅在行成本与测量可靠后调整。

验证与库 bug:仅验证受所请求或已批准变更影响的行为,使用代表性数据,包括快速滚动与大幅跳跃。验证性能声明需提供同一交互的前后渲染或 profiler 证据。仅在聚焦复现或源码追踪显示正确用法仍失败时,才按库 bug 路径处理。

限制:回收细节见 recycling.md,聊天锚定、命令式滚动或可见性见 scroll-and-visibility.md;这两份具体文档内容暂未提供。