Module 的使用

　　github地址点这里

　　根目录 assets 目录下的 cml-demo-say.zip 是个简单的示例工程，用来演示native 和 weex容器或web容器的双向通信

1. 什么是 module

module 是 Native 提供给前端页面调用的，完成一组操作的方法集合，用于扩展 Native 的能力。在 Chameleon 页面中，开发者引入相关js库后即可调用 module 中的方法。

  1. import bridge from 'chameleon-bridge';
  3. // 主动调用客户端方法
  4. export function sayHello() {
  5.     bridge.callNative(
  6.         'moduleDemo', // 模块名
  7.         'sayHello', // 方法名
  8.         {}, // 参数
  9.         res => {} // 回调方法
  10.     );
  11. }

2. Module 的使用

Module 的使用分两种情况，一种是使用 Chameleon SDK 内置的Module，一种是用户自定义实现自己的 Module。

2.1 使用内置的 Module

内置的 Module 在js 前端代码里直接使用即可，目前内置的 Module 有：

  • clipboard
  • cml
  • modal
  • storage
  • stream
  • webSocket
    Chameleon DOC 《API一章》 里描述的能力，部分实现就是由上述 module 支撑的。

2.2 自定义实现自己的 Module

示例可参看《手把手第4.4小节说明》

module 扩展3个重要的注解

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

  • @CmlParam 标注调用的参数
    详细说明

  • 功能：通过注册module提供原生能力的扩展

  • 原理：依赖bridge进行协议通信，根据不同module进行协议处理分发
  • module，扩展原生能力
    • module注册
      • 必须注册CmlEngine.registerModule(Class moduleClass)
      • 不强制要求添加@CmlModule,未添加时会使用默认设置
      • 不建议在运行中动态注册module
    • module名称
      • 默认使用module的类名
      • 配置module名称，添加注解@CmlModule(alias = "name")
    • module实例
      • 默认为实例全局唯一，即无论有多少instance都会使用同一个module实例
      • 配置全局性，添加注解@CmlModule(global = false)
    • module组合
      • 针对极特殊情况，允许多个class共用一个module名称
      • 必须有且只有一个class作为module，所有相关class均会使用该moduel配置
      • 其余class必须使用@CmlJoin(name = "name")，指定需要关联的moduel名称
      • 每个class实例之间无关联，仅会在使用时再创建实例
  • method，提供原生能力方法
    • method注册
      • 自动注册module类中所有的public方法
      • 不强制要求添加@CmlMethod,未添加时会使用默认设置
      • 如果不希望方法被误添加，需要在方法上添加@CmlIgnore
    • method名称
      • 默认使用method方法名
      • 配置method名称，添加注解@CmlMethod(alias = "name")
    • method线程
      • 默认运行在主线程
      • 配置method线程，添加注解@CmlMethod(uiThread = false)
  • param，原生能力方法所需要的参数
    • param类型
      • 针对Context、ICmlInstance等上下文类型，会根据调用环境进行查找替换
      • 对于CmlCallback的类型，会构建对应的回调，需要自行处理回调
      • 其余类型会根据bridge传递的参数进行处理
    • param参数
      • 根据birdge传递的数据，根据参数类型进行转化
      • 目前可转化的类型为JSONObject、String
      • 如果要直接转为对象，需要设置CmlJsonAdapter或接入相应json库
    • param字段
      • 只想获取传递数据中的某一个对象时，可以使用@CmlParam
      • 添加@CmlParam(name = "name")，设置该参数获取的字段
      • 添加@CmlParam(admin = "admin")，设置该参数默认值