<list>

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

基本用法

<template>
<list>
<cell v-for="num in lists">
<text>{{num}}</text>
</cell>
</list>
</template>

<script>
export default {
data () {
return {
lists: ['A', 'B', 'C', 'D', 'E']
}
}
}
</script>

子组件

<list> 组件支持更多高级功能,由以下子组件提供:

  • <cell>

    用于定义列表中的子列表项,类似于 HTML 中的 ulli的关系。jsn 会对 <cell> 进行高效的内存回收以达到更好的性能。

    使用文档请查看 <cell>

  • header 0.6.1+

    <header> 到达屏幕顶部时,吸附在屏幕顶部。

  • <refresh>

    用于给列表添加下拉刷新的功能。

    使用文档请查看 <refresh>

  • <loading>

    <loading> 用法与特性和 <refresh> 类似,用于给列表添加上拉加载更多的功能。

    使用文档请查看 <loading>

注意:

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

特性

  • show-scrollbar {boolean}:可选值为 true/ false,默认值为 true。控制是否出现滚动条。
  • loadmoreoffset {number}:默认值为 0,触发 loadmore 事件所需要的垂直偏移距离(设备屏幕底部与 <list> 底部之间的距离)。当 <list> 的滚动条滚动到足够接近 <list> 底部时将会触发 loadmore 这个事件。
  • offset-accuracy {number} 0.11+:控制onscroll事件触发的频率,默认值为10,表示两次onscroll事件之间列表至少滚动了10px。注意,将该值设置为较小的数值会提高滚动事件采样的精度,但同时也会降低页面的性能。
  • pagingEnabled {boolean}:可选值为 true/ false,默认值为 false。控制是否每次滚动一个cell,并最终定位在元素中心位置,类似垂直的viewpage交互。则对应 0v0.20+
  • scrollable {boolean}:可选值为 true/ false,默认值为 true。控制list是否可以滚动。

样式

  • 通用样式:支持所有通用样式。

    • 盒模型
    • flexbox 布局
    • position
    • opacity
    • background-color

    查看 组件通用样式

事件

  • loadmore 0.5+:如果列表滚动到底部将会立即触发这个事件,你可以在这个事件的处理函数中加载下一页的列表项。
  • scroll 0.11+: 列表发生滚动时将会触发该事件,事件的默认抽样率为10px,即列表每滚动10px触发一次,可通过属性offset-accuracy设置抽样率。

    事件中 event 对象属性:

    • contentSize {Object}:列表的内容尺寸
      • width {number}: 列表内容宽度
      • height {number}: 列表内容高度
    • contentOffset {Object}: 列表的偏移尺寸
      • x {number}: x轴上的偏移量
      • y {number}: y轴上的偏移量
  • 通用事件。

    支持所有通用事件:

    • click
    • longpress
    • appear
    • disappear

    查看 通用事件

扩展

scrollToElement(node, options)

滚动到列表某个指定项是常见需求,<list> 拓展了该功能支持滚动到指定 <cell>。通过 dom module 访问,更多信息可参考 dom module

resetLoadmore() 0.9+

在默认情况下,触发loadmore事件后,如果列表中内容没有发生变更,则下一次滚动到列表末尾时将不会再次触发loadmore事件,你可以通过调用resetLoadmore()方法来打破这一限制,调用该方法后,下一次滚动到列表末尾时将强制触发loadmore

参数

  • node {node}:指定目标节点。
  • options {Object}
    • offset {number}:一个到其可见位置的偏移距离,默认是 0。

约束

  1. 不允许相同方向的 <list> 或者 <scroller> 互相嵌套,换句话说就是嵌套的 <list>/<scroller> 必须是不同的方向。

    举个例子,不允许一个垂直方向的 <list> 嵌套的一个垂直方向的 <scroller> 中,但是一个垂直方向的 <list> 是可以嵌套的一个水平方向的 list 或者 <scroller> 中的。

  2. <list> 为根节点时无需设置高度,但是内嵌 <list> 高度必须可计算,你可以使用 flexpostion<list> 设为一个响应式高度(例如全屏显示), 也可以显式设置 <list> 组件的 height 样式。