@alipay/adc-flat-list 的组件描述
npm install @mas.io/adc-flat-listbash
tnpm install --save @alipay/adc-flat-list
`组件介绍
能力中心小程序分页加载列表组件，支持长列表优化模式（虚拟滚动），支持下拉刷新、瀑布流等功能
使用限制：需开启基础库2.0
参数说明
属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例
--|:--:|:--:|:--:|:--: | :-:
list | 是 | Array | 存储列表数据的数组。由使用方管理，并传给组件 | -- | --
onFetchData | 是 | Function | 列表数据请求; params:(page: number, limit: number); return: Promise<{ total(数据总数): number, list(数据): Array }>;失败时，请reject | null | --
useVirtualScroll | 否 | boolean | 是否开启虚拟滚动 | false | --
style | 否 | String | scroll-view容器样式 | 'height:100vh;' | --
className | 否 | String | scroll-view容器css类 | '' | --
limit | 否 | Number | 分页请求每页条数 | 10 | --
loadContent | 否 | Array[String] | 加载时的底部提示 | ['马不停蹄加载更多数据中...', '-- 已经到底了，加不了咯 --'] | --
emptyPageFooter | 否 | Array[{text}] | 空数据页面，错误处理按钮文案（等同于Page-result组件的footer） | [{ text: '刷新' }] | --
id | 否 | String | 如果项目中同时存在多个flat-list组件，并且开启虚拟滚动，需要添加唯一id加以区分 | '' | --
pullDownRefresh | 否 | Boolean | 是否开启下拉刷新。开启方法详见下文 | false | --
pullDownText | 否 | Array[String] | 下拉刷新时显示的文本 | ['下拉刷新', '松开刷新', '刷新成功', '刷新失败'] | --
autoFetch | 否 | Boolean | 是否在组件didMount时自动调用fetchData。（一般情况不必要使用此参数。如果设为false，则需要手动调用组件ref的
方法获取数据） | true | --
waterfall | 否 | Boolean \| Waterfall | 是否开启瀑布流，详见下文 | false | --
onTapLeft | 否 | Function | 空数据页面左侧按钮事件（等同于Page-result组件的onTapLeft） | 默认为刷新 | --
onTapRight | 否 | Function | 空数据页面左侧按钮事件（等同于Page-result组件的onTapRight） | null | --Slot
Name | 说明 | 是否必传
--|:--:|:--:
default | 列表内容 | 否
header | 头部内容 | 否
empty | 空数据自定义页面 | 否
footer | 自定义底部内容。slot-scope有三个属性，isLoading: 是否在加载中, isOver: 是否已是最后一页, page: 最后一页的页码数 | 否组件Ref方法
Name | 说明
--|:--:
refresh | 刷新列表内容。list的重置需要使用方自己管理在小程序中使用
`json
{
"usingComponents": {
"adc-flat-list": "@alipay/adc-flat-list/es/index"
}
}
`在 page.axml 中引用组件
html
onFetchData="onFetchData">
item="{{props.item}}"
index="{{props.index}}">
`useVirtualScroll使用说明
开启虚拟滚动时，必须确保列表数据中有唯一的id字段，因为组件内部会使用a:key="id"。普通模式也推荐有id字段。
虚拟滚动采用的是按页实现，在任何时候，最多会渲染三页的数据。因此应该使每页条数有个合适的值。
支持列表高度不一致的情况。
暂不支持列表高度可以动态改变，和用非分页方式一次渲染全部数据的情况。scroll-view透传属性
scrollTop, scrollIntoView ,scrollWithAnimation, scrollAnimationDuration,
onScroll, upperThreshold, lowerThreshold, onScrollToUpper, onScrollToLower,
scrollY, disableScroll, disableLowerScroll, disableUpperScroll
onFetchData使用方式说明
async awit
javascript
Page({
async onFetchData(page, limit) {
const res = await getMockData(page, limit);
// 如果有错，请throw error
this.setData({
list: [...this.data.list, ...res.list],
});
return {
total: res.total,
list: res.list,
};
},
})
`promise
javascript
Page({
onFetchData(page, limit) {s
return getMockData(page, limit).then(res => {
// 如果有错，请throw error
this.setData({
list: [...this.data.list, ...res.list],
});
return {
total: res.total,
list: res.list,
};
})
},
})
`一行多列实现方案
修改组件内部的 adc-flat-list-item-container 类，并配置好 item 的样式就可以实现。
使用限制：一行多列暂不支持开启虚拟滚动！
下面是一行两列的示例代码：
html
`css
.adc-flat-list-item-container {
display: flex;
flex-wrap: wrap;
}.item {
box-sizing: border-box;
width: 50%;
padding: 24rpx;
}
.item:nth-child(odd) {
padding-right: 12rpx;
}
.item:nth-child(even) {
padding-left: 12rpx;
}
`下拉刷新开启说明
下拉刷新与普通刷新不同，在成功获取新数据前，不会销毁原有的数据。使用限制：下拉刷新使用touchMove实现，因此在使用过程中注意可能和其他滚动事件，touchMove事件带来冲突。
不能再使用小程序原生的下拉刷新功能，需要在页面或app.json中配置"allowsBounceVertical": "NO"
需要在onFetchData中做相关配合，在第三个参数type中会传'pullDown'，示例代码如下：
javascript
Page({
async onFetchData(page, limit, type) {
const res = await getMockData(page, limit);
// 如果有错，请throw error if (type === 'pullDown') {
// 下拉刷新
this.setData({
// 下拉刷新时，page为1，因此获取的就是第一页的数据，直接将res.list放入list中更新列表
list: res.list,
});
} else {
// 普通加载模式
this.setData({
list: [...this.data.list, ...res.list],
});
}
return {
total: res.total,
list: res.list,
};
},
})
`瀑布流
瀑布流分为两种：
1. 能预知 item 高度的瀑布流
：每一个 item 渲染出来后，能立即获取 item 的尺寸（通过my.createSelectorQuery）。例如一个 item 中包含的图片事先就知道尺寸，通过设置css，在图片load完成之前就把宽高固定。这种瀑布流的每个 item 能并行加载，每次并行加载一页。
2. 不能预知 item 高度的瀑布流(mode=2)：例如 item 中包含图片，但不能预知图片的尺寸。此种瀑布流的 item 采用串行加载——一个 item 加载完成，能获取高度后，再去加载下一个。这种瀑布流如果网络条件不好，图片加载慢，体验肯定是要差一些的。使用限制：瀑布流暂不支持开启虚拟滚动！每个item中必须要有id
$3
属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例
--|:--:|:--:|:--:|:--: | :-:
mode | 否 | 1 \| 2 | 1是预知高度瀑布流，2是未知高度瀑布流 | 1 | --
column | 否 | Number | 列数 | 2 | --
gutter | 否 | String | item 间隔 | '24rpx' | --
preRenderRow | 否 | Number | 首页预渲染 item 的行数，未知高度瀑布流专用。因为 item 为串行加载，首页加载数量过少可能不美观。通过preRenderRow可预先并行加载几行的 item，不计算它们的高度 | 2 | --
timeout | 否 | Number(ms) | 图片加载超时时间，未知高度瀑布流专用，防止串行加载图片遇到阻塞 | 5000 | --
$3
瀑布流中的使用图片组件（一个item只能有一张）
属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例
--|:--:|:--:|:--:|:--: | :-:
scope | 是 | slot-scope | 只需将slot-scope的值传入，详见示例 | -- | scope="{{props}}"
imageSrc | 是 | String | 图片地址 | -- | --
loadingSrc | 否 | String | 正式图片加载成功前显示的预览图片。不用图片，只在style中指定一个背景色效果也不错 | -- | --
style | 是 | String | 图片的style。其中，height必须指定，backgroundColor可配合预览图片设置合适的颜色。详见示例 | -- | --
$3
`json
{
"usingComponents": {
"adc-flat-list": "/components/es/index",
"waterfall-image": "/components/es/waterfall-image/index"
}
}
`css.container {
padding: 0 24rpx;
}
`html
onFetchData="onFetchData"
pullDownRefresh
waterfall>
imageSrc="{{props.item.imageUrl}}"
loadingSrc="https://tva1.sinaimg.cn/large/006APoFYly1g8mf9qe5udg30jz0jzjtr.gif" />
商品编号：{{props.index}}
商品名称：{{props.item.name}}
商品价格：{{props.item.price}}
`javascriptconst list = (function () {
const arr = [];
for (let i = 0; i < 51; i++) {
const height = Math.floor(Math.random() * 600) + 50;
arr.push({
id: i + 1,
price: Math.ceil(Math.random() * 50),
name: ['茄宝娜雪平锅', 'stylor多功能喷雾拖把', '擦手巾'][i % 3],
imageUrl:
https://picsum.photos/300/${height}?random=${Math.random()},
height,
});
}
return arr;
})();function getMockData(page, limit) {
return new Promise((resolve) => {
setTimeout(() => {
const start = (page - 1) * limit;
const end = start + limit;
resolve({
list: list.slice(start, end),
total: list.length,
});
}, 500);
});
}
Page({
data: {
list: [],
},
async onFetchData(page, limit, type) {
const res = await getMockData(page, limit);
if (type === 'pullDown') {
// 下拉刷新
// mock数据改变
list[0].price += 1;
this.setData({
list: res.list,
});
} else {
// 普通加载模式
this.setData({
list: [...this.data.list, ...res.list],
});
}
return res;
},
});
`$3
html
onFetchData="onFetchData"
pullDownRefresh
waterfall="{{mode: 2}}">
imageSrc="{{props.item.imageUrl}}"
loadingSrc="https://tva1.sinaimg.cn/large/006APoFYly1g8mf9qe5udg30jz0jzjtr.gif" />
商品编号：{{props.index}}
商品名称：{{props.item.name}}
商品价格：{{props.item.price}}
``[![TNPM version][tnpm-image]][tnpm-url]
[![TNPM downloads][tnpm-downloads-image]][tnpm-url]
[tnpm-image]: https://npm.alibaba-inc.com/badge/v/@alipay/adc-flat-list.svg
[tnpm-url]: https://npm.alibaba-inc.com/package/@alipay/adc-flat-list
[tnpm-downloads-image]: https://npm.alibaba-inc.com/badge/d/@alipay/adc-flat-list.svg
--------------------