使用说明 #

新 API 简介 #

为了促进 CQ 的 Hybrid 融合,我们基于现有的 Hybrid 方案打造了一套兼容的 API。新API 覆盖了大多数现有功能,包括:webview、导航栏、app、分享、定位等基础功能,同时也提供了全局消息、选择联系人、检查应用是否已安装等新功能,足以满足日常开发需求。最重要的是,新API 提供了统一的功能和调用方式能更好的同时跑在两个客户端,你不再需要为每个功能查找两边的文档,写兼容的代码了。

使用方法 #

新API 在使用上与原有的 API 基本相同,在此详细说明。

所有的 API 在使用方式上都分为调用和监听两类:调用即调用某个功能,例如:打开新的页面、获取设备信息;监听即监听某个事件,例如:网络变化、当前页面接收到数据。新API 为了兼容和区分原有 API,为每个 API 都添加了对应的命名空间。例如:Webview 相关的 api 都是 hysdk.webview.xxx 的形式。

1. 调用类 API #

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

hysdk.aaa.bbb({
    param1: 'something',
    param2: 'other things',
    success: function() {},
    fail: function() {}
});

2. 监听类 API #

所有的监听 API 都是 hysdk.xxx.onXxx 的格式,可以调用多次。具体示例如下:

// 监听
hysdk.aaa.onBbb(function(){
    // trigger every time
});

在Ctrip中使用 #

整套新 API 都可以直接在携程客户端中调用。除了 @qnpm/hysdk,你还需要安装 @qnpm/hysdk-cq 这个插件。

  1. 新API 覆盖了大多数的基础功能。

  2. 如果要使用携程客户端中的一些独有的 API,请通过 hysdk.bridge.invoke 的方式来调用。具体示例如下:

     hysdk.bridge.invoke(moduleName, nativeApiName, params, tagName, callback);
    
  3. 如果要使用去哪儿客户端中的一些独有的 API,请通过 hysdk 提供的 api 直接调用,或者使用 hysdk.register 注册之后再调用。使用说明参见 文档

一些注意事项 #

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

  2. onShow 和 onReceiveData的区别:

    • onShow:发生在 webview 显示的时候,包括第一次进入和回退到当前页。
    • onReceiveData:发生在回退到当前页的时候,并且只有传递了数据才会触发,一般通过 webview.pop() 传递参数。
  3. 如果设置了多同名的 webview,在指定回退名称时,只会回退到后面一个(即堆栈中较上的那个)。

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

  5. onXXX 和 hysdk.event.on 的区别:

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

App #

hysdk.app.setStatusBarStyle #

功能

设置状态栏文字颜色。仅 iOS 有效。

环境

平台 是否支持
iOS
Android X
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
color string 状态栏颜色 dark 包括:dark(黑色)、light(白色)。默认为 dark

示例

hysdk.app.setStatusBarStyle({
    color: 'dark',
    success: function() {
        console.log('修改状态栏成功');
    }
});

hysdk.app.getNetworkType #

功能

获取当前网络信息。

环境

平台 是否支持
iOS
Android
touch X
微信 X

返回参数

参数 类型 描述 备注
type string 网络类型 包括:wifi2G3G4Gunknown

示例

hysdk.app.getNetworkType({
    success: function(data) {
        // data = { type: 'wifi' }
    },
    fail: function() {

    }
});

hysdk.app.getDeviceInfo #

功能

获取设备信息。

环境

平台 是否支持
iOS
Android
touch X
微信 X

返回参数

参数 类型 描述 备注
mac string 机器 MAC 地址 iOS7后值始终为 02:00:00:00:00:00
model string 设备或模拟器型号
osVersion string 组件版本信息
platform string 平台 包括:iOSAndroid
idfa string 仅 iOS
imei string 仅 Android

示例

hysdk.app.getDeviceInfo({
    success: function(data) {
        // Android 示例:
        // data = { 
        //     imei: "78", 
        //     mac: "bc:3a:ea:b8:38:40", 
        //     model: "OPPO R7", 
        //     osVersion: "4.4.4", 
        //     platform: "Android" 
        // }

        // iOS 示例:
        // data = {
        //     osVersion: "8.4.1", 
        //     model: "iPhone7,1", 
        //     idfa: "4CDC2D6C-4207-45AB-829D-40B4966C8A67", 
        //     mac: "02:00:00:00:00:00", 
        //     platform: "iOS"
        // }
    },
    fail: function() {

    }
});

hysdk.app.getAppInfo #

功能

获取应用信息。

环境

平台 是否支持
iOS
Android
touch X
微信 X

示例

hysdk.app.getAppInfo({
    success: function(data) {
        // Android 示例:
        // data = { 
        //     atomversion: {},
        //     cid: "beta",
        //     gid: "AE67B4C4-EBA9-BB64-0801-B046639E0BC4", // gid是设备唯一标识符
        //     lt: 1,
        //     pid: "10010", // pid是标识这个是哪个包,比如,iOS、android,ios pro
        //     qpVersion: "",
        //     sid: "C4FFB847-82C9-9FD4-F967-47049DA8133C",
        //     uid: "867664029497828", // uid是后端给每个设备分配的唯一标识符
        //     usid: "",
        //     uuid: "",
        //     versionName: "8.6.0-dev",
        //     versioninfo: "",
        //     vid: "60001169"
        // }

        // iOS 示例:
        // data = {
        //     aid: "96CF8DD9-B877-4A3C-891A-450A563F1C78",
        //     cid: "C1001",
        //     gid: "8666321D-EAED-EEA6-4459-AD2658359210",
        //     lt: 0,
        //     pid: "10010",
        //     sid: "AC2D39DD-5596-6B07-91D5-454BC9A32461",
        //     uid: "C727C669-ADA3-4822-BE5E-55F73CA1A01D",
        //     vid: "80011138"
        // }
    },
    fail: function() {

    }
});

Business #

hysdk.business.scanQRCode #

功能

扫描二维码。

环境

平台 是否支持
iOS
Android
touch X
微信 X

返回参数

参数 类型 描述 备注
result string 扫描结果 扫描到的二维码链接

示例

hysdk.business.scanQRCode({
    success: function(res) {
        // res = { result: 'http://xxx.xxx.xxx' }
    },
    fail: function() {}
});

hysdk.business.openScheme #

功能

打开 scheme。

环境

平台 是否支持
iOS
Android
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
scheme string 跳转的 scheme 地址 常用参数

示例

hysdk.business.openScheme({
    scheme: 'qunariphone://xxx/yyy',
    success: function() {},
    fail: function() {}
});

Event #

hysdk.event.addEventListener #

功能

添加全局消息监听。一个消息在当前 webview 中可以监听多次,当消息触发时,会依次执行回调。

环境

平台 是否支持
iOS
Android
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
name string 监听的消息名称 名称必须是 xxx-xxx-xxx 的格式,推荐使用 bizname-hybridid-eventname
callback function 监听的回调 -

返回参数

参数 类型 描述 备注
name string 消息名称 -
data object 消息数据 -

注意

一些系统级的消息会发送全局的消息,目前有:

  • networkChange:网络发生变化时,返回值为: {data: {type: 'wifi/2G/3G/4G/unknown'}, name: 'networkChange'}

示例

var _callback = function(data) { alert(data); }
var _callback2 = function (data) { alert(data); }

// 在同一个页面里,对同一个 name 添加两个监听
hysdk.event.addEventListener({
    name: 'biz-hybridid-test',
    callback: _callback,
    success: function (res) {},
    fail: function () {}
});

hysdk.event.addEventListener({
    name: 'biz-hybridid-test',
    callback: _callback2,
    success: function (res) {},
    fail: function () {}
});

hysdk.event.removeEventListener #

功能

移除消息监听。一个消息在当前 webview 中可以监听多次,可以移除某一次监听,也可以移除所有的监听。如果有 handler 参数,则会移除指定 handler 的监听;如果没有 handler 参数,则会移除所有的监听。

环境

平台 是否支持
iOS
Android
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
name string 移除监听的消息名称 名称必须是 xxx-xxx-xxx 的格式,推荐使用 bizname-hybridid-eventname
handler function 需要移除的监听的 callback X 如果有该参数,则会移除指定的 handler;如果没有,则移除所有监听

示例

// 移除 xxx 的单个监听 _callback2
hysdk.event.removeEventListener({
    name: 'biz-hybridid-test',
    handler: _callback2,
    success: function (res) {},
    fail: function () {}
});

// 移除 xxx 的所有监听
hysdk.event.removeEventListener({
    name: 'biz-hybridid-test',
    success: function (res) {},
    fail: function () {}
});

hysdk.event.sendEvent #

功能

发送全局消息。

环境

平台 是否支持
iOS
Android
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
name string 发送的消息名称 名称必须是 xxx-xxx-xxx 的格式,推荐使用 bizname-hybridid-eventname
data object 发送的数据 X -

示例

hysdk.event.sendEvent({
    name: 'biz-hybridid-test',
    data: {
        info: 'some detail'
    },
    success: function (res) {},
    fail: function () {}
});

Geolocation #

hysdk.geolocation.getCurrentPosition #

功能

获取当前位置信息。

环境

平台 是否支持
iOS
Android
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
enableHighAccuracy bool 是否使用高精度 X false 非常用参数
timeout number 超时时长,单位毫秒 ms X 非常用参数,当定位时间超出此限制时,调用失败回调。单位:ms
maximumAge number 缓存时长,单位毫秒 ms X 0 非常用参数,可以接受的缓存定位结果时间,当上次定位的时间距今在设定值的范围内,则直接使用上次的定位结果。可用于快速定位、对精度要求不高的场景。单位:ms

返回参数

参数 类型 描述 备注
type string 位置信息类型 gps / baidu
timestamp number 时间戳
coords object 位置信息 -
coords.accuracy number 位置精度
coords.altitude number
coords.altitudeAccuracy number
coords.heading number
coords.latitude number 纬度 浮点数,范围为90 ~ -90
coords.longitude number 经度 浮点数,范围为180 ~ -180
coords.timestamp number
coords.velocity number
coords.speed number 仅android

示例

hysdk.geolocation.getCurrentPosition({
    success: function(res) {
        // ios
        // res = {
        //     "type": gps / bd09,
        //     "timestamp": 1503650073329.418,
        //     "coords": {
        //         "accuracy": 65, // 位置精度
        //         "altitude": 68.31856536865234,
        //         "altitudeAccuracy": 10,
        //         "heading": -1,
        //         "latitude": 39.97635468414903, // 纬度,浮点数,范围为90 ~ -90
        //         "longitude": 116.299878951932, // 经度,浮点数,范围为180 ~ -180。
        //         "timestamp": 1499051091483.203,
        //         "velocity": -1,
        //     }
        // }
        // adr
        // res = {
        //     "coords": {
        //          "accuracy": "-",
        //          "altitude": 5e-324,
        //          "altitudeAccuracy": "-",
        //          "heading": "-",
        //          "latitude": 39.983641,
        //          "longitude": 116.312441,
        //          "speed": 0,
        //          "timestamp": 1503650071178,
        //          "velocity": "-"
        //      },
        //      "timestamp": 1503650071178,
        //      "type": "baidu"
        //  }
    },
    fail: function() {}
});

hysdk.navigator.refresh #

功能

设置导航栏样式。

环境

平台 是否支持
iOS
Android
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
left object 左侧配置 X - 只支持返回按钮,可自定义颜色
left.tagname string 图标名称 N left
left.color string 颜色 N #FFFFFF
left.highlightColor string 高亮颜色 N #80FFFFFF
center string 中间标题配置 N - 导航栏标题位置配置
center.type string 标题类型 N normal 包括 normal / text-image
center.param(normal时) object 标题配置 N -
center.param.tagname string 图标名称 N title
center.param.title string 标题 N ''
center.param.color string 颜色 N #FFFFFF
center.param.highlightColor string 高亮颜色 N #80FFFFFF
center.param(text-image时) object 标题配置 N -
center.param.tagname string 图标名称 N title
center.param.title string 标题 N ''
center.param.color string 颜色 N #FFFFFF
center.param.highlightColor string 高亮颜色 N #80FFFFFF
center.param.imageURL string 图片地址 N
center.param.icon string N
center.param.iconColor string N #FFFFFF
center.param.iconHighlightColor string N #80FFFFFF

示例

hysdk.navigator.refresh({
    left: {
        tagname: '',
        color: '',
        highlightColor: ''
    },
    center: {
        type: 'text-image', // normal / text-image,
        param: { // normal类型时
            tagname: '',
            title: '',
            color: '',
            highlightColor: ''
        },
        param: { // text-image类型时
            tagname: '',
            title: '',
            color: '',
            highlightColor: '',
            imageURL: '',
            //icon qunar支持,ctrip不支持
            icon: '',
            iconColor: '',
            iconHighlightColor: ''
        }
    },
    right: [{
        tagname: '',
        imageURL: '',
        title: '',
        color: '',
        highlightColor: '',
        //icon qunar支持,ctrip不支持
        icon: '',
        iconColor: '',
        iconHighlightColor: ''
    }],
    success: function () { },
    fail: function () { }
});

hysdk.navigator.onClick #

功能

监听导航栏的点击事件。

环境

平台 是否支持
iOS
Android
touch X
微信 X

返回参数

参数 类型 描述 备注
tagname string 被点击部分的 tagname 在刷新导航栏时可以配置,默认为 left title right
callback function 是否阻止默认后退事件的回调 只针对返回键,true 时阻止默认返回,false 时不阻止

示例

hysdk.navigator.onClick(function(tagname, callback){
    // tagname
    // 可以通过 callback(true) 来拦截默认的后退事件
});

Share #

hysdk.share.shareToPlatform #

功能

分享到某个平台。

环境

平台 是否支持
iOS
Android
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
shareType string 分享平台 常用参数,包括:WechatTimeline:微信朋友圈
WechatFriends:微信好友
SinaWeibo:新浪微博
QQ:QQ
QQZone:QQ 空间(Qunar 暂时没有)
SMS:短信
Email:邮件
Copy:复制(Qunar 暂时没有)
OSMore:系统更多分享
linkUrl string 链接 X 非常用参数,如果有 linkUrl,会被当作链接分享;如果没有 linkUrl,有 imageUrl,当作 imageUrl 分享;如果没有 linkUrl 和 imageUrl,当作纯文本分享。
imageUrl string 图片 X 非常用参数
title string 标题 X 非常用参数
text string 内容 X 非常用参数
options object 额外参数 X 非常用参数

示例

hysdk.share.shareToPlatform({
    shareType: 'QQ',
    linkUrl: 'https://link.url',
    imageUrl: 'https://image.url',
    title: 'share title',
    text: 'share text',
    options: {},
    success: function() {},
    fail: function() {}
);

hysdk.share.share #

功能

呼起分享弹层,设置分享内容。

环境

平台 是否支持
iOS
Android
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
shareInfos array 分享信息 数组中每一项参照 share.shareToPlatform 的参数

注意:shareType 中添加 Default 类型。如果有 Default,则显示所有平台,默认配置为 Default 的配置;如果没有 Default,则只显示配置的平台。

示例

hysdk.share.share({
    shareInfos:[{
        shareType:"QQ",
        imageUrl:"http://share.csdn.net/uploads/24bd27fd3ad6a559873c4aff3bd64a60/24bd27fd3ad6a559873c4aff3bd64a60_thumb.jpg",
        title:"分享图书",
        text:"这本书的简介大概是这样",
        linkUrl:"http://csdn.net"
    }, {
        shareType:"WechatFriends",
        imageUrl:"http://share.csdn.net/uploads/24bd27fd3ad6a559873c4aff3bd64a60/24bd27fd3ad6a559873c4aff3bd64a60_thumb.jpg",
        title:"分享图书给微信",
        text:"这本书的简介是专门为微信定制",
        linkUrl:"http://csdn.net/w"
    }, {
        shareType:"Default", //表示其他未指定的平台,都适用该分享内容
        imageUrl:"http://share.csdn.net/uploads/24bd27fd3ad6a559873c4aff3bd64a60/24bd27fd3ad6a559873c4aff3bd64a60_thumb.jpg",
        title:"通用分享图书",
        text:"这本书的简介是为其他分享定制的",
        linkUrl:"http://csdn.net/common_test"
    }],
    options:{},
    success: function() {},
    fail: function() {}
});

Tool #

hysdk.tool.chooseContact #

功能

从通讯录选择联系人。

环境

平台 是否支持
iOS
Android
touch X
微信 X

返回参数

参数 类型 描述 备注
name string 姓名 -
phoneList array 电话 电话为一个列表,每一项是 { 标签: 号码 } 的格式
emailList string 邮箱 邮箱为一个列表,每一项是 { 标签: 邮箱 } 的格式

示例

hysdk.tool.chooseContact({
    success: function(res) {
        // res = {
        //     name: 'xxx',
        //     phoneList: {
        //         '家庭': '134-1111-1111',
        //         '工作': '134-2222-2222'
        //     },
        //     emailList: {
        //         '工作': 'xxx@xxx.xxx'
        //     }
        // }
    },
    fail: function() {}
});

hysdk.checkInstalledApp #

功能

检测 app 是否已安装。

环境

平台 是否支持
iOS
Android
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
apps array 需要检测的 app 列表 -
apps[N].name string 应用名称 X - 只支持下面列表中的
apps[N].androidPkgId string 安卓应用 id X - 当没有 name 时需要传递
apps[N].iosAppId string iOS 应用 id X - 当没有 name 时需要传递

支持的应用 name:WechatSinaWeiboAlipayBaiduMapAMapQQCTripTravelQunarTravelGoogleMaps

返回参数

返回参数是一个对象,key 为要检测的应用的 name,如果没有 name,则为应用的 androidPkgId/iosAppId。

示例

hysdk.tool.checkInstalledApp({
    apps: [{
        name: 'Wechat'
    }, {
        androidPkgId: 'test.Android',
        iosAppId: 'test.iOS'
    }],
    success: function(res){
        // res = {
        //     Wechat: true,
        //     androidPkgId: false 或 iosAppId: false
        // }
    },
    fail: function(){}
);

Webview #

hysdk.webview.push #

功能

打开新的 webview

环境

平台 是否支持
iOS
Android
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
url string webview 的地址
name string webview 的名称/标识 X 推荐使用 hy_hybridId_页面名称 的格式,一般场景无需指定,如果要回退到特定 webview 时可以通过该参数来指定 webview
animate string webview 打开动画 X rignt 包括:right(从右侧滑入)、bottom(从底部滑入)、none。默认为 rignt
naviBar object webview 导航栏配置 X - 导航栏配置只提供基础的配置参数,更复杂的配置可以通过 navigator.refresh 来配置
naviBar.type string 导航栏类型 X classical-blue 包括:none(无导航栏)、classical-blue(蓝色)、classical-white(白色)、custom(自定义颜色),默认为 XXX
naviBar.color string 导航栏颜色,rgb X - 当 naviBar.type 为 custom 时, 指定导航栏的颜色
naviBar.title string 导航栏标题 X -
options object 额外配置 X -
options.showLoading bool 是否显示 loading X true
callback function 返回到当前页时的回调 X iOS 通过后退手势返回到当前页时不会触发,可以通过 hysdk.webview.enableBackGuesture 来设置是否允许后退手势

示例

hysdk.webview.push({
    url: 'https://address.of.target.url/',
    name: 'nameOfView', // 建议格式:hy_模块名_页面名
    animate: 'bottom',
    naviBar: {
        type: 'classical-blue',
        color: '#ffffff',
        title: '标题'
    },
    options: {
        showLoading: false
    },
    callback: function(data) {
        // 回到当前页面时的回调
        // iOS 通过后退手势返回到当前页时不会触发
        // 可以通过 hysdk.webview.enableBackGuesture 来设置是否允许后退手势
    },
    success: function() {},
    fail: function() {}
});

hysdk.webview.pop #

功能

回退到指定的 webview,如果不指定 name,则回到上一个页面。

环境

平台 是否支持
iOS
Android
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
name string 回退的页面名称 X 非常用参数,比如不填则回到上一个页面
data object 传递给回退页面的参数 X 非常用参数

示例

hysdk.webview.pop({
    name: 'hy_hybridId_页面名称',
    data: {},
    success: function() {},
    fail: function() {}
});

hysdk.webview.showLoading #

功能

显示/隐藏 native 的 loading,会覆盖整个 webview。新打开 webview 时如果有 loading,此时不需要再手动关闭。

环境

平台 是否支持
iOS
Android
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
show bool 显示/隐藏 true:显示;false:隐藏。

示例

hysdk.webview.showLoading({
    show: false,
    success: function() {},
    fail: function() {}
});

hysdk.webview.enableBackGuesture #

功能

启用/禁用后退手势,仅 iOS 有效。

环境

平台 是否支持
iOS
Android X
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
enable bool 启用/禁用 true:启用;false:禁用。

示例

hysdk.webview.enableBackGuesture({
    enable: false,
    success: function() {},
    fail: function() {}
});

hysdk.webview.setName #

功能

设置 webview 名称,推荐使用 hy_hybridId_页面名称 的格式。

环境

平台 是否支持
iOS
Android
touch X
微信 X

参数

参数 类型 描述 必选 默认值 备注
name string webview 名称 推荐使用 hy_hybridId_页面名称 的格式

示例

hysdk.webview.setName({
    name: 'hy_hybridId_页面名称',
    success: function() {},
    fail: function() {}
});

Webview 事件 #

hysdk.webview.onShow #

功能

当页面显示时触发,包括第一次打开页面、回退到当前页面、从后台从后台激活时。

环境

平台 是否支持
iOS
Android
touch X
微信 X

示例

hysdk.webview.onShow(function(){
    // Do something    
});

hysdk.webview.onHide #

功能

当页面隐藏时触发。

环境

平台 是否支持
iOS
Android
touch X
微信 X

示例

hysdk.webview.onHide(function(){
    // Do something
});

hysdk.webview.onReceiveData #

功能

返回到当前页时触发,与 hysdk.webview.pushcallback 回调触发时机一致。

注意:iOS 通过后退手势返回到当前页时不会触发,可以通过 hysdk.webview.enableBackGuesture 来设置是否允许后退手势。

环境

平台 是否支持
iOS
Android
touch X
微信 X

示例

// A 打开 B ,从 B 返回 A 时:

// B 页面的代码
hysdk.webview.pop({
    data: {
        title: '123',
        detail: '123123123'
    }
});

// A 页面的代码
hysdk.webview.onReceiveData(function(data){
    // data : { title: '123', detail: '123123123' }
});