uni-app 常用 API

除了网络请求，uni-app 还封装了一大批跨端 API，覆盖交互反馈、本地存储、设备信息等日常开发高频场景。它们统一以 uni. 开头，各平台行为一致。

本文按类别过一遍最常用的，每个都带代码示例，最后用一个实战场景串联。

交互反馈类

这类 API 负责给用户「说话」，提示操作结果。

uni.showToast 轻提示

最常用的提示，几秒后自动消失：

uni.showToast({ title: '保存成功' })
uni.showToast({ title: '操作失败', icon: 'none' })   // icon 为 none 时不显示图标
uni.showToast({ title: '加载中', icon: 'loading' })

参数	说明
title	提示文字，必填
icon	图标，success / error / loading / none
duration	显示时长，默认 1500 毫秒

提示：icon 默认是 success，只显示打勾图标。只想要文字时用 icon: 'none'，想要加载动画配合 loading 场景用 icon: 'loading'。

uni.showModal 弹窗确认

带「确定 / 取消」两个按钮的模态弹窗，适合删除确认等场景：

uni.showModal({
  title: '提示',
  content: '确定要删除这条记录吗？',
  success: (res) => {
    if (res.confirm) {
      console.log('用户点了确定')
    } else {
      console.log('用户点了取消')
    }
  }
})

uni.showLoading 加载中

配合耗时操作使用，页面会出现遮罩，必须手动调用 hideLoading 关闭：

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

setTimeout(() => {
  uni.hideLoading()
}, 2000)

注意：showToast 会自动消失，showLoading 不会，一定记得成对使用。

本地存储类

类似浏览器的 localStorage，把数据存到设备本地，App 和小程序都支持。

同步三件套

// 存
uni.setStorageSync('username', 'tom')

// 取
const name = uni.getStorageSync('username')
console.log(name)  // tom

// 删
uni.removeStorageSync('username')

// 清空全部
uni.clearStorageSync()

提示：getStorageSync 取不到时返回空字符串，不是 null，判断「是否有值」要用 if (name) 而不是 if (name === null)。

存对象

存储的数据不限于字符串，对象、数组直接存：

const user = { id: 1, name: 'tom', hobbies: ['code', 'game'] }
uni.setStorageSync('user', user)

const saved = uni.getStorageSync('user')
console.log(saved.name)  // tom

注意：小程序端存储容量约 10MB，别把大图片塞进去，只存结构化的小数据。

设备信息类

获取当前设备的系统、屏幕、网络等信息，做适配和统计时常用。

uni.getSystemInfoSync

同步获取，直接返回对象：

const info = uni.getSystemInfoSync()
console.log(info.system)        // iOS 18.0 / Android 14
console.log(info.platform)      // ios / android / devtools
console.log(info.windowWidth)   // 屏幕宽度（px）
console.log(info.safeArea)      // 安全区域信息（适配刘海屏）

提示：官方已把 getSystemInfo 标记为废弃，新版推荐更细的 uni.getWindowInfo()（窗口信息）、uni.getDeviceInfo()（设备信息）、uni.getAppBaseInfo()（应用信息），获取屏幕宽度用 uni.getWindowInfo().windowWidth。

uni.getLocation 获取位置

异步获取经纬度，需要用户授权：

uni.getLocation({
  type: 'gcj02',
  success: (res) => {
    console.log('纬度', res.latitude)
    console.log('经度', res.longitude)
  },
  fail: (err) => {
    console.log('获取失败或用户拒绝', err)
  }
})

三个前置条件要满足：

1. manifest.json 的 App 模块配置里勾选定位模块
2. 小程序平台在对应后台申请权限
3. H5 端要求 HTTPS 环境（浏览器安全策略）

权限类

uni.authorize 请求授权

uni.authorize 用于提前向用户申请权限，但平台兼容性要特别注意，它只在微信小程序、QQ 小程序等部分平台可用，App 端需要用原生权限 API（plus.android.requestPermissions 等），H5 端浏览器会自动弹授权，不需要这个 API。

微信小程序里请求位置的完整流程：

uni.authorize({
  scope: 'scope.userLocation',
  success: () => {
    uni.getLocation({ success: (res) => console.log(res.latitude) })
  },
  fail: () => {
    uni.showToast({ title: '请授权位置权限', icon: 'none' })
  }
})

提示：uni.getSetting 可以查询当前各权限的授权状态，配合判断「用户是第一次拒绝还是永久拒绝」，决定是提示还是引导去设置页。

扩展速查表

以下 API 也常用，用法和上面的同类，遇到时去官方文档查参数即可：

API	用途	常用场景
uni.navigateBack	返回上一页	返回按钮
uni.setClipboardData	写入剪贴板	复制订单号、链接
uni.makePhoneCall	拨打电话	客服、联系卖家
uni.scanCode	扫码	扫二维码
uni.vibrateShort	短震动	操作反馈
uni.setNavigationBarTitle	修改导航栏标题	动态标题
uni.pageScrollTo	页面滚动到指定位置	返回顶部

综合示例：首次打开显示引导页

用本地存储 + 交互反馈，实现「用户第一次打开 App 显示引导页，之后不再显示」：

<script>
export default {
  data() {
    return {
      showGuide: false
    }
  },
  onLoad() {
    // 读取"是否已看过引导"的标记
    const seen = uni.getStorageSync('guide_seen')
    if (!seen) {
      this.showGuide = true
    }
  },
  methods: {
    enterApp() {
      // 标记已看过，之后不再显示
      uni.setStorageSync('guide_seen', true)
      this.showGuide = false
      uni.showToast({ title: '欢迎使用', icon: 'success' })
    },
    showAbout() {
      uni.showModal({
        title: '关于',
        content: '这是一个用 uni-app 开发的应用',
        showCancel: false
      })
    },
    getDeviceInfo() {
      const info = uni.getSystemInfoSync()
      uni.showModal({
        title: '设备信息',
        content: `系统：${info.system}\n屏幕宽：${info.windowWidth}px`,
        showCancel: false
      })
    }
  }
}
</script>

<template>
  <view class="page">
    <!-- 首次打开显示引导层 -->
    <view class="guide" v-if="showGuide">
      <text class="guide-title">欢迎来到我的应用</text>
      <text class="guide-desc">这是一段引导说明文字</text>
      <button type="primary" @click="enterApp">开始使用</button>
    </view>

    <!-- 正常首页 -->
    <view v-else>
      <button @click="showAbout">关于</button>
      <button @click="getDeviceInfo">查看设备信息</button>
    </view>
  </view>
</template>

<style scoped>
.page {
  padding: 40rpx;
}
.guide {
  display: flex;
  flex-direction: column;
  align-items: center;
  padding-top: 200rpx;
}
.guide-title {
  font-size: 40rpx;
  font-weight: bold;
  margin-bottom: 20rpx;
}
.guide-desc {
  font-size: 28rpx;
  color: #666;
  margin-bottom: 60rpx;
}
</style>

流程串起来是，onLoad 读存储标记，没有标记就弹引导页，点「开始使用」写标记并用 showToast 反馈，后续打开直接进首页。

总结

类别	常用 API
交互反馈	showToast / showModal / showLoading + hideLoading
本地存储	setStorageSync / getStorageSync / removeStorageSync / clearStorageSync
设备信息	getSystemInfoSync（新版推荐 getWindowInfo 等）
位置	getLocation（需要授权和 manifest 配置）
权限	authorize（仅部分平台，App 端不同）

一句话总结：交互反馈让应用会说话，本地存储让数据留得下，设备信息让代码认得出设备，权限 API 记得先查平台兼容性，这套 API 组合起来就能写出体验完整的应用。