List 列表

引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

基础用法

List 组件通过 和 finished 两个变量控制加载状态，当组件滚动到底部时，会触发 load 事件并将 loading 设置成 true。此时可以发起异步操作并更新数据，数据更新完毕后，将 loading 设置成 false 即可。若数据已全部加载完毕，则直接将 finished 设置成 true 即可。

  1. <van-list
  2.   v-model:loading="loading"
  3.   :finished="finished"
  4.   finished-text="没有更多了"
  5.   @load="onLoad"
  6. >
  7.   <van-cell v-for="item in list" :key="item" :title="item" />
  8. </van-list>
  1. import { ref } from 'vue';
  3. export default {
  4.   setup() {
  5.     const list = ref([]);
  6.     const finished = ref(false);
  8.     const onLoad = () => {
  9.       // 异步更新数据
  10.       // setTimeout 仅做示例，真实场景中一般为 ajax 请求
  11.       setTimeout(() => {
  12.         for (let i = 0; i < 10; i++) {
  13.           list.value.push(list.value.length + 1);
  14.         }
  16.         // 加载状态结束
  17.         loading.value = false;
  19.         // 数据全部加载完成
  20.         if (list.value.length >= 40) {
  21.           finished.value = true;
  22.         }
  23.       }, 1000);
  24.     };
  26.     return {
  28.       onLoad,
  29.       loading,
  30.       finished,
  31.     };
  32.   },
  33. };

错误提示

若列表数据加载失败，将 error 设置成 true 即可显示错误提示，用户点击错误提示后会重新触发 load 事件。

  1. import { ref } from 'vue';
  3. export default {
  4.   setup() {
  5.     const list = ref([]);
  6.     const error = ref(false);
  7.     const loading = ref(false);
  8.       fetchSomeThing().catch(() => {
  9.         error.value = true;
  10.       });
  11.     };
  13.     return {
  14.       list,
  15.       error,
  16.       onLoad,
  17.       loading,
  18.     };
  19.   },
  20. };

下拉刷新

List 组件可以与 组件结合使用，实现下拉刷新的效果。

  1. <van-pull-refresh v-model="refreshing" @refresh="onRefresh">
  2.   <van-list
  3.     v-model:loading="loading"
  4.     :finished="finished"
  5.     finished-text="没有更多了"
  6.     @load="onLoad"
  7.   >
  8.     <van-cell v-for="item in list" :key="item" :title="item" />
  9.   </van-list>
  10. </van-pull-refresh>

Props

方法

通过 ref 可以获取到 List 实例并调用实例方法，详见组件实例方法。

类型定义

组件导出以下类型定义：

  1. import type { ListProps, ListInstance, ListDirection } from 'vant';
  1. import { ref } from 'vue';
  2. import type { ListInstance } from 'vant';
  4. const listRef = ref<ListInstance>();
  6. listRef.value?.check();

Slots

样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 。

List 的运行机制是什么？

List 会监听浏览器的滚动事件并计算列表的位置，当列表底部与可视区域的距离小于 offset 时，List 会触发一次 load 事件。

List 初始化后会触发一次 load 事件，用于加载第一屏的数据，这个特性可以通过 immediate-check 属性关闭。

为什么会连续触发 load 事件？

如果一次请求加载的数据条数较少，导致列表内容无法铺满当前屏幕，List 会继续触发 load 事件，直到内容铺满屏幕或数据全部加载完成。

因此你需要调整每次获取的数据条数，理想情况下每次请求获取的数据条数应能够填满一屏高度。

loading 和 finished 分别是什么含义？

List 有以下三种状态，理解这些状态有助于你正确地使用 List 组件：

  • 非加载中，loading 为 false，此时会根据列表滚动位置判断是否触发 load 事件（列表内容不足一屏幕时，会直接触发）。
  • 加载中，loading 为 true，表示正在发送异步请求，此时不会触发 load 事件。
  • 加载完成，finished 为 true，此时不会触发 load 事件。

使用 float 布局后一直触发加载？

若 List 的内容使用了 float 布局，可以在容器上添加 van-clearfix 类名来清除浮动，使得 List 能正确判断元素位置。

在 html、body 上设置 overflow 后一直触发加载？

如果在 html 和 body 标签上设置了 overflow-x: hidden 样式，会导致 List 一直触发加载。

  1. html,
  2. body {
  3. }

这个问题的原因是当元素设置了 overflow-x: hidden 样式时，该元素的 overflow-y 会被浏览器设置为 auto，而不是默认值 visible，导致 List 无法正确地判断滚动容器。解决方法是去除该样式，或者在 html 和 body 标签上添加 height: 100% 样式。

direction 属性设置为 up 后一直触发加载？

设置 属性为 up 后，当滚动条处于页面顶部时，就会触发 List 组件的加载。

因此在使用该属性时，建议在每次数据加载完成后，将滚动条滚动至页面底部或非顶部的位置。