# 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.vue`
- `src/pages/index/index.vue`
- `src/pages/login/index.vue`
- `src/pages/goods/index.vue`
- `src/pages/goods/album/index.vue`
- `src/pages-booking/index.vue`
- `src/pages-order/order/detail.vue`
- `src/pages/ChatMain/ChatMainList/index.vue`
- `src/pages/ChatMain/ChatLongAnswer/index.vue`
- `src/pages/ChatMain/NoticeMessage/detail.vue`
- `src/pages-bridge/UploadImage.vue`
- `src/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` |

替换策略：

1. 迁移页面时同步替换标签，不做全仓机械替换。
2. 高频基础标签可在早期建立轻量基础组件，但不要复刻 uni 组件完整语义。
3. `scroll-view`、`swiper`、`canvas`、`web-view` 必须按业务场景单独验证。

## 约束规则

- 新 Web 代码不得直接调用 `uni.*` 或 `wx.*`。
- 新业务页面不得直接散落 `fetch`、`localStorage`、`window.location` 等浏览器 API；必须通过服务封装进入。
- 新路由跳转优先使用 route name 或 `routerService`，避免字符串拼接旧路径。
- 事件名可以沿用 `src/constant/constant.js`，但事件 payload 应在 TypeScript 中补类型。
- 小程序专属能力先保留旧项目，Web 端必须有明确替代、降级或暂不支持说明。

## 第一批替换任务建议

1. `services/storage` 替代 token storage。
2. `services/event-bus` 替代登录、聊天、发现联动事件。
3. `services/router` 替代跳转语义。
4. `services/feedback` 替代 toast/loading/modal。
5. `services/http` 替代普通 API 请求。
6. `services/websocket` 和 `services/stream` 单独做聊天链路原型。

## 验收清单

- [ ] 新 Web 工程中没有新增 `uni.*` 或 `wx.*` 调用。
- [ ] 所有平台能力都有唯一封装入口。
- [ ] 聊天 WebSocket 和流式响应先做原型验证。
- [ ] 支付、登录、隐私协议有目标平台方案确认。
- [ ] 页面迁移时每个 `scroll-view`、`swiper`、`canvas` 都有对应验收项。