# jsapi

**Repository Path**: buns-li/jsapi

## Basic Information

- **Project Name**: jsapi
- **Description**: 作为Hybird App的JS端调用API
- **Primary Language**: NodeJS
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2018-05-18
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# jsapi

#### 项目介绍
作为Hybird App的JS端调用API


## 一、注入规则

1.  Android或IOS端注入到JS上下文的全局对象名称 `JSBridge`(可调整)

    原生端注入的`JSBridge`只有一个`invoke`方法, 代码模式如下:

    ```javascript
    /**
    *  android和ios内部提供的注入到JS全局上下文中的对象方法
    *  
    *  @param {String} action 操作名称
    *  @param {String} dataJSONStr 传递的数据(JSON字符串形式，需要执行JSON的反序列化)，默认空字符串
    *  @param {String} callbackid 客户端需要回调操作的会传入此回调函数的唯一标识，默认传入空字符串
    */
    JSBridge.invoke = function(action,dataJSONStr,callbackid){
        /**
         * do something
         */
    }
    ```
    
2.  H5端封装`JSBridge`并提供一个`JSApi`的全局快捷操作对象

3.  Native与H5之间的逻辑通信完全的依赖`action规则` 来做交互核心;


## 二、`Action`规则

客户端利用`JSBridge.invoke`传入的`action`操作名称的规则按如下几类分类:

1.  设备操作类型

    `action`格式: "`device`.`操作名称`"

    

    |                    action名称                     | 传入数据结构                  | respData结构                                                 |
    | :-----------------------------------------------: | :---------------------------- | :----------------------------------------------------------- |
    | `device.getNetworkType`<br>获取设备的网络连接信息 |                               | " `networkType`":`网络类型`<br>返回值如下:<br>1. `UNKNOWN`: `未知网络`<br>2. `NOTREACHABLE`:`无网络`<br>3. `wifi`: `wifi网络`<br>4.  `2g`: `2g网络`<br>5. `3g`: `3g网络`<br>6. `4g`: `4g网络` |
    |     `device.getLocation`<br>获取地理位置信息      |                               | `longitude`: `String`  `经度`<br>  `latitude` : `String`  `纬度`<br>  `accuracy` : `Number`  `精度，单位米`<br>  `speed`: `Number`  `速度，单位毫秒`<br>  `country` :  `String`  `国家名`<br>  `countryCode` :  `string`  `国家编号`<br>  `province` : `String`  `省份名`<br>  `city`:  `String`  `城市名`<br>  `cityCode` : `String`  `城市编码`<br>  `adCode` :   `String`  `区域编码`<br>  `streetNumber` : `Object`  `街道门牌信息，结构是：{street, number}`<br>  `pois`:  `Object Array`   `定位点附近的 POI 信息，结构是：{name, address}` |
    |    `device.makePhonecall`<br>唤起设备呼叫功能     | `number`: `string`:`电话号码` | `无回调函数`                                                 |

    

2.  窗口操作类型

    `action`格式: "view.`操作名称`"

    

    |                     action                      | 传入数据结构                                                 | respData结构           |
    | :---------------------------------------------: | :----------------------------------------------------------- | ---------------------- |
    |          `view.close`<br>关闭当前页面           |                                                              | `无回调函数`           |
    |      `view.fullscreen`<br>当前页面开启全屏      |                                                              | 成功与否: `true|false` |
    |             `view.back`<br>页面回退             |                                                              | `无回调函数`           |
    |           `view.forward`<br>页面前进            |                                                              | `无回调函数`           |
    |             `view.goto`<br>跳转页面             | `url`:  `跳转的页面路径`<br>`title`: `目标页面的标题`<br>`query`: `目标页面的参数字典` | `无回调函数`           |
    |       `view.changeTitle`<br>改变页面标题        | `title`: `页面标题`                                          | `无回调函数`           |
    | `view.showOptionMenu`<br>显示页面顶部右上角菜单 |                                                              | `无回调函数`           |
    | `view.hideOptionMenu`<br>隐藏页面顶部右上角菜单 |                                                              | `无回调函数`           |
    |                                                 |                                                              |                        |

    

3.  Native UI操作类型

    `action`格式: "ui.`操作名称`"

    

    |                action                | 传入数据结构                                                 | respData结构                                             |
    | :----------------------------------: | ------------------------------------------------------------ | -------------------------------------------------------- |
    |   `ui.showToast`<br>显示短消息提醒   |                                                              | `有回调函数,但不返回数据respData`                        |
    |   `ui.hideToast`<br>隐藏短消息提醒   |                                                              | `无回调函数`                                             |
    |       `ui.alert`<br>弹出提示框       | `title`:`提示标题`<br>`msg`:`提示内容`                       | `无回调函数`                                             |
    |      `ui.confirm`<br>弹出选择框      | `title`:`提示标题`<br>`msg`:`提示内容`                       | `button`: 选择的按钮 `OK`或`CANCEL`                      |
    |      `ui.prompt`<br> 弹出对话框      | `title`:`提示标题`<br>`msg`:`提示内容`<br> `placeholder`: `默认文本` | `text`:`返回的输入框中的数据文本`                        |
    |   `ui.showLoading`<br>弹出loading    | `content`: `loading的文字内容`<br>`delay`:`延迟时间`         | `无回调函数`                                             |
    |   `ui.hideLoading`<br>隐藏loading    |                                                              | `无回调函数`                                             |
    | `ui.showActionSheet`<br>弹出系统菜单 | `title`:`菜单标题`<br>`items`:  `菜单按钮的文字数组`<br>`cancelText`: `取消按钮文案，默认为` `[取消]` | `index`: [`int`] <br>从`0`开始,点击取消或蒙层时返回 `-1` |
    |                                      |                                                              |                                                          |

    

4.  图像操作类型 (后续完善)

    `action`格式: "image.`操作名称`"

    |           action           | 传入数据结构 | respData结构 |
    | :------------------------: | ------------ | ------------ |
    | `image.choose`<br>选择图像 |              |              |
    |                            |              |              |

    

5.  视频操作类型 (后续完善)

    `action`格式: "video.`操作名称`"

    |           action           | 传入数据结构 | respData结构 |
    | :------------------------: | ------------ | ------------ |
    | `video.choose`<br>选择视频 |              |              |
    |                            |              |              |

    

6.  音频操作类型 (后续完善)

    `action`格式: "audio.`操作名称`"

	|           action           | 传入数据结构 | respData结构 |
	| :------------------------: | ------------ | ------------ |
	| `audio.choose`<br>选择音频 |              |              |
	|                            |              |              |




7.  特定应用的逻辑交互操作类型

    `action`格式: "app.`应用名称`.`操作名称`"

    |                           action                            | 传入数据结构                                                 | respData结构 |
    | :---------------------------------------------------------: | ------------------------------------------------------------ | ------------ |
    | `app.score.notifyUserLotteried`<br>积分系统中通知用户已中奖 | `userid`:`用户id`<br>`userName`:`用户名称`<br>`goodsName`:`中奖商品名称`<br>`goodsId`:`中奖商品id`<br>`goodsType`:`中奖商品类型` |              |
    |                                                             |                                                              |              |

    
## 三、`H5`与`Native`的交互



**提醒注意**：为了保证页面在被拦截下来之后只在党建App里面使用, jsbridge的调用做了一个最外层的 user-agent的 判断， App端的Webview里面需要在user-agent中添加 `jxrs-hybird-app`的关键字字样，jsbridge才开通的了，同时也是为了给jsbridge提供一个类似环境变量的功能,方便本地调试;



### 1. `H5`主动调用`Native`

H5端通过封装的`JSApi`,去利用`action规则`的方式实现如下调用:

```javascript
JSApi.view.goto() //等同于 JSBridge.invoke("view.goto")的操作方式
JSApi.ui.alert() //等同于 JSBridge.invoke("ui.alert")的操作方式
```

### 2. `Native`处理`H5`端回调

针对IOS和Android在拿到`callbackid`之后，要回调H5端的话,需要执行如下操作调用

```javascript
/**
*  @param callbackid {String} 回调函数的唯一标识
*  @param jsonStr {String} 已经json序列化的对象后的字符串
*  
*  jsonStr内对象数据结构:
*   {
*      "err":{
*			"msg":"错误信息",
*      		"code":"错误代码",
*	   },
*      "respData": "准备传递给回调函数的数据对象或数据值"
*   }
*/
JSApi.notify(callbackid,jsonStr)
```
### 3. `Native`主动调用`H5`

 Native端需要调用的JS代码如下:

```javascript
/**
*  @param actionName {String} 根据Action规则产生的操作名称(此处的大部分应是特定应用的逻辑交互操作类型）
*  @param dataJSONStr {String} 需要传递的数据对象的JSON字符串
*/
JSApi.invoke(actionName,dataJSONStr)
```


## 四、特殊化

针对不同应用下,如果因为JSApi和JSBridge产生冲突的话,可以选择使用如下:

```js
JSApi.alias("新的名称").aliasBridge("新的JS上下文名称")来解决
```