跨平台Js bridge新秀-DSBridge Android篇

摘要：第一个用于调用没有返回值的函数，没有参数时传即可。第二个用于需要返回值的场景，需要传递一个接口对象，在方法中处理返回值即可。

DSBridge是目前地球上最好的IOS/Android   javascript bridge. 没有之一！

DSBridge 是H5页面与Native之间通信的桥梁，它有如下特点：

跨平台；同时支持ios和android。

双向调用；js可以调用native， native可以调用js

不仅支持异步调用，而且页支持同步调用（dsbridge是唯一一个支持同步调用的javascript bridge）

支持进度回调，多次返回（常用于文件下载进度、计时器等）

Android支持腾讯x5内核

三端易用；无论是前端还是android或ios，使用都非常简单，极大的降低集成／学习成本

与WebViewJavascriptBridge的对比请移步 DSBridge VS WebViewJavascriptBridge

添加 JitPack repository

allprojects {
  repositories {
   ...
   maven { url "https://jitpack.io" }
  }
}

添加依赖

dependencies {
    
     compile "com.github.wendux:DSBridge-Android:2.0-SNAPSHOT"

    //  使用腾讯x5内核的使用该版本
    // compile "com.github.wendux:DSBridge-Android:x5-SNAPSHOT"
    
    // 主线版本
    //compile "com.github.wendux:DSBridge-Android:master-SNAPSHOT"
}

假设Native端实现了两个api: testSyn、testAsyn。参数以json传递， testSyn为同步api,执行结束后会直接返回结果，而testAsyn为一个异步api(可能会执行耗时操作)，执行结束后，结果异步返回。

Java中实现 API

public class JsApi{
    //用于同步调用
    @JavascriptInterface
    String testSyn(JSONObject jsonObject) throws JSONException {
        // The return value type can only be  String
        return jsonObject.getString("msg") + "［syn call］";
    }
    //用于异步调用
    @JavascriptInterface
    void testAsyn(JSONObject jsonObject, CompletionHandler handler) throws JSONException {
        handler.complete(jsonObject.getString("msg")+" [asyn call]");
    }
}

为了安全起见，所有的API都必须有 “JavascriptInterface” 标注。

将实现的API安装到 DWebView

import wendu.dsbridge.DWebView
...
DWebView dwebView= (DWebView) findViewById(R.id.dwebview);
dwebView.setJavascriptInterface(new JsApi());

在h5页面中调用 Java API

初始化 dsBridge

//cdn
//
//npm
//npm install dsbridge
var dsBridge=require("dsbridge")

调用 API

// 同步调用
var str=dsBridge.call("testSyn", {msg: "testSyn"});

// 异步调用
dsBridge.call("testAsyn", {msg: "testAsyn"}, function (v) {
  alert(v);
})

Native 调用 h5 中的 javascript API

Javascript 注册供 Native调用的 API

// 注册一个加法函数供 Native 调用
 dsBridge.register("addValue",function(l,r){
     return l+r;
 })

在 Java 中调用 javascript API

webView.callHandler("addValue",new Object[]{1,"hello"},new OnReturnValue(){
       @Override
       public void onValue(String retValue) {
          Log.d("jsbridge","call succeed,return value is "+retValue);
       }
});

注意：Native调用javascript API时必须在 "PageFinished"之后进行

IOS中的使用方式请参考 DSBridge-IOS 。

"dsBridge" 是一个全局对象, 在h5页面中初始化DSBridge后便会可用，它有两个方法 "call" 和 "register";

功能：调用Native api

method: api函数名

args:参数，类型：json, 可选参数

callback(String returnValue):仅调用异步api时需要.

同步调用

如果你是一名经验丰富的开发者，想必看到第二行时已然眼睛一亮，想想node最被诟病的是什么，目前跨平台的jsbridge中没有一个能支持同步，所有需要获取值的调用都必须传一个回调，如果调用逻辑比较复杂，必将会出现“callback hell”。然而，DSBridge彻底改变了这一点。支持同步是DSBridge的最大亮点之一。

异步调用

对于一些比较耗时的api, DSBridge提供了异步支持，正如上例第三行代码所示，此时你需要传一个回调（如果没有参数，回调可作为第二个参数），当api完成时回调将会被调用，结果以字符串的形式传递。

注册 javascript API 供Native调用

为了兼容 Android和IOS ，DSBridge对Native API的签名有两个要求：

返回值必须是 String， 如果没有返回值，直接返回null就行

API的参数通过 JSONObject传递，如果有些API没有参数，你也需要申明。

​

通常情况下，调用一个方法结束后会返回一个结果，是一一对应的，现在，我们来思考如下场景：

有一个嵌入到app中显示文档下载列表的网页。要求点击网页中相应文件对应的下载按钮后，开始下载文件，并在该网页中显示下载进度。

思考：我们将文件下载的功能在natvie端实现，当点击网页上的某项时，我们通过js调用native的下载方法，native在下载的过程中，不断的向js返回进度, 然后js更新网页上的进度条，等到下载任务结束时，才算本次调用结束。而这种调用的特征就是js的一次调用，对应native的“多次返回”，考虑到native很多耗时任务都可能会多次返回（比如返回进度），DSBridge 对“多次返回”进行了支持，使用DSBridge 就可以非常方便的应对这种case了。

详细的示例请参考 DSBridge实例－在网页中展示Native进度

DWebView提供了三个api用于调用js

void callHandler(String method, Object[] args) 
void callHandler(String method, Object[] args, CompletionHandler handler)
void evaluateJavascript(String script)

前两个api中，method 为函数名，args为参数数组，可以接受String 、int 、long、float、double等。

第一个api用于调用没有返回值的js函数，没有参数时传null即可。

第二个api用于需要返回值的场景，需要传递一个CompletionHandler接口对象，在complete(String returnValue)方法中处理返回值即可。

第三个api用于执行任意js代码，内部已做版本兼容处理。

调用时机

DWebview只有在javascript context初始化成功后才能正确执行js代码，而javascript context初始化完成的时机一般都比整个页面加载完毕要早，随然DSBridge能捕获到javascript context初始化完成的时机，但是一些js api可能声明在页面尾部，甚至多带带的js文件中（请务必不要这么做），如果在javascript context刚初始化完成就调用js api, 此时js api 可能还没有注册，所以会失败，综上所述，如果是客户端主动调用 js应该在onPageFinished后调用。简单的示例如下：

webView.setWebViewClient(new WebViewClient(){
    @Override
    public void onPageFinished(WebView view, String url) {
        super.onPageFinished(view, url);
        //期望返回值
        webView.callHandler("test",new Object[]{1,"hello"},new CompletionHandler(){
            @Override
            public void complete(String retValue) {
                Log.d("jsbridge","call succeed,return value is "+retValue);
            }
        });
        //不期望返回值
        webView.callHandler("test",null);
    }
});

DWebview中下列函数会在主线程中执行，您不必在手动切换线程

void loadUrl( String url) 
void loadUrl(final String url, Map additionalHttpHeaders)
void evaluateJavascript(String script) 

DWebview已经实现 alert、prompt、comfirm对话框，您可以不做处理，也可以自定义。

如果你喜欢，欢迎star！
github:
android: https://github.com/wendux/DSB...
ios: https://github.com/wendux/DSB...