list(列表),app 端 nvue 专用组件。在 app-nvue 下,如果是长列表,使用 list 组件的性能高于使用 view 或 scroll-view 的滚动。原因在于 list 在不可见部分的渲染资源回收有特殊的优化处理。

原生渲染的资源回收机制,与 webview 渲染不同。webview 不需要数据有规则格式,长页面处于不可视的部分,其渲染资源会自动回收,除非 webview 使用区域滚动而不是页面滚动。所以 vue 页面只要不用 scroll-view,就不需要关注这个问题。而原生渲染则必须注意。

如果需要跨端,建议使用 uni-ui 的 uni-list 组件,它会自动处理 webview 渲染和原生渲染的情况,在 app-nvue 下使用 list 组件,而在其他平台则使用页面滚动。

<list> 组件是提供垂直列表功能的核心组件,拥有平滑的滚动和高效的内存管理,非常适合用于长列表的展示。最简单的使用方法是在 <list> 标签内使用一组由简单数组循环生成的 <cell> 标签填充。

						
<template>
  <list>
    <cell v-for="(item, index) in dataList" :key="item.id">
      <text>{{ item.name }}</text>
    </cell>
  <list>  
</template>

<script>
  export default {
    data() {
      return {
        dataList: [{id:'1', name:'A'}, {id:'2', name:'B'}, {id:'3', name:'C'}]
      }
    }
  }
</script>
						
					

说明:

  • 相同方向 <list> 或者 <scroll-view> 互相嵌套时,Android 平台子 <list> 不可滚动,iOS 可以,iOS 有 Bounce 效果, Android 仅可滚动时有。
  • <list> 需要显式的设置其宽高,可使用 position: absolute; 定位或 width、height 设置其宽高值。
  • list 是区域滚动,不会触发页面滚动,无法触发 pages.json 配置的下拉刷新、页面触底 onReachBottomDistance、titleNView的transparent 透明渐变。
  • Android 平台,因 <list> 高效内存回收机制,不在屏幕可见区域的组件不会被创建,导致一些内部需要计算宽高的组件无法正常工作,例如 <slider>、<progress>、<swiper>。

list 属性

list 属性
属性名属性值类型默认值说明
show-scrollbarbooleantrue控制是否出现滚动条。
bouncebooleantrue控制是否有回弹效果。
loadmoreoffsetnumber10触发 loadmore 事件所需要的垂直偏移距离(设备屏幕底部与 list 底部之间的距离),建议手动设置此值,设置大于 0 的值即可 。
offset-accuracynumber10控制 onscroll 事件触发的频率:表示两次 onscroll 事件之间列表至少滚动了 10px。注意,将该值设置为较小的数值会提高滚动事件采样的精度,但同时也会降低页面的性能。
pagingEnabledbooleanfalse是否按分页模式显示 list。
scrollablebooleantrue是否允许 list 滚动。

loadmoreoffset 示意图:

子组件

<list> 的子组件只能包括以下四种组件或是 fix 定位的组件,其他形式的组件将不能被正确渲染。

list 子组件
子组件说明
<cell>用于定义列表中的子列表项,类似于 HTML 中的 ul 之于 li。<list> 会对 <cell> 进行高效的内存回收以达到更好的性能。
<header>当 <header> 到达屏幕顶部时,吸附在屏幕顶部。
<refresh>用于给列表添加下拉刷新的功能。
<loading><loading> 用法与特性和 <refresh> 类似,用于给列表添加上拉加载更多的功能。

setSpecialEffects(object)

设置嵌套 list 父容器支持 swiper-list 吸顶滚动效果。

list 父容器属性
属性类型必填说明备注
idStringlist 父容器滚动组件 id。应为最外层滚动容器,必须是 list 组件。
headerHeightNumber吸顶距离子 list 吸顶距离最外层滚动容器顶部的距离。

说明:

  • iOS 需要配置:fixFreezing = 'true'。
						
list.setSpecialEffect({
  id: 'scroller',
  headerHeight: 150
});

//清除吸顶效果
list.setSpecialEffect({});
						
					

事件

loadmore 事件:如果列表滚动到底部将会立即触发这个事件,可以在这个事件的处理函数中加载下一页的列表项。 如果未触发,请检查是否设置了 loadmoreoffset 的值,建议此值设置大于 0。