Weex 提供了扩展机制,可以根据自己的业务进行定制自己的功能。 主要分为两类扩展:

  • Module 扩展 非 UI 的特定功能。例如 sendHttp、openURL 等。
  • Component 扩展 实现特别功能的 Native 控件。例如:RichTextview,RefreshListview 等。
  • Adapter 扩展 Weex 对一些基础功能实现了统一的接口,可实现这些接口来定制自己的业务。例如:图片下载等。
  • JS全局变量自定义扩展

JSEnv 扩展

接口

  1. Map<String, Object> options = new HashMap();
  2. options.set("testVlaue","hello");
  3. //....
  4. instance.render(pagename, template,options);

使用

  1. var value = weex.config.testValue;
  2. console.log(value);

Module 扩展

  1. Module 扩展必须继承 WXModule 类。
  2. 扩展方法必须加上@JSMethod (uiThread = false or true) 注解。Weex 会根据注解来判断当前方法是否要运行在 UI 线程,和当前方法是否是扩展方法。
  3. Weex是根据反射来进行调用 Module 扩展方法,所以Module中的扩展方法必须是 public 类型。
  4. 同样因为是通过反射调用,Module 不能被混淆。请在混淆文件中添加代码:-keep public class * extends com.taobao.weex.common.WXModule{*;}
  5. Module 扩展的方法可以使用 int, double, float, String, Map, List 类型的参数
  6. 完成 Module 后一定要在初始化时注册 WXSDKEngine.registerModule("myModule", MyModule.class); 否则会报类似错误:ReportException :undefined:9: TypeError: Object #<Object> has no method 'printLog'

示例如下:

  1. public class MyModule extends WXModule {
  2. //run ui thread
  3. @JSMethod (uiThread = true)
  4. public void printLog(String msg) {
  5. Toast.makeText(mWXSDKInstance.getContext(),msg,Toast.LENGTH_SHORT).show();
  6. }
  7. //run JS thread
  8. @JSMethod (uiThread = false)
  9. public void fireEventSyncCall(){
  10. //implement your module logic here
  11. }
  12. }

Register the module

  1. WXSDKEngine.registerModule("MyModule", MyModule.class);

JS 调用如下:

  1. <template>
  2. <div>
  3. <text onclick="click">testMyModule</text>
  4. </div>
  5. </template>
  6. <script>
  7. module.exports = {
  8. methods: {
  9. click: function() {
  10. weex.requireModule('MyModule').printLog("I am a weex Module");
  11. }
  12. }
  13. }
  14. </script>

Module 注册

registerModule(moduleName,moduleClass)

  • return(bool): 是否注册成功
  • moduleName(String): 模块名称
  • moduleClass(Class): 模块对应的class,创建module实例时使用

使用方式:

  1. WXSDKEngine.registerModule("picker", WXPickersModule.class);

Component 扩展

wee x版本 >= 0.19.0

变更说明

WXDomObject 和 Layout 引擎被下沉到 WeexCore 中使用 C++ 实现,移除 Java 代码中的 WXDomObject。此次变更涉及 WXComponent 和 WXDomObject 的适配。

迁移指南

setMeasureFunction 迁移

WXDomObject 中的 setMeasureFunction() 方法迁移至 WXComponent 中:

  1. protected void setMeasureFunction(final ContentBoxMeasurement contentBoxMeasurement);

详见:com.taobao.weex.layout.ContentBoxMeasurement.java

ContentBoxMeasurement 示例请参考:WXText.java / setMeasureFunction() 注意:ContentBoxMeasurement 只支持叶子节点。

WXComponent 接口变更
getDomObject [移除]

由于 WXDomObject 下沉至 WeexCore 中,所以 getDomObject() 方法已被删除。

构造方法 [参数变更]

WXComponent 的构造方法删除了类型为 WXDomObject 的参数,新增了类型为 BasicComponentData 的参数,其余参数保持不变:

  1. public WXComponent(WXSDKInstance instance, WXVContainer parent, int type, BasicComponentData basicComponentData);
  2. public WXComponent(WXSDKInstance instance, WXVContainer parent, BasicComponentData basicComponentData);
WXDomObject 接口变更

你无法在Java代码中访问和继承 WXDomObject,( ImmutableDomObject 接口也已被删除)

WXDomObject 的部分方法被迁移至 WXComponent中,如需使用,如下:

WXDomObject.getType() -> WXComponent.getComponentType() [迁移]

WXDomObject 中 的 getType() 方法用于获取组件类型(如:list、div、text、img…),迁移到 WXComponent 后,更名为:

  1. public String getComponentType();
获取 Layout 结果的相关方法 [迁移]

获取 Layout 结果的6个方法从 WXDomObject 迁移至 WXComponent:

  1. public float getCSSLayoutTop();
  2. public float getCSSLayoutBottom();
  3. public float getCSSLayoutLeft();
  4. public float getCSSLayoutRight();
  5. public float getLayoutWidth();
  6. public float getLayoutHeight();

移除两个废弃接口:

  1. public float getLayoutY();
  2. public float getLayoutX();

weex_sdk 版本 < 0.19.0

  1. Component 扩展类必须继承 WXComponent.
  2. Component 对应的设置属性的方法必须添加注解 @WXComponentProp(name=value(value is attr or style of dsl))
  3. Weex sdk 通过反射调用对应的方法,所以 Component 对应的属性方法必须是 public,并且不能被混淆。请在混淆文件中添加代码 -keep public class * extends com.taobao.weex.ui.component.WXComponent{*;}
  4. Component 扩展的方法可以使用 int, double, float, String, Map, List 类型的参数
  5. 完成 Component 后一定要在初始化时注册 WXSDKEngine.registerComponent("richText", RichText.class);

示例如下:

  1. public class RichText extends WXComponent<TextView> {
  2. public RichText(WXSDKInstance instance, WXDomObject dom, WXVContainer parent) {
  3. super(instance, dom, parent);
  4. }
  5. @Override
  6. protected TextView initComponentHostView(@NonNull Context context) {
  7. TextView textView = new TextView(context);
  8. textView.setTextSize(20);
  9. textView.setTextColor(Color.BLACK);
  10. return textView;
  11. }
  12. @WXComponentProp(name = "tel")
  13. public void setTel(String telNumber) {
  14. getHostView().setText("tel: " + telNumber);
  15. }
  16. }

注册你的组件:

  1. WXSDKEngine.registerComponent("richText", RichText.class);

JS 调用如下:

  1. <template>
  2. <div>
  3. <richText tel="12305" style="width:200;height:100">12305</richText>
  4. </div>
  5. </template>

组件方法支持

从WeexSDK 0.9.5开始,你可以定义组件方法

  • 在组件中如下声明一个组件方法

    1. @JSMethod
    2. public void focus(){
    3. //method implementation
    4. }
  • 注册组之后,你可以在weex 文件中调用

    1. <template>
    2. <mycomponent ref='mycomponent'></mycomponent>
    3. </template>
    4. <script>
    5. module.exports = {
    6. created: function() {
    7. this.$refs.mycomponent.focus();
    8. }
    9. }
    10. </script>

注:工程要添加依赖 compile 'com.squareup.picasso:picasso:2.5.2'

Component 注册

registerComponent(type,class,appendTree)

  • return(bool): 是否注册成功
  • type(String): 前端使用的对应标签
  • class(Class): 组件的class,在创建组件实例时调用
  • appendTree(bool): 渲染时判定逻辑,默认false
    • 如果为true,则这个组件的子组件,整颗树建立、layout完后,整体一起刷新。
    • 如果为false,则这个组件的子组件,每add一个,刷新一个。

使用方式:

  1. WXSDKEngine.registerComponent("video", WXVideo.class, false);

registerComponent(holder,appendTree,…names)

  • return(bool): 是否注册成功
  • holder(IFComponentHolder): 用于创建component的抽象工厂,默认使用SimpleComponentHolder
  • appendTree: 同上
  • names(String …): 前端使用的对应标签

使用方式:

  1. WXSDKEngine.registerComponent(
  2. new SimpleComponentHolder(
  3. WXText.class,
  4. new WXText.Creator()
  5. ),
  6. false,
  7. "text"
  8. );

Adapter 扩展

图片库Adapter

需要时集成接口 IWXImgLoaderAdapter,实现 setImage 方法。

示例如下:

  1. public class ImageAdapter implements IWXImgLoaderAdapter {
  2. public ImageAdapter() {
  3. }
  4. @Override
  5. public void setImage(final String url, final ImageView view,
  6. WXImageQuality quality, WXImageStrategy strategy) {
  7. WXSDKManager.getInstance().postOnUiThread(new Runnable() {
  8. @Override
  9. public void run() {
  10. if(view==null||view.getLayoutParams()==null){
  11. return;
  12. }
  13. if (TextUtils.isEmpty(url)) {
  14. view.setImageBitmap(null);
  15. return;
  16. }
  17. String temp = url;
  18. if (url.startsWith("//")) {
  19. temp = "http:" + url;
  20. }
  21. if (view.getLayoutParams().width <= 0 || view.getLayoutParams().height <= 0) {
  22. return;
  23. }
  24. Picasso.with(WXEnvironment.getApplication())
  25. .load(temp)
  26. .into(view);
  27. }
  28. },0);
  29. }
  30. }

Adapter 注册

ImageAdapter

WEEX和图片库完全解耦,WEEX的图片加载,都是通过调用公共接口,由实现类决定调用哪个图片库

  • IWXImgLoaderAdapter: 根据url,load图片给某个view
  • IDrawableLoader(可选): 根据url,load图片给某个drawable.

IWXImgLoaderAdapter

  1. public interface IWXImgLoaderAdapter {
  2. void setImage(String url, ImageView view, WXImageQuality quality, WXImageStrategy strategy);
  3. }
  • WXImageQuality 图片质量的设置参数,有 LOW, NORMAL, HIGH, ORIGINAL 几种质量,默认为LOW.
  • WXImageStrategy 是一个扩展类参数,配置图像是否可以剪切isClipping、锐化isSharpen以及配置占位符placeHolder

IDrawableLoader(可选)

  1. interface DrawableTarget {
  2. }
  3. interface StaticTarget extends DrawableTarget{
  4. void setDrawable(@Nullable Drawable drawable, boolean resetBounds);
  5. }
  6. interface AnimatedTarget extends DrawableTarget{
  7. void setAnimatedDrawable(@Nullable Drawable drawable);
  8. }
  9. void setDrawable(String url, DrawableTarget drawableTarget, DrawableStrategy drawableStrategy);
  10. }

IWXHttpAdapter

ImageAdapter,WEEX和网络库也是解耦的,通过接口形式调用,由实现类决定调用哪个网络库。

  1. public interface IWXHttpAdapter {
  2. void sendRequest(WXRequest request, OnHttpListener listener);
  3. }

WXRequest

  • paramMap(Map): http自定义请求参数,比如(?a=1&b=2);
  • url(String): http请求的目标url
  • method(String): http请求方法 “post”,”get”
  • body(String): http请求body
  • timeoutMs(int): 请求超时时间,默认是3s
  • instanceId(String): (页面)id

OnHttpListener

  1. interface OnHttpListener {
  2. /**
  3. * 开始请求
  4. */
  5. void onHttpStart();
  6. /**
  7. * 收到http header内容
  8. */
  9. void onHeadersReceived(int statusCode,Map<String,List<String>> headers);
  10. /**
  11. *
  12. * @param 上传进度
  13. */
  14. void onHttpUploadProgress(int uploadProgress);
  15. /**
  16. *
  17. * @param loadedLength 接收到的数据长度
  18. */
  19. void onHttpResponseProgress(int loadedLength);
  20. /**
  21. * 请求结束
  22. * @param response 返回的response
  23. */
  24. void onHttpFinish(WXResponse response);
  25. }

IWXUserTrackAdapter(可选)

打点相关,如果关注weex的打点,需要实现这个adapter

  • 基础信息:sdk版本、jsbundle大小…
  • 性能信息:sdk初始化时间、页面加载可交互时间、加载bundle时间…
  1. public interface IWXUserTrackAdapter {
  2. void commit(Context context, String eventId, String type, WXPerformance perf, Map<String, Serializable> params);
  3. }

IActivityNavBarSetter

WXNavigatorModule的实现依赖这个接口,用来操作navigation.

使用方式:

  1. WXSDKEngine.setActivityNavBarSetter(new IActivityNavBarSetter(){});

IWXStorageAdapter

WXStorageModule实现依赖这个接口,用来实现数据的存、取默认使用DefaultWXStorage实现

IWXJSExceptionAdapter

WEEX的异常上报接口,包括

  • 下载异常
  • 白屏异常
  • js异常
  • 降级异常
  1. public interface IWXJSExceptionAdapter {
  2. void onJSException(WXJSExceptionInfo exception);
  3. }

使用方式:

  1. WXSDKEngine.setJSExcetptionAdapter(new TestExceptionAdapter());

SDK混淆规则

若要在APP中使用混淆,请在相应的配置文件中添加如下规则:

  1. -keep class com.taobao.weex.WXDebugTool{*;}
  2. -keep class com.taobao.weex.devtools.common.LogUtil{*;}
  3. -keepclassmembers class ** {
  4. @com.taobao.weex.ui.component.WXComponentProp public *;
  5. }
  6. -keep class com.taobao.weex.bridge.**{*;}
  7. -keep class com.taobao.weex.dom.**{*;}
  8. -keep class com.taobao.weex.adapter.**{*;}
  9. -keep class com.taobao.weex.common.**{*;}
  10. -keep class * implements com.taobao.weex.IWXObject{*;}
  11. -keep class com.taobao.weex.ui.**{*;}
  12. -keep class com.taobao.weex.ui.component.**{*;}
  13. -keep class com.taobao.weex.utils.**{
  14. public <fields>;
  15. public <methods>;
  16. }
  17. -keep class com.taobao.weex.view.**{*;}
  18. -keep class com.taobao.weex.module.**{*;}
  19. -keep public class * extends com.taobao.weex.common.WXModule{*;}
  20. -keep public class * extends com.taobao.weex.ui.component.WXComponent{*;}
  21. -keep class * implements com.taobao.weex.ui.IExternalComponentGetter{*;}