list-view

list-view 兼容性

属性

direction 兼容性

associative-container 兼容性

refresher-default-style 兼容性

事件

UniRefresherEvent

UniScrollToUpperEvent

UniScrollToLowerEvent

展示全部

# list-view

组件类型：UniListViewElement

列表组件

# list-view 兼容性

Android	iOS	web
3.9	4.11	4.02

在App中，基于recycle-view的list，才能实现长列表的资源自动回收，以保障列表加载很多项目时，屏幕外的资源被有效回收。list-view就是基于recycle-view的list组件。

每个list由1个父组件list-view及若干子组件list-item构成。仅有有限子组件可识别，见下

list-view和scroll-view都是滚动组件，list适用于长列表场景，其他场景适用于scroll-view。

list-view支持通过子组件sticky-header处理吸顶的场景。

# 属性

名称

类型

默认值

描述

direction

string

"vertical"

滚动方向，可取值 none、horizontal、vertical，默认值vertical。注：iOS 平台仅支持vertical

值名称	描述
none	禁止滚动
horizontal	横向滚动
vertical	竖向滚动

~~scroll-x~~

boolean

false

允许横向滚动，不支持同时设置scroll-y属性为true，同时设置true时scroll-y生效。已废弃，请改用direction

~~scroll-y~~

boolean

true

允许纵向滚动，不支持同时设置scroll-x属性为true，同时设置true时scroll-y生效。已废弃，请改用direction

~~rebound~~

boolean

true

控制是否回弹效果。已废弃，请改用bounces

associative-container

string

关联的滚动容器

值名称	描述
nested-scroll-view	嵌套滚动

bounces

boolean

true

控制是否回弹效果优先级高于rebound

upper-threshold

number

距顶部/左边多远时（单位px），触发 scrolltoupper 事件

lower-threshold

number

距底部/右边多远时（单位px），触发 scrolltolower 事件

scroll-top

number

设置竖向滚动条位置

scroll-left

number

设置横向滚动条位置

show-scrollbar

boolean

true

控制是否出现滚动条

scroll-into-view

string(string.IDString)

值应为某子元素id（id不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素起始位置

scroll-with-animation

boolean

false

是否在设置滚动条位置时使用滚动动画，设置false没有滚动动画

refresher-enabled

boolean

false

开启下拉刷新，暂时不支持scroll-x = true横向刷新

refresher-threshold

number

设置下拉刷新阈值, 仅 refresher-default-style = 'none' 自定义样式下生效

refresher-max-drag-distance

number

设置下拉最大拖拽距离（单位px），默认是下拉刷新控件高度的2.5倍

refresher-default-style

string

"black"

设置下拉刷新默认样式，支持设置 black | white | none， none 表示不使用默认样式

值名称	描述
black	深颜色雪花样式
white	浅白色雪花样式
none	不使用默认样式

refresher-background

string(string.ColorString)

"transparent"

设置下拉刷新区域背景颜色，默认透明

refresher-triggered

boolean

false

设置当前下拉刷新状态，true 表示下拉刷新已经被触发，false 表示下拉刷新未被触发

enable-back-to-top

boolean

false

iOS点击顶部状态栏滚动条返回顶部，只支持竖向

custom-nested-scroll

boolean

false

子元素是否开启嵌套滚动将滚动事件与父元素协商处理

@refresherpulling

(event: UniRefresherEvent) => void

下拉刷新控件被下拉

@refresherrefresh

(event: UniRefresherEvent) => void

下拉刷新被触发

@refresherrestore

(event: UniRefresherEvent) => void

下拉刷新被复位

@refresherabort

(event: UniRefresherEvent) => void

下拉刷新被中止

@scrolltoupper

(event: UniScrollToUpperEvent) => void

滚动到顶部/左边，会触发 scrolltoupper 事件

@scrolltolower

(event: UniScrollToLowerEvent) => void

滚动到底部/右边，会触发 scrolltolower 事件

@scroll

(event: UniScrollEvent) => void

滚动时触发，event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}

@scrollend

(event: UniScrollEvent) => void

滚动结束时触发，event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}

# direction 兼容性

	Android	iOS	web
none	4.0	4.11	4.02
horizontal	4.0	x	x
vertical	4.0	4.11	4.02

# associative-container 兼容性

	Android	iOS	web
nested-scroll-view	4.11	4.11	x

# refresher-default-style 兼容性

	Android	iOS	web
black	3.9	4.11	-
white	3.9	4.11	-
none	3.93	4.11	-

# 事件

# UniRefresherEvent

# UniRefresherEvent 的属性值

名称

类型

必填

默认值

描述

detail

UniRefresherEventDetail

是

名称	类型	必备	默认值	描述
dy	number	是	-	-

bubbles

boolean

是

是否冒泡

cancelable

boolean

是

是否可以取消

type

string

是

事件类型

target

UniElement | null

否

UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。

currentTarget

UniElement | null

否

UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。

timeStamp

number

是

事件发生时的时间戳

# UniRefresherEvent 的方法

名称	类型	必填	默认值	描述
stopPropagation	() => void	是	-	阻止当前事件的进一步传播
preventDefault	() => void	是	-	阻止当前事件的默认行为

# UniScrollToUpperEvent

# UniScrollToUpperEvent 的属性值

名称

类型

必填

默认值

描述

detail

UniScrollToUpperEventDetail

是

名称	类型	必备	默认值	描述
direction	string	是	-	滚动方向 top 或 left

bubbles

boolean

是

是否冒泡

cancelable

boolean

是

是否可以取消

type

string

是

事件类型

target

UniElement | null

否

UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。

currentTarget

UniElement | null

否

UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。

timeStamp

number

是

事件发生时的时间戳

# UniScrollToUpperEvent 的方法

名称	类型	必填	默认值	描述
stopPropagation	() => void	是	-	阻止当前事件的进一步传播
preventDefault	() => void	是	-	阻止当前事件的默认行为

# UniScrollToLowerEvent

# UniScrollToLowerEvent 的属性值

名称

类型

必填

默认值

描述

detail

UniScrollToLowerEventDetail

是

名称	类型	必备	默认值	描述
direction	string	是	-	滚动方向 bottom 或 right

bubbles

boolean

是

是否冒泡

cancelable

boolean

是

是否可以取消

type

string

是

事件类型

target

UniElement | null

否

UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。

currentTarget

UniElement | null

否

UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。

timeStamp

number

是

事件发生时的时间戳

# UniScrollToLowerEvent 的方法

名称	类型	必填	默认值	描述
stopPropagation	() => void	是	-	阻止当前事件的进一步传播
preventDefault	() => void	是	-	阻止当前事件的默认行为

# UniScrollEvent

# UniScrollEvent 的属性值

名称

类型

必填

默认值

描述

detail

UniScrollEventDetail

是

名称	类型	必备	默认值	描述
scrollTop	number	是	-	竖向滚动的距离
scrollLeft	number	是	-	横向滚动的距离
scrollHeight	number	是	-	滚动区域的高度
scrollWidth	number	是	-	滚动区域的宽度
deltaY	number	是	-	当次滚动事件竖向滚动量
deltaX	number	是	-	当次滚动事件横向滚动量

bubbles

boolean

是

是否冒泡

cancelable

boolean

是

是否可以取消

type

string

是

事件类型

target

UniElement | null

否

UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。

currentTarget

UniElement | null

否

UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。

timeStamp

number

是

事件发生时的时间戳

# UniScrollEvent 的方法

名称	类型	必填	默认值	描述
stopPropagation	() => void	是	-	阻止当前事件的进一步传播
preventDefault	() => void	是	-	阻止当前事件的默认行为

# 自定义下拉刷新样式

list-view组件有默认的下拉刷新样式，如果想自定义，则需使用自定义下拉刷新。

设置refresher-default-style属性为 none 不使用默认样式

设置 list-item 定义自定义下拉刷新元素并声明为 slot="refresher"，需要设置刷新元素宽高信息否则可能无法正常显示！

<template>
	<list-view refresher-default-style="none" :refresher-enabled="true" :refresher-triggered="refresherTriggered"
			 @refresherpulling="onRefresherpulling" @refresherrefresh="onRefresherrefresh"
			 @refresherrestore="onRefresherrestore" style="flex:1" >

		<list-item v-for="i in 10" class="content-item">
			<text class="text">item-{{i}}</text>
		</list-item>

		<!-- 自定义下拉刷新元素 -->
		<list-item slot="refresher" class="refresh-box">
			<text class="tip-text">{{text[state]}}</text>
		</list-item>
	</list-view>
</template>

通过组件提供的refresherpulling、refresherrefresh、refresherrestore、refresherabort下拉刷新事件调整自定义下拉刷新元素！实现预期效果

注意：

3.93版本开始支持
目前自定义下拉刷新元素不支持放在list-view的首个子元素位置上。可能无法正常显示

# 嵌套模式

scroll-view开启嵌套模式后，list-view 可作为内层滚动视图与外层 scroll-view 实现嵌套滚动

设置内层 list-view 的 associative-container 属性为 "nested-scroll-view"，开启内层 list-view 支持与外层 scroll-view 嵌套滚动

# list-view 属性兼容性

	Android	iOS	web
direction	4.0	4.11	x
~~scroll-x~~	3.9	x	x
~~scroll-y~~	3.9	4.11	x
~~rebound~~	3.9	4.11	x
associative-container	4.11	4.11	x
bounces	4.0	4.11	x
upper-threshold	3.9	4.11	4.02
lower-threshold	3.9	4.11	4.02
scroll-top	3.9	4.11	4.02
scroll-left	3.9	4.11	x
show-scrollbar	3.9	4.11	4.02
scroll-into-view	3.9	4.11	x
scroll-with-animation	3.9	4.11	4.02
refresher-enabled	3.9	4.11	x
refresher-threshold	3.9	4.11	x
refresher-max-drag-distance	3.9	4.11	x
refresher-default-style	3.9	4.11	x
refresher-background	3.9	4.11	x
refresher-triggered	3.9	4.11	x
enable-back-to-top	x	4.11	x
custom-nested-scroll	3.9	4.11	x
@refresherpulling	3.9	4.11	x
@refresherrefresh	3.9	4.11	x
@refresherrestore	3.9	4.11	x
@refresherabort	3.9	4.11	x
@scrolltoupper	3.9	4.11	4.02
@scrolltolower	3.9	4.11	4.02
@scroll	3.9	4.11	4.02
@scrollend	3.9	4.11	x

# 子组件

# 示例

hello uni-app x

Template

Script



<template>
  <view class="main">
    <list-view :direction="scroll_direction" :rebound="bounces_boolean" :upper-threshold="upper_threshold_input"
      :lower-threshold="lower_threshold_input" :scroll-top="scroll_top_input" :scroll-left="scroll_left_input"
      :show-scrollbar="show_scrollbar_boolean" :scroll-into-view="scrollIntoView"
      :scroll-with-animation="scroll_with_animation_boolean" :refresher-enabled="refresher_enabled_boolean"
      :refresher-background="refresher_background_input" :refresher-triggered="refresher_triggered_boolean"
      :refresher-default-style="refresher_default_style_input" @click="list_view_click"
      @touchstart="list_view_touchstart" @touchmove="list_view_touchmove" @touchcancel="list_view_touchcancel"
      @touchend="list_view_touchend" @tap="list_view_tap" @longpress="list_view_longpress"
      @refresherpulling="list_view_refresherpulling" @refresherrefresh="list_view_refresherrefresh"
      @refresherrestore="list_view_refresherrestore" @refresherabort="list_view_refresherabort"
      @scrolltoupper="list_view_scrolltoupper" ref="listview" @scrolltolower="list_view_scrolltolower"
      @scroll="list_view_scroll" style="width:100%;" id="listview">
      <list-item v-for="key in scrollData" :key="key" :id="key" @click="list_item_click"
        @touchstart="list_item_touchstart" @touchmove="list_item_touchmove" @touchcancel="list_item_touchcancel"
        @touchend="list_item_touchend" @tap="list_item_tap" @longpress="list_item_longpress" class="list-item">
        <text>{{key}}</text>
      </list-item>
      <!-- #ifdef APP -->
      <list-item slot="refresher" class="refresh-box">
        <text class="tip-text">{{text[state]}}</text>
      </list-item>
      <!-- #endif -->
    </list-view>
  </view>

  <scroll-view style="flex:1" direction="vertical">
    <view class="content">
      <!-- #ifdef APP -->
      <boolean-data :defaultValue="false" title="设置当前下拉刷新状态，true 表示下拉刷新已经被触发，false 表示下拉刷新未被触发"
        @change="change_refresher_triggered_boolean"></boolean-data>
      <boolean-data :defaultValue="false" title="开启下拉刷新" @change="change_refresher_enabled_boolean"></boolean-data>
      <boolean-data :defaultValue="false" title="开启自定义样式" @change="change_refresher_style_boolean"></boolean-data>
      <!-- #endif -->
      <boolean-data :defaultValue="false" title="是否在设置滚动条位置时使用滚动动画，设置false没有滚动动画"
        @change="change_scroll_with_animation_boolean"></boolean-data>
      <boolean-data :defaultValue="false" title="控制是否出现滚动条" @change="change_show_scrollbar_boolean"></boolean-data>
      <!-- #ifdef APP -->
      <boolean-data :defaultValue="true" title="控制是否回弹效果" @change="change_bounces_boolean"></boolean-data>
      <!-- #endif -->
      <boolean-data :defaultValue="true" title="允许纵向滚动" @change="change_scroll_y_boolean"></boolean-data>
      <!-- #ifdef APP -->
      <boolean-data :defaultValue="false" title="允许横向滚动" @change="change_scroll_x_boolean"></boolean-data>
      <!-- #endif -->
      <input-data defaultValue="50" title="距顶部/左边多远时（单位px），触发 scrolltoupper 事件" type="number"
        @confirm="confirm_upper_threshold_input"></input-data>
      <input-data defaultValue="50" title="距底部/右边多远时（单位px），触发 scrolltolower 事件" type="number"
        @confirm="confirm_lower_threshold_input"></input-data>
      <input-data defaultValue="0" title="设置竖向滚动条位置" type="number" @confirm="confirm_scroll_top_input"></input-data>
      <!-- #ifdef APP -->
      <input-data defaultValue="0" title="设置横向滚动条位置" type="number" @confirm="confirm_scroll_left_input"></input-data>
      <input-data defaultValue="#FFF" title="设置下拉刷新区域背景颜色" type="text"
        @confirm="confirm_refresher_background_input"></input-data>
      <enum-data :items="size_enum" title="通过id位置跳转" @change="item_change_size_enum"></enum-data>
      <navigator url="/pages/component/list-view/list-view-refresh">
        <button type="primary" class="button">
          list-view 下拉刷新
        </button>
      </navigator>
      <!-- #endif -->
      <navigator url="/pages/component/list-view/list-view-multiplex">
        <button type="primary" class="button">
          list-view 对list-item复用测试
        </button>
      </navigator>
      <navigator url="/pages/component/list-view/list-view-multiplex-input">
        <button type="primary" class="button">
          list-view 复用测试（item中嵌入input）
        </button>
      </navigator>
      <navigator url="/pages/component/list-view/list-view-multiplex-video">
        <button type="primary" class="button">
          list-view 复用测试（item中嵌入video）
        </button>
      </navigator>
      <navigator url="/pages/component/list-view/list-view-children-in-slot">
        <button type="primary" class="button">
          list-view 测试插槽中子组件增删
        </button>
      </navigator>
    </view>
  </scroll-view>
</template>

<style>
  .main {
    max-height: 250px;
    padding: 5px 0;
    border-bottom: 1px solid rgba(0, 0, 0, .06);
    flex-direction: row;
    justify-content: center;
  }

  .main .list-item {
    width: 100%;
    height: 250px;
    border: 1px solid #666;
    background-color: #66ccff;
    align-items: center;
    justify-content: center;
  }

  .tip-text {
    color: #888;
    font-size: 12px;
  }

  .refresh-box {
    justify-content: center;
    align-items: center;
    flex-direction: row;
    height: 45px;
    width: 100%;
  }

  .button {
    margin-top: 15px;
  }
</style>

# 参见

相关 Bug

# list-item

组件类型：UniListItemElement

list-view组件的唯一合法子组件。每个item是一行

# list-item 兼容性

Android	iOS	web
3.9	4.11	4.02

# 属性

名称	类型	默认值	描述
type	number	0	对应list-item的类型 list-view 将对同类型条目进行复用，所以合理的类型拆分，可以很好地提升 list-view 性能

# list-item复用机制

仅App平台支持复用。Web平台仅渲染当前屏幕及上下一定高度内的元素，没有对list-item进行复用。

type属性定义list-item组件类型。不赋值type属性默认值为0，每一个type类型都会有对应的list-item组件缓存池。
list-view组件加载list-item组件时，会优先查询对应type缓存池是否存在可复用的list-item组件。有则复用没有则创建新的list-item组件。
list-item组件被滑动出屏幕则会优先添加到对应类型的list-item缓存池，每个类型缓存最大5个（不同平台缓存最大值不固定），如果缓存池已满则进行组件销毁！
部分list-item组件存在子元素个数差异或排版差异时。请尽可能的配置不同的type，这样可以规避获取相同type类型的list-item组件后。
- 很常见的一个错误是在长列表上方的list-item里放置banner图，却没有为这个不可复用的list-item设置单独的type，这会导致图片在复用失败后无法渲染。
- 由于子元素差异导致list-item无法正常复用问题。具体可参考示例：

	<template>
	  <view class="content">
		<list-view ref="listView" class="list" :scroll-y="true">
		  <list-item v-for="(item,index) in list" :key="index" class="content-item1" type=1>
			<text class="text">title-{{item}}</text>
			<text class="text">content-{{item}}</text>
		  </list-item>
		  <list-item v-for="(item,index) in list" :key="index" class="content-item2" type=2>
		  	<image class="image" src ="/static/test-image/logo.png"></image>
		  </list-item>
		  <list-item type=3>
			<text class="loading">{{text}}</text>
		  </list-item>
		</list-view>
	  </view>
	</template>

示例中有三种类型的list-item组件。如果都不赋值type，list-item组件滑动出屏幕后都归类到type=0的缓存池。当触发list-item组件重新加载时，获取type=0的缓存池的组件，获取到的list-item组件可能是两个text子组件也可能是一个image子组件或一个text子组件，底层复用判断时则认为该情况异常不复用，重新创建新的list-item组件！复用失败未能优化性能。正确的方式则是不同的类型设置不同的type。加载时则会获取对应type类型缓存池中的list-item组件实现复用。

注意：

避免对list-item组件的子元素设置event事件，复用后list-item组件部分子元素可能无法正常响应event，有相关业务需要对子元素设置event事件，可对list-item组件设置独立的type实现不复用。

# list-item 属性兼容性

	Android	iOS	web
type	3.9	x	4.0

# App平台

App平台scroll-x、scroll-y属性不支持同时设置为true，同时设置true时仅scroll-y生效。4.0版本开始scroll-x、scroll-y已废弃，请使用direction属性。
App平台list-view组件默认高度取值：
- list-view组件的子元素高度之和未超过list-view组件的父元素高度：
  - list-view组件的默认高度取值为子元素高度之和
- list-view组件的子元素高度之和超过list-view组件的父元素高度：
  - 3.9版本list-view组件默认高度取值为list-view组件父元素的高度。子元素高度之和超过list-view组件的高度，list-view组件可滚动。
  - 4.0版本开始list-view组件的默认高度取值为子元素高度之和。高度相同list-view组件无法滚动。开发者需要设置css属性定义list-view组件高度，让list-view组件高度小于子元素高度之和，实现滚动能力。

# Web平台

web平台仅渲染当前屏幕及上下一定距离的内容，滚动高度为空白容器占位，因此如果使用dom API获取list-item内的元素可能无法取到。
scroll-with-animation属性在safari 15.4以下版本不支持
尽量避免在list-item上使用浏览器的外边距折叠特性会导致list-view无法准确计算回收的元素的高度，进而导致滚动出现异常。即不要同时为list-item设置上边距（margin-top）和下边距（margin-bottom）。

# 示例代码

联网联表：https://gitcode.net/dcloud/hello-uni-app-x/-/blob/master/pages/template/list-news/list-news.uvue
可左右滑动的多个列表：https://gitcode.net/dcloud/hello-uni-app-x/-/tree/master/pages/template/long-list

# Bug & Tips

如需im那样的倒序列表，App端可给组件style配置 transform: rotate(180deg) 来实现。注意与下拉刷新有冲突，此时应避免启用下拉刷新。
多列瀑布流是另外的组件，后续会提供
list-view组件的overflow属性不支持配置visible
一次性初始化太多列表项，因为创建大量vnode耗时，会导致列表初始化变慢。此时推荐使用扩展组件uni-recycle-view来解决初始化慢的问题，该组件内部会分批创建节点，自动实现节点复用。