<!-- # iPhuan Open Source # JSCoreBridge # Created by iPhuan on 2017/2/16. # Copyright © 2017年 iPhuan. All rights reserved. -->

JSCoreBridge

JSCoreBridge是基于iOS平台Apache Cordova修改的开源框架，Cordova的用处在于作为桥梁通过插件的方式实现了Web与Native之间的通信，而JSCoreBridge参考其进行删减修改（移除了开发者在平时用不上的类和方法），改写了其传统的通信机制，在保留了Cordova实用的功能前提下，精简优化了框架占用大小，并且省去了繁琐的工程设置选项，通过的新的实现方式大大提供了通信效率。JSCoreBridge开源框架力在为开发者提供更便捷的Hybird开发体验。

目录

• 适用范围
• 通信原理
  • Cordova通信原理
  • JSCoreBridge通信原理
• 如何获取JSCoreBridge
• 使用说明
  • JSCoreBridge Web平台
    • jsCoreBridge.js存放说明
    • jsCoreBridge.js接口说明
  • JSCoreBridge Native平台
    • config.xml
    • JSCWebViewController
    • JSCBridgeDelegate
    • JSCPlugin
    • JSCPluginResult
    • JSCInvokedPluginCommand
    • 其他框架类
    • 自定义错误信息
  • 网页加载回调执行顺序说明
  • Cordova用法兼容性
• 风险声明
• 开源说明
• 如何联系我
• 版本更新记录

<br /> <br />

<a name="1">适用范围</a>

• 适用于Hybird开发者，希望通过JSCoreBridge框架实现客户端Web与Native之间的交互与通信。
• 适用于已经在使用Cordova框架并且考虑更换Cordova框架的开发者。

JSCoreBridge是在Cordova的基础上进行修改的，它兼容大部分Cordova的用法，熟悉Cordova的开发者极易上手。

<br />

<a name="2">通信原理</a>

<a name="2.1">Cordova通信原理：</a>

1. Web创建自定义scheme “gap://ready”，并响应链接跳转事件；
2. Cordova通过WebView代理方法webView:shouldStartLoadWithRequest:navigationType:截获该gap跳转；
3. Cordova通过WebViewstringByEvaluatingJavaScriptFromString:方法执行Cordova JS方法nativeFetchMessages获取Web当前的命令参数并转化为CDVInvokedUrlCommand对象；
4. Cordova根据CDVInvokedUrlCommand对象的className和methodName属性找到对应插件和对应的插件方法，并执行插件方法；
5. Cordova执行完插件方法后如需给Web返回数据结果，则再次通过WebViewstringByEvaluatingJavaScriptFromString:方法执行Cordova JS方法nativeCallback，通过CDVInvokedUrlCommand的callbackId作为标识将结果发送给Web对应的回调。

<br />

<a name="2.2">JSCoreBridge通信原理：</a>

不再使用传统的scheme链接跳转截取和stringByEvaluatingJavaScriptFromString:执行JS的方法，通过iOS7新增的JavaScriptCore.framework来实现JS和Native之间的通信。

1. Web调用jsCoreBridge.js的exec或者execSync方法直接将命令参数传给客户端；
2. JSCoreBridge将命令参数转化为JSCInvokedPluginCommand对象；
3. JSCoreBridge根据JSCInvokedPluginCommand对象的className和methodName属性找到对应插件和对应的插件方法，并执行插件方法；
4. JSCoreBridge执行完插件方法后如需给Web返回数据结果，直接调用jsCoreBridge.js的nativeCallback方法，通过JSCInvokedPluginCommand的callbackId作为标识将结果发送给Web对应的回调。

<br />

<a name="3">如何获取JSCoreBridge</a>

1. 直接在GitHub上获取
2. 通过CocoaPods添加到工程：

• 如果你想使用完整版的JSCoreBridge，添加以下命令行到Podfile：

    pod 'JSCoreBridge'

• 如果你想使用Lite版的JSCoreBridge，添加以下命令行到Podfile：

    pod 'JSCoreBridge/JSCoreBridgeLite'

• 如果你想使用更兼容Cordova用法的JSCoreBridge,可以添加以下命令行到Podfile：

    pod 'JSCCordova'

或者

    pod 'JSCCordova/JSCCordovaLite'

注：Lite版的JSCoreBridge将不使用config.xml进行功能选项配置，JSCoreBridgeLite仅仅实现了最基本的通信；如果你准备使用JSCCordova，更多详细说明请参考Cordova用法兼容性。

<br />

<a name="4">使用说明</a>

JSCoreBridge框架可通过CocoaPods Pod到工程，也可手动下载源码添加，加入JSCoreBridge后，简单配置config.xml和jsCoreBridge.js即可使用，如框架为手动添加，需添加JavaScriptCore.framework库。

config.xml和jsCoreBridge.js的相关说明下文会做详细介绍。

JSCoreBridge Demo中有JSCoreBridge的详细使用样例代码，可下载参考。

<br />

<a name="4.1">JSCoreBridge Web平台</a>

<a name="4.1.1">jsCoreBridge.js存放说明：</a>

• jsCoreBridge.js本身在工程当中，如打开的html文件在bundle中，可直接引用，当然如果你的html文件在bundle的子目录下，你希望jsCoreBridge.js和你的网页目录在同一级，你也可以将jsCoreBridge.js拷贝到该同级目录；
• 如果你的html文件存储在沙盒，请务必把jsCoreBridge.js拷贝到沙盒；
• 如果你的网页在远程网站上，那么你同样需要将jsCoreBridge.js放到你的远程网站上；

jsCoreBridge.js的使用原则在于，保证你的html文件能够引用到。

<br />

<a name="4.1.2">jsCoreBridge.js接口说明：</a>

jsCoreBridge.js对应于Cordova的cordova.js，通过jsCoreBridge对象来调用，也兼容Cordova用法，可以通过cordova对象调用，jsCoreBridge接口如下：

• jsCoreBridge.version

获取当前JSCoreBridge Web平台JS版本号。<br /> 客户端JSCoreBridge框架对jsCoreBridge.js有最低版本要求，Pod到工程的jsCoreBridge.js相对于当前客户端JSCoreBridge框架都是最新的版本，可放心使用，如果你自行从其他途径下载jsCoreBridge.js，请保证该版本能够兼容客户端JSCoreBridge框架。

• jsCoreBridge.exec

执行客户端对应插件方法。<br /> 通过该方法可以告诉客户端JSCoreBridge框架通过对应插件的对应方法去执行相应的事情，代码示例如下：

    var params = {title: 'JSCoreBridge Demo'};

    jsCoreBridge.exec(function (res) {
    // 成功回调
    }, function (err) {
    // 失败回调
    }, 'JSCTestPlugin', 'changeNavTitle', [params]);

• 第一个函数为成功回调，第二个函数为失败回调，通过res和err获取结果数据，当然如果你不想收到回调，这两个参数可以传空，如果你不希望接收res和err结果数据，回调函数你也可以不用带参数；
• JSCTestPlugin为客户端对应的插件Plugin类名；
• changeNavTitle为JSCTestPlugin插件中对应的插件方法；
• 最后一个参数则为Web传给客户端的参数，通过数组的方式传递，至于数组里面传递什么样的数据，由开发者自行决定，当然该参数你也可以传空或者不传。

• jsCoreBridge.execSync

同步执行客户端对应插件方法。<br /> 与exec接口不同的是该方法为同步操作，没有成功与失败回调函数，其他参数与exec用法一致。其代码示例如下：

    var version = jsCoreBridge.execSync('JSCTestPlugin', 'getAppVersionSync', null);

• deviceready

JSCoreBridge运行环境已准备就绪监听事件。<br /> 可通过以下示例代码来监听JSCoreBridge准备完成：

    document.addEventListener('deviceready', onDeviceReady, false)

:warning: 注意：
为了保证客户端插件方法能够正确执行，请在deviceready回调中或者回调执行后调用jsCoreBridge对象的方法；
如果你在deviceready回调中调用jsCoreBridge.exec，不要企望客户端对应插件方法会在jsCoreBridgeDidReady:之前调用，jsCoreBridge.exec为异步操作，除非你使用jsCoreBridge.execSync同步方法。

<br />

• pause

客户端已经进入后台监听事件。<br /> 可通过以下示例代码来监听客户端已经进入后台：

    document.addEventListener('pause', onPause, false)

• resume

客户端即将进入前台监听事件。<br /> 可通过以下示例代码来监听客户端即将进入前台：

    document.addEventListener('resume', onResume, false)

<br />

<a name="4.2">JSCoreBridge Native平台</a>

<a name="4.2.1"></a>

config.xml：

在Cordova中config.xml是框架功能选项的配置文件，包含工程的一些信息，插件白名单，Web URL白名单，WebView属性设置等。同样在JSCoreBridge中，我们将config.xml移植了过来，并对一些配置选项进行了删减，以便达到一个轻量级的JSCoreBridge框架。

config.xml文件并不是必须的，当你使用JSCoreBridgeLite时，将不再使用config.xml文件来配置框架；当然你也可以通过设置JSCWebViewController类的configEnabled属性来关闭使用config.xml，以使用一个最轻量化的JSCoreBridge。
JSCoreBridge在未使用config.xml的状况下，其仅仅满足Web与Native之间通信的基本功能，不进行插件白名单验证，不进行Web URL白名单验证，并且WebView的相关属性都保持为系统默认状态。

想了解config.xml文件如何配置，可进一步点击这里，到Cordova官方网站进行了解。
当然对于一般的开发者来说，JSCoreBridge当中的config.xml样例已足够满足需求，你只需配置插件白名单即可，配置示例如下：

    <feature name="JSCTestBasePlugin">
    <param name="ios-package" value="JSCTestBasePlugin" />
    <param name="onload" value="true" />
    </feature>

一般来说保持feature当中name的值和param当中value值一致，当然你也可以不一致，但必须保证param当中value值和对应的插件类名一致； 如果希望插件在JSCoreBridge初始化时就加载，可以通过<param name="onload" value="true" />来设置，如果不需要，可以省去该行。

在JSCoreBridge中，以下配置选项目前暂未实现：

1. content
2. access
3. engine
4. plugin
5. variable
6. preference中 (BackupWebStorage， TopActivityIndicator， ErrorUrl， OverrideUserAgent， AppendUserAgent， target-device， deployment-target， CordovaWebViewEngine， SuppressesLongPressGesture， Suppresses3DTouchGesture)

在JSCoreBridge中，以下配置选项不再需要添加：

1. widget中 (id， version，defaultlocale，ios-CFBundleVersion，xmlns，xmlns:cdv)
2. name
3. description
4. author

:warning: 如工程用到config.xml，请在JSCoreBridge/Optional目录下将config.xml复制到其他目录并添加到工程使用；

<br />

<a name="JSCWebViewController">JSCWebViewController：</a>

JSCWebViewController是JSCoreBridge框架直接供开发者使用的ViewController，可以直接使用，也可根据自己的需求来继承使用，其部分API说明如下：

• bridgeDelegate

JSCoreBridge代理。可通过该对象执行相应代理方法，具体可参考JSCBridgeDelegate。

• configFilePath

config.xml文件路径。默认为nil从Bundle根目录获取，如果设置该属性，则从该属性路径获取，不支持网络地址。

• configEnabled

是否开启config配置功能。默认开启，如需关闭，可设置为NO；当使用JSCoreBridgeLite时configEnabled属性设置不可用，始终为关闭状态。

• shouldAutoLoadURL

是否自动加载URL。默认自动加载通过initWithUrl:初始化的URL，设置为NO关闭自动加载。

• - (instancetype)initWithUrl:(NSString *)url

通过字符串链接初始化URL。可在JSCWebViewController子类中重写该方法。

• - (void)loadURL:(NSURL *)URL
• - (void)loadHTMLString:(NSString *)htmlString

通过调用以上两方法进行网页手动加载

• - (void)jsCoreBridgeWillReady:(UIWebView *)webView
• - (void)jsCoreBridgeDidReady:(UIWebView *)webView

JSCoreBridge将要准备就绪和已准备就绪回调。分别在deviceready通知回调执行之前和之后调用，方便开发者在这两个时刻进行相应操作，可在JSCWebViewController子类中重写该方法使用。

:warning: 特别提示：关于客户端Native及Web的相应回调方法的执行顺序请参考[网页加载回调执行顺序说明](#W