Uniapp – API 基本使用说明

tzming • 2023-09-05 • 前端, 小程序 • 264 阅读

基础

console 日志输出

debug

向控制台打印 debug 日志

注：App 端 debug 方法等同于 log 方法。

log

向控制台打印 log 日志

info

向控制台打印 info 日志

warn

向控制台打印 warn 日志

error

向控制台打印 error 日志

setTimeout 定时器

设定一个定时器。在定时到期以后执行注册的回调函数

参数说明

参数	类型	必填	说明
callback	Function	是	回调函数
delay	Number	否	延迟的时间，函数的调用会在该延迟之后发生，单位 ms
rest	Any	否	param1, param2, ..., paramN 等附加参数，它们会作为参数传递给回调函数

返回值

返回值	类型	说明
timeoutID	Number	定时器的编号，这个值可以传递给 clearTimeout 来取消该定时

clearTimeout(timeoutID)

取消由 setTimeout 设置的定时器。

参数说明

参数	类型	必填	说明
timeoutID	Number	是	要取消的定时器的 ID

setInterval(callback, delay, rest)

设定一个定时器。按照指定的周期（以毫秒计）来执行注册的回调函数

参数说明

参数	类型	必填	说明
callback	Function	是	回调函数
delay	Number	否	执行回调函数之间的时间间隔，单位 ms
rest	Any	否	param1, param2, ..., paramN 等附加参数，它们会作为参数传递给回调函数

返回值

返回值	类型	说明
intervalID	Number	定时器的编号，这个值可以传递给 clearInterval 来取消该定时

clearInterval(intervalID)

取消由 setInterval 设置的定时器。

参数说明

参数	类型	必填	说明
intervalID	Number	是	要取消的定时器的 ID

uni.base64ToArrayBuffer(base64)

将 Base64 字符串转成 ArrayBuffer 对象

参数说明

参数	类型	必填	说明
base64	String	是	要转化成 ArrayBuffer 对象的 Base64 字符串

uni.arrayBufferToBase64(arrayBuffer)

将 ArrayBuffer 对象转成 Base64 字符串

参数说明

参数	类型	必填	说明
arrayBuffer	ArrayBuffer	是	要转换成 Base64 字符串的 ArrayBuffer 对象

示例：

const arrayBuffer = new Uint8Array([55, 55, 55])
const base64 = uni.arrayBufferToBase64(arrayBuffer)

小程序启动

uni.getLaunchOptionsSync()

获取启动时的参数。返回值与App.onLaunch的回调参数一致

返回参数说明

参数名	类型	说明	平台差异说明
path	String	启动的路径(代码包路径，注意：App 端开发过程中热更新会直达当前页面，此时启动路径为当前页面路径)	其他平台均支持，`抖音小程序(1.12.0+)`
scene	Number	启动时的场景值，具体值含义请查看各平台文档说明。App、web端恒为 1001。钉钉小程序在 IDE 恒为0000，真机不支持。	其他平台均支持，`抖音小程序(1.12.0+)`
query	Object	启动时的 query 参数	其他平台均支持，`抖音小程序(1.12.0+)`
referrerInfo	Object	来源信息。如果没有则返回 `{}`	其他平台均支持，`抖音小程序(1.15.0+)`，`飞书小程序不支持`，`钉钉小程序不支持`
channel	String	如果应用没有设置渠道标识，则返回空字符串。取值如下	`仅 App 支持`
launcher	String	应用启动来源。取值如下	`仅 App 支持`
forwardMaterials	Array<Object>	打开的文件信息数组，只有从聊天素材场景打开（scene为1173）才会携带该参数	`微信小程序`、`QQ小程序`
entryDataHash	string	群入口信息，通过群应用商店打开、群分享卡片打开的小程序可获得	`仅QQ小程序`
chatType	number	打开的文件信息数组，只有从聊天素材场景打开（scene为1173）才会携带该参数	`仅微信小程序`
apiCategory	string	API 类别	`仅微信小程序(2.20.0+)`
showFrom	number	唤起小程序的方式，目前取值固定为 10，表示通过 schema 唤起	`仅抖音小程序(1.90.0+)`
mode	'default' \| 'halfPage'	启动小程序的模式	`仅快手小程序`
subScene	string	子场景值(定义待补充)	`仅飞书小程序`

Object referrerInfo

属性	类型	说明	平台差异说明
appId	String	来源小程序 appId	其他平台均支持，`抖音小程序(1.15.0+)`
extraData	Object	来源小程序传过来的数据	其他平台均支持，`抖音小程序(1.15.0+)`

uni.getEnterOptionsSync()

获取启动时的参数。

小程序平台：如果当前小程序是冷启动，则返回值与 App.onLaunch 的回调参数一致；如果当前是热启动，则返回值与 App.onShow 一致。关于微信小程序冷启动热启动的概念，详见

返回参数说明

参数名	类型	说明	平台差异说明
path	String	启动的路径(代码包路径)	其他平台均支持，`抖音小程序(1.12.0+)`
scene	Number	启动时的场景值，具体值含义请查看各平台文档说明。App、web端恒为 1001。	其他平台均支持，`抖音小程序(1.12.0+)`
query	Object	启动时的 query 参数	其他平台均支持，`抖音小程序(1.12.0+)`
referrerInfo	Object	来源信息。如果没有则返回 `{}`	其他平台均支持，`抖音小程序(1.15.0+)`
channel	String	如果应用没有设置渠道标识，则返回空字符串。取值如下	`仅 App 支持`
launcher	String	应用启动来源。取值如下	`仅 App 支持`
forwardMaterials	Array<Object>	打开的文件信息数组，只有从聊天素材场景打开（scene为1173）才会携带该参数	`微信小程序`
chatType	number	打开的文件信息数组，只有从聊天素材场景打开（scene为1173）才会携带该参数	`仅微信小程序`
apiCategory	string	API 类别	`仅微信小程序(2.20.0+)`
showFrom	number	唤起小程序的方式，目前取值固定为 10，表示通过 schema 唤起	`仅抖音小程序(1.90.0+)`
mode	'default' \| 'halfPage'	启动小程序的模式	`仅快手小程序`

Object referrerInfo

属性	类型	说明	平台差异说明
appId	String	来源小程序 appId	其他平台均支持，`抖音小程序(1.15.0+)`
extraData	Object	来源小程序传过来的数据。	其他平台均支持，`抖音小程序(1.15.0+)`

uni.onPageNotFound(CALLBACK)

监听应用要打开的页面不存在事件。该事件与 App.onPageNotFound 的回调时机一致

callback 参数

属性	类型	说明
path	String	不存在页面的路径 (代码包路径)
query	Object	打开不存在页面的 query 参数
isEntryPage	Boolean	是否本次启动的首个页面（例如从分享等入口进来，首个页面是开发者配置的分享页面）

uni.onError(CALLBACK)

监听小程序错误事件。如脚本错误或 API 调用报错等。该事件与 App.onError 的回调时机与参数一致。

callback 参数

string error 错误信息，包含堆栈

uni.onAppShow(CALLBACK)

监听应用切前台事件。该事件与 App.onShow 的回调参数一致。

callback 参数

属性	类型	说明	平台差异说明
path	String	应用切前台的路径 (代码包路径)
scene	Number	应用切前台的场景值
query	Object	应用切前台的 query 参数
shareTicket	String	shareTicket	微信小程序
referrerInfo	String	来源信息
entryType	String	页面展现的来源标识，可取的值为: 'user'、'schema'、'sys'，对应代表的意义如下表。	百度小程序 2.10.7+
appURL	String	展现时的调起协议，仅当entryType值为 schema 时存在。	百度小程序 2.10.7+
entryDataHash	String	群入口信息，通过群应用商店打开、群分享卡片打开的小程序可获得。	qq小程序

referrerInfo 的结构

属性	类型	说明	平台差异说明
appId	String	来源小程序的appId
extraData	Object	来源小程序传过来的数据	微信小程序和qq小程序 scene=1037或1038时支持

uni.onAppHide(CALLBACK)

监听应用切后台事件。该事件与 App.onHide 的回调参数一致。

callback 无参数

uni.offPageNotFound(CALLBACK)

取消监听应用要打开的页面不存在事件。

callback 无参数

uni.offError(CALLBACK)

取消监听应用错误事件。

callback 无参数

uni.offAppShow(CALLBACK)

取消监听小程序切前台事件。

callback 无参数

uni.offAppHide(CALLBACK)

取消监听小程序切后台事件。

callback 无参数

系统设备操作

uni-app提供了异步(uni.getSystemInfo)和同步(uni.getSystemInfoSync)的2个API获取系统信息。

系统信息返回的内容非常多，各操作系统、各家小程序、各浏览器对它们的定义也不相同。uni-app里重新梳理了这些概念，同时为了向下兼容也保留了这些平台原来的概念，但不推荐使用。

按照运行环境层级排序，从底层向上，uni-app有6个概念：

device：运行应用的设备，如iphone、huawei
os：设备的操作系统，如 ios、andriod、windows、mac、linux
rom：基于操作系统的定制，Android系统特有概念，如miui、鸿蒙
host：运行应用的宿主程序，即OS和应用之间的运行环境，如浏览器、微信等小程序宿主、集成uniMPSDK的App。uni-app直接开发的app没有host概念
uni：uni-app框架相关的信息，如uni-app框架的编译器版本、运行时版本
app：开发者的应用相关的信息，如应用名称、版本

uni.getSystemInfo(OBJECT)

异步获取系统信息

OBJECT 参数说明：

参数名	类型	必填	说明
success	Function	是	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数分类	参数	说明	App平台值域	Web平台值域	小程序平台值域	备注	uni框架最低版本要求
device	deviceId	设备 id 。由 uni-app 框架生成并存储，清空 Storage 会导致改变
	deviceType	设备类型。如`phone`、`pad`、`pc`、`unknow`	详见	`phone`、`pad`、`pc`、`unknow`	`phone`、`pad`、`pc`		uni-app 3.4.10+
	deviceBrand	设备品牌。如：`apple`、`huawei`		不支持			uni-app 3.4.10+
	deviceModel	设备型号		部分设备无法获取			uni-app 3.4.10+
	deviceOrientation	设备方向	`竖屏 portrait`、`横屏 landscape`	`竖屏 portrait`、`横屏 landscape`	`竖屏 portrait`、`横屏 landscape`。仅微信百度小程序支持		uni-app 3.4.13+
	devicePixelRatio	设备像素比					uni-app 3.4.13+
os	osName	系统名称	ios、android	ios、android、windows、macos、linux	ios、android、windows、macos		uni-app 3.4.10+
	osVersion	操作系统版本。如 ios 版本，andriod 版本					uni-app 3.4.10+
	osLanguage	操作系统语言详见	Android仅支持主语言+地区：`zh-CN 中文简体`、iOS支持主语言+次语言+地区`zh-Hans-CN 中文简体`	与浏览器语言一致	不支持		uni-app 3.4.10+
	osTheme	操作系统主题	light、dark。iOS平台只有将应用主题设置为跟随系统时才能获取到系统的主题	不支持	不支持		uni-app 3.4.10+
	osAndroidAPILevel	Android 系统API库的版本。详情参考Android 官方文档	`仅 Android 支持`	不支持	不支持		uni-app 3.4.10+
rom	romName	rom 名称	Android 部分机型获取不到值，详见。iOS 不支持	不支持	不支持		uni-app 3.4.13+
	romVersion	rom 版本	Android 部分机型获取不到值，详见。iOS 不支持	不支持	不支持		uni-app 3.4.13+
browser	browserName	浏览器名称或App的webview名称	chrome(android)、wkwebview(ios)、x5webview(app打包x5引擎)	chrome、edge、safari、firefox	不支持		uni-app 3.4.10+
	browserVersion	浏览器版本、webview 版本			不支持		uni-app 3.4.10+
host	hostName	小程序宿主或uniMPSDK的集成宿主名称，如：`WeChat`、`FeiShu`	仅 UniMPSDK 支持	不支持	详见	微信小程序真机运行才有真值	uni-app 3.4.10+
	hostVersion	宿主版本。如：微信版本号	仅 UniMPSDK 支持	不支持	小程序宿主版本		uni-app 3.4.10+
	hostLanguage	宿主语言	仅 UniMPSDK 支持	不支持	小程序宿主语言		uni-app 3.4.10+
	hostTheme	宿主主题	`light`、`dark`。仅 UniMPSDK 支持	不支持	`light`、`dark`。前提是微信小程序全局配置"darkmode":true时才能获取		uni-app 3.4.10+
	hostFontSizeSetting	用户字体大小设置。以“我-设置-通用-字体大小”中的设置为准，单位：px	不支持	不支持	微信小程序、支付宝小程序、百度小程序、QQ小程序、抖音小程序(2.53.0+)		uni-app 3.4.13+
	hostPackageName	小程序宿主包名	仅 UniMPSDK 支持	不支持	不支持		uni-app 3.4.10+
	hostSDKVersion	uni小程序SDK版本、小程序客户端基础库版本	仅 UniMPSDK 支持	不支持			uni-app 3.4.13+
uni-app框架	uniPlatform	uni-app 运行平台，与条件编译平台相同。详见	app	`web`或`h5`	各家小程序，如`mp-weixin`		uni-app 3.4.10+
	uniCompileVersion	uni 编译器版本号。详见	`3.4.10`、`3.2.9` 等	`3.4.10`、`3.2.9` 等	`3.4.10`、`3.2.9` 等		uni-app 3.4.10+
	uniRuntimeVersion	uni 运行时版本。详见	`3.4.10`、`3.2.9` 等	`3.4.10`、`3.2.9` 等	`3.4.10`、`3.2.9` 等		uni-app 3.4.10+
app	appId	`manifest` 中应用appid，即DCloud appid。					uni-app 3.4.10+
	appName	`manifest` 中应用名称				和`抖音小程序`字段冲突，`抖音小程序`原字段与`hostName`一致	uni-app 3.4.10+
	appVersion	`manifest` 中应用版本名称。					uni-app 3.4.10+
	appVersionCode	`manifest` 中应用版本名号。					uni-app 3.4.10+
	appWgtVersion	应用资源（wgt）的版本名称。					uni-app 3.4.15+
	appLanguage	应用设置的语言	`en`、`zh-Hans`、`zh-Hant`、`fr`、`es`	`en`、`zh-Hans`、`zh-Hant`、`fr`、`es`	`en`、`zh-Hans`、`zh-Hant`、`fr`、`es`		uni-app 3.4.13+
其他	ua	userAgent标识			不支持		uni-app 3.4.10+
	screenWidth	屏幕宽度
	screenHeight	屏幕高度
	windowWidth	可使用窗口宽度
	windowHeight	可使用窗口高度
	windowTop	可使用窗口的顶部位置
	windowBottom	可使用窗口的底部位置
	statusBarHeight	手机状态栏的高度
	safeArea	在竖屏正方向下的安全区域。由于此属性理解和使用比较困难，更推荐使用 safeAreaInsets 属性。详见			微信、百度（开发者工具暂不支持，真机有效）、抖音、飞书、支付宝（iOS真机）、快手、QQ小程序、华为快应用
	safeAreaInsets	在竖屏正方向下的安全区域插入位置。与小程序定义的 safeArea 用途相同，但是规范参考 iOS 平台的 safeAreaInsets 更利于理解和使用。详见			微信、百度（开发者工具暂不支持，真机有效）、抖音、飞书、支付宝小程序（iOS真机）、华为快应用		uni-app 2.5.3+

某些小程序特殊的返回参数

参数	说明	平台差异说明
benchmarkLevel	设备性能等级。取值为：-2 或 0（该设备无法运行小游戏），-1（性能未知），>=1（设备性能值，该值越高，设备性能越好，目前最高不到50）	微信小程序Android版、QQ小程序Android版
batteryLevel	剩余电量百分比（仅 iOS 有效）	微信小程序
currentBattery	当前电量百分比	支付宝小程序
navigationBarHeight	导航栏的高度	百度小程序
titleBarHeight	标题栏高度	支付宝小程序
albumAuthorized	允许微信使用相册的开关（仅 iOS 有效）	微信小程序
cameraAuthorized	允许微信使用摄像头的开关	微信小程序
locationAuthorized	允许微信使用定位的开关	微信小程序
microphoneAuthorized	允许微信使用麦克风的开关	微信小程序
notificationAuthorized	允许微信通知的开关	微信小程序
notificationAlertAuthorized	允许微信通知带有提醒的开关（仅 iOS 有效）	微信小程序
notificationBadgeAuthorized	允许微信通知带有标记的开关（仅 iOS 有效）	微信小程序
notificationSoundAuthorized	允许微信通知带有声音的开关（仅 iOS 有效）	微信小程序
bluetoothEnabled	蓝牙的系统开关	微信小程序
locationEnabled	地理位置的系统开关	微信小程序
wifiEnabled	Wi-Fi 的系统开关	微信小程序
cacheLocation	上一次缓存的位置信息	百度小程序(安卓端最低基础库版本 3.40.4 ；iOS 最低支持版本 3.70.2)
storage	设备磁盘容量	支付宝小程序

不推荐使用的返回参数，仅为向下兼容保留

参数	说明	平台差异说明
pixelRatio	设备像素比
brand	设备品牌。uni-app 3.4.10+ 后该字段为全小写，可能要做兼容处理	App、微信小程序、百度小程序、抖音小程序、飞书小程序、QQ小程序
model	设备型号	全平台支持。Web 端部分设备无法获取具体型号
system	操作系统名称及版本，如Android 10
language	应用设置的语言
version	引擎版本号	Web不支持
platform	客户端平台，值域为：`ios`、`android`、`mac（3.1.10+）`、`windows（3.1.10+）`、`linux（3.1.10+）`
host	宿主平台	百度小程序
SDKVersion	客户端基础库版本	支付宝小程序和Web不支持
swanNativeVersion	宿主平台版本号	百度小程序
app	当前运行的客户端	支付宝小程序
AppPlatform	App平台	QQ小程序
fontSizeSetting	用户字体大小设置。以“我-设置-通用-字体大小”中的设置为准，单位：px	微信小程序、支付宝小程序、百度小程序、QQ小程序、抖音小程序(2.53.0+)

uniPlatform 返回值说明

值	生效条件
app	App
web	Web
mp-weixin	微信小程序
mp-alipay	支付宝小程序
mp-baidu	百度小程序
mp-toutiao	抖音小程序
mp-lark	飞书小程序
mp-qq	QQ小程序
mp-kuaishou	快手小程序
mp-jd	京东小程序
mp-360	360小程序
quickapp-webview	快应用通用(包含联盟、华为)
quickapp-webview-union	快应用联盟
quickapp-webview-huawei	快应用华为

uniCompileVersion编译器版本和 uniRuntimeVersion运行时版本，正常情况应该是一样的值，即uni-app的版本。

如果使用HBuilder自带的uni-app开发，该值即等同于HBuilder的版本；如果使用单独的uni-app cli开发，则等同于cli版本。

romName 返回值说明

值	解释
MIUI	小米
EMUI	华为
HarmonyOS	华为鸿蒙
Magic OS	荣耀
ColorOS	oppo
Funtouch OS	vivo
FLymeOS	魅族
SmartisanOS	锤子

注意：不同rom的版本号规则不同，比如MIUI版本号是V130，而HarmonyOS的版本号是2.0.0

hostName 返回值说明

值	解释
WeChat	微信
wxwork	微信企业版
百度宿主平台枚举值列表	百度
alipay	支付宝
amap	高德
DINGTALK	钉钉
UC	UC浏览器
QUARK	夸克浏览器
AK	阿里健康
YK	优酷
抖音宿主平台枚举值列表	抖音系列
qq	QQ
KUAISHOU	快手

safeArea 返回值说明

参数	类型	说明
left	Number	安全区域左上角横坐标
right	Number	安全区域右下角横坐标
top	Number	安全区域左上角纵坐标
bottom	Number	安全区域右下角纵坐标
width	Number	安全区域的宽度，单位逻辑像素
height	Number	安全区域的高度，单位逻辑像素

safeAreaInsets 的结构

参数	类型	说明
left	Number	安全区域左侧插入位置
right	Number	安全区域右侧插入位置
top	Number	安全区顶部插入位置
bottom	Number	安全区域底部插入位置

language 返回值说明

language的国际规范是BCP47规范，分为三段，主语言-次语言-地区。例如zh-Hans-CN，表示中文-简体-中国大陆

但除了主语言外，后两者均可省略。在不同平台，它们的省略规则也不相同。

app-ios，不省略，返回zh-Hans-CN
app-android、web、微信小程序，省略次语言，返回zh-CN
uni-app框架和应用的多语言，以及支付宝小程序，则用zh-Hans来表示简体中文

所以获取语言后，不能直接字符串比较，需要拆段比较，npm上也有专门做BCP47语言规范比较的库。

deviceId 返回值说明

Web、小程序、iOS，属于对用户隐私保护比较严格的平台，在这些平台很难获取有效的设备唯一标记。

Android也已经改进用户隐私保护。在极老的手机上可以无限制获取imei，在次老的手机上，获取imei等隐私信息时需要弹框让用户授权。新的Android手机（Android10以上）已经彻底无法获取imei了。

所以标记设备，大多只能依靠本地存储一个随机数来标记。

deviceId，在app-android平台，会根据优先使用imei、mac（仅在用户已授权的情况下，如果发现需要授权或未授权，则跳过此步骤），如果没有获取到就使用随机生成的标识。其他平台是直接使用随机生成的标识。

当使用本地存贮的随机数时，发生以下情况将导致deviceId失效：

卸载App
Android上重置App数据
浏览器清空缓存或开启隐私模式，

app下需要广告追踪的场景，在iOS上可以使用idfa、部分国产Android手机可以使用OAID

deviceModel 返回值说明

uni-app 3.5.1+ 版本规范了 deviceModel 返回值，例如之前返回 iPhone11ProMax 新版本返回值为 iPhone 11 Pro Max，各设备型号参考规范中 Generation 对应的值

注意：新机型刚推出一段时间会显示 Unknown，官方会尽快进行适配。

本API在其他小程序的文档链接：

示例：

uni.getSystemInfo({
	success: function (res) {
		console.log(res.appName)
	}
});

在不同平台 getSystemInfo 的返回值（表格较长，可缩放页面后拖动横向滚动条）

标明 - 的都为 undefined，其他值都与所列出项相同

字段名称	App-Android	App-iOS	h5	Android uniMPsdk	iOS uniMPsdk	mp-weixin	mp-alipay	mp-baidu	mp-toutiao
appId	__UNI__8BB4001	__UNI__8BB4001	__UNI__8BB4001	__UNI__8BB4001	__UNI__8BB4001	__UNI__8BB4001	__UNI__8BB4001	__UNI__8BB4001	__UNI__8BB4001
appName	test	test	test	test	test	test	test	test	test
appVersion	1.0.0	1.0.0	1.0.0	1.0.0	1.0.0	1.0.0	1.0.0	1.0.0	1.0.0
appVersionCode	100	100	100	100	100	100	100	100	100
appLanguage	zh-Hans	zh-Hans	zh-Hans	zh-Hans	zh-Hans	zh-Hans	zh-Hans	zh-Hans	zh-Hans
browserName	chrome	wkwebview	safari	chrome	wkwebview	-	-	-	-
browserVersion	96.0.4664.104	13.4.13	13.0.3	88.0.4324.93	15.4	-	-	-	-
deviceId	d3db0944da20f333	F791564F-853B-47B6-8CB8-27FF59315059	16518284854447835016	c7eafa7ed8774c0d	F791564F-853B-47B6-8CB8-27FF59315059	1652178285720384773	16536215804846585135	1653359639811213582	16538995501084056633
deviceBrand	xiaomi	apple	-	huawei	apple	iphone	iphone	iphone	apple
deviceModel	Mi10Pro	iPhone13ProMax	iPhone	MXW-AN00	iPhoneSimulator	iPhone6/7/8Plus	iPhone14,3	iPhone6/7/8	iPhone6
deviceType	phone	phone	phone	phone	phone	phone	phone	phone	phone
deviceOrientation	portrait	portrait	portrait	portrait	portrait	portrait	-	portrait	-
devicePixelRatio	2.5687501430511475	3	2	3	3	3	3	2	2
hostName	-	-	safari	MPLauncherV3	uniMPDemo	WeChat、wxwork	alipay、amap、DINGTALK、UC、QUARK、AK、YK	baiduboxapp 等百度宿主平台枚举值列表	Douyin、Toutiao、news_article_lite、live_stream、XiGua、PPX
hostVersion	-	-	13.0.3	1.0	1.0.0	8.0.5	10.2.23	2.45.0	6.6.3
hostLanguage	-	-	zh-CN	zh-CN	zh-Hans-CN	zh-CN	zh-CN	zh-CN
hostTheme	-	-	-	light	light	-	-	-	-
hostPackageName	-	-	-	com.example.mplauncherv3	io.dcloud.hellounimp	-	-	-	-
hostSDKVersion	-	-	-	3.4.13	3.4.13	2.24.2	2.7.6	3.450.16	2.49.0
osName	android	ios	ios	android	ios	ios	ios	ios	ios
osVersion	12	15.5	13.2.3	10	15.4	10.0.1	15.5	15.5	10.0.1
osLanguage	zh-CN	zh-Hans-CN	-	zh-CN	zh-Hans-CN	-	-	-	-
osTheme	light	light	-	light	light	-	-	-	-
osAndroidAPILevel	31	-	-	29	-	-	-	-	-	-
romName	MIUI	-	-	HarmonyOS	-	-	-	-	-
romVersion	V130	-	-	2.0.0	-	-	-	-	-
uniPlatform	app	app	web	app	app	mp-weixin	mp-alipay	mp-baidu	mp-toutiao
uniCompileVersion	3.4.13	3.4.13	3.4.13	3.4.13	3.4.13	3.4.13	3.4.13	3.4.13	3.4.13
uniRuntimeVersion	3.4.13	3.4.13	3.4.13	3.4.13	3.4.13	3.4.13	3.4.13	3.4.13	3.4.13

uni.getSystemInfoSync()

获取系统信息的同步接口。调用参数和返回值同上getSystemInfo。

uni.getDeviceInfo()

获取设备基础信息

返回参数说明

参数名	类型	说明	平台差异说明
deviceBrand	string	设备品牌。如：`apple`、`huawei`	`H5 不支持`
deviceId	string	设备 id 。由 uni-app 框架生成并存储，清空 Storage 会导致改变
deviceModel	string	设备型号
deviceType	string	设备类型`phone`、`pad`、`pc`
deviceOrientation	string	设备方向 `竖屏 portrait`、`横屏 landscape`	`App、H5`。微信小程序请使用 `(getSystemInfo Api)[/api/system/info.html]` 获取
devicePixelRatio	string	设备像素比	`App、H5`。微信小程序请使用 `(getSystemInfo Api)[/api/system/info.html]` 获取
system	string	操作系统及版本
platform	客户端平台

小程序特殊的返回参数

参数名	类型	说明	平台差异说明
abi	String	应用二进制接口类型（仅 Android 支持）	`仅微信小程序`
benchmarkLevel	Number	设备性能等级（仅 Android 支持）。取值为：-2 或 0（该设备无法运行小游戏），-1（性能未知），>=1（设备性能值，该值越高，设备性能越好，目前最高不到50）	`仅微信小程序`

不推荐使用的返回参数，仅为向下兼容保留

参数名	类型	说明	平台差异说明
brand	string	设备品牌	`H5 不支持`
model	string	设备型号。新机型刚推出一段时间会显示unknown，微信会尽快进行适配。

uni.getWindowInfo()

获取窗口信息

返回参数说明

参数名	类型	说明
pixelRatio	number	设备像素比
screenWidth	number	屏幕宽度
screenHeight	number	屏幕高度
windowWidth	number	可使用窗口宽度
windowHeight	number	可使用窗口高度
windowTop	number	可使用窗口的顶部位置
windowBottom	number	可使用窗口的底部位置
statusBarHeight	number	手机状态栏的高度
screenTop	number	窗口上边缘的 y 值
safeArea	object	在竖屏正方向下的安全区域
safeAreaInsets	object	在竖屏正方向下的安全区域插入位置

safeArea 的结构

参数	类型	说明
left	Number	安全区域左上角横坐标
right	Number	安全区域右下角横坐标
top	Number	安全区域左上角纵坐标
bottom	Number	安全区域右下角纵坐标
width	Number	安全区域的宽度，单位逻辑像素
height	Number	安全区域的高度，单位逻辑像素

safeAreaInsets 的结构

参数	类型	说明
left	Number	安全区域左侧插入位置
right	Number	安全区域右侧插入位置
top	Number	安全区顶部插入位置
bottom	Number	安全区域底部插入位置

uni.getAppBaseInfo()

获取微信 APP 基础信息

返回参数说明

参数名	类型	说明	平台差异说明
appId	string	`manifest.json` 中应用appid，即DCloud appid。
appName	string	`manifest.json` 中应用名称
appVersion	string	`manifest.json` 中应用版本名称。
appVersionCode	string	`manifest.json` 中应用版本名号。
appLanguage	string	应用设置的语言`en`、`zh-Hans`、`zh-Hant`、`fr`、`es`	`App`、`H5`
appWgtVersion	string	应用资源（wgt）的版本名称。	App 3.5.5+
hostLanguage	string	小程序宿主语言	`App 仅 UNIMPSDK 支持`、`H5 不支持`
hostVersion	string	App、小程序宿主版本。如：微信版本号	`App 仅 UNIMPSDK 支持`、`H5 不支持`
hostName	string	小程序宿主名称	`App 仅 UNIMPSDK 支持`、`H5 不支持`
hostPackageName	string	小程序宿主包名	`仅 UNIMPSDK 支持`
hostSDKVersion	string	uni小程序SDK版本、小程序客户端基础库版本	`App 仅 UNIMPSDK 支持`、`H5 不支持`
hostTheme	string	系统当前主题，取值为light或dark。微信小程序全局配置"darkmode":true时才能获取，否则为 undefined （不支持小游戏）	`App 仅 UNIMPSDK 支持`、`H5 不支持`
hostFontSizeSetting	string	用户字体大小设置。以“我-设置-通用-字体大小”中的设置为准，单位：px	`仅小程序支持`

小程序特殊的返回参数

参数名	类型	说明	平台差异说明
SDKVersion	string	客户端基础库版本	`仅微信小程序`
enableDebug	boolean	是否已打开调试。可通过右上角菜单或 wx.setEnableDebug 打开调试	`仅微信小程序`
host	Object	当前小程序运行的宿主环境	`仅微信小程序`
theme	string	系统当前主题，取值为light或dark，全局配置"darkmode":true时才能获取，否则为 undefined （不支持小游戏）	`仅微信小程序`

不推荐使用的返回参数，仅为向下兼容保留

参数名	类型	说明	平台差异说明
language	string	应用设置的语言	`H5 不支持`
version	string	引擎版本号、微信版本号

uni.getAppAuthorizeSetting()

获取 APP 授权设置

返回参数说明

属性	类型	说明	平台差异说明
albumAuthorized	'authorized'/'denied'/'not determined'	允许使用相册的开关	App 端仅 iOS 支持
bluetoothAuthorized	'authorized'/'denied'/'not determined'/'config error'	允许使用蓝牙的开关	App 端仅 iOS 支持
cameraAuthorized	'authorized'/'denied'/'not determined'/'config error'	允许使用摄像头的开关
locationAuthorized	'authorized'/'denied'/'not determined'/'config error'	允许使用定位的开关
locationAccuracy	String	定位准确度。`"reduced"` 表示模糊定位；`"full"` 表示精准定位；`"unsupported"` 表示不支持	App 端仅 iOS 支持
microphoneAuthorized	'authorized'/'denied'/'not determined'/'config error'	允许使用麦克风的开关
notificationAuthorized	'authorized'/'denied'/'not determined'/'config error'	允许通知的开关
notificationAlertAuthorized	'authorized'/'denied'/'not determined'/'config error'	允许通知带有提醒的开关	App 端仅 iOS（10.0+）支持
notificationBadgeAuthorized	'authorized'/'denied'/'not determined'/'config error'	允许通知带有标记的开关	App 端仅 iOS（10.0+）支持
notificationSoundAuthorized	'authorized'/'denied'/'not determined'/'config error'	允许通知带有声音的开关	App 端仅 iOS（10.0+）支持
phoneCalendarAuthorized	'authorized'/'denied'/'not determined'	允许读写日历的开关	App 端不支持

Tips：

'authorized'：表示已经获得授权，无需再次请求授权；
'denied'：表示请求授权被拒绝，无法再次请求授权；（此情况需要引导用户打开系统设置，在设置页中打开权限）
'not determined'：表示尚未请求授权，会在App下一次调用系统相应权限时请求；（仅 iOS 会出现。此种情况下引导用户打开系统设置，不展示开关）
'config error'：只有在 App 端时返回
- bluetoothAuthorized：
  - Android平台不会返回 config error
  - iOS平台：表示没有在 manifest.json -> App模块配置 中配置 BlueTooth(低功耗蓝牙) 模块
- cameraAuthorized：
  - Android平台：表示没有授予 android.permission.CAMERA 权限
  - iOS平台不会返回 config error
- locationAuthorized：
  - Android平台：表示没有授予 android.permission.ACCESS_COARSE_LOCATION 权限
  - iOS平台：表示没有在 manifest.json -> App模块配置 中配置 Geolocation(定位) 模块
- microphoneAuthorized：
  - Android平台：表示没有授予 android.permission.RECORD_AUDIO 权限
  - iOS平台不会返回 config error
- notificationAuthorized、notificationAlertAuthorized、notificationBadgeAuthorized、notificationSoundAuthorized：
  - Android平台不支持
  - iOS平台：表示没有在 manifest.json -> App模块配置 中配置 Push(推送) 模块

示例：

const appAuthorizeSetting = uni.getAppAuthorizeSetting()

console.log(appAuthorizeSetting.albumAuthorized)
console.log(appAuthorizeSetting.bluetoothAuthorized)
console.log(appAuthorizeSetting.cameraAuthorized)
console.log(appAuthorizeSetting.locationAuthorized)
console.log(appAuthorizeSetting.locationReducedAccuracy)
console.log(appAuthorizeSetting.microphoneAuthorized)
console.log(appAuthorizeSetting.notificationAlertAuthorized)
console.log(appAuthorizeSetting.notificationAuthorized)
console.log(appAuthorizeSetting.notificationBadgeAuthorized)
console.log(appAuthorizeSetting.notificationSoundAuthorized)
console.log(appAuthorizeSetting.phoneCalendarAuthorized)

uni.getSystemSetting()

获取设备设置

返回参数说明

属性	类型	说明
bluetoothEnabled	boolean	蓝牙的系统开关。当值为 `false` 时，App端：有可能是配置不正确导致，此时会返回 `bluetoothError` 属性描述错误。
bluetoothError	String	App端：Android平台没有权限或者iOS平台模块配置错误时返回字符串，否则不返回此属性。详情见下
locationEnabled	boolean	地理位置的系统开关。当值为 `false` 时，App端：Android平台是准确的；iOS平台有可能是配置不正确导致，此时会返回 `locationError` 属性描述错误.
locationError	String	App端：Android平台不返回此属性；iOS平台模块配置错误时返回字符串，否则不返回此属性。详情见下
wifiEnabled	boolean	Wi-Fi 的系统开关
wifiError	String	App端：Android平台没有权限时返回此属性；iOS平台不返回此属性；。详情见下
deviceOrientation	string	设备方向。`竖屏：portrait`，`横屏：landscape`

Tips

bluetoothError：
- Android平台值为 "Missing permissions required by BluetoothAdapter.isEnabled: android.permission.BLUETOOTH" 表示没有 android.permission.BLUETOOTH 权限
- iOS平台值为 "Missing bluetooth module in manifest.json" ，表示没有在 manifest.json -> App模块配置 中配置 BlueTooth(低功耗蓝牙) 模块
locationError：
- Android平台不会返回此值；
- iOS平台值为 "Missing geolocation module in manifest.json" 表示没有在 manifest.json -> App模块配置 中配置 Geolocation(定位) 模块
wifiError
- Android平台值为 "Missing permissions required by WifiManager.isWifiEnabled: android.permission.ACCESS_WIFI_STATE" 表示没有 android.permission.ACCESS_WIFI_STATE 权限
- iOS平台不会返回此值；

示例：

const systemSetting = uni.getSystemSetting()

console.log(systemSetting.bluetoothEnabled)
console.log(systemSetting.deviceOrientation)
console.log(systemSetting.locationEnabled)
console.log(systemSetting.wifiEnabled)

uni.openAppAuthorizeSetting()

跳转系统授权管理页

App端
打开系统App的权限设置界面
微信小程序
打开系统微信App的权限设置界面

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例：

uni.openAppAuthorizeSetting({
  success (res) {
    console.log(res)
  }
})

内存

uni.onMemoryWarning(CALLBACK)

监听内存不足告警事件。

当 iOS/Android 向小程序进程发出内存警告时，触发该事件。Android 下有告警等级划分，iOS 无等级划分。

本 API 是 uni ext api，需下载插件：https://ext.dcloud.net.cn/plugin?id=10071

CALLBACK返回参数：

参数名	类型	说明
level	Number	仅 Android 有该字段，对应系统内存告警等级宏定义

level 的合法值

值	对应的Android告警值	说明
5	TRIM_MEMORY_RUNNING_MODERATE	进程在后台LRU列表的中间；释放内存可以帮助系统保持列表中稍后运行的其他进程，以获得更好的整体性能。
10	TRIM_MEMORY_RUNNING_LOW	该进程不是可消耗的后台进程，但设备内存不足
15	TRIM_MEMORY_RUNNING_CRITICAL	该进程不是可消耗的后台进程，但设备运行的内存极低，即将无法保持任何后台进程运行。

示例：

const callback = function (res) {
 console.log(res,'onMemoryWarningReceive');
}
uni.onMemoryWarning(callback);

uni.offMemoryWarning(CALLBACK)

取消监听内存不足告警事件。不传入 callback 则取消所有监听。

属性	类型	说明
回调函数	Function	内存不足告警事件的回调函数

示例：

const callback = function (res) {
 console.log(res);
}
uni.onMemoryWarning(callback);
// 和 onMemoryWarning 传入同一个函数即可
uni.offMemoryWarning(callback);

CALLBACK为调用uni.onMemoryWarning时传入的CALLBACK

网络状态

uni.getNetworkType(OBJECT)

获取网络类型。

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	是	接口调用成功，返回网络类型 networkType
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数	说明
networkType	网络类型

networkType 有效值

值	说明	平台差异说明
wifi	wifi 网络
2g	2g 网络
3g	3g 网络
4g	4g 网络
5g	5g 网络
ethernet	有线网络	App
unknown	Android 下不常见的网络类型
none	无网络

示例：

uni.getNetworkType({
	success: function (res) {
		console.log(res.networkType);
	}
});

uni.onNetworkStatusChange(CALLBACK)

监听网络状态变化。可使用uni.offNetworkStatusChange取消监听。

CALLBACK 返回参数

参数	类型	说明	平台差异说明
isConnected	Boolean	当前是否有网络连接	抖音小程序不支持
networkType	String	网络类型

示例：

uni.onNetworkStatusChange(function (res) {
	console.log(res.isConnected);
	console.log(res.networkType);
});

uni.offNetworkStatusChange(CALLBACK)

取消监听网络状态变化。

CALLBACK必须为调用uni.onNetworkStatusChange时传入的CALLBACK

例如：

var CALLBACK = function(res) {
    // ...这里写你的业务逻辑
}
uni.offNetworkStatusChange(CALLBACK)
uni.onNetworkStatusChange(CALLBACK);

系统主题

uni.onThemeChange(CALLBACK)

监听系统主题状态变化。

CALLBACK 返回参数

参数	类型	说明
theme	String	主题名称(`dark`, `light`)

示例：

uni.onThemeChange(function (res) {
	console.log(res.theme);
});

uni.offThemeChange(CALLBACK)

取消监听系统主题状态变化。

参数

Function CallBack：onThemeChange 传入的监听函数。

示例：

const callback = function (res) {
	console.log(res.theme);
}
uni.onThemeChange(callback);
uni.offThemeChange(callback); // 此时不再触发 callback 方法

加速度计

uni.onAccelerometerChange(CALLBACK)

监听加速度数据，频率：5次/秒，接口调用后会自动开始监听，可使用 uni.offAccelerometer 取消监听。

参数

function listener

加速度数据事件的监听函数

参数

Object res

参数	类型	说明
x	Number	X 轴
y	Number	Y 轴
z	Number	Z 轴

示例：

uni.onAccelerometerChange(function (res) {
	console.log(res.x);
	console.log(res.y);
	console.log(res.z);
});

uni.offAccelerometerChange(CALLBACK)

取消监听加速度数据。

参数

function listener

onAccelerometerChange 传入的监听函数。不传此参数则移除所有监听函数。

示例：

const listener = function (res) { console.log(res) }

uni.onAccelerometerChange(listener)
uni.offAccelerometerChange(listener) // 需传入与监听时同一个的函数对象

uni.startAccelerometer(OBJECT)

开始监听加速度数据。

OBJECT 参数说明

参数名	类型	默认	必填	说明	平台差异说明
interval	String	normal	否	监听加速度数据回调函数的执行频率	微信小程序、百度小程序、QQ小程序、快手小程序、京东小程序
success	Function		否	接口调用成功的回调
fail	Function		否	接口调用失败的回调函数
complete	Function		否	接口调用结束的回调函数（调用成功、失败都会执行）

interval 的合法值

值	说明
game	适用于更新游戏的回调频率，在 20ms/次左右
ui	适用于更新 UI 的回调频率，在 60ms/次左右
normal	普通的回调频率，在 200ms/次左右

示例：

uni.startAccelerometer();

uni.stopAccelerometer(OBJECT)

停止监听加速度数据。

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.stopAccelerometer();

罗盘

uni.onCompassChange(CALLBACK)

监听罗盘数据，频率：5次/秒，接口调用后会自动开始监听，可使用 uni.offCompassChange 取消监听。

CALLBACK 返回参数

参数	类型	说明
direction	Number	面对的方向度数

示例：

const callback = function (res) {
	console.log(res.direction);
}
uni.onCompassChange(callback);

uni.offCompassChange(CALLBACK)

取消监听罗盘数据。

示例：

const callback = function (res) {
	console.log(res.direction);
}
uni.onCompassChange(callback);
// 和 onCompassChange 传入同一个函数即可
uni.offCompassChange(callback);

CALLBACK为调用uni.onCompassChange时传入的CALLBACK

uni.startCompass(OBJECT)

开始监听罗盘数据。

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.startCompass();

uni.stopCompass(OBJECT)

停止监听罗盘数据。

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.stopCompass();

陀螺仪

uni.onGyroscopeChange(CALLBACK)

监听陀螺仪数据变化事件。

支付宝小程序频率为 500ms/次，微信小程序频率根据 uni.startGyroscope 的 interval 参数设置。事件只有在调用 uni.startGyroscope 后才会开始监听，使用 uni.stopGyroscope 可以停止监听。

CALLBACK 参数说明

属性	类型	说明
res	Object	res = {x,y,x}

res 的结构

名称	类型	描述
x	number	x轴方向角速度
y	number	y轴方向角速度
z	number	z轴方向角速度

uni.startGyroscope(OBJECT)

开始监听陀螺仪数据。

属性	类型	默认值	必填	说明	平台说明
interval	string	normal	否	监听陀螺仪数据回调函数的执行频率：game（20ms/次）、ui（60ms/次）、normal（200ms/次）	微信小程序
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.stopGyroscope(OBJECT)

停止监听陀螺仪数据。

属性	类型	必填	说明
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

<template>
    <view>
        <button @click="start">开始监听陀螺仪变化</button>
        <button @click="stop">停止监听陀螺仪变化</button>
    </view>
</template>


export default {
    methods: {
        start() {
            uni.onGyroscopeChange((res) => {
                console.log('gyroData.rotationRate.x = ' + res.x)
                console.log('gyroData.rotationRate.y = ' + res.y)
                console.log('gyroData.rotationRate.z = ' + res.z)
            });
            uni.startGyroscope({
                interval: "normal",
                success() {
                    console.log('success')
                },
                fail() {
                    console.log('fail')
                }
            })
        },
        stop(){
            uni.stopGyroscope({
                success() {
                    console.log('stop success!')
                },
                fail() {
                    console.log('stop fail!')
                }
            })
        }
    }
}

注意：陀螺仪相关 API 在小程序开发工具中调用可能报错，请在真机中测试

拨打电话

uni.makePhoneCall(OBJECT)

OBJECT 参数说明

参数名	类型	必填	说明
phoneNumber	String	是	需要拨打的电话号码
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例：

uni.makePhoneCall({
	phoneNumber: '114' //仅为示例
});

扫码

uni.scanCode(OBJECT)

调起客户端扫码界面，扫码成功后返回对应的结果。

OBJECT 参数说明

参数名	类型	必填	说明	平台差异说明
onlyFromCamera	Boolean	否	是否只能从相机扫码，不允许从相册选择图片	抖音小程序、百度小程序、支付宝小程序不支持此参数
scanType	Array	否	扫码类型，参考下方`scanType的合法值`	抖音小程序不支持此参数
autoDecodeCharset	Boolean	否	是否启用自动识别字符编码功能，默认为否	App
autoZoom	Boolean	否	是否启用自动放大，默认启用	仅 App-Android (3.5.4+) 支持
barCodeInput	Boolean	否	是否支持手动输入条形码	仅飞书小程序（V3.14.0）支持
hideAlbum	Boolean	否	是否隐藏相册（不允许从相册选择图片），只能从相机扫码。默认值为 false。	仅支付宝小程序支持
success	Function	否	接口调用成功的回调，返回内容详见返回参数说明。
fail	Function	否	接口调用失败的回调函数（识别失败、用户取消等情况下触发）
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

scanType的合法值

值	说明
barCode	一维码
qrCode	二维码
datamatrix	Data Matrix 码
pdf417	PDF417 条码

success 返回参数说明

参数	说明	平台差异说明
result	所扫码的内容
scanType	所扫码的类型	App、微信小程序、百度小程序、QQ小程序、京东小程序、支付宝小程序
charSet	所扫码的字符集	App、微信小程序、百度小程序(所扫码的字符集，仅支持 Android 系统)、QQ小程序、京东小程序
path	当所扫的码为当前应用的合法二维码时，会返回此字段，内容为二维码携带的 path。	微信小程序、QQ小程序、京东小程序
rawData	原始数据，base64 编码	微信小程序、QQ小程序、京东小程序、支付宝小程序
code	扫码所得数据	支付宝小程序
qrCode	扫描二维码时返回二维码数据	支付宝小程序
barCode	扫描条形码时返回条形码数据	支付宝小程序
imageChannel	来源	支付宝小程序

示例：

// 允许从相机和相册扫码
uni.scanCode({
	success: function (res) {
		console.log('条码类型：' + res.scanType);
		console.log('条码内容：' + res.result);
	}
});

// 只允许通过相机扫码
uni.scanCode({
	onlyFromCamera: true,
	success: function (res) {
		console.log('条码类型：' + res.scanType);
		console.log('条码内容：' + res.result);
	}
});

// 调起条码扫描
uni.scanCode({
	scanType: ['barCode'],
	success: function (res) {
		console.log('条码类型：' + res.scanType);
		console.log('条码内容：' + res.result);
	}
});

微信小程序自定义扫码界面，可使用camera组件。详见
微信内嵌浏览器运行H5版时，可通过js sdk实现扫码，需要引入一个单独的js，详见
在扫码界面点击返回也会进入 fail 回调中

剪贴板

uni.setClipboardData(OBJECT)

设置系统剪贴板的内容。

OBJECT 参数说明

参数名	类型	必填	说明	平台差异说明
data	String	是	需要设置的内容
showToast	Boolean	否	配置是否弹出提示，默认弹出提示	App (3.2.13+)、H5 (3.2.13+)
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.setClipboardData({
	data: 'hello',
	success: function () {
		console.log('success');
	}
});

uni.getClipboardData(OBJECT)

获取系统剪贴板内容。

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数	类型	说明
data	String	剪贴板的内容

uni.getClipboardData({
	success: function (res) {
		console.log(res.data);
	}
});

设置剪贴板内容后，小程序平台会自动弹出轻提示；（微信小程序在成功回调success里设置toast可覆盖自带的轻提示）。App平台默认与小程序保持一致策略。如不希望在App平台弹出提示，可使用Native.js自行操作剪贴板，插件市场有封装好的示例https://ext.dcloud.net.cn/plugin?id=712。也可以在设置剪切板后立即uni.hideToast()。

屏幕亮度

uni.setScreenBrightness(OBJECT)

设置屏幕亮度。

OBJECT 参数说明

参数名	类型	必填	说明
value	Number	是	屏幕亮度值，范围 0~1，0 最暗，1 最亮
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.setScreenBrightness({
	value: 0.5,
	success: function () {
		console.log('success');
	}
});

避免 onshow() 里使用 setScreenBrightness() , 亮度变化会再次触发 onShow() 造成死循环

uni.getScreenBrightness(OBJECT)

获取屏幕亮度。

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数	类型	说明
value	Number	屏幕亮度值，范围 0~1，0 最暗，1 最亮。

uni.getScreenBrightness({
	success: function (res) {
		console.log('屏幕亮度值：' + res.value);
	}
});

uni.setKeepScreenOn(OBJECT)

设置是否保持常亮状态。仅在当前应用生效，离开应用后设置失效。

OBJECT 参数说明

参数名	类型	必填	说明
keepScreenOn	Boolean	是	是否保持屏幕常亮
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数	类型	说明
errMsg	String	调用结果

// 保持屏幕常亮
uni.setKeepScreenOn({
	keepScreenOn: true
});

用户截屏事件

uni.onUserCaptureScreen(CALLBACK)

监听用户主动截屏事件，用户使用系统截屏按键截屏时触发此事件。

CALLBACK返回参数：

属性	类型	说明
path	string	截屏文件路径，仅App-Android平台支持

uni.onUserCaptureScreen(function() {
    console.log('用户截屏了')
});

uni.offUserCaptureScreen(function callback)

用户主动截屏事件。取消事件监听。

参数

属性	类型	说明
回调函数	Function	用户主动截屏事件的回调函数

uni.setUserCaptureScreen(OBJECT)

开启/关闭防截屏

OBJECT 参数说明

参数名	类型	必填	说明
enable	Boolean	是	是否允许用户截屏，ture: 允许用户截屏, false: 不允许用户截屏，防止用户截屏到应用页面内容
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

返回参数说明

参数	类型	说明
errCode	Number	调用结果
errMsg	String	调用结果描述
errSubject	String	调用模块

uni.setUserCaptureScreen({
    enable: false,
    success: (res) => {
        console.log("setUserCaptureScreen success: " + JSON.stringify(res));
    },
    fail: (res) => {
        console.log("setUserCaptureScreen fail: " + JSON.stringify(res));
    },
    complete: (res) => {
        console.log("setUserCaptureScreen complete: " + JSON.stringify(res));
    }
});

错误码

错误码	错误信息	说明
12001	system not support	当前系统不支持相关能力
12010	system internal error	系统错误

振动

uni.vibrate(OBJECT)

使手机发生振动。

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.vibrateLong(OBJECT)

使手机发生较长时间的振动（400ms）。

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.vibrateLong({
	success: function () {
		console.log('success');
	}
});

uni.vibrateShort(OBJECT)

使手机发生较短时间的振动（15ms）。

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.vibrateShort({
	success: function () {
		console.log('success');
	}
});

手机联系人

uni.addPhoneContact(OBJECT) 增加联系人

调用后，用户可以选择将该表单以“新增联系人”或“添加到已有联系人”的方式（APP端目前没有选择步骤，将直接写入），写入手机系统通讯录，完成手机通讯录联系人和联系方式的增加。

OBJECT 参数说明

参数名	类型	必填	说明
photoFilePath	String	否	头像本地文件路径
nickName	String	否	昵称
lastName	String	否	姓氏
middleName	String	否	中间名
firstName	String	是	名字
remark	String	否	备注
mobilePhoneNumber	String	否	手机号
weChatNumber	String	否	微信号
addressCountry	String	否	联系地址国家
addressState	String	否	联系地址省份
addressCity	String	否	联系地址城市
addressStreet	String	否	联系地址街道
addressPostalCode	String	否	联系地址邮政编码
organization	String	否	公司
title	String	否	职位
workFaxNumber	String	否	工作传真
workPhoneNumber	String	否	工作电话
hostNumber	String	否	公司电话
email	String	否	电子邮件
url	String	否	网站
workAddressCountry	String	否	工作地址国家
workAddressState	String	否	工作地址省份
workAddressCity	String	否	工作地址城市
workAddressStreet	String	否	工作地址街道
workAddressPostalCode	String	否	工作地址邮政编码
homeFaxNumber	String	否	住宅传真
homePhoneNumber	String	否	住宅电话
homeAddressCountry	String	否	住宅地址国家
homeAddressState	String	否	住宅地址省份
homeAddressCity	String	否	住宅地址城市
homeAddressStreet	String	否	住宅地址街道
homeAddressPostalCode	String	否	住宅地址邮政编码
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

回调结果

回调类型	errMsg	说明
success	ok	添加成功
cancel	fail cancel	用户取消操作
fail	fail ${detail}	调用失败，detail 加上详细信息。

示例：

uni.addPhoneContact({
	nickName: '昵称',
	lastName: '姓',
	firstName: '名',
	remark: '备注',
	mobilePhoneNumber: '114',
	weChatNumber: 'wx123',
	success: function () {
		console.log('success');
	},
	fail: function () {
		console.log('fail');
	}
});

手机OS对通讯录访问有严格的权限限制和要求。在小程序中使用时，需注意微信等小程序载体本身已经获得了手机端的授权许可。

蓝牙

uni.openBluetoothAdapter(OBJECT)

初始化蓝牙模块

OBJECT 参数说明

属性	类型	必填	说明
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
-1	already connect	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10010	already connect	已连接
10011	need pin	配对设备需要配对码
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

其他蓝牙相关 API 必须在 uni.openBluetoothAdapter 调用之后使用。否则 API 会返回错误（errCode=10000）。
在用户蓝牙开关未开启或者手机不支持蓝牙功能的情况下，调用 uni.openBluetoothAdapter 会返回错误（errCode=10001），表示手机蓝牙功能不可用。此时APP蓝牙模块已经初始化完成，可通过 uni.onBluetoothAdapterStateChange 监听手机蓝牙状态的改变，也可以调用蓝牙模块的所有API。

示例：

uni.openBluetoothAdapter({
  success(res) {
    console.log(res)
  }
})

uni.startBluetoothDevicesDiscovery(OBJECT)

开始搜寻附近的蓝牙外围设备。此操作比较耗费系统资源，请在搜索并连接到设备后调用 uni.stopBluetoothDevicesDiscovery 方法停止搜索。

OBJECT 参数说明

属性	类型	默认值	必填	说明
services	Array<String>		否	要搜索的蓝牙设备主 service 的 uuid 列表。某些蓝牙设备会广播自己的主 service 的 uuid。如果设置此参数，则只搜索广播包有对应 uuid 的主服务的蓝牙设备。建议主要通过该参数过滤掉周边不需要处理的其他蓝牙设备。
allowDuplicatesKey	boolean	false	否	是否允许重复上报同一设备。如果允许重复上报，则 `uni.onBlueToothDeviceFound` 方法会多次上报同一设备，但是 RSSI 值会有不同。
interval	number	0	否	上报设备的间隔。0 表示找到新设备立即上报，其他数值根据传入的间隔上报。
powerLevel	string	medium	否	扫描模式，越高扫描越快，也越耗电，仅安卓支持。low：低，medium：中，high：高。仅京东小程序支持
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10010	already connect	已连接
10011	need pin	配对设备需要配对码
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

// 以微信硬件平台的蓝牙智能灯为例，主服务的 UUID 是 FEE7。传入这个参数，只搜索主服务 UUID 为 FEE7 的设备
uni.startBluetoothDevicesDiscovery({
  services: ['FEE7'],
  success(res) {
    console.log(res)
  }
})

uni.onBluetoothDeviceFound(CALLBACK)

监听寻找到新设备的事件

CALLBACK 返回参数

属性	类型	说明
devices	Array<Object>	新搜索到的设备列表

devices 的结构

属性	类型	说明
name	string	蓝牙设备名称，某些设备可能没有
deviceId	string	用于区分设备的 id
RSSI	number	当前蓝牙设备的信号强度
advertisData	ArrayBuffer	当前蓝牙设备的广播数据段中的 ManufacturerData 数据段。
advertisServiceUUIDs	Array<String>	当前蓝牙设备的广播数据段中的 ServiceUUIDs 数据段
localName	string	当前蓝牙设备的广播数据段中的 LocalName 数据段
serviceData	Object	当前蓝牙设备的广播数据段中的 ServiceData 数据段，京东小程序不支持

若在 uni.onBluetoothDeviceFound 回调了某个设备，则此设备会添加到 uni.getBluetoothDevices 接口获取到的数组中

// ArrayBuffer转16进度字符串示例
function ab2hex(buffer) {
  const hexArr = Array.prototype.map.call(
    new Uint8Array(buffer),
    function (bit) {
      return ('00' + bit.toString(16)).slice(-2)
    }
  )
  return hexArr.join('')
}
uni.onBluetoothDeviceFound(function (devices) {
  console.log('new device list has founded')
  console.dir(devices)
  console.log(ab2hex(devices[0].advertisData))
})

uni.stopBluetoothDevicesDiscovery(OBJECT)

停止搜寻附近的蓝牙外围设备。若已经找到需要的蓝牙设备并不需要继续搜索时，建议调用该接口停止蓝牙搜索。

OBJECT 参数说明

属性	类型	必填	说明
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10010	already connect	已连接
10011	need pin	配对设备需要配对码
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

uni.stopBluetoothDevicesDiscovery({
  success(res) {
    console.log(res)
  }
})

uni.onBluetoothAdapterStateChange(CALLBACK)

监听蓝牙适配器状态变化事件

CALLBACK 返回参数

属性	类型	说明
available	boolean	蓝牙适配器是否可用
discovering	boolean	蓝牙适配器是否处于搜索状态

uni.onBluetoothAdapterStateChange(function (res) {
  console.log('adapterState changed, now is', res)
})

uni.getConnectedBluetoothDevices(OBJECT)

根据 uuid 获取处于已连接状态的设备。

OBJECT 参数说明

属性	类型	必填	说明
services	Array<String>	是	蓝牙设备主 service 的 uuid 列表
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明：

属性	类型	说明
devices	Array<Object>	搜索到的设备列表

res.devices 的结构

属性	类型	说明
name	string	蓝牙设备名称，某些设备可能没有
deviceId	string	用于区分设备的 id

错误

错误码	错误信息	说明
0	ok	正常
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10010	already connect	已连接
10011	need pin	配对设备需要配对码
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

uni.getConnectedBluetoothDevices({
  success(res) {
    console.log(res)
  }
})

uni.getBluetoothDevices(OBJECT)

获取在蓝牙模块生效期间所有已发现的蓝牙设备。包括已经和本机处于连接状态的设备。

OBJECT 参数说明

属性	类型	必填	说明
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明：

属性	类型	说明
devices	Array<Object>	uuid 对应的的已连接设备列表

res.devices 的结构

属性	类型	说明
name	string	蓝牙设备名称，某些设备可能没有
deviceId	string	用于区分设备的 id
RSSI	number	当前蓝牙设备的信号强度
advertisData	ArrayBuffer	当前蓝牙设备的广播数据段中的 ManufacturerData 数据段。
advertisServiceUUIDs	Array<String>	当前蓝牙设备的广播数据段中的 ServiceUUIDs 数据段
localName	string	当前蓝牙设备的广播数据段中的 LocalName 数据段
serviceData	Object	当前蓝牙设备的广播数据段中的 ServiceData 数据段

错误

错误码	错误信息	说明
0	ok	正常
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

// ArrayBuffer转16进度字符串示例
function ab2hex(buffer) {
  const hexArr = Array.prototype.map.call(
    new Uint8Array(buffer),
    function (bit) {
      return ('00' + bit.toString(16)).slice(-2)
    }
  )
  return hexArr.join('')
}
uni.getBluetoothDevices({
  success(res) {
    console.log(res)
    if (res.devices[0]) {
      console.log(ab2hex(res.devices[0].advertisData))
    }
  }
})

该接口获取到的设备列表为蓝牙模块生效期间所有搜索到的蓝牙设备，若在蓝牙模块使用流程结束后未及时调用 uni.closeBluetoothAdapter 释放资源，会存在调用该接口会返回之前的蓝牙使用流程中搜索到的蓝牙设备，可能设备已经不在用户身边，无法连接。
蓝牙设备在被搜索到时，系统返回的 name 字段一般为广播包中的 LocalName 字段中的设备名称，而如果与蓝牙设备建立连接，系统返回的 name 字段会改为从蓝牙设备上获取到的 GattName。若需要动态改变设备名称并展示，建议使用 localName 字段。

uni.getBluetoothAdapterState(OBJECT)

获取本机蓝牙适配器状态。

OBJECT 参数说明

属性	类型	必填	说明
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明：

属性	类型	说明
discovering	boolean	是否正在搜索设备
available	boolean	蓝牙适配器是否可用

错误

错误码	错误信息	说明
0	ok	正常
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10010	already connect	已连接
10011	need pin	配对设备需要配对码
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

uni.getBluetoothAdapterState({
  success(res) {
    console.log(res)
  }
})

uni.closeBluetoothAdapter(OBJECT)

关闭蓝牙模块。调用该方法将断开所有已建立的连接并释放系统资源。建议在使用蓝牙流程后，与 uni.openBluetoothAdapter 成对调用。

OBJECT 参数说明

属性	类型	必填	说明
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10010	already connect	已连接
10011	need pin	配对设备需要配对码
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

uni.closeBluetoothAdapter({
  success(res) {
    console.log(res)
  }
})

低功耗蓝牙

uni.setBLEMTU(OBJECT)

设置蓝牙最大传输单元。需在 uni.createBLEConnection调用成功后调用，mtu 设置范围 (22,512)。安卓5.1以上有效。

OBJECT 参数说明

属性	类型	必填	说明
deviceId	string	是	用于区分设备的 id
mtu	number	是	最大传输单元(22,512) 区间内，单位 bytes
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.writeBLECharacteristicValue(OBJECT)

向低功耗蓝牙设备特征值中写入二进制数据。注意：必须设备的特征值支持 write 才可以成功调用。

OBJECT 参数说明

属性	类型	必填	说明
deviceId	string	是	蓝牙设备 id
serviceId	string	是	蓝牙特征值对应服务的 uuid
characteristicId	string	是	蓝牙特征值的 uuid
value	ArrayBuffer	是	蓝牙设备特征值对应的二进制值
writeType	string	是	蓝牙特征值的写模式设置，有两种模式，iOS 优先 write，安卓优先 writeNoResponse 。微信小程序支持
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

writeType

属性	说明
write	强制回复写，不支持时报错
writeNoResponse	强制无回复写，不支持时报错

错误

错误码	错误信息	说明
0	ok	正常
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10010	already connect	已连接
10011	need pin	配对设备需要配对码
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

示例：

// 向蓝牙设备发送一个0x00的16进制数据
const buffer = new ArrayBuffer(1)
const dataView = new DataView(buffer)
dataView.setUint8(0, 0)
uni.writeBLECharacteristicValue({
  // 这里的 deviceId 需要在 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取
  deviceId,
  // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  serviceId,
  // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  characteristicId,
  // 这里的value是ArrayBuffer类型
  value: buffer,
  success(res) {
    console.log('writeBLECharacteristicValue success', res.errMsg)
  }
})

uni.readBLECharacteristicValue(OBJECT)

读取低功耗蓝牙设备的特征值的二进制数据值。注意：必须设备的特征值支持 read 才可以成功调用。

OBJECT 参数说明

属性	类型	必填	说明
deviceId	string	是	蓝牙设备 id
serviceId	string	是	蓝牙特征值对应服务的 uuid
characteristicId	string	是	蓝牙特征值的 uuid
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10010	already connect	已连接
10011	need pin	配对设备需要配对码
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

// 必须在这里的回调才能获取
uni.onBLECharacteristicValueChange(function (characteristic) {
  console.log('characteristic value comed:', characteristic)
})
uni.readBLECharacteristicValue({
  // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
  deviceId,
  // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  serviceId,
  // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  characteristicId,
  success(res) {
    console.log('readBLECharacteristicValue:', res.errCode)
  }
})

uni.onBLEConnectionStateChange(CALLBACK)

监听低功耗蓝牙连接状态的改变事件。包括开发者主动连接或断开连接，设备丢失，连接异常断开等等

CALLBACK 返回参数

属性	类型	说明
deviceId	string	蓝牙设备ID
connected	boolean	是否处于已连接状态

uni.onBLEConnectionStateChange(function (res) {
  // 该方法回调中可以用于处理连接意外断开等异常情况
  console.log(`device ${res.deviceId} state has changed, connected: ${res.connected}`)
})

uni.onBLECharacteristicValueChange(CALLBACK)

监听低功耗蓝牙设备的特征值变化事件。必须先启用 notifyBLECharacteristicValueChange 接口才能接收到设备推送的 notification。

CALLBACK 返回参数

属性	类型	说明
deviceId	string	蓝牙设备 id
serviceId	string	蓝牙特征值对应服务的 uuid
characteristicId	string	蓝牙特征值的 uuid
value	ArrayBuffer	特征值最新的值

// ArrayBuffer转16进度字符串示例
function ab2hex(buffer) {
  const hexArr = Array.prototype.map.call(
    new Uint8Array(buffer),
    function (bit) {
      return ('00' + bit.toString(16)).slice(-2)
    }
  )
  return hexArr.join('')
}
uni.onBLECharacteristicValueChange(function (res) {
  console.log(`characteristic ${res.characteristicId} has changed, now is ${res.value}`)
  console.log(ab2hex(res.value))
})

uni.notifyBLECharacteristicValueChange(OBJECT)

启用低功耗蓝牙设备特征值变化时的 notify 功能，订阅特征值。注意：必须设备的特征值支持 notify 或者 indicate 才可以成功调用。另外，必须先启用 notifyBLECharacteristicValueChange 才能监听到设备 characteristicValueChange 事件

OBJECT 参数说明

属性	类型	必填	说明
deviceId	string	是	蓝牙设备 id
serviceId	string	是	蓝牙特征值对应服务的 uuid
characteristicId	string	是	蓝牙特征值的 uuid
state	boolean	是	是否启用 notify
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10010	already connect	已连接
10011	need pin	配对设备需要配对码
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

uni.notifyBLECharacteristicValueChange({
  state: true, // 启用 notify 功能
  // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
  deviceId,
  // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  serviceId,
  // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  characteristicId,
  success(res) {
    console.log('notifyBLECharacteristicValueChange success', res.errMsg)
  }
})

uni.getBLEDeviceServices(OBJECT)

获取蓝牙设备所有服务(service)。

OBJECT 参数说明

属性	类型	必填	说明
deviceId	string	是	蓝牙设备 id
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明：

属性	类型	说明
services	Array<Object>	设备服务列表

res.services 的结构

属性	类型	说明
uuid	string	蓝牙设备服务的 uuid
isPrimary	boolean	该服务是否为主服务

#错误

错误码	错误信息	说明
0	ok	正常
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10010	already connect	已连接
10011	need pin	配对设备需要配对码
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

uni.getBLEDeviceServices({
  // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
  deviceId,
  success(res) {
    console.log('device services:', res.services)
  }
})

uni.getBLEDeviceRSSI(OBJECT)

2.8.4+

获取蓝牙设备的信号强度。

OBJECT 参数说明

属性	类型	必填	说明
deviceId	string	是	蓝牙设备 id
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.getBLEDeviceCharacteristics(OBJECT)

获取蓝牙设备某个服务中所有特征值(characteristic)。

OBJECT 参数说明

属性	类型	必填	说明
deviceId	string	是	蓝牙设备 id
serviceId	string	是	蓝牙服务 uuid，需要使用 `getBLEDeviceServices` 获取
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明：

属性	类型	说明
characteristics	Array<Object>	设备服务列表

res.characteristics 的结构

属性	类型	说明
uuid	string	蓝牙设备特征值的 uuid
properties	Object	该特征值支持的操作类型

properties 的结构

属性	类型	说明
read	boolean	该特征值是否支持 read 操作
write	boolean	该特征值是否支持 write 操作
notify	boolean	该特征值是否支持 notify 操作
indicate	boolean	该特征值是否支持 indicate 操作

错误

错误码	错误信息	说明
0	ok	正常
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE

uni.getBLEDeviceCharacteristics({
  // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
  deviceId,
  // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  serviceId,
  success(res) {
    console.log('device getBLEDeviceCharacteristics:', res.characteristics)
  }
})

uni.createBLEConnection(OBJECT)

连接低功耗蓝牙设备。

若APP在之前已有搜索过某个蓝牙设备，并成功建立连接，可直接传入之前搜索获取的 deviceId 直接尝试连接该设备，无需进行搜索操作。

OBJECT 参数说明

属性	类型	必填	说明
deviceId	string	是	用于区分设备的 id
timeout	number	否	超时时间，单位ms，不填表示不会超时，京东小程序不支持
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10010	already connect	已连接
10011	need pin	配对设备需要配对码
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

注意

请保证尽量成对的调用 createBLEConnection 和 closeBLEConnection 接口。安卓如果多次调用 createBLEConnection 创建连接，有可能导致系统持有同一设备多个连接的实例，导致调用 closeBLEConnection 的时候并不能真正的断开与设备的连接。
蓝牙连接随时可能断开，建议监听 uni.onBLEConnectionStateChange 回调事件，当蓝牙设备断开时按需执行重连操作
若对未连接的设备或已断开连接的设备调用数据读写操作的接口，会返回 10006 错误，建议进行重连操作。

uni.createBLEConnection({
  // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
  deviceId,
  success(res) {
    console.log(res)
  }
})

uni.closeBLEConnection(OBJECT)

断开与低功耗蓝牙设备的连接。

OBJECT 参数说明

属性	类型	必填	说明
deviceId	string	是	用于区分设备的 id
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10010	already connect	已连接
10011	need pin	配对设备需要配对码
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

uni.closeBLEConnection({
  deviceId,
  success(res) {
    console.log(res)
  }
})

iBeacon

uni.onBeaconServiceChange(CALLBACK)

监听 iBeacon 服务状态变化事件

CALLBACK 返回参数

属性	类型	说明
available	boolean	服务目前是否可用
discovering	boolean	目前是否处于搜索状态

uni.onBeaconUpdate(CALLBACK)

监听 iBeacon 设备更新事件

CALLBACK 返回参数

属性	类型	说明
beacons	Array<IBeaconInfo>	当前搜寻到的所有 iBeacon 设备列表

uni.getBeacons(OBJECT)

获取所有已搜索到的 iBeacon 设备

OBJECT 参数说明

属性	类型	必填	说明
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明：

属性	类型	说明
beacons	Array<IBeaconInfo>	iBeacon 设备列表

错误

错误码	错误信息	说明
0	ok	正常
11000	unsupport	系统或设备不支持
11001	bluetooth service unavailable	蓝牙服务不可用
11002	location service unavailable	位置服务不可用
11003	already start	已经开始搜索

uni.startBeaconDiscovery(OBJECT)

开始搜索附近的 iBeacon 设备

OBJECT 参数说明

属性	类型	默认值	必填	说明
uuids	Array＜String＞		是	iBeacon 设备广播的 uuid 列表
ignoreBluetoothAvailable	boolean	false	否	是否校验蓝牙开关，仅在 iOS 下有效
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
11000	unsupport	系统或设备不支持
11001	bluetooth service unavailable	蓝牙服务不可用
11002	location service unavailable	位置服务不可用
11003	already start	已经开始搜索

uni.startBeaconDiscovery({
  success(res) { }
})

uni.stopBeaconDiscovery(OBJECT)

停止搜索附近的 iBeacon 设备

OBJECT 参数说明

属性	类型	必填	说明
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
11000	unsupport	系统或设备不支持
11001	bluetooth service unavailable	蓝牙服务不可用
11002	location service unavailable	位置服务不可用
11003	already start	已经开始搜索

IBeaconInfo

属性	类型	说明
uuid	string	iBeacon 设备广播的 uuid
major	string	iBeacon 设备的主 id
minor	string	iBeacon 设备的次 id
proximity	number	表示设备距离的枚举值
accuracy	number	iBeacon 设备的距离
rssi	number	表示设备的信号强度

注意事项

未启用定位将影响 iBeacon 的正常使用。

电量

uni.getBatteryInfo(OBJECT)

获取设备电量

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数	类型	说明
level	Number	设备电量，范围 1 - 100
isCharging	Boolean	是否正在充电中

uni.getBatteryInfo({
  success: (res) => {
    console.log(res)
  }
})

生物认证

生物认证，包含手机的指纹识别、faceid两部分。即通过人体身体特征来进行身份认证识别。

如需要专业的活体检测、人脸识别、金融级实人认证，需另见文档uni实人认证

uni.startSoterAuthentication(OBJECT)

开始 SOTER 生物认证。

OBJECT参数说明

属性	类型	默认值	必填	说明	平台差异说明
requestAuthModes	Array		是	请求使用的可接受的生物认证方式	APP、微信小程序
challenge	String		是	挑战因子。挑战因子为调用者为此次生物鉴权准备的用于签名的字符串关键识别信息，将作为 resultJSON 的一部分，供调用者识别本次请求。例如：如果场景为请求用户对某订单进行授权确认，则可以将订单号填入此参数。	微信小程序
authContent	String	''	否	验证描述，即识别过程中显示在界面上的对话框提示内容	APP、微信小程序
success	Function		否	接口调用成功的回调函数
fail	Function		否	接口调用失败的回调函数
complete	Function		否	接口调用结束的回调函数（调用成功、失败都会执行）

OBJECT.requestAuthModes说明

值	说明
fingerPrint	指纹识别
facial	人脸识别

OBJECT.success返回值说明

属性	类型	说明	平台差异说明
authMode	string	生物认证方式	APP、微信小程序
resultJSON	string	在设备安全区域（TEE）内获得的本机安全信息（如TEE名称版本号等以及防重放参数）以及本次认证信息（仅Android支持，本次认证的指纹ID）。具体说明见下文	微信小程序
resultJSONSignature	string	用SOTER安全密钥对 resultJSON 的签名(SHA256 with RSA/PSS, saltlen=20)	微信小程序
errCode	number	错误码
errMsg	string	错误信息

resultJSON说明

此数据为设备TEE中，将传入的challenge和TEE内其他安全信息组成的数据进行组装而来的JSON，对下述字段的解释如下表。例子如下：

字段名	说明
raw	调用者传入的challenge
fid	（仅Android支持）本次生物识别认证的生物信息编号（如指纹识别则是指纹信息在本设备内部编号）
counter	防重放特征参数
tee_n	TEE名称（如高通或者trustonic等）
tee_v	TEE版本号
fp_n	指纹以及相关逻辑模块提供商（如FPC等）
fp_v	指纹以及相关模块版本号
cpu_id	机器唯一识别ID
uid	概念同Android系统定义uid，即应用程序编号

错误码说明

错误码	错误码说明
0	识别成功
90001	本设备不支持生物认证
90002	用户未授权使用该生物认证接口
90003	请求使用的生物认证方式不支持
90004	未传入challenge或challenge长度过长（最长512字符）
90005	auth_content长度超过限制（最长42个字符）
90007	内部错误
90008	用户取消授权
90009	识别失败
90010	重试次数过多被冻结
90011	用户未录入所选识别方式

uni.checkIsSupportSoterAuthentication(OBJECT)

获取本机支持的 SOTER 生物认证方式

OBJECT参数说明

属性	类型	必填	说明
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

OBJECT.success返回值说明

属性	类型	说明
supportMode	Array	该设备支持的可被SOTER识别的生物识别方式

uni.checkIsSoterEnrolledInDevice(OBJECT)

获取设备内是否录入如指纹等生物信息的接口

OBJECT参数说明

属性	类型	必填	说明
checkAuthMode	string	是	认证方式
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

OBJECT.checkAuthMode合法值

值	说明
fingerPrint	指纹识别
facial	人脸识别

OBJECT.success返回值说明

属性	类型	说明
isEnrolled	boolean	是否已录入信息
errMsg	string	错误信息

示例代码：

<template>
	<view class="content">
		<button type="primary" @click="checkIsSupportSoterAuthentication">检查支持的认证方式</button>
		<button type="primary" @click="checkIsSoterEnrolledInDeviceFingerPrint">检查是否录入指纹</button>
		<button type="primary" @click="checkIsSoterEnrolledInDeviceFaceID">检查是否录入FaceID</button>
		<button type="primary" @click="startSoterAuthenticationFingerPrint">开始指纹认证</button>
		<button type="primary" @click="startSoterAuthenticationFaceID">开始FaceID认证</button>
	</view>
</template>

<script>
	export default {
		data() {
			return {
			}
		},
		onLoad() {

		},
		methods: {
			checkIsSupportSoterAuthentication() {
				uni.checkIsSupportSoterAuthentication({
					success(res) {
						console.log(res);
					},
					fail(err) {
						console.log(err);
					},
					complete(res) {
						console.log(res);
					}
				})
			},
			checkIsSoterEnrolledInDeviceFingerPrint() {
				uni.checkIsSoterEnrolledInDevice({
					checkAuthMode: 'fingerPrint',
					success(res) {
						console.log(res);
					},
					fail(err) {
						console.log(err);
					},
					complete(res) {
						console.log(res);
					}
				})
			},
			checkIsSoterEnrolledInDeviceFaceID() {
				uni.checkIsSoterEnrolledInDevice({
					checkAuthMode: 'facial',
					success(res) {
						console.log(res);
					},
					fail(err) {
						console.log(err);
					},
					complete(res) {
						console.log(res);
					}
				})
			},
			startSoterAuthenticationFingerPrint() {
				uni.startSoterAuthentication({
					requestAuthModes: ['fingerPrint'],
					challenge: '123456',
					authContent: '请用指纹解锁',
					success(res) {
						console.log(res);
					},
					fail(err) {
						console.log(err);
					},
					complete(res) {
						console.log(res);
					}
				})
			},
			startSoterAuthenticationFaceID() {
				uni.startSoterAuthentication({
					requestAuthModes: ['facial'],
					challenge: '123456',
					authContent: '请用FaceID解锁',
					success(res) {
						console.log(res);
					},
					fail(err) {
						console.log(err);
					},
					complete(res) {
						console.log(res);
					}
				})
			}
		}
	}
</script>

<style>
	button {
		width: 200px;
		margin: 20px auto;
	}
</style>

微信小程序如果使用腾讯云的SDK，可参考网友分享

拦截器

uni.addInterceptor(STRING, OBJECT)

添加拦截器，对添加的方法产生拦截效果，如添加request方法的拦截器后，当request方法被执行时，就会触发拦截器。

STRING 参数说明

需要拦截的api名称，如：uni.addInterceptor('request', OBJECT) ，将拦截 uni.request()

OBJECT 参数说明

参数名	类型	必填	说明
invoke	Function	否	拦截前触发
returnValue	Function	否	方法调用后触发，处理返回值
success	Function	否	成功回调拦截
fail	Function	否	失败回调拦截
complete	Function	否	完成回调拦截

注意：仅支持异步接口，如：uni.setStorage(OBJECT)，暂不支持同步接口如：uni.setStorageSync(KEY,DATA)

示例：

uni.request({
    url: 'request/login', //仅为示例，并非真实接口地址。
    success: (res) => {
        console.log(res.data);
        // 打印： {code:1,...}
    }
});


uni.addInterceptor('request', {
  invoke(args) {
    // request 触发前拼接 url 
    args.url = 'https://www.example.com/'+args.url
  },
  success(args) {
    // 请求成功后，修改code值为1
    args.data.code = 1
  }, 
  fail(err) {
    console.log('interceptor-fail',err)
  }, 
  complete(res) {
    console.log('interceptor-complete',res)
  }
})

uni.addInterceptor({
  returnValue(args) {
    // 只返回 data 字段
    return args.data
  }
})

uni.removeInterceptor(STRING)

删除拦截器

STRING 参数说明

需要删除拦截器的api名称

示例：

uni.removeInterceptor('request')

拦截器的适用场景非常多，比如路由拦截，权限引导等。你可以参考插件市场,拦截器应用示例：图片选择api时无权限，引导用户快捷打开系统设置：https://ext.dcloud.net.cn/plugin?id=5095

uni.canIUse(String)

判断应用的 API，回调，参数，组件等是否在当前版本可用。

String 参数说明

使用 ${API}.${method}.${param}.${options} 或者 ${component}.${attribute}.${option} 方式来调用，例如：

${API} 代表 API 名字
${method} 代表调用方式，有效值为return, success, object, callback
${param} 代表参数或者返回值
${options} 代表参数的可选值
${component} 代表组件名字
${attribute} 代表组件属性
${option} 代表组件属性的可选值

示例：

uni.canIUse('getSystemInfoSync.return.screenWidth');
uni.canIUse('getSystemInfo.success.screenWidth');
uni.canIUse('showToast.object.image');
uni.canIUse('request.object.method.GET');

uni.canIUse('live-player');
uni.canIUse('text.selectable');
uni.canIUse('button.open-type.contact');

API Promise 化

具体 API Promise 化 的策略：
- 异步的方法，如果不传入 success、fail、complete 等 callback 参数，将以 Promise 返回数据。例如：uni.getImageInfo()
- 异步的方法，且有返回对象，如果希望获取返回对象，必须至少传入一项 success、fail、complete 等 callback 参数。例如：

// 正常使用
 const task = uni.connectSocket(
  success(res){
   console.log(res)
  }
 )

 // Promise 化
 uni.connectSocket().then(res => {
   // 此处即为正常使用时 success 回调的 res
   // uni.connectSocket() 正常使用时是会返回 task 对象的，如果想获取 task ，则不要使用 Promise 化
   console.log(res)
 })

2. 不进行 Promise 化 的 API：

- 同步的方法（即以 sync 结束）。例如：uni.getSystemInfoSync()
- 以 create 开头的方法。例如：uni.createMapContext()
- 以 manager 结束的方法。例如：uni.getBackgroundAudioManager()

Vue 2 和 Vue 3 的 API `Promise 化`

Vue 2 和 Vue 3 项目中 `API Promise 化` 返回格式不一致，以下为 `不同点` 和 `返回格式互相转换`

不同点
- Vue2 对部分 API 进行了 Promise 封装，返回数据的第一个参数是错误对象，第二个参数是返回数据。此时使用 catch 是拿不到报错信息的，因为内部对错误进行了拦截。
- Vue3 对部分 API 进行了 Promise 封装，调用成功会进入 then 方法 回调。调用失败会进入 catch 方法 回调

网络

uni.request(OBJECT) 发起请求

OBJECT 参数说明

参数名	类型	必填	默认值	说明	平台差异说明
url	String	是		开发者服务器接口地址
data	Object/String/ArrayBuffer	否		请求的参数	App 3.3.7 以下不支持 ArrayBuffer 类型
header	Object	否		设置请求的 header，header 中不能设置 Referer	App、H5端会自动带上cookie，且H5端不可手动修改
method	String	否	GET	有效值详见下方说明
timeout	Number	否	60000	超时时间，单位 ms	H5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+)、微信小程序（2.10.0）、支付宝小程序
dataType	String	否	json	如果设为 json，会对返回的数据进行一次 JSON.parse，非 json 不会进行 JSON.parse
responseType	String	否	text	设置响应的数据类型。合法值：text、arraybuffer	支付宝小程序不支持
sslVerify	Boolean	否	true	验证 ssl 证书	仅App安卓端支持（HBuilderX 2.3.3+），不支持离线打包
withCredentials	Boolean	否	false	跨域请求时是否携带凭证（cookies）	仅H5支持（HBuilderX 2.6.15+）
firstIpv4	Boolean	否	false	DNS解析时优先使用ipv4	仅 App-Android 支持 (HBuilderX 2.8.0+)
enableHttp2	Boolean	否	false	开启 http2	微信小程序
enableQuic	Boolean	否	false	开启 quic	微信小程序
enableCache	Boolean	否	false	开启 cache	微信小程序、抖音小程序 2.31.0+
enableHttpDNS	Boolean	否	false	是否开启 HttpDNS 服务。如开启，需要同时填入 httpDNSServiceId 。 HttpDNS 用法详见移动解析HttpDNS	微信小程序
httpDNSServiceId	String	否		HttpDNS 服务商 Id。 HttpDNS 用法详见移动解析HttpDNS	微信小程序
enableChunked	Boolean	否	false	开启 transfer-encoding chunked	微信小程序
forceCellularNetwork	Boolean	否	false	wifi下使用移动网络发送请求	微信小程序
enableCookie	Boolean	否	false	开启后可在headers中编辑cookie	支付宝小程序 10.2.33+
cloudCache	Object/Boolean	否	false	是否开启云加速（详见云加速服务）	百度小程序 3.310.11+
defer	Boolean	否	false	控制当前请求是否延时至首屏内容渲染后发送	百度小程序 3.310.11+
success	Function	否		收到开发者服务器成功返回的回调函数
fail	Function	否		接口调用失败的回调函数
complete	Function	否		接口调用结束的回调函数（调用成功、失败都会执行）

method 有效值

注意：method有效值必须大写，每个平台支持的method有效值不同，详细见下表。

method	App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	快手小程序	京东小程序
GET	√	√	√	√	√	√	√	√
POST	√	√	√	√	√	√	√	√
PUT	√	√	√	x	√	√	x	x
DELETE	√	√	√	x	√	x	x	x
CONNECT	x	√	√	x	x	x	x	x
HEAD	√	√	√	x	√	x	x	x
OPTIONS	√	√	√	x	√	x	x	x
TRACE	x	√	√	x	x	x	x	x

success 返回参数说明

参数	类型	说明
data	Object/String/ArrayBuffer	开发者服务器返回的数据
statusCode	Number	开发者服务器返回的 HTTP 状态码
header	Object	开发者服务器返回的 HTTP Response Header
cookies	`Array.<string>`	开发者服务器返回的 cookies，格式为字符串数组

data 数据说明

最终发送给服务器的数据是 String 类型，如果传入的 data 不是 String 类型，会被转换成 String。转换规则如下：

对于 GET 方法，会将数据转换为 query string。例如 { name: 'name', age: 18 } 转换后的结果是 name=name&age=18。
对于 POST 方法且 header['content-type'] 为 application/json 的数据，会进行 JSON 序列化。
对于 POST 方法且 header['content-type'] 为 application/x-www-form-urlencoded 的数据，会将数据转换为 query string。

上传、下载

将本地资源上传到开发者服务器，客户端发起一个 POST 请求，其中 content-type 为 multipart/form-data。如页面通过 uni.chooseImage 等接口获取到一个本地资源的临时文件路径后，可通过此接口将本地资源上传到指定服务器。另外选择和上传非图像、视频文件参考：https://ask.dcloud.net.cn/article/35547。

OBJECT 参数说明

参数名	类型	必填	说明	平台差异说明
url	String	是	开发者服务器 url
files	Array	是（files和filePath选其一）	需要上传的文件列表。使用 files 时，filePath 和 name 不生效。	App、H5（ 2.6.15+）
fileType	String	见平台差异说明	文件类型，image/video/audio	仅支付宝小程序，且必填。
file	File	否	要上传的文件对象。	仅H5（2.6.15+）支持
filePath	String	是（files和filePath选其一）	要上传文件资源的路径。
name	String	是	文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容
header	Object	否	HTTP 请求 Header, header 中不能设置 Referer。
timeout	Number	否	超时时间，单位 ms	H5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+)、微信小程序、支付宝小程序、抖音小程序、快手小程序
formData	Object	否	HTTP 请求中其他额外的 form data
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

files参数说明

files 参数是一个 file 对象的数组，file 对象的结构如下：

参数名	类型	必填	说明
name	String	否	multipart 提交时，表单的项目名，默认为 file
file	File	否	要上传的文件对象，仅H5（2.6.15+）支持
uri	String	是	文件的本地地址

success 返回参数说明

参数	类型	说明
data	String	开发者服务器返回的数据
statusCode	Number	开发者服务器返回的 HTTP 状态码

示例：

uni.chooseImage({
	success: (chooseImageRes) => {
		const tempFilePaths = chooseImageRes.tempFilePaths;
		uni.uploadFile({
			url: 'https://www.example.com/upload', //仅为示例，非真实的接口地址
			filePath: tempFilePaths[0],
			name: 'file',
			formData: {
				'user': 'test'
			},
			success: (uploadFileRes) => {
				console.log(uploadFileRes.data);
			}
		});
	}
});

返回值

如果希望返回一个 uploadTask 对象，需要至少传入 success / fail / complete 参数中的一个。例如：

var uploadTask = uni.uploadFile({
	url: 'https://www.example.com/upload', //仅为示例，并非真实接口地址。
	complete: ()=> {}
});
uploadTask.abort();

如果没有传入 success / fail / complete 参数，则会返回封装后的 Promise 对象：Promise 封装

通过 uploadTask，可监听上传进度变化事件，以及取消上传任务。

uploadTask 对象的方法列表

方法	参数	说明
abort		中断上传任务
onProgressUpdate	callback	监听上传进度变化
onHeadersReceived	callback	监听 HTTP Response Header 事件。会比请求完成事件更早,仅`微信小程序平台`支持，规范详情
offProgressUpdate	callback	取消监听上传进度变化事件，仅`微信小程序平台`支持，规范详情
offHeadersReceived	callback	取消监听 HTTP Response Header 事件，仅`微信小程序平台`支持，规范详情

onProgressUpdate 返回参数说明

参数	类型	说明
progress	Number	上传进度百分比
totalBytesSent	Number	已经上传的数据长度，单位 Bytes
totalBytesExpectedToSend	Number	预期需要上传的数据总长度，单位 Bytes

示例：

uni.chooseImage({
	success: (chooseImageRes) => {
		const tempFilePaths = chooseImageRes.tempFilePaths;
		const uploadTask = uni.uploadFile({
			url: 'https://www.example.com/upload', //仅为示例，非真实的接口地址
			filePath: tempFilePaths[0],
			name: 'file',
			formData: {
				'user': 'test'
			},
			success: (uploadFileRes) => {
				console.log(uploadFileRes.data);
			}
		});

		uploadTask.onProgressUpdate((res) => {
			console.log('上传进度' + res.progress);
			console.log('已经上传的数据长度' + res.totalBytesSent);
			console.log('预期需要上传的数据总长度' + res.totalBytesExpectedToSend);

			// 测试条件，取消上传任务。
			if (res.progress > 50) {
				uploadTask.abort();
			}
		});
	}
});

uni.downloadFile(OBJECT)

下载文件资源到本地，客户端直接发起一个 HTTP GET 请求，返回文件的本地临时路径。

OBJECT 参数说明

参数名	类型	必填	说明	平台差异说明
url	String	是	下载资源的 url
header	Object	否	HTTP 请求 Header, header 中不能设置 Referer。
timeout	Number	否	超时时间，单位 ms	H5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+)、微信小程序、支付宝小程序、抖音小程序、快手小程序
filePath	string	否	指定文件下载后存储的路径 (本地路径)	小程序端支持（微信IOS小程序保存到相册需要添加此字段才可以正常保存）
success	Function	否	下载成功后以 tempFilePath 的形式传给页面，res = {tempFilePath: '文件的临时路径'}
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

注：文件的临时路径，在应用本次启动期间可以正常使用，如需持久保存，需在主动调用 uni.saveFile，才能在应用下次启动时访问得到。

success 返回参数说明

参数	类型	说明	平台差异说明
tempFilePath	String	临时文件路径，下载后的文件会存储到一个临时文件	微信小程序、支付宝小程序、百度小程序、抖音小程序、飞书小程序
statusCode	Number	开发者服务器返回的 HTTP 状态码	微信小程序、QQ小程序、百度小程序、抖音小程序、飞书小程序
apFilePath	String	下载文件保存的路径（本地临时文件）。入参未指定 filePath 的情况下可用	支付宝小程序
filePath	String	用户文件路径 (本地路径)。传入 filePath 时会返回，跟传入的 filePath 一致	微信小程序、支付宝小程序、抖音小程序、飞书小程序
fileContent	Buffer	文件内容	QQ小程序

注意

网络请求的 超时时间 可以统一在 manifest.json 中配置 networkTimeout。

示例：

uni.downloadFile({
	url: 'https://www.example.com/file/test', //仅为示例，并非真实的资源
	success: (res) => {
		if (res.statusCode === 200) {
			console.log('下载成功');
		}
	}
});

返回值

如果希望返回一个 downloadTask 对象，需要至少传入 success / fail / complete 参数中的一个。例如：

var downloadTask = uni.downloadFile({
	url: 'https://www.example.com/file/test', //仅为示例，并非真实接口地址。
	complete: ()=> {}
});
downloadTask.abort();

通过 downloadTask，可监听下载进度变化事件，以及取消下载任务。

downloadTask 对象的方法列表

方法	参数	说明	最低版本
abort		中断下载任务	*
onProgressUpdate	callback	监听下载进度变化	*
onHeadersReceived	callback	监听 HTTP Response Header 事件，会比请求完成事件更早,仅`微信小程序平台`支持，规范详情
offProgressUpdate	callback	取消监听下载进度变化事件，仅`微信小程序平台`支持，规范详情
offHeadersReceived	callback	取消监听 HTTP Response Header 事件，仅`微信小程序平台`支持，规范详情

onProgressUpdate 返回参数说明

参数	类型	说明
progress	Number	下载进度百分比
totalBytesWritten	Number	已经下载的数据长度，单位 Bytes
totalBytesExpectedToWrite	Number	预期需要下载的数据总长度，单位 Bytes

示例：

const downloadTask = uni.downloadFile({
	url: 'http://www.example.com/file/test', //仅为示例，并非真实的资源
	success: (res) => {
		if (res.statusCode === 200) {
			console.log('下载成功');
		}
	}
});

downloadTask.onProgressUpdate((res) => {
	console.log('下载进度' + res.progress);
	console.log('已经下载的数据长度' + res.totalBytesWritten);
	console.log('预期需要下载的数据总长度' + res.totalBytesExpectedToWrite);

	// 满足测试条件，取消下载任务。
	if (res.progress > 50) {
		downloadTask.abort();
	}
});

uni.connectSocket(OBJECT)

创建一个 WebSocket 连接。

OBJECT 参数说明

参数名	类型	必填	说明	平台差异说明
url	String	是	服务器接口地址	小程序中必须是 `wss://` 协议
multiple	Boolean	否	是否多实例。传入 true 时，将返回一个包含 SocketTask 实例。	仅支付宝小程序支持
header	Object	否	HTTP Header , header 中不能设置 Referer	小程序、App 2.9.6+
method	String	否	默认是GET，有效值：OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT	仅微信小程序支持
protocols	Array<String>	否	子协议数组	App、H5、微信小程序、百度小程序、抖音小程序、飞书小程序
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例：

uni.connectSocket({
	url: 'wss://www.example.com/socket',
	header: {
		'content-type': 'application/json'
	},
	protocols: ['protocol1'],
	method: 'GET'
});

返回值

如果希望返回一个 socketTask 对象，需要至少传入 success / fail / complete 参数中的一个。例如：

var socketTask = uni.connectSocket({
	url: 'wss://www.example.com/socket', //仅为示例，并非真实接口地址。
	complete: ()=> {}
});

注意事项

微信小程序平台1.7.0 及以上版本，最多可以同时存在5个WebSocket 连接。老版本只支持一个socket连接。

uni.onSocketOpen(CALLBACK)

监听WebSocket连接打开事件。

CALLBACK 返回参数

属性	类型	说明
header	Object	连接成功的 HTTP 响应 Header

示例：

uni.connectSocket({
  url: 'wss://www.example.com/socket'
});
uni.onSocketOpen(function (res) {
  console.log('WebSocket连接已打开！');
});

uni.onSocketError(CALLBACK)

监听WebSocket错误。

示例：

uni.connectSocket({
  url: 'wss://www.example.com/socket'
});
uni.onSocketOpen(function (res) {
  console.log('WebSocket连接已打开！');
});
uni.onSocketError(function (res) {
  console.log('WebSocket连接打开失败，请检查！');
});

uni.sendSocketMessage(OBJECT)

通过 WebSocket 连接发送数据，需要先 uni.connectSocket，并在 uni.onSocketOpen 回调之后才能发送。

OBJECT 参数说明：

参数名	类型	必填	说明
data	String/ArrayBuffer	是	需要发送的内容
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例：

var socketOpen = false;
var socketMsgQueue = [];

uni.connectSocket({
  url: 'wss://www.example.com/socket'
});

uni.onSocketOpen(function (res) {
  socketOpen = true;
  for (var i = 0; i < socketMsgQueue.length; i++) {
    sendSocketMessage(socketMsgQueue[i]);
  }
  socketMsgQueue = [];
});

function sendSocketMessage(msg) {
  if (socketOpen) {
    uni.sendSocketMessage({
      data: msg
    });
  } else {
    socketMsgQueue.push(msg);
  }
}

uni.onSocketMessage(CALLBACK)

监听WebSocket接受到服务器的消息事件。

CALLBACK 返回参数

参数	类型	说明
data	String/ArrayBuffer	服务器返回的消息

示例：

uni.connectSocket({
  url: 'wss://www.example.com/socket'
});

uni.onSocketMessage(function (res) {
  console.log('收到服务器内容：' + res.data);
});

uni.closeSocket(OBJECT)

关闭 WebSocket 连接

OBJECT 参数说明

参数名	类型	必填	说明
code	Number	否	一个数字值表示关闭连接的状态号，表示连接被关闭的原因。如果这个参数没有被指定，默认的取值是1000 （表示正常连接关闭）
reason	String	否	一个可读的字符串，表示连接被关闭的原因。这个字符串必须是不长于123字节的UTF-8 文本（不是字符）
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.onSocketClose(CALLBACK)

监听WebSocket关闭事件。

示例：

uni.connectSocket({
  url: 'wss://www.example.com/socket'
});

// 注意这里有时序问题，
// 如果 uni.connectSocket 还没回调 uni.onSocketOpen，而先调用 uni.closeSocket，那么就做不到关闭 WebSocket 的目的。
// 必须在 WebSocket 打开期间调用 uni.closeSocket 才能关闭。
uni.onSocketOpen(function () {
  uni.closeSocket();
});

uni.onSocketClose(function (res) {
  console.log('WebSocket 已关闭！');
});

SocketTask

SocketTask 由 uni.connectSocket() 接口创建。

SocketTask.onMessage(CALLBACK)

监听 WebSocket 接受到服务器的消息事件

回调函数

Function

WebSocket 接受到服务器的消息事件的回调函数

回调函数中的参数

Object

属性	类型	说明
data	String/ArrayBuffer	服务器返回的消息

SocketTask.send(OBJECT)

通过 WebSocket 连接发送数据

参数

属性	类型	是否必填	说明
data	String/ArrayBuffer	是	需要发送的内容
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

SocketTask.close(OBJECT)

关闭 WebSocket 连接

参数

属性	类型	默认值	是否必填	说明
code	Number	1000（表示正常关闭连接）	否	一个数字值表示关闭连接的状态号，表示连接被关闭的原因。
reason	String		否	一个可读的字符串，表示连接被关闭的原因。
success	Function		否	接口调用成功的回调函数
fail	Function		否	接口调用失败的回调函数
complete	Function		否	接口调用结束的回调函数（调用成功、失败都会执行）

SocketTask.onOpen(CALLBACK)

监听 WebSocket 连接打开事件

回调函数

Function

WebSocket 连接打开事件的回调函数

回调函数中的参数

Object

属性	类型	说明
data	String/ArrayBuffer	服务器返回的消息

SocketTask.onClose(CALLBACK)

监听 WebSocket 连接关闭事件

回调函数

Function

WebSocket 连接关闭事件的回调函数

回调函数中的参数

Object

属性	类型	说明	平台兼容性
code	number	一个数字值表示关闭连接的状态号，表示连接被关闭的原因。	HBuilderX(3.7.12+)
reason	string	一个可读的字符串，表示连接被关闭的原因。	HBuilderX(3.7.12+)

SocketTask.onError(CALLBACK)

监听 WebSocket 错误事件

回调函数

Function

WebSocket 错误事件的回调函数

回调函数中的参数

Object

属性	类型	说明
errMsg	String	错误信息

路由跳转

uni.navigateTo(OBJECT)

保留当前页面，跳转到应用内的某个页面，使用uni.navigateBack可以返回到原页面。

OBJECT参数说明

参数	类型	必填	默认值	说明	平台差异说明
url	String	是		需要跳转的应用内非 tabBar 的页面的路径 , 路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'，path为下一个页面的路径，下一个页面的onLoad函数可得到传递的参数
animationType	String	否	pop-in	窗口显示的动画效果，详见：窗口动画	App
animationDuration	Number	否	300	窗口动画持续时间，单位为 ms	App
events	Object	否		页面间通信接口，用于监听被打开页面发送到当前页面的数据。2.8.9+ 开始支持。
success	Function	否		接口调用成功的回调函数
fail	Function	否		接口调用失败的回调函数
complete	Function	否		接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
eventChannel	EventChannel	和被打开页面进行通信

示例：

//在起始页面跳转到test.vue页面并传递参数
uni.navigateTo({
	url: 'test?id=1&name=uniapp'
});

// 在test.vue页面接受参数
export default {
	onLoad: function (option) { //option为object类型，会序列化上个页面传递的参数
		console.log(option.id); //打印出上个页面传递的参数。
		console.log(option.name); //打印出上个页面传递的参数。
	}
}

// 在起始页面跳转到test.vue页面，并监听test.vue发送过来的事件数据
uni.navigateTo({
  url: '/pages/test?id=1',
  events: {
    // 为指定事件添加一个监听器，获取被打开页面传送到当前页面的数据
    acceptDataFromOpenedPage: function(data) {
      console.log(data)
    },
    someEvent: function(data) {
      console.log(data)
    }
    ...
  },
  success: function(res) {
    // 通过eventChannel向被打开页面传送数据
    res.eventChannel.emit('acceptDataFromOpenerPage', { data: 'data from starter page' })
  }
})

// 在test.vue页面，向起始页通过事件传递数据
onLoad: function(option) {
  const eventChannel = this.getOpenerEventChannel();
  eventChannel.emit('acceptDataFromOpenedPage', {data: 'data from test page'});
  eventChannel.emit('someEvent', {data: 'data from test page for someEvent'});
  // 监听acceptDataFromOpenerPage事件，获取上一页面通过eventChannel传送到当前页面的数据
  eventChannel.on('acceptDataFromOpenerPage', function(data) {
    console.log(data)
  })
}

注意：

页面跳转路径有层级限制，不能无限制跳转新页面
跳转到 tabBar 页面只能使用 switchTab 跳转
路由API的目标页面必须是在pages.json里注册的vue页面。如果想打开web url，在App平台可以使用 plus.runtime.openURL或web-view组件；H5平台使用 window.open；小程序平台使用web-view组件（url需在小程序的联网白名单中）

uni.redirectTo(OBJECT)

关闭当前页面，跳转到应用内的某个页面。

OBJECT参数说明

参数	类型	必填	说明
url	String	是	需要跳转的应用内非 tabBar 的页面的路径，路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例：

uni.redirectTo({
	url: 'test?id=1'
});

uni.reLaunch(OBJECT)

关闭所有页面，打开到应用内的某个页面。

注意： 如果调用了 uni.preloadPage(OBJECT) 不会关闭，仅触发生命周期 onHide

OBJECT参数说明

参数	类型	必填	说明
url	String	是	需要跳转的应用内页面路径 , 路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'，如果跳转的页面路径是 tabBar 页面则不能带参数
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例：

uni.reLaunch({
	url: 'test?id=1'
});

export default {
	onLoad: function (option) {
		console.log(option.id);
	}
}

uni.switchTab(OBJECT)

跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面。

注意： 如果调用了 uni.preloadPage(OBJECT) 不会关闭，仅触发生命周期 onHide

OBJECT参数说明

参数	类型	必填	说明
url	String	是	需要跳转的 tabBar 页面的路径（需在 pages.json 的 tabBar 字段定义的页面），路径后不能带参数
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例：

{
  "tabBar": {
    "list": [{
      "pagePath": "pages/index/index",
      "text": "首页"
    },{
      "pagePath": "pages/other/other",
      "text": "其他"
    }]
  }
}

other.vue

uni.switchTab({
	url: '/pages/index/index'
});

uni.navigateBack(OBJECT)

关闭当前页面，返回上一页面或多级页面。可通过 getCurrentPages() 获取当前的页面栈，决定需要返回几层。

OBJECT参数说明

参数	类型	必填	默认值	说明	平台差异说明
delta	Number	否	1	返回的页面数，如果 delta 大于现有页面数，则返回到首页。
animationType	String	否	pop-out	窗口关闭的动画效果，详见：窗口动画	App
animationDuration	Number	否	300	窗口关闭动画的持续时间，单位为 ms	App
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例：

// 注意：调用 navigateTo 跳转时，调用该方法的页面会被加入堆栈，而 redirectTo 方法则不会。见下方示例代码

// 此处是A页面
uni.navigateTo({
	url: 'B?id=1'
});

// 此处是B页面
uni.navigateTo({
	url: 'C?id=1'
});

// 在C页面内 navigateBack，将返回A页面
uni.navigateBack({
	delta: 2
});

EventChannel

页面事件通信，可以在页面加载时，向上一页面发送数据，也可以让上一页面向即将加载的页面发送数据

EventChannel.emit(string eventName, any args)

触发一个事件

string eventName 事件名称

any args 事件参数

EventChannel.off(string eventName, function fn)

取消监听一个事件。给出第二个参数时，只取消给出的监听函数，否则取消所有监听函数

string eventName 事件名称

function fn 事件监听函数

参数 any args 触发事件参数

EventChannel.on(string eventName, function fn)

持续监听一个事件

string eventName 事件名称

function fn 事件监听函数

参数 any args 触发事件参数

EventChannel.once(string eventName, function fn)

监听一个事件一次，触发后失效

string eventName 事件名称

function fn 事件监听函数

参数 any args 触发事件参数

参考事项

页面路由拦截和管理，插件市场有很多封装好的工具类，搜索路由

页面API

getCurrentPages() 获取页面栈

getCurrentPages() 函数用于获取当前页面栈的实例，以数组形式按栈的顺序给出，第一个元素为首页，最后一个元素为当前页面。

注意： getCurrentPages()仅用于展示页面栈的情况，请勿修改页面栈，以免造成页面状态错误。

每个页面实例的方法属性列表：

方法	描述	平台说明
page.$getAppWebview()	获取当前页面的webview对象实例	App
page.$vm	当前页面的 Vue 实例
page.route	获取当前页面的路由

全局页面通讯

常用于跨页面、跨组件通讯

uni.$emit、 uni.$on 、 uni.$once 、uni.$off 触发的事件都是 App 全局级别的，跨任意组件，页面，nvue，vue 等
使用时，注意及时销毁事件监听，比如，页面 onLoad 里边 uni.$on 注册监听，onUnload 里边 uni.$off 移除，或者一次性的事件，直接使用 uni.$once 监听
注意 uni.$on 定义完成后才能接收到 uni.$emit 传递的数据

uni.$emit(eventName,OBJECT)

触发全局的自定义事件，附加参数都会传给监听器回调函数。

属性	类型	描述
eventName	String	事件名
OBJECT	Object	触发事件携带的附加参数

示例：

uni.$emit('update',{msg:'页面更新'})

uni.$on(eventName,callback)

监听全局的自定义事件，事件由 uni.$emit 触发，回调函数会接收事件触发函数的传入参数。

属性	类型	描述
eventName	String	事件名
callback	Function	事件的回调函数

示例：

uni.$on('update',function(data){
		console.log('监听到事件来自 update ，携带参数 msg 为：' + data.msg);
	})

uni.$once(eventName,callback)

监听全局的自定义事件，事件由 uni.$emit 触发，但仅触发一次，在第一次触发之后移除该监听器。

属性	类型	描述
eventName	String	事件名
callback	Function	事件的回调函数

uni.$once('update',function(data){
		console.log('监听到事件来自 update ，携带参数 msg 为：' + data.msg);
	})

uni.$off([eventName, callback])

移除全局自定义事件监听器。

属性	类型	描述
eventName	Array＜String＞	事件名
callback	Function	事件的回调函数

Tips

如果uni.$off没有传入参数，则移除App级别的所有事件监听器；
如果只提供了事件名（eventName），则移除该事件名对应的所有监听器；
如果同时提供了事件与回调，则只移除这个事件回调的监听器；
提供的回调必须跟$on的回调为同一个才能移除这个回调的监听器；

数据存储(缓存)

uni.setStorage(OBJECT)

将数据存储在本地缓存中指定的 key 中，会覆盖掉原来该 key 对应的内容，这是一个异步接口。

OBJECT 参数说明

参数名	类型	必填	说明
key	String	是	本地缓存中的指定的 key
data	Any	是	需要存储的内容，只支持原生类型、及能够通过 JSON.stringify 序列化的对象
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例：

uni.setStorage({
	key: 'storage_key',
	data: 'hello',
	success: function () {
		console.log('success');
	}
});

注意：uni-、uni_、dcloud-、dcloud_为前缀的key，为系统保留关键前缀。如uni_deviceId、uni_id_token，请开发者为key命名时避开这些前缀。

uni.setStorageSync(KEY,DATA)

将 data 存储在本地缓存中指定的 key 中，会覆盖掉原来该 key 对应的内容，这是一个同步接口。

参数说明

参数	类型	必填	说明
key	String	是	本地缓存中的指定的 key
data	Any	是	需要存储的内容，只支持原生类型、及能够通过 JSON.stringify 序列化的对象

示例：

try {
	uni.setStorageSync('storage_key', 'hello');
} catch (e) {
	// error
}

uni.getStorage(OBJECT)

从本地缓存中异步获取指定 key 对应的内容。

OBJECT 参数说明

参数名	类型	必填	说明
key	String	是	本地缓存中的指定的 key
success	Function	是	接口调用的回调函数，res = {data: key对应的内容}
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数	类型	说明
data	Any	key 对应的内容

示例：

uni.getStorage({
	key: 'storage_key',
	success: function (res) {
		console.log(res.data);
	}
});

uni.getStorageSync(KEY)

从本地缓存中同步获取指定 key 对应的内容。

参数说明

参数	类型	必填	说明
key	String	是	本地缓存中的指定的 key

示例：

try {
	const value = uni.getStorageSync('storage_key');
	if (value) {
		console.log(value);
	}
} catch (e) {
	// error
}

uni.getStorageInfo(OBJECT)

异步获取当前 storage 的相关信息。

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	是	接口调用的回调函数，详见返回参数说明
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数	类型	说明
keys	Array＜String＞	当前 storage 中所有的 key
currentSize	Number	当前占用的空间大小, 单位：kb
limitSize	Number	限制的空间大小, 单位：kb

示例：

uni.getStorageInfo({
	success: function (res) {
		console.log(res.keys);
		console.log(res.currentSize);
		console.log(res.limitSize);
	}
});

uni.getStorageInfoSync()

同步获取当前 storage 的相关信息。

示例：

try {
	const res = uni.getStorageInfoSync();
	console.log(res.keys);
	console.log(res.currentSize);
	console.log(res.limitSize);
} catch (e) {
	// error
}

uni.removeStorage(OBJECT)

从本地缓存中异步移除指定 key。

OBJECT 参数说明

参数名	类型	必填	说明
key	String	是	本地缓存中的指定的 key
success	Function	是	接口调用的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例：

uni.removeStorage({
	key: 'storage_key',
	success: function (res) {
		console.log('success');
	}
});

uni.removeStorageSync(KEY)

从本地缓存中同步移除指定 key。

参数说明

参数名	类型	必填	说明
key	String	是	本地缓存中的指定的 key

示例：

try {
	uni.removeStorageSync('storage_key');
} catch (e) {
	// error
}

uni.clearStorage()

清理本地数据缓存。

uni.clearStorage();

uni.clearStorageSync()

同步清理本地数据缓存。

try {
	uni.clearStorageSync();
} catch (e) {
	// error
}

位置操作

uni.getLocation(OBJECT)

获取当前的地理位置、速度。

OBJECT 参数说明

参数名	类型	必填	说明	平台差异说明
type	String	否	默认为 wgs84 返回 gps 坐标，gcj02 返回国测局坐标，可用于 `uni.openLocation` 和 map 组件坐标，App 和 H5 需配置定位 SDK 信息才可支持 gcj02。
altitude	Boolean	否	传入 true 会返回高度信息，由于获取高度需要较高精确度，会减慢接口返回速度	抖音小程序、飞书小程序、支付宝小程序不支持
geocode	Boolean	否	默认false，是否解析地址信息	仅App平台支持（安卓需指定 type 为 gcj02 并配置三方定位SDK）
highAccuracyExpireTime	Number	否	高精度定位超时时间(ms)，指定时间内返回最高精度，该值3000ms以上高精度定位才有效果	App (3.2.11+)、H5 (3.2.11+)、微信小程序 (基础库 2.9.0+)
timeout	String	否	默认为 5，定位超时时间，单位秒	仅飞书小程序支持
cacheTimeout	Number	否	定位缓存超时时间，单位秒；每次定位缓存当前定位数据，并记下时间戳，当下次调用在cacheTimeout之内时，返回缓存数据	仅飞书小程序、支付宝小程序支持
accuracy	String	否	默认为 high，指定期望精度，支持 high，best。当指定 high 时，期望精度值为100m，当指定 best 时期望精度值为20m。当定位得到的精度不符合条件时，在timeout之前会继续定位，尝试拿到符合要求的定位结果	仅飞书小程序支持
isHighAccuracy	Boolean	否	开启高精度定位	App (3.4.0+)、H5 (3.4.0+)、微信小程序 (基础库 2.9.0+)
success	Function	是	接口调用成功的回调函数，返回内容详见返回参数说明。
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数	说明
latitude	纬度，浮点数，范围为-90~90，负数表示南纬
longitude	经度，浮点数，范围为-180~180，负数表示西经
speed	速度，浮点数，单位m/s
accuracy	位置的精确度
altitude	高度，单位 m
verticalAccuracy	垂直精度，单位 m（Android 无法获取，返回 0）
horizontalAccuracy	水平精度，单位 m
address	地址信息（仅App端支持，需配置geocode为true）

address 地址信息说明

属性	类型	描述	说明
country	String	国家	如“中国”，如果无法获取此信息则返回undefined
province	String	省份名称	如“北京市”，如果无法获取此信息则返回undefined
city	String	城市名称	如“北京市”，如果无法获取此信息则返回undefined
district	String	区（县）名称	如“朝阳区”，如果无法获取此信息则返回undefined
street	String	街道信息	如“酒仙桥路”，如果无法获取此信息则返回undefined
streetNum	String	获取街道门牌号信息	如“3号”，如果无法获取此信息则返回undefined
poiName	String	POI信息	如“电子城．国际电子总部”，如果无法获取此信息则返回undefined
postalCode	String	邮政编码	如“100016”，如果无法获取此信息则返回undefined
cityCode	String	城市代码	如“010”，如果无法获取此信息则返回undefined

示例：

uni.getLocation({
	type: 'wgs84',
	success: function (res) {
		console.log('当前位置的经度：' + res.longitude);
		console.log('当前位置的纬度：' + res.latitude);
	}
});

注意：

- api默认不返回详细地址中文描述。需要中文地址有2种方式：1、使用高德地图小程序sdk，在app和微信上都可以获得中文地址，参考。2、只考虑app，使用plus.geolocation也可以获取中文地址。manifest里的App SDK配置仅用于app，小程序无需在这里配置。
- 可以通过用户授权API来判断用户是否给应用授予定位权限，详见
- 在 微信小程序 中，当用户离开应用后，此接口无法调用，需要申请后台持续定位权限，另外新版本中需要使用 wx.onLocationChange 监听位置信息变化；当用户点击“显示在聊天顶部”时，此接口可继续调用。

uni.chooseLocation(OBJECT)

打开地图选择位置。

OBJECT 参数说明

参数名	类型	必填	说明	平台差异说明
latitude	Number	否	目标地纬度	微信小程序（2.9.0+）、H5-Vue3（3.2.10+）
longitude	Number	否	目标地经度	微信小程序（2.9.0+）、H5-Vue3（3.2.10+）
keyword	String	否	搜索关键字，仅App平台支持
success	Function	是	接口调用成功的回调函数，返回内容详见返回参数说明。
fail	Function	否	接口调用失败的回调函数（获取定位失败、用户取消等情况下触发）
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

因平台差异，如果SDK配置百度地图，需要设置 keyword，才能显示相关地点

success 返回参数说明

参数	说明
name	位置名称
address	详细地址
latitude	纬度，浮点数，范围为-90~90，负数表示南纬，使用 gcj02 国测局坐标系。
longitude	经度，浮点数，范围为-180~180，负数表示西经，使用 gcj02 国测局坐标系。

示例：

uni.chooseLocation({
	success: function (res) {
		console.log('位置名称：' + res.name);
		console.log('详细地址：' + res.address);
		console.log('纬度：' + res.latitude);
		console.log('经度：' + res.longitude);
	}
});

uni.openLocation(OBJECT)

使用应用内置地图查看位置。

OBJECT 参数说明

参数名	类型	必填	说明	平台差异说明
latitude	Float	是	纬度，范围为-90~90，负数表示南纬，使用 gcj02 国测局坐标系
longitude	Float	是	经度，范围为-180~180，负数表示西经，使用 gcj02 国测局坐标系
scale	Int	否	缩放比例，范围5~18，默认为18	微信小程序
name	String	否	位置名	支付宝必填
address	String	否	地址的详细说明	支付宝必填
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例：

uni.getLocation({
	type: 'gcj02', //返回可以用于uni.openLocation的经纬度
	success: function (res) {
		const latitude = res.latitude;
		const longitude = res.longitude;
		uni.openLocation({
			latitude: latitude,
			longitude: longitude,
			success: function () {
				console.log('success');
			}
		});
	}
});

uni.onLocationChange(FUNCTION CALLBACK)

监听实时地理位置变化事件，需结合 uni.startLocationUpdate 或 uni.startLocationUpdateBackground 使用。

FUNCTION CALLBACK 参数

参数名	类型	说明	平台差异说明
latitude	Number	纬度，范围为 -90~90，负数表示南纬。
longitude	Number	经度，范围为 -180~180，负数表示西经。
speed	Number	速度 (m/s)	H5不支持
accuracy	number	位置的精确度
altitude	number	高度 (m)	H5不支持
verticalAccuracy	number	垂直精度 (m)	抖音小程序、快手小程序 Android 无法获取，返回 0
horizontalAccuracy	number	水平精度 (m)	抖音小程序不支持
city	string	定位到的城市信息	百度小程序、抖音小程序（iOS 不支持）
cityCode	String	城市编码	百度小程序	street	String	街道名称
city	String	城市名称	百度小程序
country	String	国家	百度小程序
countryCode	String	国家代码	百度小程序
province	String	省份	百度小程序
streetNumber	String	街道号码	百度小程序
district	String	区	百度小程序
isFullAccuracy	Boolean	是不是精确定位信息	百度小程序
altitudeAccuracy	Number	海拔的精确度信息	App

注意：

该方法会持续监听地理位置信息的变化，建议在不需要监听地理位置信息变化后，直接调用 uni.stopLocationUpdate 方法取消监听。
微信小程序若使用该接口，需要在 app.json 中进行声明，否则将无法正常使用该接口，详情
抖音小程序调用此 API 需要申请高精度权限，具体信息见高精度定位运营规范。

示例：

uni.onLocationChange(function (res) {
	console.log('纬度：' + res.latitude);
	console.log('经度：' + res.longitude);
});

uni.offLocationChange(FUNCTION CALLBACK)

关闭监听实时位置变化，前后台都停止消息接收。

FUNCTION CALLBACK 参数

参数名	类型	说明	平台差异说明
latitude	number	纬度，范围 [-90, 90]，负数表示南纬	快手小程序
longitude	number	经度，范围 [-180, 180]，负数表示西经	快手小程序
speed	number	速度 (m/s)	快手小程序
accuracy	number	位置的精确度	快手小程序
altitude	number	高度 (m)	快手小程序
verticalAccuracy	number	垂直精度 (m)（Android 无法获取，返回 0）	快手小程序
horizontalAccuracy	number	水平精度 (m)	快手小程序

uni.onLocationChangeError(FUNCTION CALLBACK)

监听持续定位接口返回失败时触发。

FUNCTION CALLBACK 参数

参数名	类型	说明	平台差异说明
errCode	Number	错误	微信小程序
errMsg	String	错误信息	抖音小程序

uni.offLocationChangeError(FUNCTION CALLBACK)

取消注册位置更新错误回调。

FUNCTION CALLBACK 参数

无返回值

uni.startLocationUpdate(OBJECT)

开启小程序进入前台时接收位置消息。

OBJECT 参数

参数名	类型	必填	说明	平台差异说明
type	String	否	指定坐标系类型，可以是 wgs84 或 gcj02	微信小程序、抖音小程序
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）
needFullAccuracy	Boolean	否	针对 iOS14/Android12 及以上的新特性，其他情况本参数忽略。默认情况宿主是精确定位就返回精确定位信息。传入 true 会强制使用精确定位信息，iOS14/Android12 及以上如果没有精确定位权限，会弹出精确定位授权弹框。

示例：

uni.startLocationUpdate({
  success: res => console.log('开启小程序接收位置消息成功'),
  fail: err => console.error('开启小程序接收位置消息失败：', err),
  complete: msg => console.log('调用开启小程序接收位置消息 API 完成')
});

uni.stopLocationUpdate(OBJECT)

关闭监听实时位置变化，前后台都停止消息接收。

OBJECT 参数

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.startLocationUpdateBackground(OBJECT)

开始监听实时地理位置信息变化事件，小程序进入前后台时均接收实时地理位置信息。

OBJECT 参数

参数名	类型	必填	说明	平台差异说明
type	String	否	指定坐标系类型，可以是 wgs84 或 gcj02	微信小程序、抖音小程序
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.createMapContext(mapId,this)

创建并返回 map 上下文 mapContext 对象。在自定义组件下，第二个参数传入组件实例this，以操作组件内 <map> 组件。

mapContext 通过 mapId 跟一个 <map> 组件绑定，通过它可以操作对应的 <map> 组件。

mapContext 对象的方法列表

方法	参数	说明	平台差异说明
getCenterLocation	OBJECT	获取当前地图中心的经纬度，返回的是 gcj02 坐标系，可以用于 uni.openLocation
moveToLocation	OBJECT	将地图中心移动到当前定位点，需要配合map组件的show-location使用
translateMarker	OBJECT	平移marker，带动画	app-nvue 2.1.5+、微信小程序带动画、抖音、支付宝、京东、百度、QQ小程序
includePoints	OBJECT	缩放视野展示所有经纬度	app-nvue 2.1.5+、微信、抖音、支付宝、京东、百度、快手、QQ小程序
getRegion	OBJECT	获取当前地图的视野范围
getRotate	OBJECT	获取当前地图的旋转角	微信、抖音、支付宝、京东、QQ小程序
getScale	OBJECT	获取当前地图的缩放级别
getSkew	OBJECT	获取当前地图的倾斜角	微信、抖音、支付宝、京东、QQ小程序
addCustomLayer	OBJECT	添加个性化图层	微信小程序
addGroundOverlay	OBJECT	创建自定义图片图层，图片会随着地图缩放而缩放	App-nvue 3.1.0+，微信、抖音小程序
addMarkers	OBJECT	添加 marker	App-nvue 3.1.0+，微信小程序
fromScreenLocation	OBJECT	获取屏幕上的点对应的经纬度，坐标原点为地图左上角	微信小程序
initMarkerCluster	OBJECT	初始化点聚合的配置，未调用时采用默认配置	App-nvue 3.1.0+，微信小程序
moveAlong	OBJECT	沿指定路径移动 marker，用于轨迹回放等场景。动画完成时触发回调事件，若动画进行中，对同一 marker 再次调用 moveAlong 方法，前一次的动画将被打断。支持 android，不支持 autoRotate 属性设置，默认为 ture	App-nvue 3.1.0+，微信、抖音小程序
openMapApp	OBJECT	拉起地图APP选择导航。	App-nvue 3.1.0+，微信、抖音、快手小程序
removeCustomLayer	OBJECT	移除个性化图层	微信小程序
removeGroundOverlay	OBJECT	移除自定义图片图层	App-nvue 3.1.0+，微信小程序
removeMarkers	OBJECT	移除 marker。	App-nvue 3.1.0+，微信小程序
setCenterOffset	OBJECT	设置地图中心点偏移，向后向下为增长，屏幕比例范围(0.25~0.75)，默认偏移为[0.5, 0.5]	微信、抖音小程序
toScreenLocation	OBJECT	获取经纬度对应的屏幕坐标，坐标原点为地图左上角。	微信小程序
updateGroundOverlay	OBJECT	更新自定义图片图层。	App-nvue 3.1.0+，微信、抖音小程序
on	Method	监听地图事件。	App-nvue 3.1.0+，微信小程序
$getAppMap		获取原生地图对象 plus.maps.Map	App-nvue 1.9.3

$getAppMap() 注意事项：

在页面中，必须在 onReady 中调用。
在组件中，必须在 mounted 中调用。
nvue没有$getAppMap()，请使用createMapContext
uni-app中使用原生地图无需提供占位div，得到$getAppMap()后直接js使用即可。
openMapApp iOS 暂不支持，后续补充

getCenterLocation 的 OBJECT 参数列表

参数	类型	必填	说明
success	Function	否	接口调用成功的回调函数，res = { longitude: "经度", latitude: "纬度"}
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

moveToLocation 的 OBJECT 参数列表

参数	类型	必填	说明
longitude	Number	否	经度，App 2.6.8、H5、京东小程序、仅微信小程序 2.8.0+ 支持
latitude	Number	否	纬度，App 2.6.8、H5、京东小程序、仅微信小程序 2.8.0+ 支持
success	Function	否	接口调用成功的回调函数，res = { longitude: "经度", latitude: "纬度"}
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

translateMarker 的 OBJECT 参数列表

参数	类型	必填	说明
markerId	Number	是	指定 marker
destination	Object	是	指定 marker 移动到的目标点
autoRotate	Boolean	是	移动过程中是否自动旋转 marker
rotate	Number	是	marker 的旋转角度
moveWithRotate	Boolean	否	平移和旋转同时进行，默认值false（仅微信小程序2.13.0支持）
duration	Number	否	动画持续时长，默认值1000ms，平移与旋转分别计算
animationEnd	Function	否	动画结束回调函数
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

includePoints 的 OBJECT 参数列表

参数	类型	必填	说明
points	Array	是	要显示在可视区域内的坐标点列表，[{latitude, longitude}]
padding	Array	否	坐标点形成的矩形边缘到地图边缘的距离，单位像素。格式为[上，右，下，左]，安卓上只能识别数组第一项，上下左右的padding一致。开发者工具暂不支持padding参数。
success	Function	否	接口调用成功的回调函数（支付宝小程序不支持）
fail	Function	否	接口调用失败的回调函数（支付宝小程序不支持）
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）（支付宝小程序不支持）

getRegion 的 OBJECT 参数列表

参数	类型	必填	说明
success	Function	否	接口调用成功的回调函数，res = {southwest, northeast}，西南角与东北角的经纬度
fail	Function	否	接口调用失败的回调函数（支付宝小程序不支持）
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）（支付宝小程序不支持）

getRotate 的 OBJECT 参数列表

参数	类型	必填	说明
success	Function	否	接口调用成功的回调函数，res = {rotate}，旋转角
fail	Function	否	接口调用失败的回调函数（支付宝小程序不支持）
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）（支付宝小程序不支持）

getScale 的 OBJECT 参数列表

参数	类型	必填	说明
success	Function	否	接口调用成功的回调函数，res = {scale}，缩放值
fail	Function	否	接口调用失败的回调函数（支付宝小程序不支持）
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）（支付宝小程序不支持）

getSkew 的 OBJECT 参数列表

参数	类型	必填	说明
success	Function	否	接口调用成功的回调函数，res = {skew}，倾斜角
fail	Function	否	接口调用失败的回调函数（支付宝小程序不支持）
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）（支付宝小程序不支持）

addCustomLayer 的 OBJECT 参数列表

属性	类型	必填	说明
layerId	string	是	个性化图层id
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

addGroundOverlay 的 OBJECT 参数列表

属性	类型	默认值	必填	说明
id	String		是	图片图层 id
src	String		是	图片路径，支持网络图片、临时路径、代码包路径
bounds	Object		是	图片覆盖的经纬度范围
visible	Boolean	true	否	是否可见
zIndex	Number	1	否	图层绘制顺序
opacity	Number	1	否	图层透明度
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.bounds 的结构

属性	类型	默认值	必填	说明
southwest	Object		是	西南角经纬度
northeast	Object		是	东北角经纬度

southwest 的结构

属性	类型	默认值	必填	说明
longitude	number		是	经度
latitude	number		是	纬度

northeast 的结构

属性	类型	默认值	必填	说明
longitude	number		是	经度
latitude	number		是	纬度

addMarkers 的 OBJECT 参数列表

属性	类型	默认值	必填	说明
markers	Array		是	同传入 map 组件的 marker 属性
clear	boolean	false	否	是否先清空地图上所有 marker
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

removeMarkers 的 OBJECT 参数列表

属性	类型	必填	说明
markerIds	Array	是	要被删除的marker的id属性组成的数组
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

moveAlong 的 OBJECT 参数列表

属性	类型	默认值	必填	说明
markerId	Number		是	指定 marker
path	Array		是	移动路径的坐标串，坐标点格式 {longitude, latitude}
autoRotate	boolean	true	否	根据路径方向自动改变 marker 的旋转角度
duration	number		是	平滑移动的时间
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

openMapApp 的 OBJECT 参数列表

属性	类型	必填	说明
longitude	Number	是	目的地经度
latitude	Number	是	目的地纬度
destination	String	是	目的地名称
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

setLocMarkerIcon 的 OBJECT 参数列表@setLocMarkerIcon

属性	类型	必填	说明
iconPath	string	否	图标路径，支持网络路径、本地路径、代码包路径
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

App nvue 3.6.9+ 支持

mapContext （App平台地图服务商差异）

属性	说明	高德是否支持	google地图是否支持
setLocMarkerIcon	设置定位点图标，支持网络路径、本地路径、代码包路径	已支持	不支持
moveAlong	沿指定路径移动 marker，用于轨迹回放等场景	已支持(不支持autoRotate属性)	已支持
addCustomLayer	添加个性化图层	不支持	不支持
removeVisualLayer	移除可视化图层	不支持	不支持
fromScreenLocation	获取屏幕上的点对应的经纬度，坐标原点为地图左上角	不支持	不支持
removeCustomLayer	移除个性化图层	不支持	不支持
setCenterOffset	设置地图中心点偏移，向后向下为增长，屏幕比例范围(0.25~0.75)	不支持	不支持
toScreenLocation	获取经纬度对应的屏幕坐标，坐标原点为地图左上角。	不支持	不支持

MapContext.on() (app-nvue、微信小程序支持)

markerClusterCreate 缩放或拖动导致新的聚合簇产生时触发，仅返回新创建的聚合簇信息。

返回参数

参数	类型	说明
clusters	Array<ClusterInfo>	聚合簇数据

markerClusterClick 聚合簇的点击事件。

返回参数

参数	类型	说明
cluster	ClusterInfo	聚合簇

ClusterInfo 结构

参数	类型	说明
clusterId	Number	聚合簇的 id
center	LatLng	聚合簇的坐标
markerIds	Array<Number>	该聚合簇内的点标记数据数组

initMarkerCluster(OBJECT) 结构

属性	类型	默认值	必填	说明
enableDefaultStyle	boolean	true	否	启用默认的聚合样式
zoomOnClick	boolean	true	否	点击已经聚合的标记点时是否实现聚合分离
gridSize	boolean	60	否	聚合算法的可聚合距离，即距离小于该值的点会聚合至一起，以像素为单位
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

三方定位和地图服务

unicloud-city-select 城市选择组件

若想要实现城市选择功能，可以使用 unicloud-city-select 城市选择组件。

下载地址：https://ext.dcloud.net.cn/plugin?name=unicloud-city-select

文档地址：https://uniapp.dcloud.net.cn/uniCloud/unicloud-city-select.html

图片操作

uni.chooseImage(OBJECT) 选择图片

从本地相册选择图片或使用相机拍照。

微信小程序从基础库 2.21.0 开始， wx.chooseImage 停止维护，请使用 uni.chooseMedia 代替。

OBJECT 参数说明

参数名	类型	必填	说明	平台差异说明
count	Number	否	最多可以选择的图片张数，默认9	见下方说明
sizeType	Array<String>	否	original 原图，compressed 压缩图，默认二者都有	App、微信小程序、支付宝小程序、百度小程序
extension	Array<String>	否	根据文件拓展名过滤，每一项都不能是空字符串。默认不过滤。	H5(HBuilder X2.9.9+)
sourceType	Array<String>	否	album 从相册选图，camera 使用相机，默认二者都有。如需直接开相机或直接选相册，请只使用一个选项
crop	Object	否	图像裁剪参数，设置后 sizeType 失效	App 3.1.19+
success	Function	是	成功则返回图片的本地文件路径列表 tempFilePaths
fail	Function	否	接口调用失败的回调函数	小程序、App
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

crop 参数说明

参数名	类型	必填	说明
quality	Number	否	取值范围为1-100，数值越小，质量越低（仅对jpg格式有效）。默认值为80。
width	Number	是	裁剪的宽度，单位为px，用于计算裁剪宽高比。
height	Number	是	裁剪的高度，单位为px，用于计算裁剪宽高比。
resize	Boolean	否	是否将width和height作为裁剪保存图片真实的像素值。默认值为true。注：设置为false时在裁剪编辑界面显示图片的像素值，设置为true时不显示

选择照片大多为了上传，uni ui封装了更完善的uni-file-picker组件，文件选择、上传到uniCloud的免费存储和cdn中，一站式集成。强烈推荐使用。

注：文件的临时路径，在应用本次启动期间可以正常使用，如需持久保存，需在主动调用 uni.saveFile，在应用下次启动时才能访问得到。

success 返回参数说明

参数	类型	说明
tempFilePaths	Array<String>	图片的本地文件路径列表
tempFiles	Array<Object>、Array<File>	图片的本地文件列表，每一项是一个 File 对象

File 对象结构如下

参数	类型	说明
path	String	本地文件路径
size	Number	本地文件大小，单位：B
name	String	包含扩展名的文件名称，仅H5支持
type	String	文件类型，仅H5支持

示例：

uni.chooseImage({
	count: 6, //默认9
	sizeType: ['original', 'compressed'], //可以指定是原图还是压缩图，默认二者都有
	sourceType: ['album'], //从相册选择
	success: function (res) {
		console.log(JSON.stringify(res.tempFilePaths));
	}
});

uni.previewImage(OBJECT) 预览图片

OBJECT 参数说明

参数名	类型	必填	说明	平台差异说明
current	String/Number	详见下方说明	详见下方说明
urls	Array<String>	是	需要预览的图片链接列表
indicator	String	否	图片指示器样式，可取值："default" - 底部圆点指示器； "number" - 顶部数字指示器； "none" - 不显示指示器。	App
loop	Boolean	否	是否可循环预览，默认值为 false	App
longPressActions	Object	否	长按图片显示操作菜单，如不填默认为保存相册	App 1.9.5+
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

current 参数说明

current 为当前显示图片的链接/索引值，不填或填写的值无效则为 urls 的第一张。

注意，当 urls 中有重复的图片链接时：

传链接，预览结果始终显示该链接在 urls 中第一次出现的位置。
传索引值，在微信/百度/抖音小程序平台，会过滤掉传入的 urls 中该索引值之前与其对应图片链接重复的值。其它平台会保留原始的 urls 不会做去重处理。

举例说明：

一组图片 [A, B1, C, B2, D]，其中 B1 与 B2 的图片链接是一样的。

传 B2 的链接，预览的结果是 B1，前一张是 A，下一张是 C。
传 B2 的索引值 3，预览的结果是 B2，前一张是 C，下一张是 D。此时在微信/百度/抖音小程序平台，最终传入的 urls 是 [A, C, B2, D]，过滤掉了与 B2 重复的 B1。

longPressActions 参数说明

参数	类型	必填	说明
itemList	Array<String>	是	按钮的文字数组
itemColor	String	否	按钮的文字颜色，字符串格式，默认为"#000000"
success	Function	否	接口调用成功的回调函数，详见返回参数说明
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数	类型	说明
index	Number	用户长按图片的索引值
tapIndex	Number	用户点击按钮列表的索引值

示例：

// 从相册选择6张图
uni.chooseImage({
	count: 6,
	sizeType: ['original', 'compressed'],
	sourceType: ['album'],
	success: function(res) {
		// 预览图片
		uni.previewImage({
			urls: res.tempFilePaths,
			longPressActions: {
				itemList: ['发送给朋友', '保存图片', '收藏'],
				success: function(data) {
					console.log('选中了第' + (data.tapIndex + 1) + '个按钮,第' + (data.index + 1) + '张图片');
				},
				fail: function(err) {
					console.log(err.errMsg);
				}
			}
		});
	}
	});

uni.closePreviewImage(OBJECT)

关闭预览图片。仅支持APP与H5

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.getImageInfo(OBJECT)

获取图片信息。

小程序下获取网络图片信息需先配置download域名白名单才能生效。

OBJECT 参数说明

参数名	类型	必填	说明
src	String	是	图片的路径，可以是相对路径，临时文件路径，存储文件路径，网络图片路径
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数名	类型	说明	平台差异说明
width	Number	图片宽度，单位px
height	Number	图片高度，单位px
path	String	返回图片的本地路径
orientation	String	返回图片的方向，有效值见下表	App、小程序、京东小程序
type	String	返回图片的格式	App、小程序、京东小程序

orientation 参数说明

枚举值	说明
up	默认
down	180度旋转
left	逆时针旋转90度
right	顺时针旋转90度
up-mirrored	同up，但水平翻转
down-mirrored	同down，但水平翻转
left-mirrored	同left，但垂直翻转
right-mirrored	同right，但垂直翻转

示例：

uni.chooseImage({
	count: 1,
	sourceType: ['album'],
	success: function (res) {
		uni.getImageInfo({
			src: res.tempFilePaths[0],
			success: function (image) {
				console.log(image.width);
				console.log(image.height);
			}
		});
	}
});

uni.saveImageToPhotosAlbum(OBJECT)

保存图片到系统相册。

OBJECT 参数说明

参数名	类型	必填	说明
filePath	String	是	图片文件路径，可以是临时文件路径也可以是永久文件路径，不支持网络图片路径
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数名	类型	说明
path	String	保存到相册的图片路径，仅 App 3.0.5+ 支持
errMsg	String	调用结果

示例：

uni.chooseImage({
	count: 1,
	sourceType: ['camera'],
	success: function (res) {
		uni.saveImageToPhotosAlbum({
			filePath: res.tempFilePaths[0],
			success: function () {
				console.log('save success');
			}
		});
	}
});

uni.compressImage(OBJECT)

压缩图片接口，可选压缩质量

OBJECT 参数说明

属性	类型	默认值	必填	说明	平台差异说明
src	String		是	图片路径，图片的路径，可以是相对路径、临时文件路径、存储文件路径
quality	Number	80	否	压缩质量，范围0～100，数值越小，质量越低，压缩率越高（仅对jpg有效）
width	String	auto	否	缩放图片的宽度，支持像素值（如"100px"）、百分比（如"50%"）、自动计算（如"auto"，即根据width与源图宽的缩放比例计算，若未设置width则使用源图宽度）	App 3.0.0+
height	String	auto	否	缩放图片的高度，支持像素值（如"100px"）、百分比（如"50%"）、自动计算（如"auto"，即根据height与源图高的缩放比例计算，若未设置height则使用源图高度）	App 3.0.0+
compressedWidth	Number	-	否	压缩后图片的宽度，单位为px，若不填写则默认以 compressHeight 为准等比缩放	微信小程序2.26.0 +
compressHeight	Number	-	否	压缩后图片的高度，单位为px，若不填写则默认以 compressedWidth 为准等比缩放	微信小程序2.26.0 +
rotate	Number	0	否	旋转度数，范围0～360	App 3.0.0+
success	Function		否	接口调用成功的回调函数
fail	Function		否	接口调用失败的回调函数
complete	Function		否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

属性	类型	说明
tempFilePath	String	压缩后图片的临时文件路径

示例：

uni.compressImage({
  src: '/static/logo.jpg',
  quality: 80,
  success: res => {
    console.log(res.tempFilePath)
  }
})

视频操作

uni.chooseVideo(OBJECT)

拍摄视频或从手机相册中选视频，返回视频的临时文件路径。

若选择和上传非图像、视频文件，另行参考：https://uniapp.dcloud.io/api/media/file

OBJECT 参数说明

参数名	类型	必填	说明	平台差异说明
sourceType	Array<String>	否	album 从相册选视频，camera 使用相机拍摄，默认为：['album', 'camera']
extension	Array<String>	否	根据文件拓展名过滤，每一项都不能是空字符串。默认不过滤。	H5(HBuilder X 2.9.9+)
compressed	Boolean	否	是否压缩所选的视频源文件，默认值为 true，需要压缩。	微信小程序、百度小程序、抖音小程序、飞书小程序、京东小程序、App(HBuilder X 3.2.7+)
maxDuration	Number	否	拍摄视频最长拍摄时间，单位秒。最长支持 60 秒。	APP平台 1.9.7+(iOS支持，Android取决于ROM的拍照组件是否实现此功能，如果没实现此功能则忽略此属性。) 微信小程序、百度小程序、京东小程序
camera	String	否	'front'、'back'，默认'back'	APP、微信小程序、京东小程序
success	Function	否	接口调用成功，返回视频文件的临时文件路径，详见返回参数说明。
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数	类型	说明	平台差异
tempFilePath	String	选定视频的临时文件路径
tempFile	File	选定的视频文件	仅H5（2.6.15+）支持
duration	Number	选定视频的时间长度，单位为 s	APP 2.1.0+、H5、微信小程序、京东小程序
size	Number	选定视频的数据量大小	APP 2.1.0+、H5、微信小程序、京东小程序
height	Number	返回选定视频的高	APP 2.1.0+、H5、微信小程序、京东小程序
width	Number	返回选定视频的宽	APP 2.1.0+、H5、微信小程序、京东小程序
name	String	包含扩展名的文件名称	仅H5支持

示例：

<template>
	<view>
		<text>hello</text>
		<button @tap="test">click me</button>
		<video :src="src"></video>
	</view>
</template>

export default {
	data() {
		return {
			src: ''
		}
	},
	methods: {
		test: function () {
			var self = this;
			uni.chooseVideo({
				sourceType: ['camera', 'album'],
				success: function (res) {
					self.src = res.tempFilePath;
				}
			});
		}
	}
}

uni.chooseMedia(OBJECT) 微信小程序选择图片

拍摄或从手机相册中选择图片或视频。

若选择和上传非图像、视频文件，另行参考：https://uniapp.dcloud.io/api/media/file

OBJECT 参数说明

参数名	类型	默认值	必填	说明
count	Number	9（注意：ios不可大于9）	否	最多可以选择的文件个数
mediaType	Array.<string>	['image', 'video']	否	文件类型
sourceType	Array.<string>	['album', 'camera']	否	图片和视频选择的来源
maxDuration	Number	10	否	拍摄视频最长拍摄时间，单位秒。时间范围为 3s 至 30s 之间
sizeType	Array.<string>	['original', 'compressed']	否	仅对 mediaType 为 image 时有效，是否压缩所选文件
camera	String	'back'	否	仅在 sourceType 为 camera 时生效，使用前置或后置摄像头
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

OBJECT.mediaType 合法值

值	说明
image	只能拍摄图片或从相册选择图片
video	只能拍摄视频或从相册选择视频
mix	可同时选择图片和视频

OBJECT.sourceType 合法值

值	说明
album	从相册选择
camera	使用相机拍摄

OBJECT.camera 合法值

值	说明
back	使用后置摄像头
front	使用前置摄像头

success 返回参数说明

参数名	类型	说明
tempFiles	Array.<string>	本地临时文件列表
type	String	文件类型，有效值有 image 、video、mix

res.tempFiles 的结构

参数名	类型	说明
tempFilePath	String	本地临时文件路径 (本地路径)
size	Number	本地临时文件大小，单位 B
duration	Number	视频的时间长度
height	Number	视频的高度
width	Number	视频的宽度
thumbTempFilePath	String	视频缩略图临时文件路径
fileType	String	文件类型

fileType 合法值

值	说明
image	图片
video	视频

示例：

uni.chooseMedia({
  count: 9,
  mediaType: ['image','video'],
  sourceType: ['album', 'camera'],
  maxDuration: 30,
  camera: 'back',
  success(res) {
    console.log(res.tempFiles)
  }
})

Tips

如需上传到cdn，可使用uniCloud.uploadFile API，uniCloud提供了免费cdn给开发者使用，详见https://uniapp.dcloud.io/uniCloud/storage?id=uploadfile
选择文件大多为了上传，uni ui封装了更完善的uni-file-picker组件，文件选择、上传到uniCloud的免费存储和cdn中，一站式集成。强烈推荐使用。
经开发者提醒，微信小程序ios真机可以选择的文件个数不能大于9，详见帖子https://ask.dcloud.net.cn/question/115561

uni.saveVideoToPhotosAlbum(OBJECT)

保存视频到系统相册。

OBJECT 参数说明

参数名	类型	必填	说明
filePath	String	是	视频文件路径，可以是临时文件路径也可以是永久文件路径
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数名	类型	说明
errMsg	String	调用结果

注意

可以通过用户授权API来判断用户是否给应用授予相册写入权限https://uniapp.dcloud.io/api/other/authorize

示例：

<template>
	<view>
		<text>hello</text>
		<button @tap="test">click me</button>
		<video :src="src"></video>
	</view>
</template>

export default {
	data() {
		return {
			src: ''
		}
	},
	methods: {
		test: function () {
			var self = this;
			uni.chooseVideo({
				sourceType: ['camera'],
				success: function (res) {
					self.src = res.tempFilePath;
					
					uni.saveVideoToPhotosAlbum({
						filePath: res.tempFilePath,
						success: function () {
							console.log('save success');
						}
					});
				}
			});
		}
	}
}

uni.getVideoInfo(OBJECT)

获取视频详细信息

OBJECT 参数说明

属性	类型	默认值	必填	说明
src	string	-	是	视频文件路径，可以是临时文件路径也可以是永久文件路径（不支持网络地址）
success	function	-	否	接口调用成功的回调函数
fail	function	-	否	接口调用失败的回调函数
complete	function	-	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数名	类型	说明	平台差异说明
orientation	string	画面方向	微信小程序、App（3.1.14+）
type	string	视频格式	微信小程序、App（3.1.14+）
duration	number	视频长度	微信小程序、App（3.1.10+）、H5
size	number	视频大小，单位 kB	微信小程序、App（3.1.10+）、H5
height	number	视频的长，单位 px	微信小程序、App（3.1.10+）、H5
width	number	视频的宽，单位 px	微信小程序、App（3.1.10+）、H5
fps	number	视频帧率	微信小程序、App（3.1.14+）
bitrate	number	视频码率，单位 kbps	微信小程序、App（3.1.14+）

res.orientation参数说明

值	说明
up	默认
down	180度旋转
left	逆时针旋转90度
right	顺时针旋转90度
up-mirrored	同up，但水平翻转
down-mirrored	同down，但水平翻转
left-mirrored	同left，但垂直翻转
right-mirrored	同right，但垂直翻转

uni.compressVideo(OBJECT)

压缩视频接口。开发者可指定压缩质量 quality 进行压缩。当需要更精细的控制时，可指定 bitrate、fps、和 resolution，当 quality 传入时，这三个参数将被忽略。原视频的相关信息可通过 getVideoInfo 获取。

App端有很多插件支持视频压缩，详见插件市场

压缩完毕后如需上传到cdn，可使用uniCloud.uploadFile API，uniCloud提供了免费cdn给开发者使用，详见https://uniapp.dcloud.io/uniCloud/storage?id=uploadfile

OBJECT 参数说明

属性	类型	必填	说明
src	string	是	视频文件路径，可以是临时文件路径也可以是永久文件路径
quality	string	是	压缩质量
bitrate	number	是	码率，单位 kbps
fps	number	是	帧率
resolution	number	是	相对于原视频的分辨率比例，取值范围(0, 1]
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

quality可取值

值	说明
low	低
medium	中
high	高

success 返回参数说明

参数名	类型	说明
tempFilePath	string	压缩后的临时文件地址
size	string	压缩后的大小，单位 kB

uni.openVideoEditor(OBJECT)

打开视频编辑器

OBJECT 参数说明

属性	类型	默认值	必填	说明
filePath	string	-	是	视频源的路径，只支持本地路径
minDuration	string	-	是	视频裁剪的最小长度（2.16.1）
maxDuration	string	-	是	视频裁剪的最大长度（2.16.1）
success	function	-	否	接口调用成功的回调函数
fail	function	-	否	接口调用失败的回调函数
complete	function	-	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数名	类型	说明
duration	number	剪辑后生成的视频文件的时长，单位毫秒（ms）
size	number	剪辑后生成的视频文件大小，单位字节数（byte）
tempFilePath	string	编辑后生成的视频文件的临时路径
tempThumbPath	string	编辑后生成的缩略图文件的临时路径

文件操作

uni.chooseFile(OBJECT) 选择文件

从本地选择文件。仅支持 H5,微信小程序可以使用 wx.chooseMessageFile

本API主要用于选择非媒体文件，如果选择的文件是媒体文件，另有3个专用API：

OBJECT 参数说明

参数名	类型	默认值	必填	说明	平台差异说明
count	Number	100	否	最多可以选择的文件数量	见下方说明
type	String	'all'	否	所选的文件的类型	见下方说明
extension	Array<String>		否	根据文件拓展名过滤，每一项都不能是空字符串。默认不过滤。	见下方说明
sourceType	Array<String>	['album','camera']	否	（仅在type为`image`或`video`时可用）`album` 从相册选图，`camera` 使用相机，默认二者都有。如需直接开相机或直接选相册，请只使用一个选项
success	Function		是	成功则返回图片的本地文件路径列表 `tempFilePaths`
fail	Function		否	接口调用失败的回调函数
complete	Function		否	接口调用结束的回调函数（调用成功、失败都会执行）

OBJECT.type 的合法值

值	说明
all	从所有文件选择
video	只能选择视频文件
image	只能选择图片文件

success 返回参数说明

参数	类型	说明
tempFilePaths	Array<String>	文件的本地文件路径列表
tempFiles	Array<Object>、Array<File>	文件的本地文件列表，每一项是一个 File 对象

File 对象结构如下

参数	类型	说明
path	String	本地文件路径
size	Number	本地文件大小，单位：B
name	String	包含扩展名的文件名称，仅H5支持
type	String	文件类型，仅H5支持

示例：

uni.chooseFile({
  count: 6, //默认100
  extension:['.zip','.doc'],
	success: function (res) {
		console.log(JSON.stringify(res.tempFilePaths));
	}
});

// 选择图片文件
uni.chooseFile({
  count: 10,
  type: 'image',
  success (res) {
    // tempFilePath可以作为img标签的src属性显示图片
    const tempFilePaths = res.tempFiles
  }
})

wx.chooseMessageFile(OBJECT) 微信小程序选择文件

从微信聊天会话中选择文件。功能如上一节 uni.chooseFile(OBJECT)

录音操作

uni.getRecorderManager()

获取全局唯一的录音管理器 recorderManager

recorderManager 对象的方法列表

方法	参数	说明	平台差异说明
start	options	开始录音
pause		暂停录音	App 暂不支持
resume		继续录音	App 暂不支持
stop		停止录音
offStop	callback	取消监听录音停止事件	仅支付宝小程序支持
onStart	callback	录音开始事件
offStart	callback	移除录音开始事件	仅支付宝小程序支持
onPause	callback	录音暂停事件
offPause	callback	移除监听录音暂停事件	仅支付宝小程序支持
onStop	callback	录音停止事件，会回调文件地址
onResume	callback	监听录音继续事件	仅小程序支持
offResume	callback	取消监听录音继续事件	仅支付宝小程序支持
onInterruptionBegin	callback	监听录音因为受到系统占用而被中断开始事件。以下场景会触发此事件：微信语音聊天、微信视频聊天、QQ语音聊天、QQ视频聊天、电话响铃、接听电话。此事件触发后，录音会被暂停。pause 事件在此事件后触发	微信小程序、百度小程序、QQ小程序、快手小程序
onInterruptionEnd	callback	监听录音中断结束事件。在收到 interruptionBegin 事件之后，小程序内所有录音会暂停，收到此事件之后才可再次录音成功。	微信小程序、百度小程序、QQ小程序、快手小程序
onFrameRecorded	callback	已录制完指定帧大小的文件，会回调录音分片结果数据。如果设置了 frameSize ，则会回调此事件	App 暂不支持
offFrameRecorded	callback	取消监听已录制完指定帧大小的文件事件，指定 frameSize 大小并且 format 参数设置为 mp3 格式，调用此接口才会有回调	仅支付宝小程序支持
onDecibelChange	callback	监听声音分贝变化事件，详见	仅支付宝小程序支持
offDecibelChange	callback	取消监听声音分贝变化事件，详见	仅支付宝小程序支持
onError	callback	录音错误事件, 会回调错误信息
offError	callback	取消监听录音错误事件	仅支付宝小程序支持

start(options) 说明

属性	类型	必填	说明	平台差异说明
duration	Number	否	指定录音的时长，单位 ms ，如果传入了合法的 duration ，在到达指定的 duration 后会自动停止录音，最大值 600000（10 分钟）,默认值 60000（1 分钟）	App、小程序支持
sampleRate	Number	否	采样率，有效值 8000/16000/44100	App、小程序支持
numberOfChannels	Number	否	录音通道数，有效值 1/2	仅小程序支持
encodeBitRate	Number	否	编码码率，有效值见下表格	仅小程序支持
format	String	否	音频格式，有效值 aac/mp3/wav/PCM。App默认值为mp3，小程序默认值aac	App、小程序支持
frameSize	String	否	指定帧大小，单位 KB。传入 frameSize 后，每录制指定帧大小的内容后，会回调录制的文件内容，不指定则不会回调。暂仅支持 mp3 格式。	App、百度小程序不支持
hideTips	Boolean	否	隐藏录音图标。	支付宝小程序10.1.85+
audioSource	String	否	指定录音的音频输入源。	微信小程序详见、支付宝小程序详见、百度小程序详见、快手小程序
detectDecibel	Boolean	否	检测声音分贝数。详见	支付宝小程序10.2.0+

其中，采样率和码率有一定要求，具体有效值如下：

采样率	编码码率
8000	16000 ~ 48000
11025	16000 ~ 48000
12000	24000 ~ 64000
16000	24000 ~ 96000
22050	32000 ~ 128000
24000	32000 ~ 128000
32000	48000 ~ 192000
44100	64000 ~ 320000
48000	64000 ~ 320000

onStop(callback) 回调结果说明

属性	类型	说明
tempFilePath	String	录音文件的临时路径
duration	Number	录音总时长。单位：s。（仅支付宝10.2.90+支持）
fileSize	Number	录音文件大小。单位：Byte。（仅支付宝10.2.90+支持）

onFrameRecorded(callback) 回调结果说明

属性	类型	说明
frameBuffer	ArrayBuffer	录音分片结果数据
isLastFrame	Boolean	当前帧是否正常录音结束前的最后一帧

onError(callback) 回调结果说明

属性	类型	说明
errMsg	String	错误信息

注意

可以通过用户授权API来判断用户是否给应用授予麦克风的访问权限https://uniapp.dcloud.io/api/other/authorize

示例：

<template>
	<view>
		<button @tap="startRecord">开始录音</button>
		<button @tap="endRecord">停止录音</button>
		<button @tap="playVoice">播放录音</button>
	</view>
</template>

const recorderManager = uni.getRecorderManager();
const innerAudioContext = uni.createInnerAudioContext();

innerAudioContext.autoplay = true;

export default {
	data() {
		return {
			text: 'uni-app',
			voicePath: ''
		}
	},
	onLoad() {
		let self = this;
		recorderManager.onStop(function (res) {
			console.log('recorder stop' + JSON.stringify(res));
			self.voicePath = res.tempFilePath;
		});
	},
	methods: {
		startRecord() {
			console.log('开始录音');

			recorderManager.start();
		},
		endRecord() {
			console.log('录音结束');
			recorderManager.stop();
		},
		playVoice() {
			console.log('播放录音');

			if (this.voicePath) {
				innerAudioContext.src = this.voicePath;
				innerAudioContext.play();
			}
		}
	}
}

背景音乐播放管理

uni.getBackgroundAudioManager()

获取全局唯一的背景音频管理器 backgroundAudioManager。

背景音频，不是游戏的背景音乐，而是类似QQ音乐那样，App在后台时，仍然在播放音乐。如果你不需要在App切后台时继续播放，那么不应该使用本API，而应该使用普通音频APIuni.createInnerAudioContext。

backgroundAudioManager 对象的属性列表

属性	类型	说明	只读
duration	Number	当前音频的长度（单位：s），只有在当前有合法的 src 时返回	是
currentTime	Number	当前音频的播放位置（单位：s），只有在当前有合法的 src 时返回	是
paused	Boolean	当前是是否暂停或停止状态，true 表示暂停或停止，false 表示正在播放	是
src	String	音频的数据源，默认为空字符串，当设置了新的 src 时，会自动开始播放，目前支持的格式有 m4a, aac, mp3, wav	否
startTime	Number	音频开始播放的位置（单位：s）	否
buffered	Number	音频缓冲的时间点，仅保证当前播放时间点到此时间点内容已缓冲。	是
title	String	音频标题，用于做原生音频播放器音频标题。原生音频播放器中的分享功能，分享出去的卡片标题，也将使用该值。	否
epname	String	专辑名，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值。	否
singer	String	歌手名，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值。	否
coverImgUrl	String	封面图url，用于做原生音频播放器背景图。原生音频播放器中的分享功能，分享出去的卡片配图及背景也将使用该图。	否
webUrl	String	页面链接，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值。	否
protocol	String	音频协议。默认值为 'http'，设置 'hls' 可以支持播放 HLS 协议的直播音频，App平台暂不支持	否
playbackRate	Number	播放的倍率。可取值：0.5/0.8/1.0/1.25/1.5/2.0，默认值为1.0。(App 3.4.5+、微信基础库 2.11.0+、支付宝小程序、抖音小程序 2.33.0+、快手小程序、百度小程序 3.120.2+)	否

backgroundAudioManager 对象的方法列表

方法	参数	说明
play		播放
pause		暂停
stop		停止
seek	position	跳转到指定位置，单位 s
onCanplay	callback	背景音频进入可以播放状态，但不保证后面可以流畅播放
onPlay	callback	背景音频播放事件
onPause	callback	背景音频暂停事件
onStop	callback	背景音频停止事件
onEnded	callback	背景音频自然播放结束事件
onTimeUpdate	callback	背景音频播放进度更新事件
onPrev	callback	用户在系统音乐播放面板点击上一曲事件（iOS only）
onNext	callback	用户在系统音乐播放面板点击下一曲事件（iOS only）
onError	callback	背景音频播放错误事件
onWaiting	callback	音频加载中事件，当音频因为数据不足，需要停下来加载时会触发

errCode 说明

errCode	说明
10001	系统错误
10002	网络错误
10003	文件错误
10004	格式错误
-1	未知错误

示例：

const bgAudioManager = uni.getBackgroundAudioManager();
bgAudioManager.title = '致爱丽丝';
bgAudioManager.singer = '暂无';
bgAudioManager.coverImgUrl = 'https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/music-a.png';
bgAudioManager.src = 'https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-hello-uniapp/2cc220e0-c27a-11ea-9dfb-6da8e309e0d8.mp3';

注意因为背景音频播放耗费手机电量，所以平台都有管控，需在manifest中填写申请，

小程序平台，需在manifest.json 对应的小程序节点下，填写"requiredBackgroundModes": ["audio"]。发布小程序时平台会审核

音频组件控制

uni.createInnerAudioContext()

创建并返回内部 audio 上下文 innerAudioContext 对象。

innerAudioContext 对象的属性列表

属性	类型	说明	只读	平台差异说明
src	String	音频的数据链接，用于直接播放。	否	微信小程序不支持本地路径
startTime	Number	开始播放的位置（单位：s），默认 0	否
autoplay	Boolean	是否自动开始播放，默认 false	否	H5端部分浏览器不支持
loop	Boolean	是否循环播放，默认 false	否
obeyMuteSwitch	Boolean	是否遵循系统静音开关，当此参数为 false 时，即使用户打开了静音开关，也能继续发出声音，默认值 true	否	微信小程序、百度小程序、抖音小程序、飞书小程序、京东小程序、快手小程序（仅在 iOS 上生效）
duration	Number	当前音频的长度（单位：s），只有在当前有合法的 src 时返回，需要在onCanplay中获取	是
currentTime	Number	当前音频的播放位置（单位：s），只有在当前有合法的 src 时返回，时间不取整，保留小数点后 6 位	是
paused	Boolean	当前是是否暂停或停止状态，true 表示暂停或停止，false 表示正在播放	是
buffered	Number	音频缓冲的时间点，仅保证当前播放时间点到此时间点内容已缓冲。	是
volume	Number	音量。范围 0~1。	否
sessionCategory	String	设置音频播放模式，可取值："ambient" - 不中止其他声音播放，不能后台播放，静音后无声音； "soloAmbient" - 中止其他声音播放，不能后台播放，静音后无声音； "playback" - 中止其他声音，可以后台播放，静音后有声音。默认值为"playback"。	否	App 3.3.7+
playbackRate	Number	播放的倍率。可取值：0.5/0.8/1.0/1.25/1.5/2.0，默认值为1.0	否	App 3.4.5+（Android 需要 6 及以上版本）、微信小程序 2.11.0、支付宝小程序、抖音小程序 2.33.0+、快手小程序、百度小程序 3.120.2+

innerAudioContext 对象的方法列表

方法	参数	说明	平台差异说明
play		播放（H5端部分浏览器需在用户交互时进行）
pause		暂停
stop		停止
seek	position	跳转到指定位置，单位 s
destroy		销毁当前实例
onCanplay	callback	音频进入可以播放状态，但不保证后面可以流畅播放
onPlay	callback	音频播放事件
onPause	callback	音频暂停事件
onStop	callback	音频停止事件
onEnded	callback	音频自然播放结束事件
onTimeUpdate	callback	音频播放进度更新事件
onError	callback	音频播放错误事件
onWaiting	callback	音频加载中事件，当音频因为数据不足，需要停下来加载时会触发
onSeeking	callback	音频进行 seek 操作事件
onSeeked	callback	音频完成 seek 操作事件
offCanplay	callback	取消监听 onCanplay 事件	微信小程序1.9.0+，支付宝小程序，抖音小程序、百度小程序
offPlay	callback	取消监听 onPlay 事件	微信小程序1.9.0+，支付宝小程序，抖音小程序、百度小程序
offPause	callback	取消监听 onPause 事件	微信小程序1.9.0+，支付宝小程序，抖音小程序、百度小程序
offStop	callback	取消监听 onStop 事件	微信小程序1.9.0+，支付宝小程序，抖音小程序、百度小程序
offEnded	callback	取消监听 onEnded 事件	微信小程序1.9.0+，支付宝小程序，抖音小程序、百度小程序
offTimeUpdate	callback	取消监听 onTimeUpdate 事件	微信小程序1.9.0+，支付宝小程序，抖音小程序、百度小程序
offError	callback	取消监听 onError 事件	微信小程序1.9.0+，支付宝小程序，抖音小程序、百度小程序
offWaiting	callback	取消监听 onWaiting 事件	微信小程序1.9.0+，支付宝小程序，抖音小程序、百度小程序
offSeeking	callback	取消监听 onSeeking 事件	微信小程序1.9.0+，支付宝小程序，抖音小程序、百度小程序
offSeeked	callback	取消监听 onSeeked 事件	微信小程序1.9.0+，支付宝小程序，抖音小程序、百度小程序

errCode 说明

errCode	说明
10001	系统错误
10002	网络错误
10003	文件错误
10004	格式错误
-1	未知错误

支持格式

格式	iOS	Android
flac	x	√
m4a	√	√
ogg	x	√
ape	x	√
amr	x	√
wma	x	√
wav	√	√
mp3	√	√
mp4	x	√
aac	√	√
aiff	√	x
caf	√	x

示例：

const innerAudioContext = uni.createInnerAudioContext();
innerAudioContext.autoplay = true;
innerAudioContext.src = 'https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-hello-uniapp/2cc220e0-c27a-11ea-9dfb-6da8e309e0d8.mp3';
innerAudioContext.onPlay(() => {
  console.log('开始播放');
});
innerAudioContext.onError((res) => {
  console.log(res.errMsg);
  console.log(res.errCode);
});

视频组件控制

uni.createVideoContext(videoId, this)

创建并返回 video 上下文 videoContext 对象。在自定义组件下，第二个参数传入组件实例this，以操作组件内 <video> 组件。

videoContext 对象的方法列表

方法	参数	说明	平台差异说明
play	无	播放
pause	无	暂停
seek	position	跳转到指定位置，单位 s
stop		停止视频	微信小程序
sendDanmu	danmu	发送弹幕，danmu 包含两个属性 text, color
playbackRate	rate	设置倍速播放，支持的倍率有 0.5/0.8/1.0/1.25/1.5。微信基础库2.6.3 起支持 2.0 倍速
requestFullScreen	无	进入全屏，可传入{direction}参数，详见 video 组件文档	H5和抖音小程序不支持{direction}参数
exitFullScreen	无	退出全屏
showStatusBar	无	显示状态栏，仅在iOS全屏下有效	微信小程序、百度小程序、QQ小程序
hideStatusBar	无	隐藏状态栏，仅在iOS全屏下有效	微信小程序、百度小程序、QQ小程序

示例：

<template>
	<view>
		<view class="page-body">
			<view class="page-section">
				<video id="myVideo" src="https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/wap2appvsnative.mp4" @error="videoErrorCallback" :danmu-list="danmuList"
				    enable-danmu danmu-btn controls>
                                </video>

				<view class="uni-list">
					<view class="uni-list-cell">
						<view>
							<view class="uni-label">弹幕内容</view>
						</view>
						<view class="uni-list-cell-db">
							<input @blur="bindInputBlur" class="uni-input" type="text" placeholder="在此处输入弹幕内容" />
						</view>
					</view>
				</view>
				<view class="btn-area">
					<button @tap="bindSendDanmu" class="page-body-button" formType="submit">发送弹幕</button>
				</view>
			</view>
		</view>
	</view>
</template>

export default {
	data() {
		return {
			title: 'video',
			src: '',
			inputValue: '',
			danmuList: [{
					text: '第 1s 出现的弹幕',
					color: '#ff0000',
					time: 1
				},
				{
					text: '第 3s 出现的弹幕',
					color: '#ff00ff',
					time: 3
				}
			]
		}
	},
	onReady: function (res) {
		this.videoContext = uni.createVideoContext('myVideo')
	},
	methods: {
		bindInputBlur: function (e) {
			this.inputValue = e.target.value
		},
		bindButtonTap: function () {
			var that = this
			uni.chooseVideo({
				sourceType: ['album', 'camera'],
				maxDuration: 60,
				camera: ['front', 'back'],
				success: function (res) {
					this.src = res.tempFilePath
				}
			})
		},
		bindSendDanmu: function () {
			this.videoContext.sendDanmu({
				text: this.inputValue,
				color: this.getRandomColor()
			})
		},
		videoErrorCallback: function (e) {
			console.log('视频错误信息:')
			console.log(e.target.errMsg)
		},
		getRandomColor: function () {
			const rgb = []
			for (let i = 0; i < 3; ++i) {
				let color = Math.floor(Math.random() * 256).toString(16)
				color = color.length == 1 ? '0' + color : color
				rgb.push(color)
			}
			return '#' + rgb.join('')
		}
	}
}

相机组件控制

uni.createCameraContext()

创建并返回 camera 组件的上下文 cameraContext 对象。

本API为 camera 组件配套的js API，与 camera 组件的平台兼容性相同，可实现非全屏摄像头。App端可通过plus.camera实现全屏摄像头。

cameraContext 对象的方法列表

方法	参数	说明	平台差异说明
takePhoto	Object	拍照，可指定质量，成功则返回图片路径。
setZoom	Object	设置缩放级别。	百度、QQ、快手、京东小程序不支持
startRecord	Object	开始录像
stopRecord	Object	结束录像，成功则返回封面与视频。
onCameraFrame	Function	获取 Camera 实时帧数据。	微信小程序详情、支付宝小程序详情、抖音小程序支持详情

cameraContext.takePhoto

takePhoto 的 Object 参数列表：

参数	类型	必填	说明
quality	String	否	成像质量，值为high（高质量）、normal（普通质量）、low（低质量），默认normal
selfieMirror	Boolean	否	是否开启镜像，默认true。仅微信小程序 2.22.0+ 支持
success	Function	否	接口调用成功的回调函数，返回照片文件的临时路径，res = { tempImagePath }
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

cameraContext.setZoom

setZoom 的 Object 参数列表：

参数	类型	必填	说明
zoom	String	是	缩放级别，范围[1, maxZoom]。zoom 可取小数，精确到小数后一位。maxZoom 可在 @initdone 返回值中获取。
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

cameraContext.startRecord

startRecord 的 Object 参数列表：

参数	类型	必填	说明
timeoutCallback	Function	否	接超过30s或页面 onHide 时会结束录像
timeout	Number	否	录制时长上限，单位为秒，默认30s。微信小程序最长不能超过 5 分钟，支付宝小程序最大录制时长 10 分钟。仅微信2.22.0+ 、支付宝1.11.0+小程序支持
selfieMirror	Boolean	否	是否开启镜像，默认true。仅微信小程序 2.22.0+ 支持
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

cameraContext.stopRecord

stopRecord 的 Object 参数列表：

参数	类型	默认值	必填	说明
compressed	Boolean	false	否	启动视频压缩，压缩效果同 `chooseVideo` 。微信2.10.0+ 、抖音2.41.0（Android暂不支持）、快手小程序支持
success	Function		否	接口调用成功的回调函数，返回封面与视频的临时路径，res = { tempThumbPath, tempVideoPath }。
fail	Function		否	接口调用失败的回调函数
complete	Function		否	接口调用结束的回调函数（调用成功、失败都会执行）

直播组件控制

uni.createLivePlayerContext(livePlayerId, this)

创建 live-player 上下文 livePlayerContext 对象。注意是直播的播放而不是推流。

参数说明

参数	说明	平台差异说明
livePlayerId	`<live-player>` 组件 id
this	在自定义组件下，当前组件实例的 this，以操作组件内 `<live-player>` 组件	微信小程序

livePlayerContext 对象的方法列表：

方法	参数	说明
play	Object	播放
stop	Object	停止
mute	Object	静音
pause	Object	暂停
resume	Object	恢复
requestFullScreen	Object	进入全屏
exitFullScreen	Object	退出全屏

requestFullScreen 的 Object 参数列表：

参数	类型	必填	说明
direction	Number	是	设置全屏时的方向，有效值为 0（正常竖向）, 90（屏幕逆时针90度）, -90（屏幕顺时针90度）。
success	Function	否	接口调用成功的回调函数。
fail	Function	否	接口调用失败的回调函数。
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）。

其他方法的 Object 参数列表：

参数	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.createLivePusherContext(livePusherId, this)

创建 live-pusher 上下文 livePusherContext 对象。

livePusherContext

start(OBJECT) 开始推流

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

pause(OBJECT) 暂停推流

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

resume(OBJECT) 恢复推流

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

stop(OBJECT) 停止推流

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

switchCamera(OBJECT) 切换前后摄像头

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

snapshot(OBJECT) 快照

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

startPreview(OBJECT) 开启摄像头预览

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

stopPreview(OBJECT) 关闭摄像头预览

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

富文本

editorContext

editor 组件对应的 editorContext 实例，可通过 uni.createSelectorQuery 获取。

onEditorReady() {
		uni.createSelectorQuery().select('#editor').context((res) => {
			this.editorCtx = res.context
		}).exec()
	}

editorContext 通过 id 跟一个 <editor> 组件绑定，操作对应的 <editor> 组件。

详情请查阅：https://uniapp.dcloud.net.cn/api/media/editor-context.html

音视频合成

uni.createMediaContainer()

创建音视频处理容器，最终可将容器中的轨道合成一个视频，返回 MediaContainer 对象

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ小程序	快手小程序	京东小程序
x	x	2.9.0+	x	x	x	x	x	x

MediaContainer.addTrack(track)

将音频或视频轨道添加到容器

参数说明

参数	说明
track	要添加的音频或视频轨道

MediaContainer.destroy()

将容器销毁，释放资源

MediaContainer.export()

将容器内的轨道合并并导出视频文件

MediaContainer.extractDataSource(object)

将容器内的轨道合并并导出视频文件 ,返回 MediaTrack 对象

参数说明

属性	类型	必填	说明
source	String	是	视频源地址，只支持本地文件

MediaContainer.removeTrack(track)

将音频或视频轨道添加到容器

参数说明

参数	说明
track	要移除的音频或视频轨道

MediaTrack

可通过 MediaContainer.extractDataSource 返回。

MediaTrack 音频或视频轨道，可以对轨道进行一些操作

参数说明

属性	类型	说明
kind	String	轨道类型，只读 ,audio:音频轨道;video:视频轨道
duration	Number	轨道长度，只读
volume	Number	音量，音频轨道下有效，可写

键盘行为

uni.hideKeyboard()

隐藏软键盘

隐藏已经显示的软键盘，如果软键盘没有显示则不做任何操作。

uni.onKeyboardHeightChange(CALLBACK)

监听键盘高度变化

参数

function listener

键盘高度变化事件的监听函数

参数

Object res

参数	类型	说明
height	Number	键盘高度

uni.onKeyboardHeightChange(res => {
  console.log(res.height)
})

uni.offKeyboardHeightChange(CALLBACK)

取消监听键盘高度变化事件

参数

function listener

onKeyboardHeightChange 传入的监听函数。不传此参数则移除所有监听函数。

const listener = function (res) { console.log(res) }

uni.onKeyboardHeightChange(listener)
uni.offKeyboardHeightChange(listener) // 需传入与监听时同一个的函数对象

uni.getSelectedTextRange(OBJECT)

在input、textarea等focus之后，获取输入框的光标位置。注意：只有在focus的时候调用此接口才有效。目前仅支持 vue 页面，nvue 可以直接使用 weex 的 getSelectionRange。

OBJECT 参数说明：

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明：

属性	类型	说明
start	Number	输入框光标起始位置
end	Number	输入框光标结束位置

uni.getSelectedTextRange({
  success: res => {
    console.log('getSelectedTextRange res', res.start, res.end)
  }
})

界面提示

uni.showToast(OBJECT) 提示框

显示消息提示框。

OBJECT参数说明

参数	类型	必填	说明	平台差异说明
title	String	是	提示的内容，长度与 icon 取值有关。
icon	String	否	图标，有效值详见下方说明，默认：success。
image	String	否	自定义图标的本地路径（app端暂不支持gif）	App、H5、微信小程序、百度小程序、抖音小程序（2.62.0+）
mask	Boolean	否	是否显示透明蒙层，防止触摸穿透，默认：false	App、微信小程序、抖音小程序（2.47.0+）
duration	Number	否	提示的延迟时间，单位毫秒，默认：1500
position	String	否	纯文本轻提示显示位置，填写有效值后只有 `title` 属性生效，且不支持通过 uni.hideToast 隐藏。有效值详见下方说明。	App
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

icon 值说明

值	说明	平台差异说明
success	显示成功图标，此时 title 文本在`小程序`平台最多显示 7 个汉字长度，`App`仅支持单行显示。	支付宝小程序无长度无限制
error	显示错误图标，此时 title 文本在`小程序`平台最多显示 7 个汉字长度，`App`仅支持单行显示。	支付宝小程序、快手小程序、抖音小程序、百度小程序、京东小程序、QQ小程序不支持
fail	显示错误图标，此时 title 文本无长度显示。	支付宝小程序、抖音小程序
exception	显示异常图标。此时 title 文本无长度显示。	支付宝小程序
loading	显示加载图标，此时 title 文本在`小程序`平台最多显示 7 个汉字长度。	支付宝小程序不支持
none	不显示图标，此时 title 文本在`小程序`最多可显示两行。

uni.showToast({
	title: '标题',
	duration: 2000
});

uni.hideToast()

隐藏消息提示框。

uni.hideToast();

uni.showLoading(OBJECT)

显示 loading 提示框, 需主动调用 uni.hideLoading 才能关闭提示框。

OBJECT参数说明

参数	类型	必填	说明	平台差异说明
title	String	是	提示的文字内容，显示在loading的下方
mask	Boolean	否	是否显示透明蒙层，防止触摸穿透，默认：false	H5、App、微信小程序、百度小程序、抖音小程序（2.47.0+）
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.showLoading({
	title: '加载中'
});

uni.hideLoading()

隐藏 loading 提示框。

uni.showLoading({
	title: '加载中'
});

setTimeout(function () {
	uni.hideLoading();
}, 2000);

uni.showModal(OBJECT)

显示模态弹窗，可以只有一个确定按钮，也可以同时有确定和取消按钮。类似于一个API整合了 html 中：alert、confirm。

OBJECT参数说明

参数	类型	必填	说明	平台差异说明
title	String	否	提示的标题
content	String	否	提示的内容
showCancel	Boolean	否	是否显示取消按钮，默认为 true
cancelText	String	否	取消按钮的文字，默认为"取消"
cancelColor	HexColor	否	取消按钮的文字颜色，默认为"#000000"	H5、微信小程序、百度小程序、抖音小程序（2.62.0+）
confirmText	String	否	确定按钮的文字，默认为"确定"
confirmColor	HexColor	否	确定按钮的文字颜色，H5平台默认为"#007aff"，微信小程序平台默认为"#576B95"，百度小程序平台默认为"#3c76ff"	H5、微信小程序、百度小程序、抖音小程序（2.62.0+）
editable	Boolean	否	是否显示输入框	H5 (3.2.10+)、App (3.2.10+)、微信小程序 (2.17.1+)、抖音小程序（2.62.0+）
placeholderText	String	否	显示输入框时的提示文本	H5 (3.2.10+)、App (3.2.10+)、微信小程序 (2.17.1+)、抖音小程序（2.62.0+）
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success返回参数说明

参数	类型	说明	平台差异说明
confirm	Boolean	为 true 时，表示用户点击了确定按钮
cancel	Boolean	为 true 时，表示用户点击了取消（用于 Android 系统区分点击蒙层关闭还是点击取消按钮关闭）
content	String	`editable` 为 true 时，用户输入的文本	H5 (3.2.10+)、App (3.2.10+)、微信小程序 (2.17.1+)、抖音小程序（2.62.0+）

uni.showModal({
	title: '提示',
	content: '这是一个模态弹窗',
	success: function (res) {
		if (res.confirm) {
			console.log('用户点击确定');
		} else if (res.cancel) {
			console.log('用户点击取消');
		}
	}
});

弹框同时使用确定取消时，需注意不同平台的确认取消按钮位置不同。在微信、H5中，确认按钮默认在右边。在App中，iOS的确认按钮默认在右边，而Android默认在左边。产生这种差异的原因是uni.showModal在App和小程序上调用的是原生提供的弹出框，原生平台的策略本身就不同。如果需要调整，可以通过自行控制按钮的文字，即“确定”按钮的文字其实可以设置为“取消”；
showModal不满足需求时，可以自行开发组件弹框。插件市场有很多自定义弹框的组件，需注意在非H5平台，前端组件无法覆盖原生组件（如地图、video），遮罩也无法盖住tabbar和navigationbar。如需覆盖原生组件或遮罩tabbar等，App端推荐使用subNvue；
小程序平台，cancelText和confirmText有长度限制，最多允许 4 个字符；
钉钉小程序真机与模拟器表现有差异，真机title，content均为必填项
各家小程序平台对于 confirm、cancel 字段返回规则可能不尽相同，包含两种情况：{ confirm: true, cancel: false } 或 { confirm: true }，但并不影响使用 if 去做判断

uni.showActionSheet(OBJECT)

从底部向上弹出操作菜单

OBJECT参数说明

参数	类型	必填	说明	平台差异说明
title	String	否	菜单标题	App、H5、支付宝小程序、钉钉小程序、微信小程序 3.4.5+（仅真机有效）
alertText	String	否	警示文案（同菜单标题）	微信小程序（仅真机有效）
itemList	Array<String>	是	按钮的文字数组	微信、百度、抖音小程序数组长度最大为6个
itemColor	HexColor	否	按钮的文字颜色，字符串格式，默认为"#000000"	App-iOS、飞书小程序不支持
popover	Object	否	大屏设备弹出原生选择按钮框的指示区域，默认居中显示	App-iPad（2.6.6+）、H5（2.9.2）
success	Function	否	接口调用成功的回调函数，详见返回参数说明
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

popover 值说明（仅App生效）

值	类型	说明
top	Number	指示区域坐标，使用原生 navigationBar 时一般需要加上 navigationBar 的高度
left	Number	指示区域坐标
width	Number	指示区域宽度
height	Number	指示区域高度

success返回参数说明

参数	类型	说明
tapIndex	Number	用户点击的按钮，从上到下的顺序，从0开始

uni.showActionSheet({
	itemList: ['A', 'B', 'C'],
	success: function (res) {
		console.log('选中了第' + (res.tapIndex + 1) + '个按钮');
	},
	fail: function (res) {
		console.log(res.errMsg);
	}
});

导航条

uni.setNavigationBarTitle(OBJECT)

动态设置当前页面的标题。

OBJECT参数说明

参数	类型	必填	说明
title	String	是	页面标题
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

如果需要在页面进入时设置标题，可以在onReady内执行，以避免被框架内的修改所覆盖。如果必须在onShow内执行需要延迟一小段时间

uni.setNavigationBarColor(OBJECT)

设置页面导航条颜色。如果需要进入页面就设置颜色，请延迟执行，防止被框架内设置颜色逻辑覆盖

OBJECT参数说明

参数	类型	必填	说明	平台差异说明
frontColor	String	是	前景颜色值，包括按钮、标题、状态栏的颜色，仅支持 #ffffff 和 #000000	App、H5、微信小程序、百度小程序、抖音小程序、QQ小程序、快手小程序、京东小程序
backgroundColor	String	是	背景颜色值，有效值为十六进制颜色
animation	Object	否	动画效果，{duration,timingFunc}	微信小程序、百度小程序、QQ小程序、快手小程序、京东小程序
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

animation 结构

属性	类型	默认值	必填	说明
duration	number	0	否	动画变化时间，单位 ms
timingFunc	String	'linear'	否	动画变化方式

animation.timingFunc 有效值

值	说明
linear	动画从头到尾的速度是相同的。
easeIn	动画以低速开始
easeOut	动画以低速结束。
easeInOut	动画以低速开始和结束。

success返回参数说明

参数名	类型	说明
errMsg	String	调用结果

uni.setNavigationBarColor({
    frontColor: '#ffffff',
    backgroundColor: '#ff0000',
    animation: {
        duration: 400,
        timingFunc: 'easeIn'
    }
})

uni.showNavigationBarLoading(OBJECT)

在当前页面显示导航条加载动画。

App平台调用此API时会在屏幕中间悬浮显示loading

OBJECT参数说明

参数	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.showNavigationBarLoading()

uni.hideNavigationBarLoading(OBJECT)

在当前页面隐藏导航条加载动画。

App平台调用此API时会关闭屏幕中间悬浮显示的loading

OBJECT参数说明

参数	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.hideNavigationBarLoading()

uni.hideHomeButton(OBJECT)

隐藏返回首页按钮。

OBJECT参数说明

参数	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.hideHomeButton()

微信小程序自基础库版本2.8.3开始支持
当用户打开的小程序最底层页面是非首页时，默认展示“返回首页”按钮，开发者可在页面onShow中调用hideHomeButton进行隐藏。

getMenuButtonBoundingClientRect()

在小程序平台，如果原生导航栏被隐藏，仍然在右上角会有一个悬浮按钮，微信下也被称为胶囊按钮。本API用于获取小程序下该菜单按钮的布局位置信息，方便开发者布局顶部内容时避开该按钮。

坐标信息以屏幕左上角为原点。

返回值说明

属性	类型	说明
width	number	宽度，单位：px
height	number	高度，单位：px
top	number	上边界坐标，单位：px
right	number	右边界坐标，单位：px
bottom	number	下边界坐标，单位：px
left	number	左边界坐标，单位：px

let menuButtonInfo = uni.getMenuButtonBoundingClientRect()

设置Tabbar底层导航

uni.setTabBarItem(OBJECT)

动态设置 tabBar 某一项的内容

OBJECT参数说明：

属性	类型	默认值	必填	说明	平台差异
index	number		是	tabBar 的哪一项，从左边算起
text	String		否	tab 上的按钮文字
iconPath	String		否	图片路径，icon 大小限制为 40kb，建议尺寸为 81px * 81px，当 position 为 top 时，此参数无效。微信小程序 2.7.0+、支付宝小程序支持网络图片，其他平台暂不支持网络图片
selectedIconPath	String		否	选中时的图片路径，icon 大小限制为 40kb，建议尺寸为 81px * 81px ，当 position 为 top 时，此参数无效
pagePath	String		否	页面绝对路径，必须在 pages 中先定义，被替换掉的 pagePath 不会变成普通页面（仍然需要使用 uni.switchTab 跳转）	App（2.8.4+）、H5（2.8.4+）
visible	Boolean	true	否	该项是否显示	App（3.2.10+）、H5（3.2.10+）
iconfont	Object		否	字体图标，优先级高于 iconPath	App（3.4.4+）
success	Funtion		否	接口调用成功的回调函数
fail	Funtion		否	接口调用失败的回调函数
complete	Funtion		否	接口调用结束的回调函数（调用成功、失败都会执行）

iconfont参数说明：

属性	类型	说明
text	String	字库 Unicode 码
selectedText	String	选中后字库 Unicode 码
fontSize	String	字体图标字号(px)
color	String	字体图标颜色
selectedColor	String	字体图标选中颜色

uni.setTabBarItem({
  index: 0,
  text: 'text',
  iconPath: '/path/to/iconPath',
  selectedIconPath: '/path/to/selectedIconPath'
})

注意: 设置 iconfont 属性时，pages.json iconfontSrc 需要指定字体文件，参考下面的配置

// pages.json
{
  "tabBar": {
    "iconfontSrc":"static/iconfont.ttf",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "Tab1",
        "iconfont": {
          "text": "\ue102",
          "selectedText": "\ue103",
          "fontSize": "17px",
          "color": "#000000",
          "selectedColor": "#0000ff"
        }
      }
    ]
  }
}

uni.setTabBarStyle(OBJECT)

动态设置 tabBar 的整体样式

OBJECT参数说明：

属性	类型	必填	说明
color	String	否	tab 上的文字默认颜色，HexColor
selectedColor	String	否	tab 上的文字选中时的颜色，HexColor
backgroundColor	String	否	tab 的背景色，HexColor
backgroundImage	String	否	图片背景。支持设置本地图片或创建线性渐变如，优先级高于 backgroundColor，仅 App 2.7.1+ 支持
backgroundRepeat	String	否	背景图平铺方式。repeat：背景图片在垂直方向和水平方向平铺；repeat-x：背景图片在水平方向平铺，垂直方向拉伸；repeat-y：背景图片在垂直方向平铺，水平方向拉伸；no-repeat：背景图片在垂直方向和水平方向都拉伸。默认使用 no-repeat。仅 App 2.7.1+ 支持
borderStyle	String	否	tabBar上边框的颜色，仅支持 black/white
midButton	Object	否	中间按钮仅在 list 项为偶数时有效详情。HBuilderX 3.6.9+
success	Funtion	否	接口调用成功的回调函数
fail	Funtion	否	接口调用失败的回调函数
complete	Funtion	否	接口调用结束的回调函数（调用成功、失败都会执行）

backgroundImage创建线性渐变说明

backgroundImage: linear-gradient(to top, #a80077, #66ff00);

目前暂不支持 radial-gradient（径向渐变）。

目前只支持两种颜色的渐变，渐变方向如下：

to right：从左向右渐变
to left：从右向左渐变
to bottom：从上到下渐变
to top：从下到上渐变
to bottom right：从左上角到右下角
to top left：从右下角到左上角

uni.setTabBarStyle({
  color: '#FF0000',
  selectedColor: '#00FF00',
  backgroundColor: '#0000FF',
  borderStyle: 'white'
})

uni.hideTabBar(OBJECT)

隐藏 tabBar

OBJECT参数说明：

属性	类型	默认值	必填	说明
animation	boolean	false	否	是否需要动画效果，仅微信小程序、支付宝小程序、百度小程序、抖音小程序、飞书小程序、QQ小程序、快手小程序、京东小程序支持
success	Funtion		否	接口调用成功的回调函数
fail	Funtion		否	接口调用失败的回调函数
complete	Funtion		否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.showTabBar(OBJECT)

显示 tabBar

OBJECT参数说明：

属性	类型	默认值	必填	说明
animation	boolean	false	否	是否需要动画效果，仅微信小程序、支付宝小程序、百度小程序、抖音小程序、飞书小程序、QQ小程序、快手小程序、京东小程序支持
success	Funtion		否	接口调用成功的回调函数
fail	Funtion		否	接口调用失败的回调函数
complete	Funtion		否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.setTabBarBadge(OBJECT)

为 tabBar 某一项的右上角添加文本。

OBJECT参数说明：

参数	类型	必填	说明
index	Number	是	tabBar的哪一项，从左边算起
text	String	是	显示的文本，不超过 3 个半角字符
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.setTabBarBadge({
  index: 0,
  text: '1'
})

uni.removeTabBarBadge(OBJECT)

移除 tabBar 某一项右上角的文本。

OBJECT参数说明：

参数	类型	必填	说明
index	Number	是	tabBar的哪一项，从左边算起
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.showTabBarRedDot(OBJECT)

显示 tabBar 某一项的右上角的红点。

OBJECT参数说明：

参数	类型	必填	说明
index	Number	是	tabBar的哪一项，从左边算起
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.hideTabBarRedDot(OBJECT)

隐藏 tabBar 某一项的右上角的红点。

OBJECT参数说明：

参数	类型	必填	说明
index	Number	是	tabBar的哪一项，从左边算起
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.onTabBarMidButtonTap(CALLBACK)

监听中间按钮的点击事件

Tip

tabbar是原生的，层级高于前端元素
uni-app插件市场有封装的前端tabbar，但性能不如原生tabbar
如果想要一个中间带+号的tabbar，在HBuilderX中新建uni-app项目、选择底部选项卡模板
以上大部分操作 tabbar 的 API 需要在 tabbar 渲染后才能使用，避免在 tabbar 未初始化前使用

背景

uni.setBackgroundColor(OBJECT)

动态设置窗口的背景色。

参数说明

属性	类型	必填	说明
backgroundColor	String	否	窗口的背景色，必须为十六进制颜色值
backgroundColorTop	String	否	顶部窗口的背景色，必须为十六进制颜色值，仅 iOS 支持
backgroundColorBottom	String	否	底部窗口的背景色，必须为十六进制颜色值，仅 iOS 支持
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.setBackgroundColor({
    backgroundColor: '#ffffff',
    backgroundColorTop: '#222222',
    backgroundColorBottom: '#333333'
})

uni.setBackgroundTextStyle(OBJECT)

动态设置下拉背景字体、loading 图的样式。

参数说明

属性	类型	必填	说明
textStyle	String	是	下拉背景字体、loading 图的样式，值为：dark、light
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

uni.setBackgroundTextStyle({
  textStyle: 'dark' // 下拉背景字体、loading 图的样式为dark
})

动画

uni.createAnimation(OBJECT)

创建一个动画实例 animation。调用实例的方法来描述动画。最后通过动画实例的export方法导出动画数据传递给组件的animation属性。

OBJECT参数说明：

参数	类型	必填	默认值	说明
duration	Integer	否	400	动画持续时间，单位ms
timingFunction	String	否	"linear"	定义动画的效果
delay	Integer	否	0	动画延迟时间，单位 ms
transformOrigin	String	否	"50% 50% 0"	设置transform-origin

timingFunction 有效值：

值	说明
linear	动画从头到尾的速度是相同的
ease	动画以低速开始，然后加快，在结束前变慢
ease-in	动画以低速开始
ease-in-out	动画以低速开始和结束
ease-out	动画以低速结束
step-start	动画第一帧就跳至结束状态直到结束
step-end	动画一直保持开始状态，最后一帧跳到结束状态

var animation = uni.createAnimation({
  transformOrigin: "50% 50%",
  duration: 1000,
  timingFunction: "ease",
  delay: 0
})

animation

动画实例可以调用以下方法来描述动画，调用结束后会返回自身，支持链式调用的写法。

animation 对象的方法列表：

样式：

方法	参数	说明
opacity	value	透明度，参数范围 0~1
backgroundColor	color	颜色值
width	length	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值
height	length	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值
top	length	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值
left	length	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值
bottom	length	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值
right	length	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值

旋转：

方法	参数	说明
rotate	deg	deg的范围-180~180，从原点顺时针旋转一个deg角度
rotateX	deg	deg的范围-180~180，在X轴旋转一个deg角度
rotateY	deg	deg的范围-180~180，在Y轴旋转一个deg角度
rotateZ	deg	deg的范围-180~180，在Z轴旋转一个deg角度
rotate3d	(x,y,z,deg)	同transform-function rotate3d

缩放：

方法	参数	说明
scale	sx,[sy]	一个参数时，表示在X轴、Y轴同时缩放sx倍数；两个参数时表示在X轴缩放sx倍数，在Y轴缩放sy倍数
scaleX	sx	在X轴缩放sx倍数
scaleY	sy	在Y轴缩放sy倍数
scaleZ	sz	在Z轴缩放sz倍数
scale3d	(sx,sy,sz)	在X轴缩放sx倍数，在Y轴缩放sy倍数，在Z轴缩放sz倍数

偏移：

方法	参数	说明
translate	tx,[ty]	一个参数时，表示在X轴偏移tx，单位px；两个参数时，表示在X轴偏移tx，在Y轴偏移ty，单位px。
translateX	tx	在X轴偏移tx，单位px
translateY	ty	在Y轴偏移ty，单位px
translateZ	tz	在Z轴偏移tz，单位px
translate3d	(tx,ty,tz)	在X轴偏移tx，在Y轴偏移ty，在Z轴偏移tz，单位px

倾斜：

方法	参数	说明
skew	ax,[ay]	参数范围-180~180；一个参数时，Y轴坐标不变，X轴坐标延顺时针倾斜ax度；两个参数时，分别在X轴倾斜ax度，在Y轴倾斜ay度
skewX	ax	参数范围-180~180；Y轴坐标不变，X轴坐标延顺时针倾斜ax度
skewY	ay	参数范围-180~180；X轴坐标不变，Y轴坐标延顺时针倾斜ay度

矩阵变形：

方法	参数	说明
matrix	(a,b,c,d,tx,ty)	同 transform-function matrix
matrix3d		同transform-function matrix3d

动画队列

调用动画操作方法后要调用 step() 来表示一组动画完成，可以在一组动画中调用任意多个动画方法，一组动画中的所有动画会同时开始，一组动画完成后才会进行下一组动画。step 可以传入一个跟 uni.createAnimation() 一样的配置参数用于指定当前组动画的配置。

<view :animation="animationData" style="background:red;height:100rpx;width:100rpx"></view>

export default{
  data() {
    return {
      animationData: {}
    }
  },
  onShow: function(){
    var animation = uni.createAnimation({
      duration: 1000,
        timingFunction: 'ease',
    })

    this.animation = animation

    animation.scale(2,2).rotate(45).step()

    this.animationData = animation.export()

    setTimeout(function() {
      animation.translate(30).step()
      this.animationData = animation.export()
    }.bind(this), 1000)
  },
  methods:{
    rotateAndScale: function () {
      // 旋转同时放大
      this.animation.rotate(45).scale(2, 2).step()
      this.animationData = this.animation.export()
    },
    rotateThenScale: function () {
      // 先旋转后放大
      this.animation.rotate(45).step()
      this.animation.scale(2, 2).step()
      this.animationData = this.animation.export()
    },
    rotateAndScaleThenTranslate: function () {
      // 先旋转同时放大，然后平移
      this.animation.rotate(45).scale(2, 2).step()
      this.animation.translate(100, 100).step({ duration: 1000 })
      this.animationData = this.animation.export()
    }
  }
}

滚动

uni.pageScrollTo(OBJECT)

将页面滚动到目标位置。可以指定滚动到具体的scrollTop数值，也可以指定滚动到某个元素的位置

OBJECT参数说明

参数名	类型	必填	说明
scrollTop	Number	否	滚动到页面的目标位置（单位px）
selector	String	否	元素选择器，用于指定要滚动到的元素位置，App、H5、微信小程序2.7.3+ 、支付宝小程序1.20.0+支持
duration	Number	否	滚动动画的时长，默认300ms，单位 ms
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

selector 语法

selector类似于 CSS 的选择器，但仅支持下列语法。

ID选择器：#the-id
class选择器（可以连续指定多个）：.a-class.another-class
子元素选择器：.the-parent > .the-child
后代选择器：.the-ancestor .the-descendant
跨自定义组件的后代选择器：.the-ancestor >>> .the-descendant
多选择器的并集：#a-node, .some-other-nodes

uni.pageScrollTo({
	scrollTop: 0,
	duration: 300
});

窗口变化

uni.onWindowResize(CALLBACK)

监听窗口尺寸变化事件

CALLBACK 参数说明

属性	类型	说明
size	Object	变化后的窗口的大小，单位为 px ，{windowWidth,windowHeight}

const windowResizeCallback = (res) => {
  console.log('变化后的窗口宽度=' + res.size.windowWidth)
  console.log('变化后的窗口高度=' + res.size.windowHeight)
}
uni.onWindowResize(windowResizeCallback)

横竖屏切换时，会触发此事件。

uni.offWindowResize(CALLBACK)

取消监听窗口尺寸变化事件

Tips

CALLBACK为调用uni.onWindowResize时传入的CALLBACK

uni.offWindowResize(windowResizeCallback)

下拉刷新

onPullDownRefresh

在 js 中定义 onPullDownRefresh 处理函数（和onLoad等生命周期函数同级），监听该页面用户下拉刷新事件。

需要在 pages.json 里，找到的当前页面的pages节点，并在 style 选项中开启 enablePullDownRefresh。
当处理完数据刷新后，uni.stopPullDownRefresh 可以停止当前页面的下拉刷新。

uni.startPullDownRefresh(OBJECT)

开始下拉刷新，调用后触发下拉刷新动画，效果与用户手动下拉刷新一致。

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数	类型	说明
errMsg	String	接口调用结果

uni.stopPullDownRefresh()

停止当前页面下拉刷新。

示例：

pages.json

{
    "pages": [
        {
        	"path": "pages/index/index",
        	"style": {
        		"navigationBarTitleText": "uni-app",
        		"enablePullDownRefresh": true
        	}
        }
    ],
    "globalStyle": {
    	"navigationBarTextStyle": "white",
    	"navigationBarBackgroundColor": "#0faeff",
    	"backgroundColor": "#fbf9fe"
    }
}

index.vue

// 仅做示例，实际开发中延时根据需求来使用。
export default {
	data() {
		return {
			text: 'uni-app'
		}
	},
	onLoad: function (options) {
		setTimeout(function () {
			console.log('start pulldown');
		}, 1000);
		uni.startPullDownRefresh();
	},
	onPullDownRefresh() {
		console.log('refresh');
		setTimeout(function () {
			uni.stopPullDownRefresh();
		}, 1000);
	}
}

媒体查询

MediaQueryObserver 对象，用于监听页面 media query 状态的变化，如界面的宽高是不是在某个指定的范围内。

uni.createMediaQueryObserver([this])

创建并返回一个 MediaQueryObserver 对象实例。

this说明：

自定义组件实例。小程序端不支持此参数，传入仅为抹平写法差异

MediaQueryObserver 对象的方法列表

方法	说明
MediaQueryObserver.observe(Object descriptor, function callback)	开始监听页面 media query 变化情况
MediaQueryObserver.disconnect()	停止监听，回调函数将不再触发

Object descriptor

属性名	类型	必填	说明
minWidth	number	否	页面最小宽度（ px 为单位）
maxWidth	number	否	页面最大宽度（ px 为单位）
width	number	否	页面宽度（ px 为单位）
minHeight	number	否	页面最小高度（ px 为单位）
maxHeight	number	否	页面最大高度（ px 为单位）
height	number	否	页面高度（ px 为单位）
orientation	string	否	屏幕方向（ landscape 或 portrait ）

observe 回调函数包含一个参数

参数	类型	说明
matches	boolean	页面的当前状态是否满足所指定的 media query

示例：

<template>
    <view class="content">
        <view class="">
            要求页面最小宽度 375px， 且页面宽度最大 500px，是否匹配: {{matches}}
        </view>
        <view>
            要求屏幕方向为纵向，是否匹配: {{landscape}}
        </view>
    </view>
</template>

<script>
    let landscapeOb
    export default {
        data() {
            return {
                matches: false,
                landscape: false,
                mediaQueryOb: null
            }
        },
        onLoad() {

        },
        
        // 和 UI 相关的 api 在组件 mountd 后执行
        mounted() {
            this.testMediaQueryObserver()
            this.landscapeObserver()
        },

        methods: {
            testMediaQueryObserver() {
                this.mediaQueryOb = uni.createMediaQueryObserver(this)

                this.mediaQueryOb.observe({
                    minWidth: 375,  //页面最小宽度 375px
                    maxWidth: 500  //页面宽度最大 500px
                }, matches => {
                    this.matches = matches;
                })
            },
            landscapeObserver() {
                landscapeOb = uni.createMediaQueryObserver(this)
                landscapeOb.observe({
                    orientation: 'landscape'  //屏幕方向为纵向
                }, matches => {
                        this.landscape = matches
                })
            },
            destroyed () {
                this.mediaQueryOb.disconnect()  //组件销毁时停止监听
                landscapeOb.disconnect()
            }
        }
    }
</script>

<style>
    .content {
        text-align: center;
        height: 400upx;
    }
</style>

语言操作

uni.getLocale()

获取当前设置的语言

如果当前应用设置过语言，会获取到之前设置的语言，未设置时会返回根据系统语言类型自动选择的语言。

uni.setLocale(locale)

设置当前语言

仅可设置为框架内置语言与自定义扩展的语言，遵循 BCP47 规范。

参数说明

参数名	类型	必填
locale	String	是

uni.onLocaleChange(callback)

用于监听应用语言切换

callback返回参数说明

参数名	类型	说明
locale	String	当前语言

注意事项

组件和接口显示会根据设置的语言环境自动切换，未支持的系统语言环境会显示为英文。
App-Android、App-iOS 平台修改系统语言后会重启应用。
App-Android 平台设置新的语言后会自动重启应用。
框架内置如下语言，如需自定义内容或增加其他语言参考：自定义国际化内容。
- 英语 en
- 中文简体 zh-Hans
- 繁体 zh-Hant
- 法语 fr
- 西班牙语 es
在 manifest.json -> locale 可以配置应用的默认语言。
仅 3.1.5 - 3.2.4 版本会自动使用 vue-i18n 内配置的语言。
在小程序平台仅影响用户业务层（vue-i18n）的语言配置，不能影响小程序原生组件和接口的语言。

语言回退规则

需要注意的是，语言的处理逻辑是建立在应用locale目录配置了对应资源的前提下。资源配置文档

即

如果应用的 locale目录下配置了对应的资源，那么语言的设置和获取是一致的
如果应用的 locale目录没有配置对应的资源，则会根据具体的平台规则进行回退。

举个例子，应用中仅配置了英文和中文资源，没有配置日语资源，但是通过系统设置修改语言为日文，此时调用 uni.getLocale() 在android平台上获取到的返回值不会是jp 而是en

小程序更新

uni.getUpdateManager()

本API返回全局唯一的版本更新管理器对象： updateManager，用于管理小程序更新。

updateManager 对象的方法列表：

方法	参数	说明
onCheckForUpdate	callback	当向小程序后台请求完新版本信息，会进行回调
onUpdateReady	callback	当新版本下载完成，会进行回调
onUpdateFailed	callback	当新版本下载失败，会进行回调
applyUpdate		当新版本下载完成，调用该方法会强制当前小程序应用上新版本并重启

onCheckForUpdate(callback) 回调结果说明：

属性	类型	说明
hasUpdate	Boolean	是否有新的版本

示例

const updateManager = uni.getUpdateManager();

updateManager.onCheckForUpdate(function (res) {
  // 请求完新版本信息的回调
  console.log(res.hasUpdate);
});

updateManager.onUpdateReady(function (res) {
  uni.showModal({
    title: '更新提示',
    content: '新版本已经准备好，是否重启应用？',
    success(res) {
      if (res.confirm) {
        // 新的版本已经下载好，调用 applyUpdate 应用新版本并重启
        updateManager.applyUpdate();
      }
    }
  });

});

updateManager.onUpdateFailed(function (res) {
  // 新的版本下载失败
});

如果您喜欢本站，点击这儿不花一分钱捐赠本站

这些信息可能会帮助到你：下载帮助 | 报毒说明 | 进站必看

修改版本安卓软件，加群提示为修改者自留，非本站信息，注意鉴别

THE END

二维码

打赏

海报