列表 List

列表组件。集成加载状态和空状态的列表组件。

重要提示

重要提示

需在 App.vue 中引入 pure-styles 样式，@import '@/uni_modules/pure-styles/index.css';

兼容性

• 兼容：✅
• 不兼容：❌
• 未知：❔

H5	安卓	苹果	微信	支付宝	百度	抖音	QQ	快手	飞书	京东
✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅

小红书	鸿蒙	360	华为快应用	快应用联盟
✅	❔	❔	❔	❔

插件市场地址

DCloud 插件市场地址

使用方式

• 通过 v-model 绑定列表数据。
• 通过 loadPromise 绑定查询列表的函数，该函数需返回一个 Promise。

内部判断是否加载全部数据的逻辑

• 默认情况下，组件内容通过 pageSize 和接口返回新数据的长度判断是否加载了全部数据。
  • 如果新数据长度小于 pageSize，则认为已加载全部数据。
  • 否则，认为未加载全部数据。
  • 需通过 pageSize 属性传入每页的数据长度。
• 通过列表全部数据的总长度和当前列表数据的长度判断是否加载了全部数据。
  • 如果当前列表数据长度大于等于总长度，则认为已加载全部数据。
  • 否则，认为未加载全部数据。
  • 需要通过 listTotalKeyName 属性设置接口返回数据中表示数据总长度的属性名，支持深层写法，如 data.total。
• 通过接口返回的总页数和当前页码判断是否加载了全部数据。
  • 如果当前页码 +1 大于等于总页数，则认为已加载全部数据。
  • 否则，认为未加载全部数据。
  • 需要通过 pageTotalKeyName 属性设置接口返回数据中表示数据总页数的属性名，支持深层写法，如 data.totalPage。

空状态的显示逻辑

• 至少请求过一次数据。
• 当前页码等于defaultIndex。
• 数据为空或请求失败。
• showEmpty 属性为 true。

满足以上所有条件后才会显示空状态。

<template>
    <pure-list v-model="list" :pageSize="pageSize" :loadPromise="queryList" ref="listRef">
        <view class="item" v-for="(item, index) in list" :key="index">{{ index + 1 }}</view>
    </pure-list>
</template>

<script setup>
    import { ref } from "vue";
    import { onReady, onPullDownRefresh, onReachBottom } from "@dcloudio/uni-app";

    // 组件的引用
    const listRef = ref(null);

    // 列表数据
    const list = ref([]);

    // 每页数据长度
    const pageSize = 15;

    // 页面渲染完成后
    onReady(() => {
        // 加载第一页数据
        listRef.value.load();
    });

    // 上拉加载
    onReachBottom(() => {
        listRef.value.load();
    });

    // 下拉刷新
    onPullDownRefresh(() => {
        listRef.value.refresh();
    });

    // 查询数据
    function queryList() {
        // 模拟查询数据
        // 需返回 Promise
        return new Promise((resolve) => {
            const newList = [];

            // 默认返回的数据长度小于pageSize，则被认为没有更多数据了
            // 这里模拟实现一下
            const size = list.value.length >= pageSize * 3 ? pageSize - 5 : pageSize;

            for (let i = 0; i < size; i++) {
                newList.push({
                    id: Math.random(),
                });
            }

            // 模拟接口返回的数据
            const result = {
                code: 0,
                errMsg: "请求成功",
                data: {
                    list: newList,
                },
            };

            setTimeout(() => {
                resolve(result);
            }, 1000);
        });
    }
</script>

Props

属性名	说明	类型	默认值	可选值	版本
v-model	列表数据	Array	[]	-	+1.0.0
loadPromise	加载数据的函数	Function	undefined	-	+1.0.0
pageSize	每页数据长度	Number	10	-	+1.0.0
defaultIndex	默认页码，即从哪一页开始加载数据	Number	1	-	+1.0.0
showEmpty	是否显示空状态	Boolean	true	false	+1.0.0
showLoadmore	是否显示加载状态	Boolean	true	false	+1.0.0
emptyOpts	空状态组件配置项，参考	Object	{}	-	+1.0.0
loadmoreOpts	加载状态组件配置项，参考	Object	{}	-	+1.0.0
listDataKeyName	接口返回数据中表示列表数据的键名	String	data.list	-	+1.0.0
listTotalKeyName	接口返回数据中表示列表总长度数据的键名	String	""	-	+1.0.0
pageTotalKeyName	接口返回数据中表示列表总页数数据的键名，优先级高于 listTotalKeyName	String	``	-	+1.0.0

Event

事件名	说明	回调参数	版本
complete	加载数据函数请求完成后的事件	-	+1.0.0

Slots

名称	说明	参数	版本
default	默认，列表项	-	+1.0.0