uni-app 开发：高频核心 API（一）

目录

[1. 网络请求：uni.request](#1. 网络请求：uni.request)

[2. 页面路由跳转：uni.navigateTo / uni.redirectTo / uni.switchTab](#2. 页面路由跳转：uni.navigateTo / uni.redirectTo / uni.switchTab)

[3. 本地数据存储：uni.setStorageSync / uni.getStorageSync 等](#3. 本地数据存储：uni.setStorageSync / uni.getStorageSync 等)

[4. 交互反馈：uni.showToast / uni.showLoading / uni.showModal](#4. 交互反馈：uni.showToast / uni.showLoading / uni.showModal)

[5. 列表交互：下拉刷新 onPullDownRefresh 与 触底加载 onReachBottom](#5. 列表交互：下拉刷新 onPullDownRefresh 与 触底加载 onReachBottom)

[6. 设备与安全区信息：uni.getSystemInfoSync](#6. 设备与安全区信息：uni.getSystemInfoSync)

1. 网络请求：uni.request

出处 ：uni-app 官方文档 - 网络请求

用处：与后端服务器进行 HTTP 通信，获取或提交数据。

基础用法：

uni.request({
    url: 'https://api.example.com/user',
    method: 'GET',
    data: { id: 1 },
    success: (res) => { console.log(res.data); },
    fail: (err) => { console.error(err); }
});

企业实战应用：

在企业项目中，绝对不推荐直接使用原生 uni.request。通常会在项目初始化时进行二次封装，基于 Promise 拦截器模式实现：

1. 请求拦截：自动注入 Token、统一处理请求头、在弱网环境下展示全局 Loading。
2. 响应拦截 ：剥离外层包装数据（如只返回 res.data.data），根据业务状态码（如 401）统一处理登录失效跳转，非 200 状态码统一弹出错误 Toast。
   封装后的调用方式通常为 this.$api.getUser({ id: 1 })。

注意事项：

• 跨端差异 ：在 H5 端开发时，会面临跨域问题，需在 manifest.json 或 vue.config.js 中配置 devServer 代理。
• 并发控制 ：多个无依赖接口请求，推荐使用 Promise.all() 提升首屏加载速度。
• 超时处理：原生默认超时 60s，企业级应用建议全局配置缩短至 10-15s，并增加重试机制或超时 Toast 提示。

2. 页面路由跳转：uni.navigateTo / uni.redirectTo / uni.switchTab

出处 ：uni-app 官方文档 - 页面路由

用处 ：控制页面的流转与导航。这几者是最常用的路由 API，区别在于对页面栈管理的方式不同：

• uni.navigateTo：保留当前页面，跳转到应用内的某个页面（非 tabBar 页）。页面栈深度 +1。

    // 从列表页跳转到详情页，按返回键可回到列表页
    uni.navigateTo({ url: '/pages/detail/detail?id=1' });

• uni.redirectTo：关闭当前页面，跳转到应用内的某个页面（非 tabBar 页）。页面栈深度不变（替换栈顶页面）。

    // 表单填写页提交成功后，跳转到结果页，避免用户按返回键回到表单页重复提交
    uni.redirectTo({ url: '/pages/result/result' });

• uni.switchTab：关闭所有非 tabBar 页面，跳转到 tabBar 页面。

    // 从任意页面点击底部导航回到首页
    uni.switchTab({ url: '/pages/index/index' });

• uni.reLaunch（补充）：关闭所有页面，打开应用内某个页面。常用于强退重登后的重定向。

企业实战应用：

1. 参数拼接 ：封装统一的路由跳转方法，将对象参数自动序列化为 URL Query 串，目标页面在 onLoad(options) 中解析。
2. 权限拦截：在封装的跳转方法中前置校验用户登录态或角色权限，未授权则重定向至登录页。

注意事项：

• 页面栈限制 ：小程序端页面栈最大层级为 10 层，过度使用 navigateTo 会导致跳转失效，深层级跳转需考虑 reLaunch。
• 防抖：防止用户狂点按钮导致连续入栈，需在跳转方法内加防抖锁。
• TabBar 限制 ：navigateTo 和 redirectTo 均无法跳转至配置在 pages.json 中 tabBar 的页面。

3. 本地数据存储：uni.setStorageSync / uni.getStorageSync 等

出处 ：uni-app 官方文档 - 本地存储

用处：在客户端本地持久化存储数据，如用户 Token、主题配置等。细分 API 各司其职：

• uni.setStorageSync(key, data)：同步写入本地缓存。
• uni.getStorageSync(key)：同步读取本地缓存。
• uni.removeStorageSync(key)：同步移除指定 key 的缓存。
• uni.clearStorageSync()：同步清理本地全部缓存。

基础用法：

uni.setStorageSync('userToken', 'abc-123-xyz');
const token = uni.getStorageSync('userToken');

企业实战应用：

不会在业务代码中散落调用，而是统一封装为 storage.js 模块：

const TOKEN_KEY = 'APP_TOKEN';
export const setToken = (token) => uni.setStorageSync(TOKEN_KEY, token);
export const getToken = () => uni.getStorageSync(TOKEN_KEY);
export const clearToken = () => uni.removeStorageSync(TOKEN_KEY); // 退出登录时调用

实现语义化调用，便于后期统一更换存储 Key 或做加密处理。

注意事项：

• 同步与异步 ：带 Sync 后缀为同步阻塞，不带（如 uni.setStorage）为异步回调。企业开发中处理 Token 等小数据多用同步，以保证后续逻辑依赖生效；存储极大数据时才用异步版避免卡顿。
• 容量限制：微信小程序单条数据上限 1MB，总容量上限 10MB。切勿将大段列表数据塞入 Storage。
• 敏感数据：Token 等敏感信息尽量做混淆处理，避免明文直存。

4. 交互反馈：uni.showToast / uni.showLoading / uni.showModal

出处 ：uni-app 官方文档 - 交互反馈

用处：向用户提供操作反馈。不同场景需选用不同反馈层级：

• uni.showToast：轻提示，用于成功/失败的短暂反馈，自动消失，不阻断用户操作。

    uni.showToast({ title: '保存成功', icon: 'success' });

• uni.showLoading / uni.hideLoading：加载提示，需手动关闭，常配合网络请求展示加载态，阻断后续点击。

    uni.showLoading({ title: '加载中...', mask: true });
    // 请求完成后
    uni.hideLoading();

• uni.showModal：模态弹窗，需用户交互（确认/取消）后关闭，用于重要操作的二次确认。

    uni.showModal({ title: '提示', content: '确认删除该项？', success: (res) => { if (res.confirm) { /* 执行删除 */ } } });

企业实战应用：

1. 接口流转反馈 ：通常在请求拦截器中调用 showLoading，响应拦截器中调用 hideLoading。
2. 表单校验 ：前端校验不通过时，用 showToast 配合 icon: 'none' 提示具体错误。

注意事项：

• 互斥性 ：showToast 和 showLoading 是互斥的，同时调用后者会覆盖前者。接口报错时，需先 hideLoading 再 showToast。
• 遮罩层 ：showLoading 时建议配置 mask: true，防止用户在请求未完成时重复点击触发多次请求。

5. 列表交互：下拉刷新 onPullDownRefresh 与 触底加载 onReachBottom

出处 ：uni-app 官方文档 - 页面生命周期

用处：实现标准的列表数据更新与分页无限滚动加载。

基础用法：

需在 pages.json 对应页面配置 "enablePullDownRefresh": true。

export default {
    onPullDownRefresh() { // 用户下拉触发：重置数据，刷新第一页
        this.fetchList(true);
    },
    onReachBottom() { // 页面滚动到底部触发：追加请求下一页
        this.loadMore();
    }
}

企业实战应用：

这是资讯、电商列表页的标配。企业实战中需配合状态机管理：

1. 下拉刷新 ：重置分页参数（page=1），请求成功后覆盖 原列表数据，并手动调用 uni.stopPullDownRefresh() 停止动画。
2. 触底加载 ：追加数据，维护加载状态（loading, noMore）。当接口返回数组为空或长度小于 pageSize 时，显示"没有更多了"并锁定触底事件。

注意事项：

• 防重锁 ：触底事件在快速滑动时可能连续触发，必须通过 isLoading 状态锁防止重复发起请求。
• iOS 兼容 ：部分 iOS 机型触底计算存在偏差，可结合 scroll-view 组件的 @scrolltolower 事件替代页面级触底，控制更精准。
• 停止动画 ：下拉刷新的数据请求无论成功失败，都必须在 finally 块中调用 uni.stopPullDownRefresh()，否则刷新动画会一直转圈。

6. 设备与安全区信息：uni.getSystemInfoSync

出处 ：uni-app 官方文档 - 获取系统信息

用处 ：同步获取设备的基础信息（如品牌、型号、系统版本）以及屏幕相关尺寸。在现代全面屏（刘海屏、水滴屏、底部手势条）普及的今天，最核心的用途是获取屏幕边界到安全区的距离，防止 UI 元素被遮挡。

关键属性细分：

• safeAreaInsets ：屏幕边界到安全区域的距离对象（核心重点）。
  • top：顶部状态栏高度（刘海/挖孔区域），常用于自定义导航栏撑高。
  • bottom：底部安全区高度（手势条/虚拟按键区域），常用于底部吸底元素增加内边距。
• statusBarHeight ：状态栏高度（与 safeAreaInsets.top 通常一致）。
• windowHeight：可使用窗口高度（去除了状态栏和虚拟底部导航的高度）。

基础用法：

const systemInfo = uni.getSystemInfoSync();
console.log('顶部安全距离:', systemInfo.safeAreaInsets.top);
console.log('底部安全距离:', systemInfo.safeAreaInsets.bottom);

企业实战应用：

在企业开发中，安全区数据是写死不了的（因设备而异），通常在 App.vue 的 onLaunch 中全局获取一次，并存储到全局状态管理（如 Vuex/Pinia）或挂载到全局对象上：

// App.vue
export default {
    onLaunch() {
        const info = uni.getSystemInfoSync();
        // 定义全局属性，供所有页面的自定义导航栏和吸底组件使用
        this.globalData.statusBarHeight = info.statusBarHeight; 
        this.globalData.safeBottom = info.safeAreaInsets.bottom || 0;
    }
}

在业务页面中，常用于以下两个高频场景：

1. 自定义导航栏 ：由于原生导航栏无法满足 UI 设计需求，需隐藏原生导航栏（navigationStyle: custom），此时需用一个空白 view 撑出 statusBarHeight 的高度，防止内容顶到刘海屏里。
2. 底部吸底按钮（如提交订单） ：在 CSS 中为底部按钮动态添加 padding-bottom: calc(常量safeBottom + 20rpx)，避免按钮被 iPhone 底部小黑条遮挡。

注意事项：

• 全局缓存 ：该 API 为同步执行且伴随少量性能开销，不建议在每个页面的 onLoad 中频繁调用。应在应用启动时获取一次并挂载到 globalData 或状态管理中复用。
• API 演进 ：微信小程序基础库 2.20.1 起推荐拆分使用 uni.getDeviceInfo（设备信息）和 uni.getWindowInfo（窗口信息）以提升性能。但为了保证跨端兼容性（特别是 App 和 H5），getSystemInfoSync 目前仍是企业项目中最稳妥的跨端获取方案。
• H5 端兼容 ：H5 端部分老旧 PC 浏览器或非全面屏设备可能返回 safeAreaInsets 为 undefined，在代码中务必做好兜底处理（|| 0）。