List 列表

介绍

瀑布流滚动加载,用于展示长列表,当列表即将滚动到底部时,会触发事件并加载更多列表项。

引入

  1. import { createApp } from 'vue';
  2. import { List } from 'vant';
  3. const app = createApp();
  4. app.use(List);

代码演示

基础用法

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

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

错误提示

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

  1. <van-list
  2. v-model:loading="state.loading"
  3. v-model:error="state.error"
  4. error-text="请求失败,点击重新加载"
  5. @load="onLoad"
  6. >
  7. <van-cell v-for="item in state.list" :key="item" :title="item" />
  8. </van-list>
  1. import { reactive } from 'vue';
  2. export default {
  3. setup() {
  4. const state = reactive({
  5. list: [],
  6. error: false,
  7. loading: false,
  8. });
  9. const onLoad = () => {
  10. fetchSomeThing().catch(() => {
  11. state.error = true;
  12. });
  13. };
  14. return {
  15. state,
  16. onLoad,
  17. };
  18. },
  19. };

下拉刷新

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

  1. <van-pull-refresh v-model="state.refreshing" @refresh="onRefresh">
  2. <van-list
  3. v-model:loading="state.loading"
  4. :finished="state.finished"
  5. finished-text="没有更多了"
  6. @load="onLoad"
  7. >
  8. <van-cell v-for="item in state.list" :key="item" :title="item" />
  9. </van-list>
  10. </van-pull-refresh>
  1. import { reactive } from 'vue';
  2. export default {
  3. setup() {
  4. const state = reactive({
  5. list: [],
  6. loading: false,
  7. finished: false,
  8. refreshing: false,
  9. });
  10. const onLoad = () => {
  11. setTimeout(() => {
  12. if (state.refreshing) {
  13. state.list = [];
  14. state.refreshing = false;
  15. }
  16. for (let i = 0; i < 10; i++) {
  17. state.list.push(state.list.length + 1);
  18. }
  19. state.loading = false;
  20. if (state.list.length >= 40) {
  21. state.finished = true;
  22. }
  23. }, 1000);
  24. };
  25. const onRefresh = () => {
  26. // 清空列表数据
  27. state.finished = false;
  28. // 重新加载数据
  29. // 将 loading 设置为 true,表示处于加载状态
  30. state.loading = true;
  31. onLoad();
  32. };
  33. return {
  34. state,
  35. onLoad,
  36. onRefresh,
  37. };
  38. },
  39. };

API

Props

参数说明类型默认值
v-model:loading是否处于加载状态,加载过程中不触发load事件booleanfalse
finished是否已加载完成,加载完成后不再触发load事件booleanfalse
error是否加载失败,加载失败后点击错误提示可以重新
触发load事件,必须使用sync修饰符
booleanfalse
offset滚动条与底部距离小于 offset 时触发load事件number | string300
loading-text加载过程中的提示文案string加载中…
finished-text加载完成后的提示文案string-
error-text加载失败后的提示文案string-
immediate-check是否在初始化时立即执行滚动位置检查booleantrue
direction滚动触发加载的方向,可选值为upstringdown

Events

事件名说明回调参数
load滚动条与底部距离小于 offset 时触发-

方法

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

方法名说明参数返回值
check检查当前的滚动位置,若已滚动至底部,则会触发 load 事件--

Slots

名称说明
default列表内容
loading自定义底部加载中提示
finished自定义加载完成后的提示文案
error自定义加载失败后的提示文案

样式变量

组件提供了下列 Less 变量,可用于自定义样式,使用方法请参考主题定制

名称默认值描述
@list-icon-margin-right5px-
@list-text-color@gray-6-
@list-text-font-size@font-size-md-
@list-text-line-height50px-

常见问题

List 的运行机制是什么?

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

为什么 List 初始化后会立即触发 load 事件?

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

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

如果一次请求加载的数据条数较少,导致列表内容无法铺满当前屏幕,List 会继续触发 load 事件,直到内容铺满屏幕或数据全部加载完成。因此你需要调整每次获取的数据条数,理想情况下每次请求获取的数据条数应能够填满一屏高度。

loading 和 finished 分别是什么含义?

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

  • 非加载中,loadingfalse,此时会根据列表滚动位置判断是否触发load事件(列表内容不足一屏幕时,会直接触发)
  • 加载中,loadingtrue,表示正在发送异步请求,此时不会触发load事件
  • 加载完成,finishedtrue,此时不会触发load事件

在每次请求完毕后,需要手动将loading设置为false,表示加载结束

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

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

  1. <van-list>
  2. <div class="van-clearfix">
  3. <div class="float-item" />
  4. <div class="float-item" />
  5. <div class="float-item" />
  6. </div>
  7. </van-list>

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

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

  1. html,
  2. body {
  3. overflow-x: hidden;
  4. }

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

List 列表 - 图1