API 概述
uni-app的 js API 由标准 ECMAScript 的 js API 和 uni 扩展 API 这两部分组成。
标准 ECMAScript 的 js 仅是最基础的 js。浏览器基于它扩展了 window、document、navigator 等对象。小程序也基于标准 js 扩展了各种 wx.xx、my.xx、swan.xx 的 API。node 也扩展了 fs 等模块。
uni-app 基于 ECMAScript 扩展了 uni 对象，并且 API 命名与小程序保持兼容。
标准 js 和浏览器 js 的区别
uni-app的 js 代码，web 端运行于浏览器中。非 web 端（包含小程序和 App），Android 平台运行在 v8 引擎中，iOS 平台运行在 iOS 自带的 jscore 引擎中，都没有运行在浏览器或 webview 里。
非 web 端，虽然不支持 window、document、navigator 等浏览器的 js API，但也支持标准 ECMAScript。
请注意不要把浏览器里的 js 等价于标准 js。
所以 uni-app 的非web端，一样支持标准 js，支持 if、for 等语法，支持字符串、数字、时间、布尔值、数组、自定义对象等变量类型及各种处理方法。仅仅是不支持 window、document、navigator 等浏览器专用对象。
各端特色 API 调用
除了 uni-app 框架内置的跨端 API，各端自己的特色 API 也可通过条件编译自由使用。
各端特色 API 规范参考各端的开发文档。其中 App 端的 JS API 参考html5plus.org；uni-app 也支持通过扩展原生插件来丰富 App 端的开发能力，具体参考插件开发文档
各平台的 API 新增，不需要 uni-app 升级，开发者就可以直接使用。
各平台 API 独有的字段，如快手小程序 ks.pay 的 payType、paymentChannel 字段，开发者在调用 API 时正常传入即可，会透传至快手小程序的 API 上
补充说明
- uni.on 开头的 API 是监听某个事件发生的 API 接口，接受一个 CALLBACK 函数作为参数。当该事件触发时，会调用 CALLBACK 函数。
- 如未特殊约定，其他 API 接口都接受一个 OBJECT 作为参数。
- OBJECT 中可以指定 success，fail，complete 来接收接口调用结果。
- 平台差异说明若无特殊说明，则表示所有平台均支持。
- 异步 API 会返回
errMsg 字段，同步 API 则不会。比如：getSystemInfoSync 在返回结果中不会有 errMsg。
API Promise 化
具体 API Promise 化 的策略：
不进行 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 方法 回调
使用示例：
示例源码如下，请查看 pre > code 标签中的内容
// 默认方式
uni.request({
url: "https://www.example.com/request",
success: (res) => {
console.log(res.data);
},
fail: (err) => {
console.error(err);
},
});
// Promise
uni
.request({
url: "https://www.example.com/request",
})
.then((data) => {
// data为一个数组
// 数组第一项为错误信息 即为 fail 回调
// 第二项为返回数据
var [err, res] = data;
console.log(res.data);
});
// Await
async function request() {
var [err, res] = await uni.request({
url: "https://www.example.com/request",
});
console.log(res.data);
}
示例源码如下，请查看 pre > code 标签中的内容
// 默认方式
uni.request({
url: "https://www.example.com/request",
success: (res) => {
console.log(res.data);
},
fail: (err) => {
console.error(err);
},
});
// 使用 Promise then/catch 方式调用
uni
.request({
url: "https://www.example.com/request",
})
.then((res) => {
// 此处的 res 参数，与使用默认方式调用时 success 回调中的 res 参数一致
console.log(res.data);
})
.catch((err) => {
// 此处的 err 参数，与使用默认方式调用时 fail 回调中的 err 参数一致
console.error(err);
});
// 使用 Async/Await 方式调用
async function request() {
try {
var res = await uni.request({
url: "https://www.example.com/request",
});
// 此处的 res 参数，与使用默认方式调用时 success 回调中的 res 参数一致
console.log(res);
} catch (err) {
// 此处的 err 参数，与使用默认方式调用时 fail 回调中的 err 参数一致
console.error(err);
}
}
返回格式互相转换
示例源码如下，请查看 pre > code 标签中的内容
// Vue 2 转 Vue 3, 在 main.js 中写入以下代码即可
function isPromise(obj) {
return (
!!obj &&
(typeof obj === "object" || typeof obj === "function") &&
typeof obj.then === "function"
);
}
uni.addInterceptor({
returnValue(res) {
if (!isPromise(res)) {
return res;
}
return new Promise((resolve, reject) => {
res.then((res) => {
if (!res) {
resolve(res);
return;
}
if (res[0]) {
reject(res[0]);
} else {
resolve(res[1]);
}
});
});
},
});
示例源码如下，请查看 pre > code 标签中的内容
// Vue 3 转 Vue 2, 在 main.js 中写入以下代码即可
function isPromise(obj) {
return (
!!obj &&
(typeof obj === "object" || typeof obj === "function") &&
typeof obj.then === "function"
);
}
uni.addInterceptor({
returnValue(res) {
if (!isPromise(res)) {
return res;
}
const returnValue = [undefined, undefined];
return res
.then((res) => {
returnValue[1] = res;
})
.catch((err) => {
returnValue[0] = err;
})
.then(() => returnValue);
},
});
API 列表
基础
日志打印等。
网络
| API | 说明 |
|---|
| 发起请求 | - |
|
| 上传、下载 | - |
|
| WebSocket | - |
|
| SocketTask | - |
|
| mDNS | mDNS 服务 |
| UDP 通信 | UDP 通信 |
页面和路由
数据缓存
位置
| API | 说明 |
|---|
| 获取位置 | - |
|
| 查看位置 | - |
|
| 位置更新 | - |
|
| 地图组件控制 | - |
|
媒体
| API | 说明 |
|---|
| 图片 | - |
|
| 文件 | - |
|
| 录音管理 | - |
|
| 背景音频播放管理 | - |
|
| 音频组件管理 | - |
|
| 视频 | - |
|
| 视频组件管理 | - |
|
| 相机组件管理 | - |
|
| 直播组件管理 | - |
|
| 富文本 | - |
|
| 音视频合成 | - |
|
设备
键盘
界面
| API | 说明 |
|---|
| 交互反馈 | - |
|
| 设置导航条 | - |
|
| 设置 TabBar | - |
|
| 背景 | - |
|
| 动画 | - |
| API | 说明 |
|---|
| uni.createAnimation | 创建一个动画实例 animation。调用实例的方法来描述动画。最后通过动画实例的 export 方法导出动画数据传递给组件的 animation 属性。 |
|
| 滚动 | - |
|
| 窗口 | - |
|
| 宽屏适配 | - |
|
| 字体 | - |
|
| 下拉刷新 | - |
|
| 节点信息 | - |
|
| 节点布局相交状态 | - |
|
| 媒体查询 | - |
|
| 菜单 | - |
|
| 语言 | - |
|
文件
画布
组件上下文对象
广告
第三方服务
平台扩展
其他
授权
设置
收货地址
获取发票抬头
小程序跳转
模板消息
小程序更新
调试
获取第三方平台数据
因文档同步原因，本页面列出的 API 可能不全。如在本文未找到相关 API，可以在左侧树中寻找或使用文档右上角的搜索功能。
