uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
uni-app x
uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
简体中文
组件
list-view
兼容性
属性
事件
UniRefresherEvent
UniScrollToUpperEvent
UniScrollToLowerEvent
UniScrollEvent
自定义下拉刷新样式
嵌套模式
展示全部

# list-view

组件类型：UniListViewElement

列表组件

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

在App中，基于recycle-view的list，才能实现长列表的渲染资源复用，以保障列表加载很多项目时，不会一直增加渲染内容。list-view就是基于recycle-view的list组件。

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

# 兼容性

Web 微信小程序 Android iOS HarmonyOS
4.02 4.41 3.9 4.11 4.61

目前微信小程序下，list-view被编译为scroll-view。目前uni-app x还未优化skyline的配置，未来会把list-view编译为skyline的list-view。

# 属性

名称 类型 默认值 兼容性 描述
direction string "vertical"
滚动方向，可取值 none、horizontal、vertical，默认值vertical。注：iOS 平台仅支持vertical
合法值 兼容性 描述
none
禁止滚动
horizontal
横向滚动
vertical
竖向滚动
associative-container string ""
关联的滚动容器
合法值 兼容性 描述
nested-scroll-view
嵌套滚动
bounces boolean true
控制是否回弹效果 优先级高于rebound
upper-threshold number 50
距顶部/左边多远时（单位px），触发 scrolltoupper 事件
lower-threshold number 50
距底部/右边多远时（单位px），触发 scrolltolower 事件
scroll-top number 0
设置竖向滚动条位置
scroll-left number 0
设置横向滚动条位置
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 45
设置下拉刷新阈值, 仅 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}
padding Array -
(Array)
长度为 4 的数组，按 top、right、bottom、left 顺序指定内边距
rebound boolean true
控制是否回弹效果。已废弃，请改用bounces
scroll-y boolean true
允许纵向滚动，不支持同时设置scroll-x属性为true，同时设置true时scroll-y生效。已废弃，请改用direction
scroll-x boolean false
允许横向滚动，不支持同时设置scroll-y属性为true，同时设置true时scroll-y生效。已废弃，请改用direction

# 事件

# UniRefresherEvent

# UniRefresherEvent 的属性值
名称 类型 必填 默认值 兼容性 描述
detail UniRefresherEventDetail 是 - - -
名称 类型 必备 默认值 兼容性 描述
dy number 是 - - -

# UniScrollToUpperEvent

# UniScrollToUpperEvent 的属性值
名称 类型 必填 默认值 兼容性 描述
detail UniScrollToUpperEventDetail 是 - -
名称 类型 必备 默认值 兼容性 描述
direction string 是 - - 滚动方向 top 或 left

# UniScrollToLowerEvent

# UniScrollToLowerEvent 的属性值
名称 类型 必填 默认值 兼容性 描述
detail UniScrollToLowerEventDetail 是 - -
名称 类型 必备 默认值 兼容性 描述
direction string 是 - - 滚动方向 bottom 或 right

# UniScrollEvent

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

# 自定义下拉刷新样式

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

  1. 设置refresher-default-style属性为 none 不使用默认样式
  2. 设置 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>
  3. 通过组件提供的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-item
sticky-header
sticky-section

子组件sticky-header/section用于处理吸顶的场景。

# 示例

示例为hello uni-app x alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

扫码体验（手机浏览器跳转到App直达页）

示例

<script>
  type ScrollEventTest = {
    type : string;
    target : UniElement | null;
    currentTarget : UniElement | null;
    direction ?: string
  }
  import { ItemType } from '@/components/enum-data/enum-data-types'
  export default {
    data() {
      return {
        refresher_triggered_boolean: false,
        refresher_enabled_boolean: false,
        scroll_with_animation_boolean: false,
        show_scrollbar_boolean: false,
        bounces_boolean: true,
        scroll_y_boolean: true,
        scroll_x_boolean: false,
        scroll_direction: "vertical",
        upper_threshold_input: 50,
        lower_threshold_input: 50,
        scroll_top_input: 0,
        scroll_left_input: 0,
        refresher_background_input: "#FFF",
        scrollData: [] as Array<string>,
        size_enum: [{ "value": 0, "name": "item---0" }, { "value": 3, "name": "item---3" }] as ItemType[],
        scrollIntoView: "",
        refresherrefresh: false,
        refresher_default_style_input: "black",
        text: ['继续下拉执行刷新', '释放立即刷新', '刷新中', ""],
        state: 3,
        reset: true,
        // 自动化测试
        isScrollTest: '',
        isScrolltolowerTest: '',
        isScrolltoupperTest: '',
        scrollDetailTest: null as UniScrollEventDetail | null,
        scrollEndDetailTest: null as UniScrollEventDetail | null,
      }
    },
    onLoad() {
      let lists : Array<string> = []
      for (let i = 0; i < 10; i++) {
        lists.push("item---" + i)
      }
      this.scrollData = lists
    },
    methods: {
      list_view_click() { console.log("组件被点击时触发") },
      list_view_touchstart() { console.log("手指触摸动作开始") },
      list_view_touchmove() { console.log("手指触摸后移动") },
      list_view_touchcancel() { console.log("手指触摸动作被打断，如来电提醒，弹窗") },
      list_view_touchend() { console.log("手指触摸动作结束") },
      list_view_tap() { console.log("手指触摸后马上离开") },
      list_view_longpress() { console.log("如果一个组件被绑定了 longpress 事件，那么当用户长按这个组件时，该事件将会被触发。") },
      list_view_refresherpulling(e : RefresherEvent) {
        console.log("下拉刷新控件被下拉")
        if (this.reset) {
          if (e.detail.dy > 45) {
            this.state = 1
          } else {
            this.state = 0
          }
        }
      },
      list_view_refresherrefresh() {
        console.log("下拉刷新被触发 ")
        this.refresherrefresh = true
        this.refresher_triggered_boolean = true
        this.state = 2
        this.reset = false;
        setTimeout(() => {
          this.refresher_triggered_boolean = false
        }, 1500)
      },
      list_view_refresherrestore() {
        this.refresherrefresh = false
        this.state = 3
        this.reset = true
        console.log("下拉刷新被复位")
      },
      list_view_refresherabort() { console.log("下拉刷新被中止") },
      list_view_scrolltoupper(e : UniScrollToUpperEvent) {
        console.log("滚动到顶部/左边，会触发 scrolltoupper 事件  direction=" + e.detail.direction)
        this.checkEventTest({
          type: e.type,
          target: e.target,
          currentTarget: e.currentTarget,
          direction: e.detail.direction,
        } as ScrollEventTest, 'scrolltoupper')
      },
      list_view_scrolltolower(e : UniScrollToLowerEvent) {
        console.log("滚动到底部/右边，会触发 scrolltolower 事件  direction=" + e.detail.direction)
        this.checkEventTest({
          type: e.type,
          target: e.target,
          currentTarget: e.currentTarget,
          direction: e.detail.direction,
        } as ScrollEventTest, 'scrolltolower')
      },
      list_view_scroll(e : UniScrollEvent) {
        console.log("滚动时触发，event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}")
        this.scrollDetailTest = e.detail
        this.checkEventTest({
          type: e.type,
          target: e.target,
          currentTarget: e.currentTarget
        } as ScrollEventTest, 'scroll')
      },
      list_view_scrollend(e : UniScrollEvent) {
        console.log("滚动结束时触发", e.detail)
        this.scrollEndDetailTest = e.detail
        this.checkEventTest({
          type: e.type,
          target: e.target,
          currentTarget: e.currentTarget
        } as ScrollEventTest, 'scrollend')
      },
      list_item_click() { console.log("list-item组件被点击时触发") },
      list_item_touchstart() { console.log("手指触摸list-item组件动作开始") },
      list_item_touchmove() { console.log("手指触摸list-item组件后移动") },
      list_item_touchcancel() { console.log("手指触摸list-item组件动作被打断，如来电提醒，弹窗") },
      list_item_touchend() { console.log("手指触摸list-item组件动作结束") },
      list_item_tap() { console.log("手指触摸list-item组件后马上离开") },
      list_item_longpress() { console.log("list-item组件被绑定了 longpress 事件，那么当用户长按这个组件时，该事件将会被触发。") },
      change_refresher_triggered_boolean(checked : boolean) { this.refresher_triggered_boolean = checked },
      change_refresher_enabled_boolean(checked : boolean) { this.refresher_enabled_boolean = checked },
      change_scroll_with_animation_boolean(checked : boolean) { this.scroll_with_animation_boolean = checked },
      change_show_scrollbar_boolean(checked : boolean) { this.show_scrollbar_boolean = checked },
      change_bounces_boolean(checked : boolean) { this.bounces_boolean = checked },
      change_scroll_y_boolean(checked : boolean) {
        this.scroll_y_boolean = checked
        this.change_scroll_direction()
      },
      change_scroll_x_boolean(checked : boolean) {
        this.scroll_x_boolean = checked
        this.change_scroll_direction()
      },
      change_scroll_direction() {
        if (this.scroll_y_boolean && this.scroll_x_boolean || this.scroll_y_boolean) {
          this.scroll_direction = "vertical"
        } else if (!this.scroll_y_boolean && !this.scroll_x_boolean) {
          this.scroll_direction = "none"
        } else if (!this.scroll_y_boolean && this.scroll_x_boolean) {
          this.scroll_direction = "horizontal"
        }
      },
      confirm_upper_threshold_input(value : number) { this.upper_threshold_input = value },
      confirm_lower_threshold_input(value : number) { this.lower_threshold_input = value },
      confirm_scroll_top_input(value : number) { this.scroll_top_input = value },
      confirm_scroll_left_input(value : number) { this.scroll_left_input = value },
      confirm_refresher_background_input(value : string) { this.refresher_background_input = value },
      item_change_size_enum(index : number) { this.scrollIntoView = "item---" + index },
      //自动化测试专用
      setScrollIntoView(id : string) { this.scrollIntoView = id },
      // 自动化测试专用（由于事件event参数对象中存在循环引用，在ios端JSON.stringify报错，自动化测试无法page.data获取）
      checkEventTest(e : ScrollEventTest, eventName : String) {
        const isPass = e.type === eventName && e.target instanceof UniElement && e.currentTarget instanceof UniElement;
        const result = isPass ? `${eventName}:Success` : `${eventName}:Fail`;
        switch (eventName) {
          case 'scroll':
            this.isScrollTest = result
            break;
          case 'scrolltolower':
            this.isScrolltolowerTest = result + `-${e.direction}`
            break;
          case 'scrolltoupper':
            this.isScrolltoupperTest = result + `-${e.direction}`
            break;
          default:
            break;
        }
      },
      //自动化测试例专用
      check_scroll_height() : Boolean {
        var listElement = this.$refs["listview"] as UniElement
        console.log("check_scroll_height--" + listElement.scrollHeight)
        if (listElement.scrollHeight > 2000) {
          return true
        }
        return false
      },
      //自动化测试例专用
      check_scroll_width() : Boolean {
        var listElement = this.$refs["listview"] as UniElement
        console.log("check_scroll_width" + listElement.scrollWidth)
        if (listElement.scrollWidth > 2000) {
          return true
        }
        return false
      },
      change_refresher_style_boolean(checked : boolean) {
        if (checked) {
          this.refresher_default_style_input = "none"
        } else {
          this.refresher_default_style_input = "black"
        }
      }
    }
  }
</script>

<template>
  <view class="main">
    <list-view :direction="scroll_direction" :bounces="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" @scrollend="list_view_scrollend" 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>
      <navigator url="/pages/component/list-view/list-view-children-if-show">
        <button type="primary" class="button">
          list-item v-if v-show 组合增删
        </button>
      </navigator>
      <navigator url="/pages/component/list-view/list-view-long-press">
        <button type="primary" class="button">
          list-item 中设置长按事件测试
        </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>

# 参见

# 性能优化

长列表是非常需要注意性能优化的。 当你的长列表卡顿时，请注意：

  1. 尽可能减少列表item中的组件数量。
  2. 排查代码的内存泄漏，尤其是on后没有off。
  3. 不要一次性加载太多数据，而是分批加载。
  4. 对VNode、DOM进行虚拟化

这些技巧另有专门教程

# 示例代码

# Bug & Tips

  • 如需im那样的倒序列表，App端可给组件style配置 transform: rotate(180deg) 来实现。注意与下拉刷新有冲突，此时应避免启用下拉刷新。
  • list-view组件的overflow属性不支持配置visible
  • list-view组件不适合做瀑布流，多列瀑布流另见 waterflow组件
本页导读
list-view
兼容性
属性
事件
UniRefresherEvent
UniScrollToUpperEvent
UniScrollToLowerEvent
UniScrollEvent
自定义下拉刷新样式
嵌套模式
子组件
示例
参见
性能优化
示例代码
Bug & Tips