uni-app
的js API由标准ECMAScript的js API 和 uni 扩展 API 这两部分组成。
标准ecmascript的API非常多,本文档没有必要列全,仅以console、settimeout为例做简要说明。扩展 API 命名与小程序相同。
uni-app
的js代码,h5端运行于浏览器中。非h5端,Android平台运行在v8引擎中,iOS平台运行在iOS自带的jscore引擎中。
非H5端,虽然不支持window、document、navigator等浏览器的js API,但也支持标准ECMAScript。
开发者不要把浏览器里的js等价于标准js。
ECMAScript由Ecma国际管理,是基础js语法。浏览器基于标准js扩充了window、document等js API;Node.js基于标准js扩充了fs等模块;小程序也基于标准js扩展了各种wx.xx、my.xx、swan.xx的API。
所以uni-app的非H5端,一样支持标准js,支持if、for等语法,支持字符串、数组、时间等变量及各种处理方法。仅仅是不支持浏览器专用对象。
除了uni-app框架内置的跨端API,各端自己的特色API也可通过条件编译自由使用。
各端特色API规范参考各端的开发文档。其中App端的JS API参考html5plus.org;uni-app也支持通过扩展原生插件来丰富App端的开发能力,具体参考插件开发文档
各平台的API新增,不需要uni-app升级,开发者就可以直接使用。
- uni.on 开头的 API 是监听某个事件发生的 API 接口,接受一个 CALLBACK 函数作为参数。当该事件触发时,会调用 CALLBACK 函数。
- 如未特殊约定,其他 API 接口都接受一个 OBJECT 作为参数。
- OBJECT 中可以指定 success,fail,complete 来接收接口调用结果。
- 平台差异说明若无特殊说明,则表示所有平台均支持。
uni-app 对部分 API 进行了 Promise 封装,返回数据的第一个参数是错误对象,第二个参数是返回数据。
详细策略如下:
- 异步的方法,如果不传入 success、fail、complete 等 callback 参数,将以 Promise 返回数据。例如:uni.getImageInfo()
- 异步的方法且有返回对象,如果希望获取返回对象,必须至少传入一项 success、fail、complete 等 callback 参数。例如:uni.connectSocket()
- 同步的方法(即以 sync 结束),不封装 Promise。例如:uni.getSystemInfoSync()
- 以 create 开头的方法,不封装 Promise。例如:uni.createMapContext()
- 以 manager 结束的方法,不封装 Promise。例如:uni.getBackgroundAudioManager()
使用示例:
// 默认方式
uni.request({
url: 'https://www.example.com/request',
success: (res) => {
console.log(res.data);
}
});
// Promise
uni.request({
url: 'https://www.example.com/request'
})
.then(data => {//data为一个数组,数组第一项为错误信息,第二项为返回数据
var [error, res] = data;
console.log(res.data);
})
// Await
function async request () {
var [error, res] = await uni.request({
url: 'https://www.example.com/request'
});
console.log(res.data);
}
API | 说明 |
---|---|
uni.request | 发起网络请求 |
API | 说明 |
---|---|
uni.uploadFile | 上传文件 |
uni.downloadFile | 下载文件 |
API | 说明 |
---|---|
uni.connectSocket | 创建 WebSocket 连接 |
uni.onSocketOpen | 监听 WebSocket 打开 |
uni.onSocketError | 监听 WebSocket 错误 |
uni.sendSocketMessage | 发送 WebSocket 消息 |
uni.onSocketMessage | 接受 WebSocket 消息 |
uni.closeSocket | 关闭 WebSocket 连接 |
uni.onSocketClose | 监听 WebSocket 关闭 |
API | 说明 |
---|---|
SocketTask.send | 通过 WebSocket 连接发送数据 |
SocketTask.close | 关闭 WebSocket 连接 |
SocketTask.onOpen | 监听 WebSocket 连接打开事件 |
SocketTask.onClose | 监听 WebSocket 连接关闭事件 |
SocketTask.onError | 监听 WebSocket 错误事件 |
SocketTask.onMessage | 监听 WebSocket 接受到服务器的消息事件 |
API | 说明 |
---|---|
uni.chooseImage | 从相册选择图片,或者拍照 |
uni.previewImage | 预览图片 |
uni.getImageInfo | 获取图片信息 |
uni.saveImageToPhotosAlbum | 保存图片到系统相册 |
API | 说明 |
---|---|
uni.getRecorderManager | 录音管理 |
API | 说明 |
---|---|
uni.getBackgroundAudioManager | 背景音频播放管理 |
API | 说明 |
---|---|
uni.createInnerAudioContext | 音频组件管理 |
API | 说明 |
---|---|
uni.chooseVideo | 从相册选择视频,或者拍摄 |
uni.chooseMedia | 拍摄或从手机相册中选择图片或视频。 |
uni.saveVideoToPhotosAlbum | 保存视频到系统相册 |
uni.createVideoContext | 视频组件管理 |
API | 说明 |
---|---|
uni.createCameraContext | 相机组件管理 |
API | 说明 |
---|---|
uni.createLivePlayerContext | 直播组件管理 |
API | 说明 |
---|---|
uni.saveFile | 保存文件 |
uni.getSavedFileList | 获取已保存的文件列表 |
uni.getSavedFileInfo | 获取已保存的文件信息 |
uni.removeSavedFile | 删除已保存的文件信息 |
uni.getFileInfo | 获取文件信息 |
uni.openDocument | 打开文件 |
API | 说明 |
---|---|
uni.getStorage | 获取本地数据缓存 |
uni.getStorageSync | 获取本地数据缓存 |
uni.setStorage | 设置本地数据缓存 |
uni.setStorageSync | 设置本地数据缓存 |
uni.getStorageInfo | 获取本地缓存的相关信息 |
uni.getStorageInfoSync | 获取本地缓存的相关信息 |
uni.removeStorage | 删除本地缓存内容 |
uni.removeStorageSync | 删除本地缓存内容 |
uni.clearStorage | 清理本地数据缓存 |
uni.clearStorageSync | 清理本地数据缓存 |
API | 说明 |
---|---|
uni.getLocation | 获取当前位置 |
uni.chooseLocation | 打开地图选择位置 |
API | 说明 |
---|---|
uni.openLocation | 打开内置地图 |
API | 说明 |
---|---|
uni.createMapContext | 地图组件控制 |
API | 说明 |
---|---|
uni.getSystemInfo | 获取系统信息 |
uni.getSystemInfoSync | 获取系统信息 |
uni.canIUse | 判断应用的 API,回调,参数,组件等是否在当前版本可用 |
API | 说明 |
---|---|
uni.onMemoryWarning | 监听内存不足告警事件 |
API | 说明 |
---|---|
uni.getNetworkType | 获取网络类型 |
uni.onNetworkStatusChange | 监听网络状态变化 |
API | 说明 |
---|---|
uni.onAccelerometerChange | 监听加速度数据 |
uni.startAccelerometer | 开始监听加速度数据 |
uni.stopAccelerometer | 停止监听加速度数据 |
API | 说明 |
---|---|
uni.onCompassChange | 监听罗盘数据 |
uni.startCompass | 开始监听罗盘数据 |
uni.stopCompass | 停止监听罗盘数据 |
API | 说明 |
---|---|
uni.onGyroscopeChange | 监听陀螺仪数据 |
uni.startGyroscope | 开始监听陀螺仪数据 |
uni.stopGyroscope | 停止监听陀螺仪数据 |
API | 说明 |
---|---|
uni.makePhoneCall | 拨打电话 |
API | 说明 |
---|---|
uni.scanCode | 扫码 |
API | 说明 |
---|---|
uni.setClipboardData | 设置剪贴板内容 |
uni.getClipboardData | 获取剪贴板内容 |
API | 说明 |
---|---|
uni.setScreenBrightness | 设置屏幕亮度 |
uni.getScreenBrightness | 获取屏幕亮度 |
uni.setKeepScreenOn | 设置是否保持常亮状态 |
API | 说明 |
---|---|
uni.onUserCaptureScreen | 监听用户截屏事件 |
API | 说明 |
---|---|
uni.vibrate | 使手机发生振动 |
uni.vibrateLong | 使手机发生较长时间的振动 |
uni.vibrateShort | 使手机发生较短时间的振动 |
API | 说明 |
---|---|
uni.addPhoneContact | 添加手机通讯录 |
API | 说明 |
---|---|
uni.openBluetoothAdapter | 初始化蓝牙模块 |
uni.startBluetoothDevicesDiscovery | 搜寻附近的蓝牙外围设备 |
uni.onBluetoothDeviceFound | 监听寻找到新设备的事件 |
uni.stopBluetoothDevicesDiscovery | 停止搜寻 |
uni.onBluetoothAdapterStateChange | 监听蓝牙适配器状态变化事件 |
uni.getConnectedBluetoothDevices | 根据 uuid 获取处于已连接状态的设备 |
uni.getBluetoothDevices | 获取已发现的蓝牙设备 |
uni.getBluetoothAdapterState | 获取本机蓝牙适配器状态 |
uni.closeBluetoothAdapter | 关闭蓝牙模块 |
API | 说明 |
---|---|
uni.writeBLECharacteristicValue | 向低功耗蓝牙设备特征值中写入二进制数据 |
uni.readBLECharacteristicValue | 读取低功耗蓝牙设备的特征值的二进制数据值 |
uni.onBLEConnectionStateChange | 监听低功耗蓝牙连接状态的改变事件 |
uni.onBLECharacteristicValueChange | 监听低功耗蓝牙设备的特征值变化事件 |
uni.notifyBLECharacteristicValueChange | 监听低功耗蓝牙设备的特征值变化事件 |
uni.getBLEDeviceServices | 获取蓝牙设备所有服务(service) |
uni.getBLEDeviceCharacteristics | 获取蓝牙设备某个服务中所有特征值(characteristic) |
uni.createBLEConnection | 连接低功耗蓝牙设备 |
uni.closeBLEConnection | 断开与低功耗蓝牙设备的连接 |
API | 说明 |
---|---|
uni.onBeaconServiceChange | 监听 iBeacon 服务状态变化事件 |
uni.onBeaconUpdate | 监听 iBeacon 设备更新事件 |
uni.getBeacons | 获取所有已搜索到的 iBeacon 设备 |
uni.startBeaconDiscovery | 停止搜索附近的 iBeacon 设备 |
uni.stopBeaconDiscovery | 开始搜索附近的 iBeacon 设备 |
API | 说明 |
---|---|
uni.startSoterAuthentication | 开始生物认证 |
uni.checkIsSupportSoterAuthentication | 获取本机支持的生物认证方式 |
uni.checkIsSoterEnrolledInDevice | 获取设备内是否录入如指纹等生物信息的接口 |
API | 说明 |
---|---|
uni.showToast | 显示提示框 |
uni.showLoading | 显示加载提示框 |
uni.hideToast | 隐藏提示框 |
uni.hideLoading | 隐藏提示框 |
uni.showModal | 显示模态弹窗 |
uni.showActionSheet | 显示菜单列表 |
API | 说明 |
---|---|
uni.setNavigationBarTitle | 设置当前页面标题 |
uni.setNavigationBarColor | 设置页面导航条颜色 |
uni.showNavigationBarLoading | 显示导航条加载动画 |
uni.hideNavigationBarLoading | 隐藏导航条加载动画 |
API | 说明 |
---|---|
uni.setTabBarItem | 动态设置 tabBar 某一项的内容 |
uni.setTabBarStyle | 动态设置 tabBar 的整体样式 |
uni.hideTabBar | 隐藏 tabBar |
uni.showTabBar | 显示 tabBar |
uni.setTabBarBadge | 为 tabBar 某一项的右上角添加文本 |
uni.removeTabBarBadge | 移除 tabBar 某一项右上角的文本 |
uni.showTabBarRedDot | 显示 tabBar 某一项的右上角的红点 |
uni.hideTabBarRedDot | 隐藏 tabBar 某一项的右上角的红点 |
API | 说明 |
---|---|
uni.setBackgroundColor | 动态设置窗口的背景色。 |
uni.setBackgroundTextStyle | 动态设置下拉背景字体、loading 图的样式。 |
API | 说明 |
---|---|
uni.createAnimation | 创建一个动画实例 animation。调用实例的方法来描述动画。最后通过动画实例的export方法导出动画数据传递给组件的animation属性。 |
API | 说明 |
---|---|
uni.pageScrollTo | 将页面滚动到目标位置。 |
API | 说明 |
---|---|
uni.createCanvasContext | 创建绘图上下文 |
uni.canvasToTempFilePath | 将画布内容保存成文件 |
uni.canvasGetImageData | 获取画布图像数据 |
uni.canvasPutImageData | 设置画布图像数据 |
API | 说明 |
---|---|
onPullDownRefresh | 监听该页面用户下拉刷新事件 |
uni.startPullDownRefresh | 开始下拉刷新 |
uni.stopPullDownRefresh | 停止当前页面下拉刷新 |
API | 说明 |
---|---|
uni.createSelectorQuery | 创建查询请求 |
selectorQuery.select | 根据选择器选择单个节点 |
selectorQuery.selectAll | 根据选择器选择全部节点 |
selectorQuery.selectViewport | 选择显示区域 |
selectorQuery.exec | 执行查询请求 |
nodesRef.boundingClientRect | 获取布局位置和尺寸 |
nodesRef.scrollOffset | 获取滚动位置 |
nodesRef.fields | 获取任意字段 |
API | 说明 |
---|---|
uni.createIntersectionObserver | 创建 IntersectionObserver 对象 |
intersectionObserver.relativeTo | 指定参照节点 |
intersectionObserver.relativeToViewport | 指定页面显示区域作为参照区域 |
intersectionObserver.observe | 指定目标节点并开始监听 |
intersectionObserver.disconnect | 停止监听 |
API | 说明 |
---|---|
uni.navigateTo | 保留当前页面,跳转到应用内的某个页面,使用uni.navigateBack可以返回到原页面 |
uni.redirectTo | 关闭当前页面,跳转到应用内的某个页面 |
uni.reLaunch | 关闭所有页面,打开到应用内的某个页面 |
uni.switchTab | 跳转到 tabBar 页面,并关闭其他所有非 tabBar 页面 |
uni.navigateBack | 关闭当前页面,返回上一页面或多级页面 |
API | 说明 |
---|---|
uni.getProvider | 获取服务供应商 |
uni.login | 登录 |
uni.getUserInfo | 获取用户信息 |
uni.share | 分享 |
uni.shareWithSystem | 使用系统分享 |
uni.requestPayment | 支付 |
uni.subscribePush | 开启推送 |
uni.unsubscribePush | 关闭推送 |
uni.onPush | 监听透传数据 |
uni.offPush | 移除监听透传数据 |
API | 说明 |
---|---|
uni.requireNativePlugin | 引入 App 原生插件 |
API | 说明 |
---|---|
uni.authorize | 提前向用户发起授权请求 |
API | 说明 |
---|---|
uni.openSetting | 调起客户端小程序设置界面,返回用户设置的操作结果。 |
uni.getSetting | 获取用户的当前设置。 |
API | 说明 |
---|---|
uni.chooseAddress | 获取用户收货地址 |
API | 说明 |
---|---|
uni.chooseInvoiceTitle | 选择用户的发票抬头,需要用户授权 scope.invoiceTitle。 |
API | 说明 |
---|---|
uni.navigateToMiniProgram | 打开另一个小程序。 |
uni.navigateBackMiniProgram | 跳转回上一个小程序,只有当另一个小程序跳转到当前小程序时才会能调用成功。 |
API | 说明 |
---|---|
addTemplate | 组合模板并添加至帐号下的个人模板库。 |
deleteTemplate | 删除帐号下的某个模板。 |
getTemplateLibraryById | 获取模板库某个模板标题下关键词库。 |
getTemplateLibraryList | 获取APP模板库标题列表 |
getTemplateList | 获取帐号下已存在的模板列表。 |
sendTemplateMessage | 发送模板消息 |
alipay.open.app.mini.templatemessage.send | 支付宝小程序通过 openapi 给用户触达消息,主要为支付后的触达(通过消费id)和用户提交表单后的触达(通过formId)。 |
API | 说明 |
---|---|
uni.getUpdateManager | 返回全局唯一的版本更新管理器对象: updateManager,用于管理小程序更新。 |
API | 说明 |
---|---|
uni.setEnableDebug | 设置是否打开调试开关。此开关对正式版也能生效。 |
API | 说明 |
---|---|
uni.getExtConfig | 获取第三方平台自定义的数据字段。 |
uni.getExtConfigSync | uni.getExtConfig 的同步版本。 |