小程序开发
uniapp多端开发
内置组件
nvue组件

基础列表组件

# 基础列表组件

list 组件是 App 端 nvue 页面中的专用长列表组件，专为处理大量数据渲染时的性能优化而设计。它通过内存管理机制，回收不可见部分的渲染资源，极大地提高了长列表的滚动性能。

# 1. 什么是 `list` 组件？

list 组件用于在 App 端 nvue 页面中展示垂直长列表，与 view 或 scroll-view 不同，list 提供了更高效的资源回收和滚动处理机制，特别适用于处理大量列表项。通过 list 组件的优化，开发者可以在页面上流畅地展示长列表，而不需要担心性能瓶颈。

使用场景

长列表展示：用于展示大量数据的长列表，适用于社交应用中的消息流、商品展示等场景。
内存管理优化：通过资源回收机制优化长列表的性能，提升应用的流畅度。
支持下拉刷新与上拉加载：结合 <refresh> 和 <loading> 组件实现列表的下拉刷新和上拉加载功能。

# 2. `list` 组件的常用属性

list 组件提供了多种属性用于控制列表的显示和行为。以下是常用属性的详细说明及使用示例：

属性名	说明	类型	默认值
`show-scrollbar`	控制是否出现滚动条	Boolean	true
`bounce`	控制是否回弹效果	Boolean	true
`loadmoreoffset`	触发 `loadmore` 事件所需的垂直偏移距离	Number	0
`offset-accuracy`	控制 `onscroll` 事件触发的频率	Number	10
`pagingEnabled`	是否按分页模式显示列表	Boolean	false
`scrollable`	是否允许列表滚动	Boolean	true
`enable-back-to-top`	点击顶部状态栏时是否返回顶部（仅支持 iOS 端）	Boolean	false

# 2.1 显示列表项并自定义滚动条

说明：通过 show-scrollbar 属性控制列表是否显示滚动条，默认开启。
类型：Boolean
默认值：true

<template>
  <!-- 自定义 list 组件，展示数据 -->
  <list :show-scrollbar="true" @loadmore="loadMore">
    <!-- 列表项 -->
    <cell v-for="(item, index) in dataList" :key="item.id">
      <text>{{ item.name }}</text>
    </cell>
  </list>
</template>

<script>
import { ref } from 'vue'

export default {
  setup() {
    const dataList = ref([
      { id: "1", name: 'Item A' },
      { id: "2", name: 'Item B' },
      { id: "3", name: 'Item C' }
    ]);

    const loadMore = () => {
      console.log("触发了 loadmore 事件");
      // 在此处可以加载更多数据
    };

    return { dataList, loadMore };
  }
}
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 2.2 上拉加载更多

说明：通过 loadmoreoffset 属性设置触发 loadmore 事件的偏移距离，开发者可以根据该事件实现上拉加载更多的功能。
类型：Number
默认值：0

<template>
  <!-- 设置 loadmoreoffset，允许上拉加载更多数据 -->
  <list :loadmoreoffset="100" @loadmore="loadMore">
    <cell v-for="(item, index) in dataList" :key="item.id">
      <text>{{ item.name }}</text>
    </cell>
  </list>
</template>

<script>
import { ref } from 'vue'

export default {
  setup() {
    const dataList = ref([
      { id: "1", name: 'Item A' },
      { id: "2", name: 'Item B' },
      { id: "3", name: 'Item C' }
    ]);

    const loadMore = () => {
      console.log("加载更多数据");
      dataList.value.push({ id: String(dataList.value.length + 1), name: `Item ${dataList.value.length + 1}` });
    };

    return { dataList, loadMore };
  }
}
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 2.3 设置分页模式

说明：通过 pagingEnabled 属性启用分页模式，列表将按分页显示。
类型：Boolean
默认值：false

<template>
  <!-- 启用分页模式 -->
  <list :pagingEnabled="true" @loadmore="loadMore">
    <cell v-for="(item, index) in dataList" :key="item.id">
      <text>{{ item.name }}</text>
    </cell>
  </list>
</template>

<script>
import { ref } from 'vue'

export default {
  setup() {
    const dataList = ref([
      { id: "1", name: 'Item A' },
      { id: "2", name: 'Item B' },
      { id: "3", name: 'Item C' }
    ]);

    const loadMore = () => {
      console.log("分页加载更多数据");
      dataList.value.push({ id: String(dataList.value.length + 1), name: `Item ${dataList.value.length + 1}` });
    };

    return { dataList, loadMore };
  }
}
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 3. 子组件

list 组件支持以下四种子组件，用于实现各种功能：

cell：用于定义列表项。
header：用于在列表顶部定义一个固定的头部，当滚动到顶部时，头部会吸附在顶部。
refresh：用于添加下拉刷新功能。
loading：用于添加上拉加载更多的功能。

# 3.1 使用 `cell` 定义列表项

说明：cell 是 list 中的基本子组件，用于定义每个列表项。

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

<script>
import { ref } from 'vue'

export default {
  setup() {
    const dataList = ref([
      { id: "1", name: 'Item A' },
      { id: "2", name: 'Item B' },
      { id: "3", name: 'Item C' }
    ]);

    return { dataList };
  }
}
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 3.2 添加 `refresh` 和 `loading`

说明：使用 refresh 添加下拉刷新功能，使用 loading 添加上拉加载更多功能。

<template>
  <!-- 列表，包含下拉刷新和上拉加载功能 -->
  <list @loadmore="loadMore">
    <!-- 下拉刷新 -->
    <refresh @refresh="onRefresh">下拉刷新</refresh>
    
    <!-- 列表项 -->
    <cell v-for="item in dataList" :key="item.id">
      <text>{{ item.name }}</text>
    </cell>

    <!-- 上拉加载 -->
    <loading>加载更多</loading>
  </list>
</template>

<script>
import { ref } from 'vue'

export default {
  setup() {
    const dataList = ref([
      { id: "1", name: 'Item A' },
      { id: "2", name: 'Item B' },
      { id: "3", name: 'Item C' }
    ]);

    const onRefresh = () => {
      console.log("下拉刷新");
      // 处理刷新逻辑
    };

    const loadMore = () => {
      console.log("上拉加载更多");
      // 加载更多数据
    };

    return { dataList, onRefresh, loadMore };
  }
}
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

编辑此页

上次更新: 2025/02/01, 02:18:15

← 条形码/二维码组件列表单元格组件→