全部产品
Search

搜索本产品

    SuperApp：规范与约束

    文档中心

    SuperApp：规范与约束

    更新时间：Aug 29, 2024

    本文介绍接入WindVane相关JS API时的规范和约束。

    路由规范

    由于WindVane小程序需要下载到本地进行离线加载，所以对路由使用有一定约束。

    • 如果您使用React开发小程序，需要使用HashHistory路由，不能使用BrowserHistory路由。

    • 如果您使用Vue开发小程序，需要使用Hash路由，不能使用History路由。

    原因是BrowserHistory、History均需要server端支持，而WindVane小程序是本地离线加载，没有对应的server端服务。

    UA规范

    WindVane会在所设置的默认UA后面跟上WindVane标记、WindVaneSDK的版本号、客户端补充UA和当前屏幕的分辨率，便于通过判断UA的方式来检查环境。

    完整的UA格式为：默认UA （App名称/App版本号）WindVane/WindVaneSDK版本号 客户端补充UA 分辨率宽x分辨率高。

    Android UA示例：

    Mozilla/5.0 (Linux; Android 10; TAS-AN00 Build/HUAWEITAS-AN00; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/88.0.4324.93 Mobile Safari/537.36 TTID/aaa WindVane/8.5.0

    iOS UA示例：

    Mozilla\/5.0 (iPhone; CPU iPhone OS 15_5 like Mac OS X) AppleWebKit\/605.1.15 (KHTML, like Gecko) Mobile\/19F70 AliApp(EMASDemo\/2.0.0) WindVane\/8.6.1 TBIOS 1170x2532

    • WindVane iOS需要通过setAppUA方法自行设置客户端补充UA，且分辨率中使用的是小写字母x。

    • WindVane Android没有提供设置客户端补充UA的方法，分辨率中使用的是大写字母X。

    重要

    客户端补充UA不可作为识别iOS/Android平台或客户端版本的依据。

    JSAPI规范

    使用 window.WindVane.call(className, methodName, params, successCallback, failureCallback, timeout) 来调用客户端提供的功能。

    说明

    JSAPI不支持在iframe内部调用。

    输入参数

    类型

    名称

    描述

    string

    className

    要调用的客户端类名。

    string

    methodName

    要调用的客户端方法名。

    object

    params

    要传递给客户端的参数。

    function

    successCallback

    执行成功后的回调。

    function

    failureCallback

    执行失败后的回调。

    number

    timeout

    可选，执行超时，超时后自动以 {ret:['HY_TIMEOUT']} 参数调用失败回调。

    successCallback和failureCallback都是由Native调用过来的，因此如果需要try...catch捕获异常，需要将捕获写到回调函数内部。

    为了简便起见，文档中会将要调用的客户端类名和方法，记作className.methodName 的格式。

    回调参数如果成功执行客户端接口，则进入success回调，否则进入failure回调，回调函数的参数与被调用的接口相关。

    可能的回调ret回调参数中可能包含ret属性，表示此次执行的状态，其可能的值为：

    值

    描述

    'HY_SUCCESS'

    表示API执行成功了，该值只会在success回调中使用。

    'HY_CLOSED'

    表示JS Bridge功能被强制关闭，一般由于页面URL不在信任域名内，或Native端未开启JSBridge功能，请检查URL或者联系H5的容器Native开发排查。

    'HY_NO_HANDLER'

    表示当前客户端没有提供这个API，请检查调用的JSBridge是否正确，并联系JSBridge的Native提供方排查。

    'HY_PARAM_ERR'

    表示传入的参数错误，请检查传入的参数是否有误。

    'HY_NO_PERMISSION'

    表示当前页面没有权限调用这个接口。

    'HY_FAILED'

    表示API执行失败了，请联系JS Bridge的Native提供方排查。

    'HY_EXCEPTION'

    表示API执行时发生了异常，请联系JS Bridge的Native提供方排查。

    'HY_USER_DENIED'

    表示当前API缺少用户授权，例如需要访问相册的接口，但用户并未允许客户端访问相册。

    'HY_USER_CANCELLED'

    表示用户主动取消了当前API的功能执行。

    'HY_RET_PHOTO_CANCLE'

    表示使用WVCamera提供的接口拍照时，被用户取消。

    'HY_TIMEOUT'

    表示JSBridge调用超时。

    'HY_RESULT_PARSE_ERROR'

    表示Native传递给H5的数据出现格式错误

    'HY_NOT_IN_WINDVANE'

    表示当前不是WindVane环境（如浏览器），或者客户端未正确提供WindVane的UserAgent。也有可能是页面 JS 错误的修改了windvane.js 中的环境变量（例如设置了 WindVane.isAvailable = false）。

    'HY_NOT_SUPPORT_DEVICE'

    表示JSBridge在不支持的设备中（如浏览器）被调用。也有可能是页面JS错误的修改了windvane.js中的环境变量（例如设置了 WindVane.isAvailable = false）。

    'HY_NO_HANDLER_ON_WP'

    表示JSBridge在不支持的Windows设备中（如浏览器）被调用。

    'WV_ERR::PARAM_PARSE_ERROR'

    表示Native传递给H5的数据出现格式错误。

    根据调用的JSAPI的不同，ret属性可能不存在，可能是一个字符串，也可能是一个数组，其中ret[0]包含了客户端接口的执行状态。 并不是所有JSAPI都会调用回调函数，这与客户端的实现有关。JSAPI文档中会指出什么情况下会进入成功回调或失败回调。