List 列表 - Vant 4
📋 List 列表
🎯 介绍
List 组件就像是一个"智能瀑布" 🌊！它能够自动感知用户的滚动行为，当用户即将到达列表底部时，就会像魔法师一样自动"变出"更多内容。无论是商品列表、新闻资讯还是社交动态，都能提供丝滑流畅的无限滚动体验，让用户沉浸在内容的海洋中！
📦 引入
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from'vue'; import { List } from'vant'; const app = createApp(); app.use(List);🚀 代码演示
🔧 基础用法
List 组件通过 loading 和 finished 两个变量控制加载状态，就像给列表装上了"智能大脑" 🧠！当组件滚动到底部时，会触发 load 事件并将 loading 设置成 true。此时可以发起异步操作并更新数据，数据更新完毕后，将 loading 设置成 false 即可。若数据已全部加载完毕，则直接将 finished 设置成 true 即可。
import { ref } from'vue'; exportdefault { setup() { const list = ref([]); const loading = ref(false); const finished = ref(false); constonLoad = () => { // 异步更新数据// setTimeout 仅做示例，真实场景中一般为 ajax 请求setTimeout(() => { for (let i = 0; i < 10; i++) { list.value.push(list.value.length + 1); } // 加载状态结束 loading.value = false; // 数据全部加载完成if (list.value.length >= 40) { finished.value = true; } }, 1000); }; return { list, onLoad, loading, finished, }; }, };❌ 错误提示
若列表数据加载失败，将 error 设置成 true 即可显示错误提示，就像给用户一个贴心的"重试按钮" 🔄！用户点击错误提示后会重新触发 load 事件，让失败变成重新开始的机会。
import { ref } from'vue'; exportdefault { setup() { const list = ref([]); const error = ref(false); const loading = ref(false); constonLoad = () => { fetchSomeThing().catch(() => { loading.value = false; error.value = true; }); }; return { list, error, onLoad, loading, }; }, };🔄 下拉刷新
List 组件可以与 PullRefresh 组件结合使用，实现下拉刷新的效果，就像给列表装上了"时光倒流器"，让用户轻松获取最新内容！
import { ref } from'vue'; exportdefault { setup() { const list = ref([]); const loading = ref(false); const finished = ref(false); const refreshing = ref(false); constonLoad = () => { setTimeout(() => { if (refreshing.value) { list.value = []; refreshing.value = false; } for (let i = 0; i < 10; i++) { list.value.push(list.value.length + 1); } loading.value = false; if (list.value.length >= 40) { finished.value = true; } }, 1000); }; constonRefresh = () => { // 清空列表数据 finished.value = false; // 重新加载数据// 将 loading 设置为 true，表示处于加载状态 loading.value = true; onLoad(); }; return { list, onLoad, loading, finished, onRefresh, refreshing, }; }, };API
Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:loading | 是否处于加载状态，加载过程中不触发 load 事件 | boolean | false |
| v-model:error | 是否加载失败，加载失败后点击错误提示可以重新触发 load 事件 | boolean | false |
| finished | 是否已加载完成，加载完成后不再触发 load 事件 | boolean | false |
| offset | 滚动条与底部距离小于 offset 时触发 load 事件 | *number | string* |
| loading-text | 加载过程中的提示文案 | string | 加载中... |
| finished-text | 加载完成后的提示文案 | string | - |
| error-text | 加载失败后的提示文案 | string | - |
| immediate-check | 是否在初始化时立即执行滚动位置检查 | boolean | true |
| disabled | 是否禁用滚动加载 | boolean | false |
| direction | 滚动触发加载的方向，可选值为 up | string | down |
scroller v4.6.4 | 指定需要监听滚动事件的节点，默认为最近的父级滚动节点 | Element | - |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| load | 滚动条与底部距离小于 offset 时触发 | - |
方法
通过 ref 可以获取到 List 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| check | 检查当前的滚动位置，若已滚动至底部，则会触发 load 事件 | - | - |
类型定义
组件导出以下类型定义：
importtype { ListProps, ListInstance, ListDirection } from'vant';ListInstance 是组件实例的类型，用法如下：
import { ref } from'vue'; importtype { ListInstance } from'vant'; const listRef = ref<ListInstance>(); listRef.value?.check();Slots
| 名称 | 说明 |
|---|---|
| default | 列表内容 |
| loading | 自定义底部加载中提示 |
| finished | 自定义加载完成后的提示文案 |
| error | 自定义加载失败后的提示文案 |
主题定制
样式变量
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-list-text-color | var(--van-text-color-2) | - |
| --van-list-text-font-size | var(--van-font-size-md) | - |
| --van-list-text-line-height | 50px | - |
| --van-list-loading-icon-size | 16px | - |
常见问题
List 的运行机制是什么？
List 会监听浏览器的滚动事件并计算列表的位置，当列表底部与可视区域的距离小于 offset 时，List 会触发一次 load 事件。
为什么 List 初始化后会立即触发 load 事件？
List 初始化后会触发一次 load 事件，用于加载第一屏的数据，这个特性可以通过 immediate-check 属性关闭。
为什么会连续触发 load 事件？
如果一次请求加载的数据条数较少，导致列表内容无法铺满当前屏幕，List 会继续触发 load 事件，直到内容铺满屏幕或数据全部加载完成。
因此你需要调整每次获取的数据条数，理想情况下每次请求获取的数据条数应能够填满一屏高度。
loading 和 finished 分别是什么含义？
List 有以下三种状态，理解这些状态有助于你正确地使用 List 组件：
- 非加载中，
loading为false，此时会根据列表滚动位置判断是否触发load事件（列表内容不足一屏幕时，会直接触发）。 - 加载中，
loading为true，表示正在发送异步请求，此时不会触发load事件。 - 加载完成，
finished为true，此时不会触发load事件。
在每次请求完毕后，需要手动将 loading 设置为 false，表示加载结束。
使用 float 布局后一直触发加载？
若 List 的内容使用了 float 布局，可以在容器上添加 van-clearfix 类名来清除浮动，使得 List 能正确判断元素位置。
在 html、body 上设置 overflow 后一直触发加载？
如果在 html 和 body 标签上设置了 overflow-x: hidden 样式，会导致 List 一直触发加载。
html, body { overflow-x: hidden; }这个问题的原因是当元素设置了 overflow-x: hidden 样式时，该元素的 overflow-y 会被浏览器设置为 auto，而不是默认值 visible，导致 List 无法正确地判断滚动容器。解决方法是去除该样式，或者在 html 和 body 标签上添加 height: 100% 样式。
direction 属性设置为 up 后一直触发加载？
设置 direction 属性为 up 后，当滚动条处于页面顶部时，就会触发 List 组件的加载。
因此在使用该属性时，建议在每次数据加载完成后，将滚动条滚动至页面底部或非顶部的位置。
📚 相关文档
🔄 交互组件
- PullRefresh 下拉刷新 - 下拉刷新组件，与列表完美搭配
- SwipeCell 滑动单元格 - 滑动单元格组件，增强列表项交互
📋 列表相关
- Cell 单元格 - 单元格组件，构建列表项的基础组件
- IndexBar 索引栏 - 索引栏组件，长列表快速定位利器
🚀 性能优化
- Lazyload 懒加载 - 懒加载组件，提升列表性能的神器
- Loading 加载 - 加载组件，优化等待体验
- Skeleton 骨架屏 - 骨架屏组件，加载状态的优雅展示
🎨 设计组件
- Empty 空状态 - 空状态组件，无数据时的友好提示
- ConfigProvider 全局配置 - 全局配置组件，统一管理主题样式
- Divider 分割线 - 分割线组件，列表内容分组利器
🛠️ 开发指南
- Advanced Usage 进阶用法 - 进阶用法指南，组件实例方法详解