Vant 是一款基于 Vue.js 的移动端 UI 组件库,它提供了丰富的列表组件,可以帮助开发者快速构建出优质的移动端应用。
Vant 列表组件包含了多种不同的列表样式,可以满足不同的需求。它有一个基本的列表,可以用来显示文本、图片、复选框或单选框;还有一个带图标的列表,可以用来显示文本和图标;还有一个带头部的列表,可以用来显示文本、图片、复选框或单选框。此外,Vant 还提供了一个带联动效果的列表,可以用来显示文本、图片、复选框或单选框。
// 基本列表// 带图标的列表 // 带头部的列表 // 联动效果的列表
瀑布流滚动加载,用于展示长列表,当列表即将滚动到底部时,会触发事件并加载更多列表项。
通过以下方式来全局注册组件,更多注册方式请参考组件注册。
import { createApp } from "vue";
import { List } from "vant";
const app = createApp();
app.use(List);
List 组件通过 loading
和 finished
两个变量控制加载状态,当组件滚动到底部时,会触发 load
事件并将 loading
设置成 true
。此时可以发起异步操作并更新数据,数据更新完毕后,将 loading
设置成 false
即可。若数据已全部加载完毕,则直接将 finished
设置成 true
即可。
<van-list
v-model:loading="loading"
:finished="finished"
finished-text="没有更多了"
@load="onLoad"
>
<van-cell v-for="item in list" :key="item" :title="item" />
</van-list>
import { ref } from "vue";
export default {
setup() {
const list = ref([]);
const loading = ref(false);
const finished = ref(false);
const onLoad = () => {
// 异步更新数据
// 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 事件。
<van-list
v-model:loading="loading"
v-model:error="error"
error-text="请求失败,点击重新加载"
@load="onLoad"
>
<van-cell v-for="item in list" :key="item" :title="item" />
</van-list>
import { ref } from "vue";
export default {
setup() {
const list = ref([]);
const error = ref(false);
const loading = ref(false);
const onLoad = () => {
fetchSomeThing().catch(() => {
error.value = true;
});
};
return {
list,
error,
onLoad,
loading,
};
},
};
List 组件可以与 PullRefresh 组件结合使用,实现下拉刷新的效果。
<van-pull-refresh v-model="refreshing" @refresh="onRefresh">
<van-list
v-model:loading="loading"
:finished="finished"
finished-text="没有更多了"
@load="onLoad"
>
<van-cell v-for="item in list" :key="item" :title="item" />
</van-list>
</van-pull-refresh>
import { ref } from "vue";
export default {
setup() {
const list = ref([]);
const loading = ref(false);
const finished = ref(false);
const refreshing = ref(false);
const onLoad = () => {
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);
};
const onRefresh = () => {
// 清空列表数据
finished.value = false;
// 重新加载数据
// 将 loading 设置为 true,表示处于加载状态
loading.value = true;
onLoad();
};
return {
list,
onLoad,
loading,
finished,
onRefresh,
refreshing,
};
},
};
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
v-model:loading | 是否处于加载状态,加载过程中不触发 load 事件 |
boolean | false
|
v-model:error | 是否加载失败,加载失败后点击错误提示可以重新触发 load 事件 |
boolean | false
|
finished | 是否已加载完成,加载完成后不再触发 load 事件 |
boolean | false
|
offset | 滚动条与底部距离小于 offset 时触发 load 事件 |
number | string | 300
|
loading-text | 加载过程中的提示文案 | string | 加载中...
|
finished-text | 加载完成后的提示文案 | string | - |
error-text | 加载失败后的提示文案 | string | - |
immediate-check | 是否在初始化时立即执行滚动位置检查 | boolean | true
|
disabled | 是否禁用滚动加载 | boolean | false
|
direction | 滚动触发加载的方向,可选值为 up
|
string | down
|
事件名 | 说明 | 回调参数 |
---|---|---|
load | 滚动条与底部距离小于 offset 时触发 | - |
通过 ref 可以获取到 List 实例并调用实例方法,详见组件实例方法。
方法名 | 说明 | 参数 | 返回值 |
---|---|---|---|
check | 检查当前的滚动位置,若已滚动至底部,则会触发 load 事件 | - | - |
组件导出以下类型定义:
import type { ListProps, ListInstance, ListDirection } from "vant";
ListInstance 是组件实例的类型,用法如下:
import { ref } from "vue";
import type { ListInstance } from "vant";
const listRef = ref<ListInstance>();
listRef.value?.check();
名称 | 说明 |
---|---|
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 会监听浏览器的滚动事件并计算列表的位置,当列表底部与可视区域的距离小于 offset
时,List 会触发一次 load
事件。
List 初始化后会触发一次 load 事件,用于加载第一屏的数据,这个特性可以通过 immediate-check
属性关闭。
如果一次请求加载的数据条数较少,导致列表内容无法铺满当前屏幕,List 会继续触发 load
事件,直到内容铺满屏幕或数据全部加载完成。
因此你需要调整每次获取的数据条数,理想情况下每次请求获取的数据条数应能够填满一屏高度。
List
有以下三种状态,理解这些状态有助于你正确地使用 List
组件:
loading
为 false
,此时会根据列表滚动位置判断是否触发 load
事件(列表内容不足一屏幕时,会直接触发)。loading
为 true
,表示正在发送异步请求,此时不会触发 load
事件。finished
为 true
,此时不会触发 load
事件。在每次请求完毕后,需要手动将 loading
设置为 false
,表示加载结束。
若 List 的内容使用了 float 布局,可以在容器上添加 van-clearfix
类名来清除浮动,使得 List 能正确判断元素位置。
<van-list>
<div class="van-clearfix">
<div class="float-item" />
<div class="float-item" />
<div class="float-item" />
</div>
</van-list>
如果在 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 后,当滚动条处于页面顶部时,就会触发 List 组件的加载。
因此在使用该属性时,建议在每次数据加载完成后,将滚动条滚动至页面底部或非顶部的位置。
介绍用于标记关键词和概括主要内容。引入通过以下方式来全局注册组件,更多注册方式请参考组件注册。import { createApp } from ...
介绍Vant 是基于有赞Zan Design System视觉规范实现的组件库,在这里可以下载 Vant 的设计资源。设计稿组件设计稿(Sketch)包含...
介绍日历组件用于选择日期或日期区间。实例演示引入通过以下方式来全局注册组件,更多注册方式请参考组件注册。import { createA...
介绍用户可以在文本框内输入或编辑文字。实例演示引入通过以下方式来全局注册组件,更多注册方式请参考组件注册。import { creat...
介绍建立父子组件之间的关联关系,进行数据通信和方法调用,基于provide和inject实现。代码演示基本用法在父组件中使用useChildr...
介绍用于搜索场景的输入框组件。实例演示引入通过以下方式来全局注册组件,更多注册方式请参考组件注册。import { createApp } f...
介绍用于优惠券的兑换和选择。实例演示引入通过以下方式来全局注册组件,更多注册方式请参考组件注册。import { createApp } fro...
介绍用于从一组相关联的数据集合中进行选择。实例演示引入通过以下方式来全局注册组件,更多注册方式请参考组件注册。import { c...