Tragram Android使用指南

具体组件可以查看官方文档:http://tangram.pingguohe.net/docs/android/access-tangram

接入Tangram代码

1.引入依赖

1
2
// gradle
compile 'com.alibaba.android:tangram:1.0.0@aar'

或者

1
2
3
4
5
6
7
// maven
<dependency>
<groupId>com.alibaba.android</groupId>
<artifactId>tangram</artifactId>
<version>1.0.0</version>
<type>aar</type>
</dependency>

2.初始化 Tangram 环境

应用全局只需要初始化一次,提供一个通用的图片加载器,一个应用内通用的ImageView类型(通常情况下每个应用都有自定义的 ImageView,如果没有的话就提供系统的 ImageView 类)。

1
2
3
4
5
6
7
8
TangramBuilder.init(context, new IInnerImageSetter() {
@Override
public <IMAGE extends ImageView> void doLoadImageUrl(@NonNull IMAGE view,
@Nullable String url) {
//假设你使用 Picasso 加载图片
Picasso.with(context).load(url).into(view);
}
}, ImageView.class);

3.初始化 TangramBuilder

在 Activity 中初始化TangramBuilder,假设你的 Activity 是TangramActivity

1
TangramBuilder.InnerBuilder builder = TangramBuilder.newInnerBuilder(TangramActivity.this);

这一步 builder 对象生成的时候,内部已经注册了框架所支持的所有组件和卡片,以及默认的IAdapterBuilder(它被用来创建 绑定到 RecyclerView 的Adapter)。

4.注册自定义的卡片和组件

1
2
3
4
5
6
7
//TangramBuilder中已经预先注册了许多组件及卡片,可直接使用;此处只需要注册自定义的组件及卡片即可
builder = TangramBuilder.newInnerBuilder(this);
builder.registerCell("自定义名字1", 自定义组件1.class);
builder.registerCell("自定义名字2", 自定义组件2.class);
builder.registerCard("自定义名字3", 自定义卡片3.class);
builder.registerCell(数字, 自定义组件4.class);
builder.registerVirtualView("VirtualView名字");//Tangram对VirtualView的支持

一般情况下,内置卡片的类型已经满足大部分场景了,业务方主要是注册一下自定义组件。注册组件有3种方式:

  • 注册绑定组件类型和自定义View,比如builder.registerCell(1, TestView.class);。意思是类型为1的组件渲染时会被绑定到TestView的实例上,这种方式注册的组件使用通用的组件模型BaseCell
  • 注册绑定组件类型、自定义 model、自定义View,比如builder.registerCell(1, TestCell.class, TestView.class);。意思是类型为1的组件使用自定义的组件模型TestCell,它应当继承于BaseCell,在渲染时会被绑定到TestView的实例上。
  • 注册绑定组件类型、自定义model、自定义ViewHolder,比如builder.registerCell(1, TestCell.class, new ViewHolderCreator<>(R.layout.item_holder, TestViewHolder.class, TestView.class));。意思是类型为1的组件使用自定义的组件模型TestCell,它应当继承于BaseCell,在渲染时以R.layout.item_holder为布局创建类型为TestView的 view,并绑定到类型为TestViewHolder的 viewHolder 上,组件数据被绑定到定到TestView的实例上。

一般情况下,使用前两种方式注册组件即可。至于组件开发规范,请参考组件开发

5.生成TangramEngine实例

在上述基础上调用:

1
TangramEngine engine = builder.build();

6.绑定业务 support 类到 engine

Tangram 内部提供了一些常用的 support 类辅助业务开发,业务方也可以自定义所需要的功能模块注册进去。以下常用三个常用的support,分别处理点击、卡片数据加载、曝光逻辑,详情请参考文档

1
2
3
engine.register(SimpleClickSupport.class, new XXClickSupport());
engine.register(CardLoadSupport.class, new XXCardLoadSupport());
engine.register(ExposureSupport.class, new XXExposureSuport());

7.绑定 recyclerView

1
2
3
4
setContentView(R.layout.main_activity);
RecyclerView recyclerView = (RecyclerView) findViewById(R.id.main_view);
...
engine.bindView(recyclerView);

8.监听 recyclerView 的滚动事件

1
2
3
4
5
6
7
8
recyclerView.addOnScrollListener(new RecyclerView.OnScrollListener() {
@Override
public void onScrolled(RecyclerView recyclerView, int dx, int dy) {
super.onScrolled(recyclerView, dx, dy);
//在 scroll 事件中触发 engine 的 onScroll,内部会触发需要异步加载的卡片去提前加载数据
engine.onScrolled();
}
});

9.设置悬浮类型布局的偏移(可选)

如果你的 recyclerView 上方还覆盖有其他 view,比如底部的 tabbar 或者顶部的 actionbar,为了防止悬浮类 view 和这些外部 view 重叠,可以设置一个偏移量。

1
engine.getLayoutManager().setFixOffset(0, 40, 0, 0);

10.设置卡片预加载的偏移量(可选)

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

1
engine.setPreLoadNumber(3)

11.加载数据并传递给 engine

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

1
2
3
4
5
6
7
8
String json = new String(getAssertsFile(this, "data.json"));
JSONArray data = null;
try {
data = new JSONArray(json);
engine.setData(data);
} catch (JSONException e) {
e.printStackTrace();
}

12.退出的时候销毁 engine

1
engine.destroy();

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

坚持原创技术分享,您的支持将鼓励我继续创作!