8.2 KiB
8.2 KiB
uni-app API 替换矩阵
文档状态
- 状态：阶段 0 盘点产物
- 日期：2026-05-25
- 来源：
rg扫描src，排除src/uni_modules - 目标：为 Vue3 Web 改造建立 uni 运行时替换账本
扫描摘要
高频 uni.* 使用统计：
| API | 次数 | 主要风险 |
|---|---|---|
uni.showToast |
74 | 用户反馈入口分散 |
uni.navigateTo |
26 | 路由跳转分散 |
uni.$emit |
26 | 跨组件事件耦合 |
uni.hideLoading |
19 | loading 状态分散 |
uni.$on |
13 | 事件监听生命周期需重建 |
uni.createSelectorQuery |
12 | DOM 测量方式不同 |
uni.navigateBack |
9 | 返回逻辑需路由服务承接 |
uni.$off |
9 | 事件清理需统一 |
uni.connectSocket |
8 | 聊天实时链路高风险 |
uni.showModal |
7 | Modal 交互需统一 |
uni.showLoading |
6 | loading 交互需统一 |
uni.getSystemInfoSync |
6 | 系统信息和安全区需 Web 替代 |
uni.hideKeyboard |
5 | 键盘行为 Web 不等价 |
uni.request |
4 | 请求层需替换 |
uni.getLocation/openLocation |
6 | 浏览器定位和地图打开需授权/降级 |
uni.requestPayment |
2 | 支付方案需重新确认 |
uni.login |
2 | 微信登录不能直接迁移 |
uni.chooseImage |
2 | 图片选择上传需 Web 化 |
uni.saveImageToPhotosAlbum |
2 | 浏览器保存相册不可等价 |
微信原生 wx.* 使用：
| API | 次数 | 文件 |
|---|---|---|
wx.getPrivacySetting |
1 | src/components/Privacy/index.vue |
wx.openPrivacyContract |
1 | src/components/Privacy/index.vue |
uni 页面生命周期使用集中在：
src/App.vuesrc/pages/index/index.vuesrc/pages/login/index.vuesrc/pages/goods/index.vuesrc/pages/goods/album/index.vuesrc/pages-booking/index.vuesrc/pages-order/order/detail.vuesrc/pages/ChatMain/ChatMainList/index.vuesrc/pages/ChatMain/ChatLongAnswer/index.vuesrc/pages/ChatMain/NoticeMessage/detail.vuesrc/pages-bridge/UploadImage.vuesrc/components/Privacy/index.vue
替换矩阵
| 分类 | 当前 API/能力 | 代表文件 | Web 替代方案 | 目标封装 | 阶段 | 风险 |
|---|---|---|---|---|---|---|
| 路由 | uni.navigateTo、uni.navigateBack、uni.reLaunch |
src/router/index.js、src/hooks/useGoLogin.js、多页面 |
Vue Router push/back/replace |
services/router |
2 | 中 |
| 请求 | uni.request |
src/request/base/request.js、src/request/api/AgentChatStream.js |
Axios 或 fetch |
services/http、services/stream |
2/4 | 高 |
| 上传 | uni.uploadFile |
src/request/api/UpdateFile.js |
FormData + fetch/axios |
services/http/upload |
2/7 | 中 |
| 下载 | uni.downloadFile |
src/pages/webview/bridge.js |
fetch blob + object URL |
services/browser/download |
7 | 中 |
| 存储 | uni.setStorageSync、uni.getStorageSync、uni.removeStorageSync |
src/constant/token.js |
localStorage/sessionStorage |
services/storage |
2/3 | 低 |
| 事件 | uni.$emit、uni.$on、uni.$off |
聊天、发现、登录、通知 | mitt typed event bus |
services/event-bus |
2 | 中 |
| 反馈 | uni.showToast、uni.showModal、uni.showLoading、uni.hideLoading |
多页面和组件 | 统一 Toast/Modal/Loading 组件 | services/feedback |
2 | 低 |
| 生命周期 | onLoad、onShow、onHide、onUnload、onReady |
页面组件 | Vue onMounted/onUnmounted + Router hooks |
页面组合式函数 | 4-7 | 中 |
| 应用启动 | onLaunch、uni.onNetworkStatusChange、uni.getNetworkType |
src/App.vue |
App bootstrap + online/offline 事件 |
app/bootstrap |
2/3 | 中 |
| 系统信息 | uni.getSystemInfoSync、uni.getWindowInfo |
导航栏、登录、卡片 | window.innerWidth、CSS env、ResizeObserver |
services/browser/viewport |
2/8 | 中 |
| DOM 测量 | uni.createSelectorQuery |
Tabs、发现 tabs、长回答 | DOM API、getBoundingClientRect、ResizeObserver |
局部 composable | 5/6 | 中 |
| 键盘 | uni.onKeyboardHeightChange、uni.hideKeyboard |
src/pages/ChatMain/ChatInputArea/index.vue |
VisualViewport API、blur、CSS 视口适配 | features/chat/composables |
4 | 高 |
| WebSocket | uni.connectSocket |
src/utils/WebSocketManager.js |
浏览器原生 WebSocket |
services/websocket |
4 | 高 |
| 流式响应 | enableChunked、uni.arrayBufferToBase64 |
src/request/api/AgentChatStream.js |
fetch + ReadableStream、TextDecoder、SSE parser |
services/stream |
4 | 高 |
| 登录 | uni.login |
src/manager/LoginManager.js |
微信 Web 授权、H5 登录或后端 token 方案 | services/auth |
3 | 高 |
| 支付 | uni.requestPayment |
src/pages-booking/index.vue、FooterSection |
微信 JS-SDK/H5 支付/后端支付跳转 | features/payment |
6 | 高 |
| 图片选择 | uni.chooseImage |
CreateServiceOrder、webview/bridge.js |
<input type="file"> |
services/browser/file-picker |
7 | 中 |
| 保存图片 | uni.saveImageToPhotosAlbum |
Qrcode、webview/bridge.js |
下载链接、长按保存提示 | services/browser/download |
7 | 中 |
| 图片预览 | uni.previewImage |
图片组件 | 弹窗预览组件 | components/ImagePreview |
5/6 | 低 |
| Canvas | uni.createCanvasContext、uni.canvasToTempFilePath、uni.upx2px |
src/components/Qrcode |
浏览器 Canvas、二维码库 | components/Qrcode |
6/7 | 中 |
| 定位地图 | uni.getLocation、uni.openLocation |
LocationCard、LocationInfo、Discovery |
Geolocation API、地图 URL/SDK | services/browser/location |
5/6 | 中 |
| 电话 | uni.makePhoneCall |
LocationCard、订单卡片 |
tel: 链接 |
services/browser/phone |
6/7 | 低 |
| 小程序隐私 | wx.getPrivacySetting、wx.openPrivacyContract、uni.getPrivacySetting |
src/components/Privacy/index.vue |
Web 隐私协议弹窗/链接 | features/auth/privacy |
3/7 | 中 |
| 分享 | uni.showShareMenu、utils/share.js |
src/main.js、src/utils/share.js |
Web Share API 或自定义分享 | services/browser/share |
7 | 中 |
| 更新 | uni.getUpdateManager |
src/utils/UpdateManager.js |
Web 无等价；PWA 时另做 | 待定 | 9 | 低 |
模板标签替换摘要
高频 uni/小程序标签：
| 标签 | 次数 | Web 替代 |
|---|---|---|
<view> |
997 | div 或布局组件 |
<text> |
292 | span、p |
<image> |
65 | img 或图片组件 |
<button> |
20 | button |
<scroll-view> |
18 | div + CSS overflow |
<input> |
9 | input |
<uni-popup> |
7 | Modal/Drawer 组件 |
<swiper>、<swiper-item> |
6 | 轮播组件或 CSS scroll snap |
<textarea> |
3 | textarea |
<z-paging> |
3 | 列表分页/虚拟列表组件 |
<zero-markdown-view> |
3 | Markdown 渲染库 |
<canvas> |
2 | 浏览器 canvas |
替换策略：
- 迁移页面时同步替换标签，不做全仓机械替换。
- 高频基础标签可在早期建立轻量基础组件，但不要复刻 uni 组件完整语义。
scroll-view、swiper、canvas、web-view必须按业务场景单独验证。
约束规则
- 新 Web 代码不得直接调用
uni.*或wx.*。 - 新业务页面不得直接散落
fetch、localStorage、window.location等浏览器 API；必须通过服务封装进入。 - 新路由跳转优先使用 route name 或
routerService，避免字符串拼接旧路径。 - 事件名可以沿用
src/constant/constant.js，但事件 payload 应在 TypeScript 中补类型。 - 小程序专属能力先保留旧项目，Web 端必须有明确替代、降级或暂不支持说明。
第一批替换任务建议
services/storage替代 token storage。services/event-bus替代登录、聊天、发现联动事件。services/router替代跳转语义。services/feedback替代 toast/loading/modal。services/http替代普通 API 请求。services/websocket和services/stream单独做聊天链路原型。
验收清单
- 新 Web 工程中没有新增
uni.*或wx.*调用。 - 所有平台能力都有唯一封装入口。
- 聊天 WebSocket 和流式响应先做原型验证。
- 支付、登录、隐私协议有目标平台方案确认。
- 页面迁移时每个
scroll-view、swiper、canvas都有对应验收项。