# list 列表

  • app端nvue专用组件。在app-nvue下,如果是长列表,使用list组件的性能高于使用view或scroll-view的滚动。原因在于list在不可见部分的渲染资源回收有特殊的优化处理。原生渲染的资源回收机制,与webview渲染不同。webview不需要数据有规则格式,长页面处于不可视的部分,其渲染资源会自动回收,除非webview使用区域滚动而不是页面滚动。所以vue页面只要不用scroll-view,就不需要关注这个问题。而原生渲染则必须注意。
  • <list> 组件是提供垂直列表功能的核心组件,拥有平滑的滚动和高效的内存管理,非常适合用于长列表的展示。最简单的使用方法是在 <list> 标签内使用一组由简单数组循环生成的 <cell> 标签填充。
  • uni-app官方详细文档
  • weex官方详细文档

# 示例

<template>
	<list ref="list">
		<!-- 注意事项: 不能使用 index 作为 key 的唯一标识 -->
		<cell v-for="(item, index) in lists" :key="item.id">
			<text>{{item.name}}</text>
		</cell>
	</list>
</template>

<script>
	export default {
		data() {
			return {
				lists: [{id: "1",name: 'A'}, {id: "2",name: 'B'}, {id: "3",name: 'C'}]
			}
		},
		methods: {
			// 重置 loadmore
			resetLoadMore() {
				this.$refs["list"].resetLoadmore();
			}
		}
	}
</script>

<style lang="scss">

</style>

注意

  • 相同方向 <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> 的子组件只能包括以下四种组件或是 fix 定位的组件,其他形式的组件将不能被正确渲染。

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

# API

# Attribute 属性

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

# Ref 实例

事件名 说明 回调参数 返回参数
resetLoadmore 重置loadmore - -

# Event 事件

事件名 说明 参数 返回值
@loadmore 如果列表滚动到底部将会立即触发这个事件,你可以在这个事件的处理函数中加载下一页的列表项。 如果未触发,请检查是否设置了loadmoreoffset的值,建议此值设置大于0 - -
@scroll 列表发生滚动时将会触发该事件,事件的默认抽样率为 10px,即列表每滚动 10px 触发一次,可通过属性 offset-accuracy 设置抽样率。 -

# 属性/事件说明

以下专题为个别组件属性的详细讲解,帮助您快速理解属性使用。

# @scroll

列表发生滚动时将会触发该事件,事件的默认抽样率为 10px,即列表每滚动 10px 触发一次,可通过属性 offset-accuracy 设置抽样率。

  • contentSize {Object} :列表的内容尺寸
    • width {number}:列表内容宽度 +height {number}:列表内容高度
  • contentOffset {Object} :列表的偏移尺寸
    • x {number}:x轴上的偏移量
    • y {number}:y轴上的偏移量
  • isDragging {boolean} : 用户是否正在拖动列表

# setSpecialEffects(object)

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

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

# list.setSpecialEffects(args)

设置嵌套父容器信息,args 为要设置的参数为json类型可以包含下列元素

属性 类型 默认值 必填 备注
id string - 和list同时滚动的组件id,应为外层的scroller
headerHeight float 0 要吸顶的header顶部距离scroller顶部的距离
  <list id="" fixFreezing="true"></list>
  // ios 需要配置 fixFreezing="true"

  //设置
  const list = this.$refs["list0"];
  list.setSpecialEffects({id:"scroller", headerHeight:150});
  
  //清除
  list.setSpecialEffects({});