更新记录
1.2.4(2024-11-24) 下载此版本
- [优化] 新增
udpate
动态更新数据方法
1.2.3(2024-11-02) 下载此版本
- [修复] 组件重新渲染时未重置待渲染位置的问题
- [优化] 图片宽度支持 px 单位
1.2.2(2024-10-18) 下载此版本
- [修复] 解决了因为数据id重复导致的 小程序平台 waterfall-item 组件不会重新渲染的问题
平台兼容性
Vue2 | Vue3 |
---|---|
√ | × |
App | 快应用 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节小程序 | QQ小程序 |
---|---|---|---|---|---|---|
HBuilderX 4.0 app-vue | √ | √ | √ | √ | √ | √ |
钉钉小程序 | 快手小程序 | 飞书小程序 | 京东小程序 |
---|---|---|---|
× | × | × | × |
H5-Safari | Android Browser | 微信浏览器(Android) | QQ浏览器(Android) | Chrome | IE | Edge | Firefox | PC-Safari |
---|---|---|---|---|---|---|---|---|
√ | √ | √ | √ | √ | √ | √ | √ | √ |
瀑布流 helang-waterfall
插件简介
这是一款简单又好用的瀑布流布局组件,从
1.2.1
版本开始全新升级为组件+插槽的方案实现,极大的简便了组件的使用和内容调整。
源码中有详细的注释,请各位开发者按个人需求自行修改。
对使用有疑问,可以先导入 [示例项目] 学习 页面与组件的使用流程
组件使用
示例源码
示例源码较多,请下载示例项目查看
组件清单
// 引用组件
/* 瀑布流组件 */
// 容器组件
import Waterfall from "@/uni_modules/helang-waterfall/components/waterfall/waterfall-list";
// 分栏组件
import WaterfallCol from "@/uni_modules/helang-waterfall/components/waterfall/waterfall-col";
// 内容组件
import WaterfallItem from "@/uni_modules/helang-waterfall/components/waterfall/waterfall-item";
export default {
// ...
// 注册组件
components: {
"waterfall": Waterfall,
"waterfall-col": WaterfallCol,
"waterfall-item": WaterfallItem
},
// ...
}
容器组件 waterfall-list
插槽
插槽名称 | 透传数据 | 说明 |
---|---|---|
default | 详情见default插槽透传数据说明 | 瀑布流列表内容,放置 waterfall-col 组件 |
tips | - | 瀑布流列表下方提示信息 |
default插槽透传数据说明
- 数据结构:
{ list,colWidth }
- 字段说明:
- list:渲染的数据列表,数据增加了
__waterfall_renderId
、__waterfall_imageHeight
属性__waterfall_renderId
用于<waterfall-item>组件循环渲染的key
__waterfall_reportHeightTime
用于<waterfall-item>组件监听是否需要重新上报高度的时机__waterfall_imageHeight
用于<image>标签的style高度
- colWidth:栏目的宽度,用于 <waterfall-col> 组件的
colWidth
属性
- list:渲染的数据列表,数据增加了
属性
属性名 | 类型 | 默认值 | 说明 |
---|---|---|---|
col | Number | 2 | 列表分栏数量,不可动态修改 |
imageWidth | Number / String | 305 | 列表中图片渲染的宽度,可支持 px 和 rpx单位的宽度,Number类型为rpx单位,若需要px单位则可写152px , 不可动态修改 ,305是示例列表的图片渲染宽度 |
imageKey | String | url | 数据中图片的key值,默认为url |
hideList | Boolean | false | 是否隐藏列表,可隐藏列表部分来展示更多的提示内容(如:空列表时) |
cacheImageHeight | Boolean | true | 是否缓存图片高度,能减少图片信息的加载过程提高渲染效率。 |
方法
- 源码演示
// 组件绑定 ref
<waterfall ref="helangWaterfall">...</waterfall>
// 通过 ref 调用组件中的方案
// 渲染
this.$refs.helangWaterfall.render(数据Array,是否重绘Boolean);
// 上报当前高度
this.$refs.helangWaterfall.reportHeight({
colIndex: 栏目序号Number,
height: 高度Number,
reportHeightTimeChange: 是否需要重新上报高度Boolean
});
// 更新数据
this.$refs.helangWaterfall.update({
colIndex: 栏目序号Number,
itemIndex: 渲染项序号Number,
data: 新的数据Object,切记需要保留之前的属性,仅做新属性的覆盖,参考示例项目,
reportHeight: 是否上报高度Boolean
});
- 详细说明
方法名称 | 参数 | 说明 |
---|---|---|
render | (数据Array,是否重绘Boolean) | 开启瀑布流渲染 |
reportHeight | ({ colIndex: 栏目序号Number, height: 高度Number, reportHeightTimeChange: 是否需要重新上报高度Boolean }) |
汇报当前项的渲染高度,数据从<waterfall-item @height="onRenderHeight"> 获取 |
update | ({ colIndex: 栏目序号Number, itemIndex: 渲染项序号Number, data: 新的数据Object,切记需要保留之前的属性,仅做新属性的覆盖,参考示例项目 reportHeight: 是否上报高度Boolean,用于改变数据会导致节点渲染高度发生改变时使用(如有添加、展开、删除节点的操作时) }) |
更新数据,可参考示例项目的收藏和改变高度的功能实现 |
事件
事件名称 | 参数 | 说明 |
---|---|---|
@statusChange | (渲染状态值String) | 监听瀑布流组件的渲染状态,状态有:RENDER_LOADING(加载中) 、RENDER_START(渲染开始) 、RENDER_END(渲染结束) ,可让业务代码配合拦截部分操作减少渲染过程中的BUG发生 |
分栏组件 waterfall-col
属性
属性名 | 类型 | 默认值 | 说明 |
---|---|---|---|
colWidth | String | '' | 栏目宽度,数据来源于 waterfall-lsit 的插槽透传的colWidth 属性 |
内容组件 waterfall-item
属性
属性名 | 类型 | 默认值 | 说明 |
---|---|---|---|
colIndex | Number | 0 | 栏目索引,用于汇报渲染高度时使用 |
reportHeightTime | Number / String / undefined / null | 0 | 高度上报时间,用于监听是否数据发生更新 |
事件
方法名 | 回调参数 | 说明 |
---|---|---|
@height | ({colIndex, height,reportHeightTimeChange}) | 监听当前内容渲染后的高度,colIndex :栏目索引、height :渲染的高度值、reportHeightTimeChange :是否需要重新上报高度Boolean |
常见问题解答
1. 列表渲染速度太慢,怎么优化?
瀑布流布局最大的难点是在于图片加载是一个异步的过程,所以本插件也是利用了图片加载这个事件来触发组件初始化完成的。为了更好的加载体验和降低用户的用户的流量消耗,推荐使用缩略图
来做为列表中的显示(也应当这么做,不只是在瀑布流布局中),这也是做好一个产品最基本的优化要求。
友情提示:
- 当前项目源码使用了 ES6 和 scss 请添加运行依赖
- [插件ZIP]只包含模板文件和数据文件,不包含项目运行依赖(如 pages.json)
- [示例项目ZIP]是完整的项目文件,可下载后导入 HBuilderX 中直接运行体验
- 文件下载在当前页面的上部靠右位置,有 [下载插件ZIP] [下载示例项目ZIP] 按钮,点击即可下载