易达信息科技

阅读本文大概需要20分钟

熟悉阿里出品的vlayout的读者都知道，vlayout极大地扩展了RecyclerView的LayoutManager，从而为RecyclerView提供了一组布局。使用该开源项目，可以让我们在同一个RecyclerView里处理线性、网格等等各种复杂的布局。然而，使用vlayout时，一切都需要用Java代码实现，而且都是写在客户端上，一旦需要修改就必须发版，不是很灵活，于是阿里又提出了Tangram，其可以使用json来配置布局，可以说极大地提升了灵活性。下面我们来学习一下如何使用Tangram。

目录

1 Tangram的概念

2 Tangram使用步骤

2.1 引入依赖

2.2 初始化 Tangram 环境

2.3 初始化 TangramBuilder

2.4 注册自定义的卡片和组件

2.5 生成 TangramEngine 实例

2.6 绑定业务 support 类到 engine

2.7 绑定 RecyclerView

2.8 监听 RecyclerView 的滚动事件

2.9 设置悬浮类型布局的偏移（可选）

2.10 设置卡片预加载的偏移量（可选）

2.11 加载数据并传递给 engine

2.12 退出的时候销毁 engine

3 组件与布局

3.1 页面概念模型

3.1.1 页面

3.1.2 布局（卡片）

3.1.3 组件

3.2 组件开发

3.2.1 通用 model 开发组件

3.2.2 自定义 model 开发组件

3.2.3 json数据开发

3.3 处理业务逻辑

3.3.1 处理点击

3.3.2 处理曝光

3.3.3 异步加载数据

3.4 布局（卡片）

3.4.1 流式（网格）布局

3.4.2 一拖N布局

3.4.3 浮动布局

3.4.4 固定布局

3.4.5 吸顶布局

3.4.6 轮播滚动布局

3.4.7 横向滚动布局

3.4.8 瀑布流布局

4 示例

参考链接

---

Tangram 是阿里出品的用于快速实现组合布局的框架模型，在手机天猫 Android 及 iOS版广泛使用。

中文翻译为七巧板，即该框架提供一系列基本单元布局，通过快速拼装就能搭建出一个具备多种布局的页面。

Tangram提供了流式布局、滚动布局，瀑布流布局，固定布局等数种布局样式，布局提供样式参数供调整，布局内部也可填充任意的视图(View)，使Native开发的页面具备一定的动态性，并提供极致的性能。

Tangram包含的特点如下：

• Android iOS 双平台支持，iOS 版本参考开源库 Tangram-iOS。
• 通过 json 创建页面视图，并提供了默认的解析器。
• 可轻松实现页面视图的回收与复用。
• 框架提供多种默认的布局方式。
• 通过 json 数据或代码支持自定义布局样式。
• 高性能，基于vlayout。
• 支持扩展功能模块。

下面来看看如何使用Tangram。

在APP的build.gradle中添加：

其中，Tangram的版本号可以改成最新的，最新版本号可以在这个链接找到：https://github.com/alibaba/Tangram-Android/releases

另外还要添加VirtualView和UltraViewPager这两个库，否则运行时会出现问题：

VirtualView的最新版本号可以在这里找到：https://github.com/alibaba/Virtualview-Android/releases

应用全局只需要初始化一次，需要提供一个图片加载器，例如使用Glide库或Picasso库，代码如下：

在 Activity 中初始化TangramBuilder，假如你的 Activity 是TangramActivity，则代码如下：

注册组件的方式有如下3种：

（1）注册绑定组件类型和自定义View，示例代码：

（2）注册绑定组件类型、自定义 model、自定义View，示例代码：

（3）注册绑定组件类型、自定义model、自定义ViewHolder，示例代码：

这里先不做详解，关于卡片和组件的详细使用请参见第3节。

在上述基础上调用：

Tangram 内部提供了一些常用的 support 类辅助业务开发，具体请见3.3节，使用方式有如下3种：

如果你的 RecyclerView 上方还覆盖有其他 view，比如底部的 tabbar 或者顶部的 actionbar，为了防止悬浮类 view 和这些外部 view 重叠，可以设置一个偏移量。此功能需要额外引入vlayout（https://github.com/alibaba/vlayout）。代码如下：

在页面滚动过程中会触发engine.onScrolled()方法，会去寻找屏幕外需要异步加载数据的卡片，默认往下寻找5个，让数据预加载出来，我们也可以修改这个偏移量，代码如下：

数据一般是调用接口加载远程数据，这里演示的是 mock 加载本地的数据：

通过主动调用 destroy 方法，可以释放内部的资源，比如清理 adapter、清理事件总线缓存的未处理消息、注销广播等。注意调用 destroy 方法之后就不需要调用 unbind 方法了。

我们将一个普通的列表页面结构化成树状结构：分别是页面、布局（卡片）和组件。一个页面下面可以挂载多个布局或者组件，一个布局下面可以挂载多个组件，整体是一个树状结构描述。每一层次都有各自的职责，如下图：

3.1.1 页面

如上图所示，一个页面包含一个卡片列表，每个卡片持有一个组件列表，整个页面是一个页面 - 布局 - 组件的树状结构。它要求整体可滚动，并且能按照组件的类型去回收复用。

在实现上，在 Tangram-iOS 里，它是基于 LazyScrollView 的页面容器，在 Tangram-Android 里，它是基于 vlayout 构建的 RecyclerView。

3.1.2 布局（卡片）

布局的主要职责是负责对组件进行布局，它有四个组成：header、footer、body、style，如下图所示：

最重要的是 body 部分，它包含了内嵌的组件，如果布局没有 body，即没有组件，也就不在视觉上做渲染。卡片的布局也就是对 body 里包含的组件来进行布局。Tangram 内置了一系列布局能力对组件进行布局，包括流式布局、瀑布流布局、吸顶布局、悬浮布局、轮播布局等等，基本上常见的布局方式都可以覆盖到。header、footer 是卡片的标题和尾部，目前只有轮播卡片、通用流式卡片支持 header、footer。style 是对布局样式的描述，所有布局会有一些通用的样式属性比如边距、间距，也有一些特有的比如宽高比，通过样式的描述，可以让布局能力更加丰富。

布局描述就是一种布局类型的声明，因为框架已经内置了布局能力，只需要声明采用哪一种布局方式，因此不需要布局模板。如果框架的内置布局能力满足不了需求，还可以自定义扩展新的布局类型注册到 Tangram 里。

以下是一个布局的 json 描述示例（type, style, header, footer, items都是关键字）：

3.1.3 组件

组件的职责就是负责基本的 UI 展示和交互，它是按照业务划分的最小单元，不像通用的 UI 框架那样会设计文本、按钮、线条那样的基础元素。

在 Tangram 里，组件长什么样，框架是不知道的，框架内也不内置组件，都是由我们接入的时候自行按需注册。同布局一样，组件的数据描述也需要提供与 UI 相关的模板，包含3部分：类型、数据、样式。类型是必须的，如果我们在 Tangram 里注册过这种类型，那么就能被框架解析处理；数据也是必须的，它包含了业务信息；样式是可选的，组件可以按照自己的需求定义样式，在实现的时候解读样式数据。

以下是一个组件的 json 描述示例（type, style都是关键字）：

这样，就可以将多个组件的 json 数据放到布局的items里，然后将多个布局的 json 数据组合成一个 json 列表，就形成了一个页面。

下面的步骤，先使用Java进行组件的开发，并进行注册，然后使用json来描述整体的布局。

组件分为两层：model 和 View。model是对json数据的解析，View就是我们自定义的View。Tangram 里提供了通用 model 类型baseCell，其包含了对json数据的解析，还有位置等信息。开发组件有两种方式：

1. 采用通用 model，开发自定义 View；
2. 采用自定义 model 和自定义 View。

3.2.1 通用 model 开发组件

这种方式无需关心 model，主要是开发自定义 View。

自定义 View 有两种实现规范：

（1）使用接口方式，避免了反射调用，性能上更优，步骤如下：

• 实现一个自定义View，比如XXTangramView；
• 实现接口ITangramViewLifeCycle，包含三个方法：

• 主要在上述public void postBindView(baseCell cell)方法里完成组件业务逻辑。

下面实现一个示例，其中包含一个ImageView和一个TextView，代码如下：

（2）使用注解方式，动态绑定数据：

• 实现一个自定义View，比如XXTangramView；
• 必须添加下面三个方法，以@CellRender注解，功能同上，只是被反射调用：

• 还可以为组件的每个属性实现单独的设置方法，而不是在postBindView方法里一次性绑定数据，这些方法必须以@CellRender注解，框架会在public void postBindView(baseCell cell)方法调用之前调用这些数据绑定方法，示例代码：

下面采用注解的方式实现之前用接口方式实现的自定义View，代码如下：

以上两种方式开发的组件在页面初始化的时候调用TangramBuilder.InnerBuilder的registerCell(String type, Class<V> viewClz)方法进行注册，也就是2.4节的第一种注册方式，代码如下：

意思是类型为“InterfaceCell”的组件渲染时会被绑定到CustomInterfaceView的实例上，类型为“AnnotationCell”的组件渲染时会被绑定到CustomAnnotationView的实例上，这种方式注册的组件使用通用的组件模型baseCell。

在自定义 View 里访问 json 数据：

组件的View对应于一个统一的model，类型是baseCell，要在View里访问 json 数据，baseCell提供了以下方法：

这些方法都会先访问baseCell里持有的原始json数据，同时支持访问style节点下的属性。

例如上面示例代码的第46~47行中使用的代码cell.optParam("text")，它的含义就是取json数据中key为“text”的字段。

3.2.2 自定义 model 开发组件

采用通用的 model 开发组件，只需要写 View 就可以了，然而需要在每次绑定数据的时候都要取原始 json 数据解析一下字段。有时候我们会有一些通用的业务字段定义，每个组件里重复解析会让代码显得冗余，因此也提供了注册自定义 model 的兼容模式开发组件。这个时候就需要写自定义 model 和自定义 View 两部分了。

（1）自定义 model 开发

• 实现一个自定义 model 类，继承自 baseCell。
• 实现以下几个方法：

示例代码：

（2）自定义 View 开发

类似于3.2.1节，示例代码：

这种方式开发的组件在页面初始化的时候调用TangramBuilder.InnerBuilder的registerCell(int type, @NonNull Class<? extends baseCell> cellClz, @NonNull Class<V> viewClz)方法进行注册，也就是2.4节的第二种注册方式，代码如下：

意思是类型为“CustomCell”的组件使用自定义的组件模型CustomCell，在渲染时会被绑定到CustomCellView的实例上。

也可采用2.4节的第三种注册方式，即注册绑定组件类型、自定义model、自定义ViewHolder，示例代码：

意思是类型为“HolderCell”的组件使用自定义的组件模型CustomHolderCell，在渲染时以R.layout.item_holder为布局创建类型为TextView的 view，并绑定到类型为CustomViewHolder的 viewHolder 上，组件数据被绑定到TextView的实例上。

CustomHolderCell.java的代码如下：

item_holder.xml的代码如下：

CustomViewHolder.java的代码如下：

一般情况下，使用上一节和这一节的第一种注册方式这两种方式注册组件即可。

3.2.3 json数据开发

下面针对上面开发的几种组件，根据3.1节的格式写一个简单的json示例。

在项目的assets文件夹下（没有的话自己建一个）新建data.json，代码如下：

运行APP，显示效果如下：

3.3.1 处理点击

此时所有组件可以显示出来了，但是还没有点击事件。组件 View 的点击处理，可以实现SimpleClickSupport，然后在组件自定义的 View 内部调用setonClickListener(cell);，那么组件的点击行为会被回调到SimpleClickSupport里统一处理。

当然使用SimpleClickSupport只是一种推荐的使用方式，我们选择自定义的点击处理也是可以的。

选用SimpleClickSupport的时候有几个注意点：

• 建议开启优化模式 —— setOptimizedMode(true)，这样点击会被统一回调到public void defaultClick(View v, baseCell cell, int pos)方法里，我们就可以根据组件类型、View的类型即组件类型做点击处理。
• 如果不开启优化模式，SimpleClickSupport内部会跟进被点击的组件类型和 View 的类型来做路由，它要求我们在SimpleClickSupport的实现类里为每个组件的点击提供以 onClickXXX 或者 onXXXClick 为命名规范的点击处理方法，并且参数列表是View targetView, baseCell cell, int type或者View targetView, baseCell cell, int type, Map<String, Object> params。这种方式效率会低一些，针对采用自定义 model 开发组件的时候有用。

那么我们新建一个CustomClickSupport类，代码如下：

在CustomInterfaceView.java和CustomAnnotationView.java的cellInited()方法中添加如下代码：

在CustomCell.java的bindView()方法中添加如下代码：

在CustomHolderCell.java的bindView()方法中添加如下代码：

最后如2.6节在初始化的时候注册一下，代码如下：

运行一下APP，点击每个组件，就会弹出toast提示了。

3.3.2 处理曝光

所谓曝光，就是被 RecyclerView 的 Adapter 绑定数据的那个时候，也就是某个Item即将滑动到屏幕范围内的时候。在这个时候业务上如果需要有一些处理，就需要实现ExposureSupport类。它定义了3个层面的曝光接口，一是曝光布局，二是曝光组件整体区域，三是曝光组件局部区域。我们实现它的子类，并针对这三个层面的曝光做分别的实现。分别说明如下：

（1）布局的整体曝光

需要重写回调接口方法public abstract void onExposure(@NonNull Card card, int offset, int position);。新建CustomExposureSupport.java，代码如下：

然后如2.6节在初始化的时候注册一下，代码如下：

为了方便说明，我们将data.json改成如下代码：

运行APP，当我们滚到每一个布局的时候，就会打印一条日志，全部日志如下：

（2）组件的整体曝光

• 建议开启优化模式 —— setOptimizedMode(true)，这样曝光接口被统一回调到public void defaultExposureCell(@NonNull View targetView, @NonNull baseCell cell, int type)方法里，我们可以根据组件类型、View的类型即组件类型做曝光处理。
• 如果不开启优化模式，ExposureSupport内部会跟进被点击的组件类型和 View 的类型来做路由，它要求我们在ExposureSupport的实现类里为每个组件的点击提供以 onExposureXXX 或者 onXXXExposure 为命名规范的点击处理方法，并且参数列表是View targetView, baseCell cell, int type。这种方式效率会低一些，针对采用自定义 model 开发组件的时候有用。

在CustomExposureSupport.java里添加如下代码：

运行APP，当我们滚到每一个组件的时候，就会打印一条日志，全部日志如下：

（3）组件的局部区域曝光

• 建议开启优化模式 —— setOptimizedMode(true)，这样曝光接口被统一回调到public void defaultTrace(@NonNull View targetView, @NonNull baseCell cell, int type)方法里，我们可以根据组件类型、View的类型即组件类型做曝光处理。
• 如果不开启优化模式，ExposureSupport内部会跟进被点击的组件类型和 View 的类型来做路由，它要求我们在ExposureSupport的实现类里为每个组件的点击提供以 onTraceXXX 或者 onXXXTrace 为命名规范的点击处理方法，并且参数列表是View targetView, baseCell cell, int type。这种方式效率会低一些，针对采用自定义 model 开发组件的时候有用。

前两个层面的曝光调用都是框架层调用，而组件局部曝光，则需要我们在组件逻辑里自行调用。使用方式如下：

那么，我们在CustomInterfaceView.java和CustomAnnotationView.java的cellInited()方法中添加如下代码：

然后在CustomCell.java的bindView()方法中添加如下代码：

在CustomHolderCell.java的bindView()方法中添加如下代码：

最后在CustomExposureSupport.java里添加如下代码：

运行APP，当我们滚到每一个组件的时候，就会打印一条日志。与（2）不同的是，（2）是在第一次曝光的时候调用，而（3）是在每次曝光的时候都会调用。全部日志如下：

3.3.3 异步加载数据

有时 Tangram 的页面的数据无法一次性返回，有些区块布局内的数据需要异步加载、甚至分页加载。Tangram 里内置了封装了异步加载的逻辑，需要各个层面配合完成，这里加以说明：

（1）布局model 的load，loadParams，loadType，hasMore

• load 是接口名称，表示这个布局需要执行异步加载的接口。
• loadParams 是异步加载接口的常规参数字典，需要在调用接口时透传。
• loadType 是异步加载的方式，-1表示需要异步加载，1表示需要异步加载且有分页。
• hasMore 与 loadType 配合，当 loadType = 1 的时候表示分页是否结束。

示例代码：

（2）setPreLoadNumber(int preLoadNumber)

调用TangramEngine上的setPreLoadNumber(int preLoadNumber)方法，设置触发卡片预加载的时机，默认 preLoadNumber 是5，表示在滑动过程中，提前去触发可见范围之外5块布局以内的异步加载逻辑。可以通过这个接口调整预加载的范围。

（3）onScrolled()

在recyclerView 的 onScrollListener里调用TangramEngine上的onScrolled()方法，触发预加载的逻辑，代码如2.8节。

（4）CardLoadSupport与AsyncLoader，AsyncPageLoader

在配置完上述异步加载的基础设置之后，提供一个自定义的CardLoadSupport服务，该服务需要提供一个自定义的AsyncLoader和AsyncPageLoader。

AsyncLoader的loadData(final Card card, @NonNull final LoadedCallback loadedCallback)方法回调是卡片异步加载的入口。加载完成之后通过LoadedCallback的回写接口告知布局加载是否完成。

AsyncPageLoader的loadData(int page, @NonNull Card card, @NonNull final LoadedCallback callback)方法是回调卡片分页加载的入口。加载完成之后通过LoadedCallback的回写接口告知布局加载是否完成，是否还有下一页。

代码如下：

AsyncLoader加载成功之后回调示例代码：

AsyncPageLoader加载成功之后回调示例代码：

我们就不在demo实现了，有兴趣的读者可以去深入研究。

更多组件高级用法，例如使用定时器等，可参看使用定时器 - Tangram

Tangram的强大之处就在于可以在json中混合各种类型的布局，其主要职责是负责对组件进行布局。Tangram 内置了一系列布局能力对组件进行布局，包括流式布局、瀑布流布局、吸顶布局、悬浮布局、轮播布局等等，基本上常见的布局方式都可以覆盖到。

下面对各种布局分别进行阐述。

3.4.1 流式（网格）布局

流式布局是最常用的布局。详细说明