# waterfall

**Repository Path**: Cookizz/waterfall

## Basic Information

- **Project Name**: waterfall
- **Description**: Android瀑布流布局框架
- **Primary Language**: Android
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 2
- **Created**: 2015-03-11
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# waterfall
<br/>


**1. 简介**

瀑布流（waterfall）是一种元素定宽不定高、横向看去参差不齐的多列布局。随着页面向下滚动，这种布局会不断加载数据块并附加至当前的尾部。它提供错落有致、琳琅满目的视觉效果，特别适用于展现多彩纷呈的图片集。

<br/>

**2. 为Android应用搭建瀑布流布局**

在Android中应用这种布局不是一件很轻松的事，不过这个waterfall框架已经把大部分工作帮你做好了，你只需学会如何使用它。

2.1 引用瀑布流组件

在你的项目里引用waterfall工程库，并在你需要的布局位置添加瀑布流组件（瀑布流默认为2列，具体怎么设置请参看[注意事项](#attentions)）。

```xml
<com.cookizz.waterfall.Waterfall
	android:id="@+id/waterfall"
	android:layout_width="match_parent"
	android:layout_height="match_parent">
```

```java
Waterfall mWaterfall = (Waterfall) findViewById(R.id.waterfall);
```

2.2 实现你的Adapter

推荐你在Adapter中使用一款开源框架：Universal-Image-Loader。它封装了令人头疼的图片加载功能，并提供options满足开发者大部分需求，譬如：使用缓存、使用本地缓存、设置位图格式等。

2.3 添加监听器

给瀑布流添加懒加载监听，规定当页面滑至最底部时要做些什么（通常是加载一批新数据附加至当前的尾部）、当新数据附加完毕时要做些什么。

```java
mWaterfall.addLazyLoadListener(new LazyLoadListener() {
	@Override
	public void onLazyLoadReady() {
		// TODO your code here
	}
	@Override
	public void onLazyLoadFinish() {
		// TODO your code here
	}
});
```

<br/>


<p name="attentions"><strong>3. 注意事项</strong></p>

3.1 元素的排列顺序

在任意时刻，当你向waterfall中添加一个元素的时候，waterfall总是会把这个元素附加到当前所有列中最短的那一列之后，其意图很明显：尽最大努力使各列元素总高度保持近似一致。

3.2 自定义属性

waterfall允许你在xml中自定义2类属性：列数（`column_count`）、元素间距（`item_margin`）。

```xml
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:waterfall="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <com.cookizz.waterfall.Waterfall
        android:id="@+id/waterfall"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        waterfall:column_count="3"
        waterfall:column_count_portrait="3"
        waterfall:column_count_landscape="4"
        waterfall:item_margin="8dp"/>
</RelativeLayout>
```

3.3 header & footer

你可以根据需要实现瀑布流的header和footer。

```java
View footer = getLayoutInflater().inflate(R.layout.waterfall_item_footer, null);
mWaterfall.addFooterView(footer);
```

通常，你的footer会有2种状态：如果你的懒加载需要等待一定的时间，你的footer会处于“正在加载”状态；当加载完毕后，这个footer会切换为隐藏状态（直到下一次懒加载准备就绪）。

如何实现这种带状态的footer呢？除了通过实现上述LazyLoadListener的监听器方法之外，waterfall提供了一种更简单的方法：给你的footer实现ILazyLoadFooter接口，规定footer如何表示特定的2种状态，因为waterfall已经为你做好了触发的时机，所以你只需给你的footer实现这个接口就可以了。

```java
public interface ILazyLoadFooter {
	/**
	 * show footer when a lazy-load is ready
	 */
	public void show();
	/**
	 * hide footer when the lazy-load is finished
	 */
	public void hide();
}
```