🔌 客户端 API 列表

API 命名空间

所有 API 约定均使用 DSBridge-Android/DSBridge-IOS 作为调用函数和响应的功能。

在当前实现，没有定义 API 资源的情况下，不使用命名空间功能，将 API 添加到 DWebView 实例时，命名空间参数为 null

Android

dwebView.addJavascriptObject(new H5Api(), null);

iOS

[dwebview addJavascriptObject:[[H5Api alloc] init] namespace:nil];

为提高代码语义化，H5Api 类中实现的函数名 以具名行为的方式命名。

如业务 user 业务名称约定为 getUser； 响应/处理方法以 on 为前缀，如分享按钮 setShare

参数

返回值

Android

返回值	典型值	类型	备注
true	true false	Boolean

iOS

返回值	典型值	类型	备注
1	``	String

钩子/生命周期

onWebViewCreated

onWebViewCreated 生命周期，网页代码开始运行，响应网页，以便网页运行后续续业务。

示例

@JavascriptInterface
public void onWebViewCreated(Object msg, CompletionHandler<Boolean> handler) {
    handler.complete(true);
}

notifyWebViewUpdated

notifyWebViewUpdated 生命周期，有配置或数据更新时，通知网页。调用 dWebView.callHandler 函数，传入 updateObj JSONObject 参数

如用户完成登录后，用户的信息将会被更新，那么客户端调用 notifyWebViewUpdated，传参数 { "name": "user" }

网页获取参数后主动调取 getUser ，获取最新的用户信息，进入后续的流程

参数

updateObj

{
  "name": "user"
}

name	类型	备注
user	String	用户信息

返回值

返回值	典型值	类型	备注
retValue	true false	Boolean	retValue 表示 updated 的响应结果

示例

JSONObject updateObj = new JSONObject();
try { 
    updateObj.put("name", "user"); 
} catch (JSONException e) {
    e.printStackTrace();
}

dWebView.callHandler("notifyWebViewUpdated", new Object[]{ updateObj }, new OnReturnValue<Boolean>() {
    @Override
    public void onValue(Boolean retValue) {
        showToast(retValue);
    }
});

事件

与 notifyWebViewUpdated 生命周期不同的是，notifyEvent 不强制开发者更新对应的数据。

如用户登录后，调用 notifyEvent，传参数 { "name": "loginSuccess" } ，表示用户成功登陆。

notifyEvent

参数

eventName

{
  "name": "shareSuccess"
}

eventName	类型	备注
shareSuccess	String	点击分享到社交应用
loginSuccess	String	关闭登录页之后
BindPhoneSuccess	String	绑定手机成功，多数情况下是单独调起绑定手机页面后的成功回调

示例

JSONObject eventName = new JSONObject();
try { 
    eventName.put("name", "shareSuccess"); 
} catch (JSONException e) {
    e.printStackTrace();
}

dWebView.callHandler("notifyEvent", new Object[]{ eventName }, new OnReturnValue<Boolean>() {
    @Override
    public void onValue(Boolean retValue) {
        showToast(retValue);
    }
});

业务方法

getUserByNative

返回用户信息

返回值

返回值	典型值	类型	备注
json	user	JSONObject	见数据结构

WARNING

前端先调用 getLoginStatusByNative，判断是否登录，避免得到空的返回值

示例

@JavascriptInterface
public void getUserByNative(Object _null, CompletionHandler<JSONObject> handler) throws JSONException {
    JSONObject user = new JSONObject();
    user.put("username", "Mather");
    handler.complete(content);
}

getLoginStatusByNative

返回用户是否登录的状态

参数

无参数

返回值

返回值	典型值	类型	备注
true	true false	Boolean

onSetShare

设置网页分享信息，标题、描述、分享地址和分享小图

参数

shareObject

{
  "title": "分享标题",
  "desc" : "分享描述",
  "icon" : "http://images.infzm.com/medias/2018/0816/136580.jpeg@770x510",
  "url"  : "http://www.infzm.com/content/136473"
}

返回值

返回值	典型值	类型	备注
true	true false	Boolean

示例

@JavascriptInterface
public void onSetShare(Object shareObject, CompletionHandler<Boolean> handler) throws JSONException {
    JSONObject shareObject = (JSONObject) shareObject;
    String title       = shareObject.getString("title");
    String desc        = shareObject.getString("desc");
    handler.complete(true);
}

onOpenNativeLogin

仅仅是登录页，无后续绑定手机流程。

WARNING

为避免逻辑冲突，建议先判断登录状态，再调起登录页

WARNING

建议前端开发者使用 onOpenNativePage API 调起登录页

参数

无参数

返回值

返回值	典型值	类型	备注
true	true false	Boolean

示例

@JavascriptInterface
public void onOpenNativeLogin(Object _null, CompletionHandler<JSONObject> handler) throws JSONException {
    //launch login page
    handler.complete(true);
}

onOpenNativePage

打开客户端页面，其数据结构参考[APP 路由参数支持表]

参数

nativePageParams

{
  "version": "1.1.0",
  "link_type": "10",
  "terms_id": "6"
}

返回值

返回值	典型值	类型	备注
json	openNativePage-Success / openNativePage-Fail	JSONObject	见数据结构

openNativePage-Success

{
  "code": "200",
  "msg": "路由存在"
}

openNativePage-Fail

{
  "code": "404",
  "msg": "路由不存在"
}

示例

@JavascriptInterface
public void onOpenNativePage(Object nativePageParams, CompletionHandler<Boolean> handler) throws JSONException {
    JSONObject nativePage = (JSONObject) nativePageParams;
    double link_type = nativePage.getString("link_type");
    
    JSONObject response = new JSONObject();
    try { 
        response.put("code", "200"); 
        response.put("msg", "路由存在");
    } catch (JSONException e) {
        e.printStackTrace();
    }
    
    handler.complete(response);
}