Hanks10100 closed pull request #244: update docs for android-apis
URL: https://github.com/apache/incubator-weex-site/pull/244
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/docs/docs/api/android-apis.md b/docs/docs/api/android-apis.md
index 6ec6b37f9..2ec67b3d7 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 e69de29bb..4e29f4fdb 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页面或者提示用户当前版本不支持。
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
With regards,
Apache Git Services
