uni-app 微信小程序 Skyline 长列表虚拟化组件 list-builder 使用指南-创锋一号

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-view（uni-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-height：static 定高模式的高度表

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 type="static" :list="list" :child-count="total" :child-height="[100]" :padding="[0, 16, 0, 16]" @itembuild="onItemBuild" @itemdispose="onItemDispose" > <view class="row" wx:for="{{list}}" wx:key="index">{{item}}</view> </list-builder> </template>

与 uni-app 其他列表组件的分工

在仓库组件体系中，长列表场景存在多个候选组件，理解它们的分工才能做出正确选型：

选型结论：

微信小程序 + Skyline + 超长单列列表：优先list-builder，它比list-view更进一步地把虚拟化下沉到 Skyline 渲染层，节点创建/回收由底层托管；
需要跨端（App/Web）统一实现：选list-view，仓库文档 docs/component/list-view.md 指出其 App 端基于复用回收实现长列表渲染资源复用，且支持下拉刷新、吸顶（sticky-header/sticky-section）、嵌套滚动等丰富能力；
网格/多列：微信端用grid-builder（aligned 等高网格 / 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 模式并谎报高度，会出现滚动定位偏差与内容重叠。

企业官网建设流程全解析