Android APIs

Weex 初步接入请参考:https://github.com/weexteam/article/issues/25

WXSDKEngine 是 Weex 对外的总入口。

主要提供了一下功能:

  1. 设置相关 Adapter 和获取 adapter。
  2. 注册自定义 module 和 component
  3. 重置 JSFramework

Adapter 介绍

Weex 为了重用 Native 通用库提供了对应的接口进行设置。

  1. IWXImgLoaderAdapter 图片适配器。

    Weex 会把需要设置图片的 View 和 URL 透露出来,Native 端需要实现这个接口进行图片下载。 Weex 没有提供图片默认实现。

    接口定义如下:

    1. publicinterfaceIWXImgLoaderAdapter{
    2. void setImage(String url,ImageView view,WXImageQuality quality,WXImageStrategy strategy);
    3. }

    WXImageQuality 表示图片的质量,WXImageQuality 取如下值 LOW, NORMAL, HIGH, ORIGINAL 图片质量依次变高。默认为 LOWWXImageStrategy 为扩展类,表示了图片是否可以裁剪 (isClipping) 锐化 (isSharpen) 占位符 (placeHolder) 等。

  2. IWXHttpAdapter 网络下载适配器。

    Weex 自定义了 WXRequestOnHttpListener,Native 重载接口后可以从 Request 中获取URL,Header 等参数,网络请求完成后可以通过 OnHttpListener 进行回调通知。Weex 提供了默认网络请求:DefaultWXHttpAdapter, 使用的是 HttpURLConnection 进行网络请求。

    接口定义如下:

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

    WXRequest 定义了网络请求相关的参数,请求方法,请求主体,超时时间。Weex默认超时时间是3000.

    OnHttpListener 定义了网络请求结束后对应方法。定义如下:

    1. interfaceOnHttpListener{
    2. /**
    3. * start request
    4. */
    5. void onHttpStart();
    6. /**
    7. * headers received
    8. */
    9. void onHeadersReceived(int statusCode,Map<String,List<String>> headers);
    10. /**
    11. * post progress
    12. * @param uploadProgress
    13. */
    14. void onHttpUploadProgress(int uploadProgress);
    15. /**
    16. * response loaded length (bytes), full length should read from headers (content-length)
    17. * @param loadedLength
    18. */
    19. void onHttpResponseProgress(int loadedLength);
    20. /**
    21. * http response finish
    22. * @param response
    23. */
    24. void onHttpFinish(WXResponse response);
    25. }
  3. IWXUserTrackAdapter Weex 相关性能数据 (首屏加载时间、JS-Native 通信时间、dom 更新时间等) 和其他通用信息 (JSLib 文件大小, Weex SDK 版本号等)。

    接口定义:

    1. publicinterfaceIWXUserTrackAdapter{
    2. void commit(Context context,String eventId,String type,WXPerformance perf,Map<String,Serializable> params);
    3. }

    Native 实现接口后可以通过 WXPerformanceparams 获取对应的信息。
    WXPerformane 对应字段表示含义请参考文档:https://github.com/weexteam/article/issues/124

    后续随着开发 Weex 还会定义更多的 Adapter,此文档也会定时更新。

Native 和 JS 通信

  1. 自定义事件通知

    多用于某个自定义控件进行事件通知,例如自定义点击事件,响应下拉事件等。

    WXSDKInstance.java

    1. publicvoid fireEvent(String elementRef,finalString type,finalMap<String,Object> data,finalMap<String,Object> domChanges){}
    2. publicvoid fireEvent(String elementRef,finalString type,finalMap<String,Object> data){
    3. fireEvent(elementRef,type,data,null);
    4. }
    5. publicvoid fireEvent(String elementRef,String type){
    6. fireEvent(ref,type,newHashMap<String,Object>());
    7. }

    elementRef:事件发生的控件 ID。

    type: 自定义事件,Weex 默认以 onXxxxx 开头为自定义事件。onPullDown (下拉事件)。

    data: 需要透出的参数,例如当前控件的大小,坐标等其他信息。

    domChanges:更新 ref 对应控件的 Attribute 和 Style。

  2. 事件回调

    多用于 Module 回调,例如定位 Module 完成后需要通知 JS。使用方法如下:

    1. publicclassWXLocationextendsWXModule{
    2. @JSMethod
    3. publicvoid getLocation(JSCallback callback){
    4. //获取定位代码.....
    5. Map<String,String> data=newHashMap<>();
    6. data.put("x","x");
    7. data.put("y","y");
    8. //通知一次
    9. callback.invoke(data);
    10. //持续通知
    11. callback.invokeAndKeepAlive(data);
    12. //invoke方法和invokeAndKeepAlive两个方法二选一
    13. }
    14. }

注册滑动事件

Weex 获取滑动事件可以通过 WXSDKInstance 注册 registerOnWXScrollListener 监听

接口定义如下:

  1. publicinterfaceOnWXScrollListener{
  2. /**
  3. * The view is not currently scrolling.
  4. */
  5. int IDLE =RecyclerView.SCROLL_STATE_IDLE;
  6. /**
  7. * The view is currently being dragged by outside input such as user touch input.
  8. */
  9. int DRAGGING =RecyclerView.SCROLL_STATE_DRAGGING;
  10. /**
  11. * The view is currently animating to a final position while not under
  12. * outside control.
  13. */
  14. int SETTLING =RecyclerView.SCROLL_STATE_SETTLING;
  15. /**
  16. * Callback method to be invoked when the view has been scrolled. This will be
  17. * called after the scroll has completed.
  18. * <p>
  19. * This callback will also be called if visible item range changes after a layout
  20. * calculation. In that case, dx and dy will be 0.
  21. *
  22. */
  23. void onScrolled(View view,int x,int y);
  24. /**
  25. * Callback method to be invoked when view's scroll state changes.
  26. *
  27. */
  28. void onScrollStateChanged(View view,int x,int y,int newState);
  29. }

自定义NavBar

Weex 提供了 WXNavigatorModule 进行导航控制,对应的方法可以通过设置 IActivityNavBarSetter 接口进行定制。

使用方法:

  1. WXSDKEngine.setActivityNavBarSetter(newIActivityNavBarSetter(){
  2. });

其他介绍

动态适配容器

因为 Android 手机的碎片化导致屏幕适配很困难。Weex 对外提供的接口 render 需要动态传入容器的宽高,但是传入的宽高有时会发生变化,例如 ActionBar 隐藏等,这是传入的 Weex 容器也要进行对应的变化。
为了适应这种变化,Weex 提供了接口 WXSDKInstance.setSize(int width, int height) 来改变容器的大小。

  1. /**
  2. *
  3. * @param width 容器宽度
  4. * @param height 容器高度
  5. */
  6. publicvoid setSize(int width,int height){};

降级使用

Weex 处于发展阶段会增加一些新的特性和功能,但是这些新的特性和功能都必须升级 SDK 才能实现,对于没有升级的应用应该怎么处理呢?可以使用降级功能。

所谓降级功能就是 Weex 无法运行的版本或者手机,可以用 Weex h5 来代替。

Native 端可以通过接口 IWXRenderListener 中的 onException 方法进行处理,如果是主动降级 errCode 是以“|”分割的字符。“|”前面的字符为1表示主动降级,Native 端可以跳转到对应的 H5 页面。或者用其他的方式提示用户当前环境不支持 Weex。