框架提供丰富的 API,可以方便的调起客户端提供的能力,如获取用户信息,本地存储,支付功能等。

JS API命名与小程序相同。各端受自身限制,可能某些API无法使用,具体见每个API的兼容性说明。

除了uni-app框架内置的跨端API,各端自己的特色API也可通过条件编译自由使用。

各端特色API规范参考各端的开发文档。其中App端的JS API参考html5plus.org;uni-app也支持通过扩展原生插件来丰富App端的开发能力,具体参考插件开发文档

说明

  • uni.on 开头的 API 是监听某个事件发生的 API 接口,接受一个 CALLBACK 函数作为参数。当该事件触发时,会调用 CALLBACK 函数。
  • 如未特殊约定,其他 API 接口都接受一个 OBJECT 作为参数。
  • OBJECT 中可以指定 success,fail,complete 来接收接口调用结果。
  • 平台差异说明若无特殊说明,则表示所有平台均支持。

Promise 封装

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()使用示例:
  1. // 默认方式
  2. uni.request({
  3. url: 'https://www.example.com/request',
  4. success: (res) => {
  5. console.log(res.data);
  6. }
  7. });
  8. // Promise
  9. uni.request({
  10. url: 'https://www.example.com/request'
  11. })
  12. .then(data => {//data为一个数组,数组第一项为错误信息,第二项为返回数据
  13. var [error, res] = data;
  14. console.log(res.data);
  15. })
  16. // Await
  17. function async request () {
  18. var [error, res] = await uni.request({
  19. url: 'https://www.example.com/request'
  20. });
  21. console.log(res.data);
  22. }

API 列表

网络

发起请求
API说明
uni.request发起网络请求
上传、下载
API说明
uni.uploadFile上传文件
uni.downloadFile下载文件
WebSocket
API说明
uni.connectSocket创建 WebSocket 连接
uni.onSocketOpen监听 WebSocket 打开
uni.onSocketError监听 WebSocket 错误
uni.sendSocketMessage发送 WebSocket 消息
uni.onSocketMessage接受 WebSocket 消息
uni.closeSocket关闭 WebSocket 连接
uni.onSocketClose监听 WebSocket 关闭
SocketTask
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.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断开与低功耗蓝牙设备的连接
iBeacon
API说明
uni.onBeaconServiceChange监听 iBeacon 服务状态变化事件
uni.onBeaconUpdate监听 iBeacon 设备更新事件
uni.getBeacons获取所有已搜索到的 iBeacon 设备
uni.startBeaconDiscovery停止搜索附近的 iBeacon 设备
uni.stopBeaconDiscovery开始搜索附近的 iBeacon 设备

界面

交互反馈
API说明
uni.showToast显示提示框
uni.showLoading显示加载提示框
uni.hideToast隐藏提示框
uni.hideLoading隐藏提示框
uni.showModal显示模态弹窗
uni.showActionSheet显示菜单列表
设置导航条
API说明
uni.setNavigationBarTitle设置当前页面标题
uni.setNavigationBarColor设置页面导航条颜色
uni.showNavigationBarLoading显示导航条加载动画
uni.hideNavigationBarLoading隐藏导航条加载动画
设置TabBar
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.setBackgroundColor动态设置下拉背景字体、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.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.getExtConfigSyncuni.getExtConfig 的同步版本。

发现错误?想参与编辑?在 GitHub 上编辑此页面!