### 关于新 API

为了促进 CQ 的 Hybrid 融合，双方提供了一套新的 api，即这套新 api 能够很好的兼容 Ctrip 客户端。对于还未提供兼容版本的功能，你可能需要判断当前的客户端环境，然后分别调用对应的 api。

新 API 为了兼容 HySDK 中已有的 API，为每个 API 都添加了对应的命名空间。例如：Webview 相关的 api 都是 hysdk.webview.xxx 的形式。

### 新 API 使用简介

新 API 在使用上与原有的 API 并没有什么区别，在此详细说明一下。

所有的 API 在使用方式上都分为调用和监听两类：调用即调用某个功能，例如：打开新的页面、获取设备信息；监听即监听某个事件，例如：网络变化、当前页面接收到数据。

#### 1. 调用 API

调用 API 的参数是一个对象，包括在调用时候需要指定的一些参数。由于所有的调用 API 都是异步的，所以我们为所有的 API 均提供了 `success` 和 `fail` 两个参数，分别为调用成功和失败的回调。具体示例如下：

```javascript
hysdk.xxx.xxx({
    param1: 'something',
    param2: 'other things',
    success: function() {},
    fail: function() {}
});
```

#### 2. 监听 API

所有的监听 API 都是 `hysdk.xxx.onXxx` 的格式，都有对应的移除监听和监听一次的 API。

- `hysdk.xxx.onXxx`：监听，参数为回调函数。
- `hysdk.xxx.onceXxx`：监听一次，参数为回调函数。
- `hysdk.xxx.offXxx`：移除监听。如果有参数，参数为监听时的回调函数的句柄，则移除指定的监听；如果没有参数，则移除所有监听。

具体示例如下：

```javascript
// 监听
hysdk.xxx.onXxx(function(){
    // trigger every time
});

// 监听一次
hysdk.xxx.onceXxx(function(){
    // trigger once
});

// 移除监听
var _xxx_callback = function() {};
hysdk.xxx.onXxx(_xxx_callback);
hysdk.xxx.offXxx({}, _xxx_callback); // 移除指定监听（第一个参数为移除的回调，可以是 function 或 {}）
hysdk.xxx.offXxx(); // 移除所有监听
```

### 新 API 注意事项

1. 先调用 `hysdk.config({...})` 才能使用其他 API。因为在 HySDK 初始化的时候，需要读取一些配置，而这些配置需要通过 config 来进行配置。所以，我们就把初始化放在了 config 之后。

2. onShow 和 onReceiveData的区别：

    - onShow：发生在 webview 显示的时候，包括
    - onReceiveData：发生在回退到当前页的时候

3. 如果设置了多同名的 webview，在指定回退名称时，只会回退到后面一个（即堆栈中较上的那个）

4. iOS 如果是通过客户端的扫码进入的 webview，在 webview 中再次调用扫码功能，会没有任何响应。

5. onXXX 和 event.on 的区别：

    - onXXX：webview 内部的消息，只针对当前 webview 的特定事件
    - event.on：跨 webview 的消息，可以接收客户端任何来源的自定义事件