uni-app 微信小程序 Skyline 长列表虚拟化组件 list-builder 使用指南【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app本篇指南以仓库文档 docs/component/list-builder.md 为骨架系统讲解 uni-app 项目中微信小程序 Skyline 专用长列表虚拟化组件list-builder的兼容性边界、全部属性语义、static/dynamic 两种渲染模式、列表项创建与回收事件机制并结合仓库中list-view、grid-builder等列表类组件的实现与文档帮助你判断何时选用list-builder以及如何写出高性能、可复用的长列表页面。list-builder 是什么list-builder是微信小程序Skyline 渲染引擎提供的高性能长列表组件在 uni-app 中被归类为「微信专用组件 → Skyline」分组参见仓库组件导航 docs/component/_sidebar.md 中的微信专用组件 Skyline list-builder条目。它的核心价值在于列表项虚拟化与回收复用在渲染超长列表时Skyline 只维护屏幕可视区域附近的少量列表项节点配合itembuild/itemdispose事件对列表项进行「创建 - 回收 - 复用」的循环管理从而避免为成千上万条数据创建海量原生节点导致的内存膨胀与滚动卡顿。需要特别说明的是与list-viewuni-app 内置实现、支持 App/Web 等多端不同list-builder在当前仓库源码中没有独立实现代码——它属于 uni-app 编译到微信小程序后透传给 Skyline 原生渲染层的组件因此其行为、事件与能力边界以微信小程序 Skyline 平台为准。这也意味着它的兼容性严格受限详见下文。兼容性仅在微信小程序可用根据原文档 docs/component/list-builder.md 的兼容性矩阵| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | 4.41 | x | x | x |解读仅微信小程序端支持且基础库版本要求 4.41 及以上Web、App-Android、App-iOS、HarmonyOS 端均不支持标记为x即不可用该组件运行前提是页面开启Skyline 渲染在pages.json中为页面配置 Skyline 渲染方式脱离 Skyline 环境无法使用使用前应做好条件编译隔离避免在非微信小程序端引用该组件导致编译或运行异常。属性详解list-builder共提供 6 个属性原文档完整属性表如下| 名称 | 类型 | 兼容性 | 描述 | | :- | :- | :-: | :- | | padding | Array | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x |(Array)长度为 4 的数组按 top、right、bottom、left 顺序指定内边距 | | type | string | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x |(string)类型默认为定高模式 | | list | Array | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x |(Array)需要用于渲染的列表 | | child-count | Array | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x |(Array)完整列表的长度如果不传则取 list 的长度作为其值 | | child-height | Array | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x |(Array)列表项的高度当 type 为 static 时必须传入 | | itembuild | eventhandle | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x |(eventhandle)列表项创建时触发event.detail {index}index 即被创建的列表项序号 | | itemdispose | eventhandle | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x |(eventhandle)列表项回收时触发event.detail {index}index 即被回收的列表项序号 |list驱动渲染的数据源list是组件渲染所需的列表数据类型为 Array。它决定了列表要渲染哪些内容与child-count配合构成虚拟化渲染的基础list中每一项对应一个列表项slot 中的内容会被渲染到每个列表项内与常规v-for列表不同list-builder不会一次性为list的全部数据创建节点而是按需创建可视范围内的列表项。child-count声明完整列表长度child-count表示完整列表的长度。原文档明确如果不传则取list的长度作为其值。这一点在「分批加载 / 无限滚动」场景下非常关键当数据是异步分批拉取时可以先通过child-count声明一个比当前list实际长度更大的「占位总数」让 Skyline 预先按该长度规划滚动区域再逐步向list追加真实数据避免滚动条长度随数据增长不断跳动。由于它直接参与滚动区域高度的预估取值应尽量准确否则可能出现滚动到底却无更多内容、或未到底就触发触底加载的问题。child-heightstatic 定高模式的高度表child-height是数组类型逐项声明列表项的高度。注意原文档的强制约束当type为static时必须传入。它是 static 模式下 Skyline 计算滚动区域总高度的依据所有列表项等高传数组时按对应索引取值由于 static 模式不需要测量每个节点的真实高度省去了布局测量环节是性能最高的一种模式若列表项实际渲染高度与child-height声明不一致会造成滚动定位偏差因此声明值必须与真实 item 高度严格一致。padding内边距padding为长度为 4 的数组按 top、right、bottom、left 顺序指定内边距即[top, right, bottom, left]。它作用于列表整体内容区在长列表滚动时保持列表项与容器边缘的间距。type渲染模式开关type为 string 类型默认值为定高模式即static。取值与描述见原文档| 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | static | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 定高模式所有列表项等高需要传入 child-height | | dynamic | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 不定高模式 |两种模式的选型建议static定高模式所有列表项高度一致如统一为 100rpx 的纯文本行、商品卡固定高。此模式必须配置child-height性能最佳适合超高量级上万条的纯展示列表dynamic不定高模式列表项高度不固定由内容撑开如富文本、图文混排、评论回复等。此模式需要 Skyline 动态测量每个列表项高度无需也不能依赖 child-height 的等高假设性能低于 static但更灵活。事件机制列表项的创建与回收list-builder暴露两个关键事件用于配合虚拟化池管理列表项节点| 事件 | 触发时机 | event.detail | | :- | :- | :- | | itembuild | 列表项创建时触发 |{ index }index 为被创建的列表项序号 | | itemdispose | 列表项回收时触发 |{ index }index 为被回收的列表项序号 |这两个事件的价值在于按需初始化/销毁资源在itembuild中加载图片、建立订阅等重量级资源在itemdispose中释放资源、取消定时器避免列表项滚出屏幕后资源滞留造成内存泄漏状态重置列表项被回收后其 DOM/组件状态可能残留再次itembuild复用时需要依据 index 重新绑定数据——这一点与仓库中list-view的复用注意事项一致仓库文档 docs/component/list-view.md 明确提示「list-item 内部组件如果有内部状态不受绑定数据影响则需要依赖 onReuse、onRecycle 等生命周期函数进行状态重置否则会出现状态错乱」list-builder的itembuild/itemdispose本质上承担了同一职责性能统计与调试通过记录 build/dispose 频次可以观测列表项复用率验证虚拟化是否生效。典型用法示意uni-app 微信小程序端Skyline 渲染template list-builder typestatic :listlist :child-counttotal :child-height[100] :padding[0, 16, 0, 16] itembuildonItemBuild itemdisposeonItemDispose view classrow wx:for{{list}} wx:keyindex{{item}}/view /list-builder /template与 uni-app 其他列表组件的分工在仓库组件体系中长列表场景存在多个候选组件理解它们的分工才能做出正确选型| 组件 | 归属 | 渲染方式 | 适用场景 | | :- | :- | :- | :- | | list-builder | 微信专用组件Skyline | Skyline 虚拟化列表项创建/回收由 itembuild/itemdispose 驱动 | 微信小程序端、Skyline 渲染下的超高量级长列表 | | list-view / list-item | 内置列表容器 | uni-app 多端内置实现App 端基于复用回收docs/component/list-view.md | App/Web/微信等多端通用的长列表支持下拉刷新、吸顶、嵌套滚动 | | grid-builder | 微信专用组件Skyline | Skyline 网格虚拟化支持 aligned / masonry 两种布局 | 微信端网格列表、瀑布流docs/component/grid-builder.md | | waterflow | 内置瀑布流容器 | 多列瀑布流布局 | 多列瀑布流场景docs/component/waterflow.md | | scroll-view | 可滚动视图容器 | 常规滚动无回收复用 | 数据量不大、非长列表的滚动场景 |选型结论微信小程序 Skyline 超长单列列表优先list-builder它比list-view更进一步地把虚拟化下沉到 Skyline 渲染层节点创建/回收由底层托管需要跨端App/Web统一实现选list-view仓库文档 docs/component/list-view.md 指出其 App 端基于复用回收实现长列表渲染资源复用且支持下拉刷新、吸顶sticky-header/sticky-section、嵌套滚动等丰富能力网格/多列微信端用grid-builderaligned 等高网格 / masonry 瀑布流跨端用waterflow。使用注意事项与最佳实践结合原文档约束与仓库列表类组件的通用经验使用list-builder时应注意环境前提仅微信小程序 4.41 且页面启用 Skyline 渲染时可用其他端一律不支持务必用条件编译#ifdef MP-WEIXIN包裹static 模式必须配置 child-height漏传会导致高度计算缺失、滚动区域异常声明高度须与真实 item 高度一致child-count 与 list 的关系默认取list.length做分批加载时先声明占位总数再逐步追加数据保证滚动条稳定善用 itembuild/itemdispose 做资源管理把图片加载、数据订阅放在 build 时把释放动作放在 dispose 时参照 docs/component/list-view.md 中关于复用状态重置的建议防止复用后状态错乱不要放大图、减少 item 内节点数量仓库 docs/component/list-view.md 的列表性能优化经验同样适用——减少列表项中元素数量、避免过多圆角阴影、为不监听事件的节点设置 flatten 拍平属性能显著提升滚动帧率高度不固定的内容用 dynamic 模式强行把所有内容塞进 static 模式并谎报高度会出现滚动定位偏差与内容重叠。延伸阅读docs/component/list-builder.md本主题原始文档含完整属性表与兼容性矩阵docs/component/list-view.mduni-app 内置长列表容器 list-view / list-item 的复用回收机制、下拉刷新与嵌套滚动docs/component/grid-builder.md微信 Skyline 网格虚拟化组件aligned / masonry 布局docs/component/waterflow.md跨端多列瀑布流容器docs/component/scroll-view.md常规可滚动容器非长列表场景的首选docs/component/_sidebar.md组件文档总导航可在「微信专用组件 → Skyline」分组下查看 list-builder 的定位【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考