手把手教你系列- 变色龙SDK使用范例

以一个小demo工程,讲述变色龙SDK的使用方式,引领轻松入门。Demo 工程在根目录 app 目录下,用 Android Studio 导入并 run 起来后,再对照以下说明文档看会好理解。

根目录 assets 目录下的 cml-demo-say.zip 是个简单的示例工程

用来演示native 和 weex容器或web容器的双向通信。app 目录下demo工程加载的 weex bundle 和 h5 页就是这个工程实现的。

1. compile 依赖添加

1.1 项目根目录 build.gradle 里添加 maven 仓库地址

buildscript {
    repositories {
        jcenter()
        maven {
            url 'https://maven.google.com/'
        }
    }
    ...
}

allprojects {
    repositories {
        maven {
            url 'https://maven.google.com/'
        }
        jcenter()
        mavenCentral()
        ...
    }
}

1.2 在 app 模块的 build.gradle 里添加依赖

1.2.1 首先添加如下依赖

dependencies {
    ...
    compile "com.android.support:support-v4:$SUPPORT_VER"
    compile "com.android.support:appcompat-v7:$SUPPORT_VER"
    compile "com.android.support:recyclerview-v7:$SUPPORT_VER"
    compile "com.didiglobal.chameleon:cmlsdk:$VERSION"
    compile "com.didiglobal.chameleon:cmlweb:$VERSION"
}

1.2.2 添加渲染引擎依赖

cml native sdk 采用 weex 作为渲染引擎,当前依赖的weex版本是

  • weex -> com.taobao.android:weex_sdk:0.20.0.2
dependencies {
    ...
    compile "com.didiglobal.chameleon:cmlweex:$VERSION"
}

com.android.tools.build:gradle 3.0 以后的版本用 implementation 替换 compile,完整的依赖列表可参考示例工程。

2. 权限添加及 android 6.0 以上系统授权

Chameleon SDK 已经添加了如下权限,android 6.0 以上系统版本需要在调起相关页面后手动授权。

    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />

3. 混淆

参考示例工程

4. 初始化入口

实现自己的 Application 类,在应用启动的时候进行初始化调用。

4.1 Application demo

public class MyApplication extends Application implements CmlConfig {
    @Override
    public void onCreate() {
        super.onCreate();

        CmlEngine.getInstance().init(this, this);
    }

    @Override
    public void configAdapter() {
        // 开发阶段可以禁用js bundle缓存
        CmlEnvironment.CML_ALLOW_BUNDLE_CACHE = false;
        // 开发阶段手动降级测试
//        CmlEnvironment.CML_DEGRADE = false;

        // 注册降级Adapter
        CmlEnvironment.setDegradeAdapter(new CmlDegradeDefault());
//        CmlEnvironment.setToastAdapter(xxx);
//        CmlEnvironment.setLoggerAdapter(xxx);
//        CmlEnvironment.setDialogAdapter(xxx);
//        CmlEnvironment.setNavigatorAdapter(xxx);
//        CmlEnvironment.setStatisticsAdapter(xxx);
//        CmlEnvironment.setImageLoaderAdapter(xxx);

    }

    @Override
    public void registerModule() {
        CmlEngine.getInstance().registerModule(ModuleDemo.class);
    }
}

4.2 将 Application 添加到 AndroidManifest.xml

<application
    android:name=".MyApplication"
    android:allowBackup="false"
    ...
</application>

4.3 适配器的实现

适配器是暴露给SDK使用者的一组接口,用于提供扩展SDK的能力,其中一部分接口提供了默认实现,未提供默认实现的需要使用者自己实现并注册到SDK中。

image

  • 以下适配器提供了默认实现 http / json / log / modal / storage / thread / websocket / imagloader

  • 以下适配器未提供默认实现 navigator / degrade / statistics

以降级适配器举例,只需要两个步骤:

  • 新建类 CmlDegradeDefault,实现接口 ICmlDegradeAdapter
  • 在 MyApplication 的 configAdapter 方法里注册适配器。

4.4 module 的实现

module 的基本概念可参看这里, SDK层实现在如下位置:

image

module 的实现主要分两个步骤,一个是 native 侧的代码实现,一个是 js 侧的代码实现。同时,native 和 js 的通信是双向的,及native 可以主动调用 js 侧的方法,js 侧也可以主动调用 native 侧的方法。

image

4.4.1 native 侧的实现

以下内容请在 Chameleon SDK demo 运行起来的前提下阅读,方便理解即将描述的内容。

实现一个module扩展需要如下几个步骤:

  • 根据需求和前端RD确定module/method/args参数
  • native RD根据约定实现module扩展,前端RD根据约定实现js 并打包成jsbundle
  • native RD可以将jsbundle放到assets目录下加载调试,也可以远程加载调试

demo实现了双向通信,js 调用 native接口约定如下 (module的概念):

  • module名是 moduleDemo
  • method名是 sayHello
  • args名是 {"content":"测试"}

实现的效果是点击jsbundle里的按钮,会弹 测试 toast

native 调用 js接口约定如下:

  • module名是 moduleDemo
  • method名是 NaTellJS
  • args名是 {"content":"测试"}

实现的效果是点击 native 侧的按钮,会动态改变 jsbundle里的文字显示。

module 的实现需要先了解3个注解

  • @CmlModule 标注这个类是扩展模块
  • @CmlMethod 标注可供JS侧调用的方法
  • @CmlParam 标注调用的参数

以下是根据约定实现的 module 扩展示例

@CmlModule(alias = "moduleDemo")
public class ModuleDemo {
    @CmlMethod(alias = "sayHello")
    public void sayHello(ICmlActivityInstance instance, @CmlParam(name = "content") String content) {
        Toast.makeText(instance.getContext(), content, Toast.LENGTH_SHORT);
    }
}

将 module 注册到SDK

public class MyApplication extends Application implements CmlConfig {
    @Override
    public void onCreate() {
        super.onCreate();

        CmlEngine.getInstance().init(this, this);
        CmlEngine.getInstance().registerModule(ModuleDemo.class); // 在这里注册
    }
    ...
}

从前端RD拿到 JSBundle, 进行渲染,重点关注demo工程里CmlViewActivity

private static final String URL_JS_BUNDLE_OK = "https://www.example.com/degradle.html?cml_addr=http://172.22.138.92:8000/weex/cml-demo-say.js";

@Override
protected void onCreate(Bundle savedInstanceState) {
    ....
    // cmlView.render(URL_JS_BUNDLE_OK, null); // 加载远程jsbundle
    cmlView.render("file://local/cml-demo-say.js", null); // 加载assets目录里的jsbundle
    ...
}

js侧的实现以及 jsbundle 打包参看接下来的 4.4.2 小结。

4.4.2 js 侧的实现

同样以上面要实现的module和方法为例,我们来看一下js侧的实现。

参考根目录 assets 目录下的 cml-demo-say.zip

1.初始化前端项目(也可以使用已有的项目)

cml init project
请输入项目名称 cml-demo-say

2.打开项目下 src/pages/index/index.cml文件,粘贴以下代码。以下代码主要是展示了js和native双向的通信的方法实现。先粘贴,然后我们在下面介绍通信封装的原理。

<template>
  <page title="chameleon">
    <scroller height="{{winHeight}}">
      <view class="scroller-wrap">
        <view style="padding: 20cpx;">
          <text>1,JS调用Native</text>
          <text>callback返回内容: {{callbackRes}}</text>
          <button
            c-bind:onclick="sayHello"
            text="JS调用Native sayHello方法"
            style="margin-top: 20cpx;"
          ></button>
        </view>
        <view style="padding: 20cpx;">
          <text>2,Native调用JS 的NaTellJS方法已经注册监听,点击Native的改变文字按钮,下发状态文字将改变</text>
          <text>状态:{{status}}</text>
        </view>
      </view>
    </scroller>
  </page>
</template>

<script>
import cml from "chameleon-api";
import cmlBridge from "chameleon-bridge";

class Index {
  data = {
    title: "chameleon",
    callbackRes: '',
    status: '等待Native调用',
    winHeight: 0
  }
  methods = {
    // 此处的方法实现你可以封装到其他目录,作为统一扩展的api
    sayHello() {
      cmlBridge.callNative(
        'moduleDemo', // 模块名
        'sayHello', // 方法名
        { content: 'Hello Chameleon!' }, // 参数
        res => {
          this.callbackRes = res;
        } // 回调方法
      );
    }
  }
  mounted() {
    // 主动监听客户端调用js
    cmlBridge.listenNative(
      'moduleDemo', // 模块名
      'NaTellJS', // 方法名
      res => {
        this.status = res.content;
      }
    );
    cml.getSystemInfo().then((info) => {
      this.winHeight = Number(info.viewportHeight)
    });
  }
}
export default new Index();
</script>

<style scoped>
.scroller-wrap {
  display: flex;
  flex-direction: column;
  align-items: center;
}
</style>
<script cml-type="json">
{
  "base": {
    "usingComponents": {
    }
  },
  "wx": {
    "navigationBarTitleText": "index",
    "backgroundTextStyle": "dark",
    "backgroundColor": "#E2E2E2"
  }
}
</script>

3.你可以运行cml weex dev或者cml weex build命令,将jsbundle文件的在线地址或本地文件给到Native同学,按照上面Native部分提到的集成方式(本地或远程地址)进行联调。点击第一项的按钮你可以看到,客户端弹出了"Hello Chameleon!"的弹框。同时在callback返回内容:后返回了内容。点击Native端的“改变文字”按钮,在页面上的“状态:”后显示了客户端发来的“测试”字样。

4.接下来我们看一下原理:

我们通过chameleon-bridge提供的callNative和listenNative来与端通信,他们的参数及意义如下:

  • callNative(module:String, method:String, args:Object, callback:Function) JS主动调用Native方法
  • listenNative(module:String, method:String, callback:Function) 监听Native调用js
JS主动调用Native方法

首先看methods里我们通过chameleon-bridge提供的callNative方法实现了sayHello方法,让js与native主动通信。

sayHello() {
    cmlBridge.callNative(
        'moduleDemo', // 模块名
        'sayHello', // 方法名
        { content: 'Hello Chameleon!' }, // 参数
        res => {
            this.callbackRes = res;
        } // 回调方法
    );
}

这样就调用到了native的模块名为moduleDemo的模块的sayHello方法,同时native会回调我们。当然你还可以封装到其他目录,作为统一扩展的api来存放并引入到项目文件中使用。

监听Native调用js

mounted里我们通过chameleon-bridge提供的listenNative方法在页面初始化时监听了客户端要调用我们的模块名为moduleDemo的NaTellJS方法。注意,这个模块在前端其实可以理解为一个和Native同学约定的方法命名集合。调用前端chameleon-bridge库的listenNative方法会进行监听的注册,便可以被客户端调用到。

cmlBridge.listenNative(
    'moduleDemo', // 模块名
    'NaTellJS', // 方法名
    res => {
        this.status = res.content;
    }
);

同样你可以将此方法封装到其他api集合位置,进行引入使用,如:

export function onNaTellJS(callback) {
    cmlBridge.listenNative(
        'moduleDemo', // 模块名
        'NaTellJS', // 方法名
        callback
    );
}

如此一来,你便可以封装自己的扩展api了。

4.5 js bundle 缓存的禁用

开发截断为了方便实时预览效果,可以关闭 js bundle 的缓存。

@Override
public void configAdapter() {
    // 开发阶段可以禁用js bundle缓存
    CmlEnvironment.CML_ALLOW_BUNDLE_CACHE = false;

    ...

}

5. 页面调起

5.1 整个页面使用 Chameleon 容器实现

CmlEngine.getInstance().launchPage(activity, url, options);

// 即将支持
CmlEngine.getInstance().launchPage(activity, url, options, requestCode, launchCallback);

5.2 使用CmlView

参考根目录 app 目录下demo

CmlView 用在和原生 Native View 混合布局的场景,

    private CmlView cmlView;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_test_cml_view);
        FrameLayout flRoot = findViewById(R.id.fl_root);
        cmlView = new CmlView(this);
        flRoot.addView(cmlView, new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));
        cmlView.onCreate();
        cmlView.render(MainActivity.TEST_URL, null);
    }

    @Override
    protected void onResume() {
        super.onResume();
        if (cmlView != null) {
            cmlView.onResume();
        }
    }

    @Override
    protected void onPause() {
        super.onPause();
        if (cmlView != null) {
            cmlView.onPause();
        }
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        if (cmlView != null) {
            cmlView.onDestroy();
        }
    }

5.3 打开普通URL

如果打开的是普通的URL,则会自动使用 CmlWebEngine 调起 Web Container,渲染 H5 页面

    // 演示打开一般的URL
    private static final String URL_NORMAL = "https://www.didiglobal.com";
    ...

    @Override
    public void onClick(View view) {
        switch (view.getId()) {
            case R.id.txt_open_url:
                CmlEngine.getInstance().launchPage(this, URL_NORMAL, null);
                break;
            ...
        }
    }

5.4 打开 JS Bundle

如果打开的是JS Bundle URL,则会自动使用 native 渲染引擎调起 native Container,渲染 JS Bundle

    // 这是一个可以正常打开的 JS_BUNDLE
    private static final String URL_JS_BUNDLE_OK = "https://beatles-chameleon.github.io/chameleon-ui-builtin/dist/web/chameleon-ui-builtin.html?cml_addr=https%3A%2F%2Fbeatles-chameleon.github.io%2Fchameleon-ui-builtin%2Fdist%2Fweex%2Fchameleon-ui-builtin.js#/";
    ...

    @Override
    public void onClick(View view) {
        switch (view.getId()) {
            ...
            case R.id.txt_open_js_bundle:
                CmlEngine.getInstance().launchPage(this, URL_JS_BUNDLE_OK, null);
                break;
            ...
        }
    }

5.5 预加载

如果打开的是一个已经预加载过的 JS Bundle URL,则会忽略下载过程,直接使用 native 渲染引擎渲染界面

    // 这是一个测试预加载的 JS_BUNDLE
    private static final String URL_JS_BUNDLE_PRELOAD = "https://beatles-chameleon.github.io/chameleon-ui-builtin/dist/web/chameleon-ui-builtin.html?cml_addr=https%3A%2F%2Fbeatles-chameleon.github.io%2Fchameleon-ui-builtin%2Fdist%2Fweex%2Fchameleon-ui-builtin.js#/";
    ...

    @Override
    public void onClick(View view) {
        switch (view.getId()) {
            ...
            case R.id.txt_preload:
                CmlEngine.getInstance().launchPage(this, URL_JS_BUNDLE_PRELOAD, null);
                break;
            ...
        }
    }

5.6 自动降级

如果打开的是一个错误的JS Bundle URL,则会自动降级,使用 CmlWebEngine 调起 Web Container,渲染前面 H5 地址页面,具体可以查看

  • 工程化 -> Chameleon URL 一节关于,Chameleon URL 的定义
  • Native渲染能力接入 -> 自动降级 一节,关于自动降级的详细说明
    // 这是一个错误的 JS_BUNDLE
    private static final String URL_JS_BUNDLE_ERR = "https://www.didiglobal.com?cml_addr=xxx.js";
    ...

    @Override
    public void onClick(View view) {
        switch (view.getId()) {
            ...
            case R.id.txt_degrade:
                CmlEngine.getInstance().launchPage(this, URL_JS_BUNDLE_ERR, null);
                break;
        }
    }

6. 预加载

如果某些 js bundle 不需要实时下载下来渲染,可以先配置到预加载列表里提前下载下来,提升用户交互体验。

6.1 预加载列表的配置

组装 CmlBundle 列表,并通过 CmlEngine 接口设置到SDK里,具体可以参考 demo。

   private List<CmlBundle> getPreloadList() {
        CmlJsBundleEnvironment.DEBUG = true;
        List<CmlBundle> cmlModels = new ArrayList<>();
        CmlBundle model = new CmlBundle();
        model.bundle = Util.parseCmlUrl(URL_JS_BUNDLE_PRELOAD);
        model.priority = 2;
        cmlModels.add(model);
        return cmlModels;
    }

    ...

    CmlEngine.getInstance().initPreloadList(getPreloadList());

6.2 开始预加载列表

根据使用方的业务,在适当位置执行预加载

CmlEngine.getInstance().performPreload();

results matching ""

    No results matching ""