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 升级，开发者就可以直接使用。

#说明

• uni.on 开头的 API 是监听某个事件发生的 API 接口，接受一个 CALLBACK 函数作为参数。当该事件触发时，会调用 CALLBACK 函数。

• 如未特殊约定，其他 API 接口都接受一个 OBJECT 作为参数。

• OBJECT 中可以指定 success，fail，complete 来接收接口调用结果。

• 平台差异说明若无特殊说明，则表示所有平台均支持。

• 异步 API 会返回 errMsg 字段，同步 API 则不会。比如：getSystemInfoSync 在返回结果中不会有 errMsg。

#API Promise 化

1. 具体 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 方法 回调

  使用示例：

  Vue2

  Vue 3

  // 默认方式uni.request({
    url: "https://www.example.com/request",
    success: (res) => {
      console.log(res.data);
    },
    fail: (err) => {
      console.error(err);
    },});// Promiseuni  .request({
      url: "https://www.example.com/request",
    })
    .then((data) => {
      // data为一个数组
      // 数组第一项为错误信息 即为 fail 回调
      // 第二项为返回数据
      var [err, res] = data;
      console.log(res.data);
    });// Awaitasync function request() {
    var [err, res] = await uni.request({
      url: "https://www.example.com/request",
    });
    console.log(res.data);}

  复制代码

• 返回格式互相转换

// 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[0]) {
          reject(res[0]);
        } else {
          resolve(res[1]);
        }
      });
    });
  },});

#API 列表

#基础

#日志打印

#网络

#发起请求

#上传、下载

#WebSocket

#SocketTask

#媒体

#图片

#文件

#录音管理

#背景音频播放管理

#音频组件管理

#视频

#相机组件管理

#直播组件管理

#文件

#数据缓存