API 参考

uni-app 提供了丰富的 API 接口，让开发者能够调用各种设备功能和平台服务。本章节将详细介绍各类 API 的使用方法。

API 分类

基础 API

网络请求

• uni.request() - 发起网络请求
• uni.uploadFile() - 上传文件
• uni.downloadFile() - 下载文件
• uni.connectSocket() - 创建 WebSocket 连接

数据缓存

• uni.setStorage() - 异步存储数据
• uni.setStorageSync() - 同步存储数据
• uni.getStorage() - 异步获取数据
• uni.getStorageSync() - 同步获取数据
• uni.removeStorage() - 异步删除数据
• uni.clearStorage() - 清空本地数据

界面 API

交互反馈

• uni.showToast() - 显示消息提示框
• uni.showLoading() - 显示加载提示框
• uni.hideLoading() - 隐藏加载提示框
• uni.showModal() - 显示模态对话框
• uni.showActionSheet() - 显示操作菜单

导航栏

• uni.setNavigationBarTitle() - 设置导航栏标题
• uni.setNavigationBarColor() - 设置导航栏颜色
• uni.showNavigationBarLoading() - 显示导航栏加载动画
• uni.hideNavigationBarLoading() - 隐藏导航栏加载动画

背景

• uni.setBackgroundColor() - 设置窗口背景色
• uni.setBackgroundTextStyle() - 设置下拉背景字体样式

路由 API

页面跳转

• uni.navigateTo() - 保留当前页面，跳转到应用内的某个页面
• uni.redirectTo() - 关闭当前页面，跳转到应用内的某个页面
• uni.reLaunch() - 关闭所有页面，打开到应用内的某个页面
• uni.switchTab() - 跳转到 tabBar 页面
• uni.navigateBack() - 关闭当前页面，返回上一页面

设备 API

系统信息

• uni.getSystemInfo() - 获取系统信息
• uni.getSystemInfoSync() - 同步获取系统信息
• uni.canIUse() - 判断应用的 API，回调，参数，组件等是否在当前版本可用

网络状态

• uni.getNetworkType() - 获取网络类型
• uni.onNetworkStatusChange() - 监听网络状态变化

加速度计

• uni.onAccelerometerChange() - 监听加速度数据
• uni.startAccelerometer() - 开始监听加速度数据
• uni.stopAccelerometer() - 停止监听加速度数据

罗盘

• uni.onCompassChange() - 监听罗盘数据
• uni.startCompass() - 开始监听罗盘数据
• uni.stopCompass() - 停止监听罗盘数据

媒体 API

图片

• uni.chooseImage() - 从本地相册选择图片或使用相机拍照
• uni.previewImage() - 预览图片
• uni.getImageInfo() - 获取图片信息
• uni.saveImageToPhotosAlbum() - 保存图片到系统相册

录音

• uni.startRecord() - 开始录音
• uni.stopRecord() - 停止录音

音频播放控制

• uni.playVoice() - 开始播放语音
• uni.pauseVoice() - 暂停正在播放的语音
• uni.stopVoice() - 结束播放语音

音乐播放控制

• uni.getBackgroundAudioManager() - 获取全局唯一的背景音频管理器
• uni.createAudioContext() - 创建并返回 audio 上下文 audioContext 对象

视频

• uni.chooseVideo() - 拍摄视频或从手机相册中选视频
• uni.saveVideoToPhotosAlbum() - 保存视频到系统相册
• uni.createVideoContext() - 创建并返回 video 上下文 videoContext 对象

位置 API

获取位置

• uni.getLocation() - 获取当前的地理位置、速度
• uni.chooseLocation() - 打开地图选择位置

查看位置

• uni.openLocation() - 使用应用内置地图查看位置

文件 API

文件管理

• uni.saveFile() - 保存文件到本地
• uni.getSavedFileList() - 获取本地已保存的文件列表
• uni.getSavedFileInfo() - 获取本地文件的文件信息
• uni.removeSavedFile() - 删除本地存储的文件
• uni.openDocument() - 新开页面打开文档

绘图 API

Canvas

• uni.createCanvasContext() - 创建 canvas 绘图上下文
• uni.canvasToTempFilePath() - 把当前画布指定区域的内容导出生成指定大小的图片
• uni.canvasGetImageData() - 返回一个数组，用来描述 canvas 区域隐含的像素数据
• uni.canvasPutImageData() - 将像素数据绘制到画布

第三方平台 API

登录

• uni.login() - 调用接口获取登录凭证
• uni.checkSession() - 检查登录状态是否过期

授权

• uni.authorize() - 提前向用户发起授权请求
• uni.getSetting() - 获取用户的当前设置

用户信息

• uni.getUserInfo() - 获取用户信息

微信支付

• uni.requestPayment() - 发起微信支付

模板消息

• uni.addTemplate() - 组合模板并添加至帐号下的个人模板库
• uni.deleteTemplate() - 删除帐号下的某个模板
• uni.getTemplateLibraryById() - 获取模板库某个模板标题下关键词库
• uni.getTemplateLibraryList() - 获取小程序模板库标题列表
• uni.getTemplateList() - 获取帐号下已存在的模板列表
• uni.sendTemplateMessage() - 发送模板消息

API 使用示例

网络请求示例

// 发起 GET 请求
uni.request({
  url: 'https://api.example.com/data',
  method: 'GET',
  data: {
    id: 1
  },
  success: (res) => {
    console.log('请求成功', res.data)
  },
  fail: (err) => {
    console.error('请求失败', err)
  }
})

// 发起 POST 请求
uni.request({
  url: 'https://api.example.com/submit',
  method: 'POST',
  data: {
    name: '张三',
    age: 25
  },
  header: {
    'Content-Type': 'application/json'
  },
  success: (res) => {
    console.log('提交成功', res.data)
  }
})

数据存储示例

// 异步存储数据
uni.setStorage({
  key: 'userInfo',
  data: {
    name: '张三',
    age: 25
  },
  success: () => {
    console.log('存储成功')
  }
})

// 同步存储数据
try {
  uni.setStorageSync('token', 'abc123')
  console.log('存储成功')
} catch (e) {
  console.error('存储失败', e)
}

// 异步获取数据
uni.getStorage({
  key: 'userInfo',
  success: (res) => {
    console.log('获取成功', res.data)
  }
})

// 同步获取数据
try {
  const token = uni.getStorageSync('token')
  console.log('获取成功', token)
} catch (e) {
  console.error('获取失败', e)
}

页面跳转示例

// 跳转到新页面
uni.navigateTo({
  url: '/pages/detail/detail?id=123'
})

// 重定向到新页面
uni.redirectTo({
  url: '/pages/login/login'
})

// 返回上一页
uni.navigateBack({
  delta: 1
})

// 跳转到 tabBar 页面
uni.switchTab({
  url: '/pages/index/index'
})

交互反馈示例

// 显示提示框
uni.showToast({
  title: '操作成功',
  icon: 'success',
  duration: 2000
})

// 显示加载框
uni.showLoading({
  title: '加载中...'
})

// 隐藏加载框
setTimeout(() => {
  uni.hideLoading()
}, 2000)

// 显示模态对话框
uni.showModal({
  title: '提示',
  content: '确定要删除这条记录吗？',
  success: (res) => {
    if (res.confirm) {
      console.log('用户点击确定')
    } else if (res.cancel) {
      console.log('用户点击取消')
    }
  }
})

系统信息示例

// 获取系统信息
uni.getSystemInfo({
  success: (res) => {
    console.log('设备品牌：', res.brand)
    console.log('设备型号：', res.model)
    console.log('操作系统：', res.platform)
    console.log('系统版本：', res.system)
    console.log('屏幕宽度：', res.screenWidth)
    console.log('屏幕高度：', res.screenHeight)
  }
})

// 同步获取系统信息
try {
  const res = uni.getSystemInfoSync()
  console.log('系统信息：', res)
} catch (e) {
  console.error('获取系统信息失败', e)
}

选择图片示例

// 选择图片
uni.chooseImage({
  count: 1,
  sizeType: ['original', 'compressed'],
  sourceType: ['album', 'camera'],
  success: (res) => {
    const tempFilePaths = res.tempFilePaths
    console.log('选择的图片：', tempFilePaths)
    
    // 预览图片
    uni.previewImage({
      urls: tempFilePaths
    })
  }
})

API 兼容性

不同平台对 API 的支持程度可能不同，使用前请查看具体 API 的兼容性说明：

API 类别	H5	小程序	App
网络请求	✅	✅	✅
数据缓存	✅	✅	✅
界面交互	✅	✅	✅
路由跳转	✅	✅	✅
设备信息	部分	✅	✅
媒体功能	部分	✅	✅
位置服务	部分	✅	✅
文件操作	部分	✅	✅
第三方平台	❌	✅	部分

注意事项

1. 异步 API：大部分 API 都是异步的，需要通过 success、fail、complete 回调函数处理结果
2. 同步 API：同步 API 通常以 Sync 结尾，会阻塞当前线程，谨慎使用
3. 平台差异：不同平台对 API 的支持可能不同，开发时需要注意兼容性
4. 权限申请：某些 API 需要用户授权才能使用，如位置、相机、麦克风等
5. 错误处理：建议为每个 API 调用添加错误处理逻辑

相关链接

• 快速上手 - 学习如何创建和运行 uni-app 项目
• 网络请求 - 详细了解网络请求的使用方法
• 数据存储 - 学习本地数据存储的最佳实践
• 常见问题 - 查看 API 使用中的常见问题和解决方案