uni-app微信小程序开发：高频核心 API（一）

目录1. 网络请求uni.request2. 页面路由跳转uni.navigateTo / uni.redirectTo / uni.switchTab3. 本地数据存储uni.setStorageSync / uni.getStorageSync 等4. 交互反馈uni.showToast / uni.showLoading / uni.showModal5. 列表交互下拉刷新 onPullDownRefresh 与 触底加载 onReachBottom6. 设备与安全区信息uni.getSystemInfoSync1. 网络请求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 拦截器模式实现请求拦截自动注入 Token、统一处理请求头、在弱网环境下展示全局 Loading。响应拦截剥离外层包装数据如只返回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?id1 });uni.redirectTo关闭当前页面跳转到应用内的某个页面非 tabBar 页。页面栈深度不变替换栈顶页面。// 表单填写页提交成功后跳转到结果页避免用户按返回键回到表单页重复提交 uni.redirectTo({ url: /pages/result/result });uni.switchTab关闭所有非 tabBar 页面跳转到 tabBar 页面。// 从任意页面点击底部导航回到首页 uni.switchTab({ url: /pages/index/index });uni.reLaunch补充关闭所有页面打开应用内某个页面。常用于强退重登后的重定向。企业实战应用参数拼接封装统一的路由跳转方法将对象参数自动序列化为 URL Query 串目标页面在onLoad(options)中解析。权限拦截在封装的跳转方法中前置校验用户登录态或角色权限未授权则重定向至登录页。注意事项页面栈限制小程序端页面栈最大层级为 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) { /* 执行删除 */ } } });企业实战应用接口流转反馈通常在请求拦截器中调用showLoading响应拦截器中调用hideLoading。表单校验前端校验不通过时用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(); } }企业实战应用这是资讯、电商列表页的标配。企业实战中需配合状态机管理下拉刷新重置分页参数page1请求成功后覆盖原列表数据并手动调用uni.stopPullDownRefresh()停止动画。触底加载追加数据维护加载状态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; } }在业务页面中常用于以下两个高频场景自定义导航栏由于原生导航栏无法满足 UI 设计需求需隐藏原生导航栏navigationStyle: custom此时需用一个空白view撑出statusBarHeight的高度防止内容顶到刘海屏里。底部吸底按钮如提交订单在 CSS 中为底部按钮动态添加padding-bottom: calc(常量safeBottom 20rpx)避免按钮被 iPhone 底部小黑条遮挡。注意事项全局缓存该 API 为同步执行且伴随少量性能开销不建议在每个页面的onLoad中频繁调用。应在应用启动时获取一次并挂载到globalData或状态管理中复用。API 演进微信小程序基础库 2.20.1 起推荐拆分使用uni.getDeviceInfo设备信息和uni.getWindowInfo窗口信息以提升性能。但为了保证跨端兼容性特别是 App 和 H5getSystemInfoSync目前仍是企业项目中最稳妥的跨端获取方案。H5 端兼容H5 端部分老旧 PC 浏览器或非全面屏设备可能返回safeAreaInsets为undefined在代码中务必做好兜底处理|| 0。