影视app
编辑 | blame | 历史 | 原始文档

瀑布流 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 }
  • 字段说明：
    1. list：渲染的数据列表，数据增加了 __waterfall_renderId、__waterfall_imageHeight 属性
      1. __waterfall_renderId 用于<waterfall-item>组件循环渲染的 key
      2. __waterfall_reportHeightTime 用于<waterfall-item>组件监听是否需要重新上报高度的时机
      3. __waterfall_imageHeight 用于<image>标签的 style高度
    2. colWidth：栏目的宽度，用于 <waterfall-col> 组件的colWidth属性

属性

属性名 类型 默认值 说明
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. 列表渲染速度太慢，怎么优化？

瀑布流布局最大的难点是在于图片加载是一个异步的过程，所以本插件也是利用了图片加载这个事件来触发组件初始化完成的。为了更好的加载体验和降低用户的用户的流量消耗，推荐使用缩略图来做为列表中的显示（也应当这么做，不只是在瀑布流布局中），这也是做好一个产品最基本的优化要求。

友情提示：

  1. 当前项目源码使用了 ES6 和 scss 请添加运行依赖
  2. [插件ZIP]只包含模板文件和数据文件，不包含项目运行依赖（如 pages.json）
  3. [示例项目ZIP]是完整的项目文件，可下载后导入 HBuilderX 中直接运行体验
  4. 文件下载在当前页面的上部靠右位置，有 [下载插件ZIP] [下载示例项目ZIP] 按钮，点击即可下载