You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@weex.apache.org by ha...@apache.org on 2018/12/19 13:26:58 UTC
[incubator-weex-site] branch draft updated: update docs for
android-apis (#244)
This is an automated email from the ASF dual-hosted git repository.
hanks pushed a commit to branch draft
in repository https://gitbox.apache.org/repos/asf/incubator-weex-site.git
The following commit(s) were added to refs/heads/draft by this push:
new 626cb99 update docs for android-apis (#244)
626cb99 is described below
commit 626cb99af75cbac59d837492079f3c5b6b17cc60
Author: chen <lu...@users.noreply.github.com>
AuthorDate: Wed Dec 19 21:26:54 2018 +0800
update docs for android-apis (#244)
---
docs/docs/api/android-apis.md | 295 +++++++++++++++++++++------------------
docs/zh/docs/api/android-apis.md | 272 ++++++++++++++++++++++++++++++++++++
2 files changed, 430 insertions(+), 137 deletions(-)
diff --git a/docs/docs/api/android-apis.md b/docs/docs/api/android-apis.md
index 6ec6b37..2ec67b3 100644
--- a/docs/docs/api/android-apis.md
+++ b/docs/docs/api/android-apis.md
@@ -6,41 +6,75 @@ order: 2.2
version: 2.1
---
-# Android APIs
-## WXSDKEngine
-1. Register the module and component
-1. Set up various adapters
-
-### Module & Component
-#### Component
-One can register a component using the following function:
-
- public static boolean registerComponent(IFComponentHolder holder, boolean appendTree, String ... names)
-
-* holder is a abstract factory designed for create Component, and SimpleComponentHolder is the a simple way to achieve IFComponentHolder.
-* appendTree is an additional flag which is unused now.
-* names is the component's name in front end template file. A Android component could be mapped into multiple names.
-
-#### Module
-One can register a module using the following way:
-
- public static <T extends WXModule> boolean registerModule(String moduleName, Class<T> moduleClass,boolean global) throws WXException
-
-* moduleName is the name in front end template.
-* moduleClass is the Java class of the module, which provide a constructor with an empty parameter.
-* global is a flag, true for singleton in the whole app, false for creating an object for each WXSDKIntance.
-
-### Adapter
-#### ImageAdapter
+# WXSDKEngine
+
+1. Register component
+2. Register module
+3. Set up various adapters
+
+## Register component
+
+### __registerComponent(type,class,appendTree)__
+
+- `return`(_bool_): register success
+- `type`(_String_): component's name,such as `div`
+- `class`(_Class_): ComponentClass，called when init component
+- `appendTree`(_bool_): render option logic，default false
+ - if true，render compoent tree one-time
+ - if false，render component one by one
+
+usage:
+
+```
+WXSDKEngine.registerComponent("video", WXVideo.class, false);
+```
+
+### __registerComponent(holder,appendTree，...names)__
+
+- `return`(_bool_): register success
+- `holder`(_IFComponentHolder_): abstract factory designed for create Component, and __SimpleComponentHolder__ is the a simple way to achieve IFComponentHolder.
+- `appendTree`: see `registerComponent(type,class,appendTree)`
+- `names`(_String ..._): component's name in front end template file
+
+usage:
+
+```
+WXSDKEngine.registerComponent(
+ new SimpleComponentHolder(
+ WXText.class,
+ new WXText.Creator()
+ ),
+ false,
+ "text"
+ );
+```
+
+## Register module
+
+registerModule(moduleName,moduleClass)
+
+- `return`(_bool_): register success
+- `moduleName`(_String_): module name
+- `moduleClass`(_Class_): the Java class of the module, which provide a constructor with an empty parameter.
+
+使用方式:
+
+```
+WXSDKEngine.registerModule("picker", WXPickersModule.class);
+```
+
+## Set up various adapters
+
+### ImageAdapter
Image adapter is responsible for loading images according to URLs. There are two types of image adapter:
1. Loading a image to a view according to URL.
1. Loading a image to a specified object according to URL.
In order to use image component, one must implement the first adapter, while the second adapter is optional.
-##### IWXImgLoaderAdapter
+#### IWXImgLoaderAdapter
public interface IWXImgLoaderAdapter {
void setImage(String url, ImageView view, WXImageQuality quality, WXImageStrategy strategy);
@@ -49,111 +83,130 @@ In order to use image component, one must implement the first adapter, while the
* `WXImageQuality` that the quality of the picture variables, take the following values `LOW`, `NORMAL`, `HIGH`, `ORIGINAL` picture quality in turn higher. The default is `LOW`.
* `WXImageStrategy` is an extension class that indicates whether the image can be cut (isClipping) sharpening (isSharpen) placeholder (placeHolder) and so on.
-##### IDrawableLoaderAdapter
+#### IDrawableLoaderAdapter
This adapter is optional.
void setDrawable(String url, DrawableTarget drawableTarget, DrawableStrategy drawableStrategy);
* `DrawableTarget` is a object into where will load an image. `DrawableTarget` is one of `StaticTarget` or `AnimatedTarget`.
-#### IWXHttpAdapter
+### IWXHttpAdapter
Weex custom `WXRequest` and `OnHttpListener`, Native reload interface can be obtained from the Request URL, Header and other parameters, the network request can be completed through `OnHttpListener` callback notification. Weex provides the default network request: `DefaultWXHttpAdapter`, using `HttpURLConnection` for network requests.
The interface is defined as follows:
- public interface IWXHttpAdapter {
- void sendRequest(WXRequest request, OnHttpListener listener);
- }
-
-* `WXRequest` defines the parameters related to the network request, the request method, the request body, and the timeout time. Weex default timeout is 3000.
-
-* `OnHttpListener` defines the corresponding method after the network request ends. Defined as follows:
-
- interface OnHttpListener {
-
- /**
- * start request
- */
- void onHttpStart();
-
- /**
- * headers received
- */
- void onHeadersReceived(int statusCode,Map<String,List<String>> headers);
-
- /**
- * post progress
- * @param uploadProgress
- */
- void onHttpUploadProgress(int uploadProgress);
-
- /**
- * response loaded length (bytes), full length should read from headers (content-length)
- * @param loadedLength
- */
- void onHttpResponseProgress(int loadedLength);
-
- /**
- * http response finish
- * @param response
- */
- void onHttpFinish(WXResponse response);
- }
-
-#### IWXUserTrackAdapter
+```
+public interface IWXHttpAdapter {
+ void sendRequest(WXRequest request, OnHttpListener listener);
+}
+```
+
+#### WXRequest
+
+* `WXRequest` defines the parameters related to the network request, the request method, the request body, and the timeout time. Weex default timeout is 3s.
+
+#### OnHttpListener
+
+```
+ interface OnHttpListener {
+
+ /**
+ * start request
+ */
+ void onHttpStart();
+
+ /**
+ * headers received
+ */
+ void onHeadersReceived(int statusCode,Map<String,List<String>> headers);
+
+ /**
+ * post progress
+ * @param uploadProgress
+ */
+ void onHttpUploadProgress(int uploadProgress);
+
+ /**
+ * response loaded length (bytes), full length should read from headers (content-length)
+ * @param loadedLength
+ */
+ void onHttpResponseProgress(int loadedLength);
+
+ /**
+ * http response finish
+ * @param response
+ */
+ void onHttpFinish(WXResponse response);
+ }
+```
+
+### IWXUserTrackAdapter
Weex related performance data (first screen loading time, JS-Native communication time, dom update time, etc.) and other general information (JSLib file size, Weex SDK version number, etc.).
- public interface IWXUserTrackAdapter {
- void commit(Context context, String eventId, String type, WXPerformance perf, Map<String, Serializable> params);
- }
+```
+public interface IWXUserTrackAdapter {
+ void commit(Context context, String eventId, String type, WXPerformance perf, Map<String, Serializable> params);
+}
+```
Native implementation interface can be obtained through `WXPerformance` and `params` corresponding information.
-#### IActivityNavBarSetter
+### IActivityNavBarSetter
Weex provided the ability of navigation through `WXNavigatorModule` which relys on IActivityNavBarSetter.
Usage:
- WXSDKEngine.setActivityNavBarSetter(new IActivityNavBarSetter(){});
+```
+WXSDKEngine.setActivityNavBarSetter(new IActivityNavBarSetter(){});
+```
-#### IWXStorageAdapter
+### IWXStorageAdapter
Weex provided the ability of local storage through `WXStorageModule` which depends on IWXStorageAdapter. One can use `DefaultWXStorage` as the default implementation of IWXStorageAdapter.
-#### IWXJSExceptionAdapter
-IWXJSExceptionAdapter is used to handle JavaScript exception.
-
-## WXSDKInstace
-### Weex Native and JavaScript communication.
-
-#### Custom events
+### IWXJSExceptionAdapter
+IWXJSExceptionAdapter is used to handle weex exception.
+- DownLoadException
+- WhiteSceenException
+- JSException
+- DownGradeException
+
+```
+public interface IWXJSExceptionAdapter {
+ void onJSException(WXJSExceptionInfo exception);
+}
+```
+usage：
+
+```
+WXSDKEngine.setJSExcetptionAdapter(new TestExceptionAdapter());
+```
+
+# WXSDKInstace
+
+## Custom events
Used for a custom control for event notifications, such as custom click events, response drop events, and so on.
-`WXSDKInstance.java `
-
- public void fireEvent(String elementRef,final String type, final Map<String, Object> data,final Map<String, Object> domChanges){ }
-
- public void fireEvent(String elementRef,final String type, final Map<String, Object> data){
- fireEvent(elementRef,type,data,null);
- }
-
- public void fireEvent(String elementRef, String type){
- fireEvent(ref,type,new HashMap<String, Object>());
- }
+```
+void fireEvent(elementRef,type)
+void fireEvent(elementRef,type, data)
+void fireEvent(elementRef,type,data,domChanges)
+```
-* `elementRef`：The event occurred for the control ID。
+* `elementRef`(_String_): The event occurred for the control ID。
-* `type`: Custom events, Weex defaults to a custom event starting with onXxxxx. OnPullDown (drop-down event)
+* `type`(_String_): Custom events, Weex defaults to a custom event starting with onXxxxx. OnPullDown (drop-down event)
-* `data`: Need to reveal the parameters, such as the current control of the size, coordinates and other information。
+* `data`(_Map<String, Object>_): Need to reveal the parameters, such as the current control of the size, coordinates and other information。
-* `domChanges`：Update ref for the control's Attribute and Style
+* `domChanges`(_Map<String, Object>_): Update ref for the control's Attribute and Style
-#### Event callback
+## Event callback
Used for Module callback, for example, after the completion of positioning Module need to notify JS. Use as follows:
- public class WXLocation extends WXModule {
+```
+public class WXLocation extends WXModule {
@JSMethod
public void getLocation(JSCallback callback){
@@ -166,47 +219,15 @@ Used for Module callback, for example, after the completion of positioning Modul
//Continuous connection
callback.invokeAndKeepAlive(data);
//Invoke method and invokeAndKeepAlive two methods of choice }
- }
+}
+```
-### Weex Native and other Native code communication
-#### OnWXScrollListener
-Weex gets the scroll event You can register `registerOnWXScrollListener` via `WXSDKInstance`
-The interface is defined as follows:
- public interface OnWXScrollListener {
-
- /**
- * The view is not currently scrolling.
- */
- int IDLE = RecyclerView.SCROLL_STATE_IDLE;
- /**
- * The view is currently being dragged by outside input such as user touch input.
- */
- int DRAGGING = RecyclerView.SCROLL_STATE_DRAGGING;
- /**
- * The view is currently animating to a final position while not under
- * outside control.
- */
- int SETTLING = RecyclerView.SCROLL_STATE_SETTLING;
-
- /**
- * Callback method to be invoked when the view has been scrolled. This will be
- * called after the scroll has completed.
- * <p>
- * This callback will also be called if visible item range changes after a layout
- * calculation. In that case, dx and dy will be 0.
- *
- */
- void onScrolled(View view, int x, int y);
-
- /**
- * Callback method to be invoked when view's scroll state changes.
- *
- */
- void onScrollStateChanged(View view, int x, int y, int newState);
- }
+## OnWXScrollListener
+Weex gets the scroll event You can register `registerOnWXScrollListener` via `WXSDKInstance`
+
+## Other Introduction
-## Other Introduction
### setSize
You can use the `mWXSDKInstance.setSize()` method to change the size of the Weex container.
diff --git a/docs/zh/docs/api/android-apis.md b/docs/zh/docs/api/android-apis.md
index e69de29..4e29f4f 100644
--- a/docs/zh/docs/api/android-apis.md
+++ b/docs/zh/docs/api/android-apis.md
@@ -0,0 +1,272 @@
+---
+title: Android APIs
+type: references
+group: API
+order: 2.2
+version: 2.1
+---
+
+
+
+# WXSDKEngine
+
+1. 注册module
+2. 注册component
+3. 设置自定义的adapter
+
+
+## 注册Component
+
+### __registerComponent(type,class,appendTree)__
+
+- `return`(_bool_): 是否注册成功
+- `type`(_String_): 前端使用的对应标签
+- `class`(_Class_): 组件的class，在创建组件实例时调用
+- `appendTree`(_bool_): 渲染时判定逻辑，默认false
+ - 如果为true，则这个组件的子组件，整颗树建立、layout完后，整体一起刷新。
+ - 如果为false，则这个组件的子组件，每add一个，刷新一个。
+
+使用方式:
+
+```
+WXSDKEngine.registerComponent("video", WXVideo.class, false);
+```
+
+### __registerComponent(holder,appendTree，...names)__
+
+- `return`(_bool_): 是否注册成功
+- `holder`(_IFComponentHolder_): 用于创建component的抽象工厂，默认使用__SimpleComponentHolder__。
+- `appendTree`: 同上
+- `names`(_String ..._): 前端使用的对应标签
+
+使用方式:
+
+```
+WXSDKEngine.registerComponent(
+ new SimpleComponentHolder(
+ WXText.class,
+ new WXText.Creator()
+ ),
+ false,
+ "text"
+ );
+```
+
+
+## 注册Module
+
+registerModule(moduleName,moduleClass)
+
+- `return`(_bool_): 是否注册成功
+- `moduleName`(_String_): 模块名称
+- `moduleClass`(_Class_): 模块对应的class，创建module实例时使用
+
+使用方式:
+
+```
+WXSDKEngine.registerModule("picker", WXPickersModule.class);
+```
+
+## 注册Adapter
+
+### ImageAdapter
+
+__WEEX和图片库完全解耦__，WEEX的图片加载，都是通过调用公共接口，由实现类决定调用哪个图片库
+
+- `IWXImgLoaderAdapter`: 根据url，load图片给某个view
+- `IDrawableLoader`(可选): 根据url，load图片给某个drawable.
+
+
+#### IWXImgLoaderAdapter
+
+```
+public interface IWXImgLoaderAdapter {
+ void setImage(String url, ImageView view, WXImageQuality quality, WXImageStrategy strategy);
+}
+```
+
+* `WXImageQuality` 图片质量的设置参数,有 `LOW`, `NORMAL`, `HIGH`, `ORIGINAL` 几种质量，默认为`LOW`.
+* `WXImageStrategy` 是一个扩展类参数，配置图像是否可以剪切`isClipping`、锐化`isSharpen`以及配置占位符`placeHolder`
+
+#### IDrawableLoader(可选)
+
+```
+ interface DrawableTarget {
+
+ }
+
+ interface StaticTarget extends DrawableTarget{
+ void setDrawable(@Nullable Drawable drawable, boolean resetBounds);
+ }
+
+ interface AnimatedTarget extends DrawableTarget{
+ void setAnimatedDrawable(@Nullable Drawable drawable);
+ }
+
+ void setDrawable(String url, DrawableTarget drawableTarget, DrawableStrategy drawableStrategy);
+}
+```
+
+
+### IWXHttpAdapter
+
+同`ImageAdapter`,__WEEX和网络库也是解耦的__，通过接口形式调用，由实现类决定调用哪个网络库。
+
+```
+public interface IWXHttpAdapter {
+ void sendRequest(WXRequest request, OnHttpListener listener);
+}
+```
+
+#### WXRequest
+
+- `paramMap`(_Map<String, String>_): 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
+
+```
+interface OnHttpListener {
+
+ /**
+ * 开始请求
+ */
+ void onHttpStart();
+
+ /**
+ * 收到http header内容
+ */
+ void onHeadersReceived(int statusCode,Map<String,List<String>> headers);
+
+ /**
+ *
+ * @param 上传进度
+ */
+ void onHttpUploadProgress(int uploadProgress);
+
+ /**
+ *
+ * @param loadedLength 接收到的数据长度
+ */
+ void onHttpResponseProgress(int loadedLength);
+
+ /**
+ * 请求结束
+ * @param response 返回的response
+ */
+ void onHttpFinish(WXResponse response);
+}
+```
+
+### IWXUserTrackAdapter(可选)
+
+打点相关，如果关注weex的打点，需要实现这个adapter
+- 基础信息：sdk版本、jsbundle大小...
+- 性能信息：sdk初始化时间、页面加载可交互时间、加载bundle时间...
+
+```
+public interface IWXUserTrackAdapter {
+ void commit(Context context, String eventId, String type, WXPerformance perf, Map<String, Serializable> params);
+}
+```
+
+### IActivityNavBarSetter
+
+`WXNavigatorModule`的实现依赖这个接口，用来操作navigation.
+
+使用方式:
+
+```
+WXSDKEngine.setActivityNavBarSetter(new IActivityNavBarSetter(){});
+```
+
+### IWXStorageAdapter
+
+`WXStorageModule`实现依赖这个接口，用来实现数据的存、取默认使用`DefaultWXStorage`实现
+
+
+### IWXJSExceptionAdapter
+
+WEEX的异常上报接口，包括
+
+- 下载异常
+- 白屏异常
+- js异常
+- 降级异常
+
+```
+public interface IWXJSExceptionAdapter {
+ void onJSException(WXJSExceptionInfo exception);
+}
+```
+
+使用方式：
+
+```
+WXSDKEngine.setJSExcetptionAdapter(new TestExceptionAdapter());
+```
+
+# WXSDKInstace
+
+Weex Native 和 JavaScript 世界交互通信.
+
+## 自定义发送事件
+
+向js世界发送一些事件，比如`click`事件
+
+```
+void fireEvent(elementRef,type)
+void fireEvent(elementRef,type, data)
+void fireEvent(elementRef,type,data,domChanges)
+```
+
+* `elementRef`(_String_)：产生事件的组件id
+
+* `type`(_String_): 事件名称，weex默认事件名称格式为"onXXX",比如`OnPullDown `
+
+* `data`(_Map<String, Object>_): 需要发送的一些额外数据，比如`click`时，view大小，点击坐标等等。
+
+* `domChanges`(_Map<String, Object>_): 目标组件的属性和样式发生的修改内容
+
+
+## 结果回调
+
+JS调用时，有的场景需要返回一些数，比如以下例子，返回x、y坐标
+
+```
+public class WXLocation extends WXModule {
+
+ @JSMethod
+ public void getLocation(JSCallback callback){
+ //Get the code for the location information .....
+ Map<String,String> data=new HashMap<>();
+ data.put("x","x");
+ data.put("y","y");
+ //notify once
+ callback.invoke(data);
+ //Continuous connection
+ callback.invokeAndKeepAlive(data);
+ //Invoke method and invokeAndKeepAlive two methods of choice }
+}
+```
+
+## OnWXScrollListener
+
+如果想要拿到instance滚动的信息，需要在`WXSDKInstance`上注册`registerOnWXScrollListener` ，详细参数见`OnWXScrollListener `
+
+
+
+## 其它的一些接口介绍
+### 设置instance显示的大小
+
+使用`mWXSDKInstance.setSize()`来改变instance容器显示的大小
+
+
+### 降级
+
+Weex在开发过程中，会不断增加新的feature，但是这些feature可能在老版本上不兼容。这种情况下，native可以在`IWXRenderListener`的`onException`中进行判断，如果错误信息是 "|"格式. 并且分割后，"|"前第一个字符串等于1，这时候native可以直接降级到h5页面或者提示用户当前版本不支持。