删除多个完成报告文件，优化项目结构以提升可维护性。
This commit is contained in:
@@ -21,7 +21,8 @@
|
||||
### 2.1 miniprogram.config.js
|
||||
|
||||
- `router`：每个页面单独 key，对应 Next 路由，**不要使用 `other` 数组**。
|
||||
- 动态底部导航：`appExtraConfig` 中**不配置** `tabBar`，用自定义 React 组件 + `wx.reLaunch`。
|
||||
- **`redirect`**：`notFound`、`accessDenied` 必须填 **router 里存在的页面名**（如 `index`），不要填不存在的 `home`。
|
||||
- **底部菜单**：`appExtraConfig` 中**不配置** `tabBar`。Web 端多为自定义底部菜单组件（主页面统一引入、有显隐逻辑），转化时**不要**改为小程序原生 tabBar，保留「统一菜单组件」+ `wx.reLaunch` 跳转。
|
||||
- `global`：建议 `rem: true`、`pageStyle: true`。
|
||||
- `pages`：为每个页面配置 `extra.navigationBarTitleText`。
|
||||
|
||||
@@ -56,12 +57,18 @@ appExtraConfig: {
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `adapters/env.js` | `isMiniProgram()`：`typeof wx !== 'undefined' && wx.getSystemInfoSync` |
|
||||
| `adapters/request.js` | Web：`fetch`；小程序：`wx.request`，统一返回 Promise |
|
||||
| `adapters/request.js` | Web：`fetch`（相对路径）；小程序：`wx.request`，**必须带完整 baseUrl**，本项目线上域名为 `https://soul.quwanzhi.com`（见开发文档 8、部署） |
|
||||
| `adapters/storage.js` | Web：`localStorage`；小程序：`wx.getStorageSync`/`setStorageSync` |
|
||||
| `adapters/router.js` | Web：`window.location` 或 Next Router；小程序：`wx.navigateTo`/`wx.reLaunch`，路径用 `toMpPath(path)` 转成小程序页面路径 |
|
||||
|
||||
业务代码**只**通过适配层访问请求、存储、路由，不直接使用 `window`、`document`、`localStorage`、`URLSearchParams` 等。
|
||||
|
||||
**请求基地址（转化时必须处理）**：小程序端不能使用相对路径，需用完整 URL。本项目线上 API 域名为 **`https://soul.quwanzhi.com`**，见 `开发文档/8、部署/当前项目部署到线上.md`。转化时：
|
||||
|
||||
- 在**壳**的 `miniprogram/app.js` 的 `globalData` 中设置 `baseUrl: 'https://soul.quwanzhi.com'`（或从环境/配置读取）。
|
||||
- 在 **adapters/request.js** 中，小程序分支：`url` 若不以 `http` 开头则拼上 `getApp().globalData.baseUrl`，再调用 `wx.request`。
|
||||
- 不要写死为 `your-domain.com` 或其它占位域名。
|
||||
|
||||
---
|
||||
|
||||
## 4. 功能控制一致
|
||||
@@ -74,6 +81,18 @@ appExtraConfig: {
|
||||
|
||||
---
|
||||
|
||||
## 4.5 底部菜单：必须用自定义组件，不要用原生 tabBar
|
||||
|
||||
- **原因**：Web 端底部菜单多为**自定义组件**（如 `BottomNav`），主页面统一引入，有「某页不显示菜单」「根据 API 显隐某项」等逻辑；原生 tabBar 样式与可操作性差，且无法等价实现上述逻辑。
|
||||
- **要求**：转化时**不要**把自定义底部菜单改成小程序原生 `tabBar`。
|
||||
- **做法**：
|
||||
- `appExtraConfig` 中不配置 `tabBar`。
|
||||
- 各主页面（首页、目录、我的、找伙伴等）**继续引入同一底部菜单组件**，由该组件控制：是否在本页显示、各菜单项显隐（如 `matchEnabled` 控制「找伙伴」）、样式、点击跳转（小程序内用 `wx.reLaunch`）。
|
||||
- 与 Web 一致：阅读页、文档页、关于页等可不渲染该组件或由布局隐藏。
|
||||
- **检查**：若发现被改成了原生 tabBar，应回退为「主页面引入统一菜单组件」的方式。
|
||||
|
||||
---
|
||||
|
||||
## 5. UI 来源策略
|
||||
|
||||
- **复制适配**：从 Next 的 `app/**/page.tsx`、`components/**` 复制到 newpp，改为 JSX，用适配层替代 `Link`/`useRouter`/`usePathname`/`fetch`。
|
||||
@@ -91,7 +110,40 @@ appExtraConfig: {
|
||||
|
||||
---
|
||||
|
||||
## 7. 构建与合并流程
|
||||
## 7. 安全区与标题/胶囊避让（必须）
|
||||
|
||||
### 7.1 电池栏/顶部安全区
|
||||
|
||||
- **问题**：使用自定义导航栏（`navigationStyle: 'custom'`）时，状态栏（电池、时间）会与页面顶部重叠，若不做占位，标题会被挡。
|
||||
- **做法**：
|
||||
- 在**壳**的 `app.js` 的 `onLaunch` 中**同步**获取系统信息并计算占位高度，写入 `globalData`：
|
||||
- `statusBarHeight`：`wx.getSystemInfoSync().statusBarHeight || 44`
|
||||
- `navBarHeight`：用 `wx.getMenuButtonBoundingClientRect()` 计算「状态栏 + 胶囊区域」总高，公式：`menuButton.bottom + menuButton.top - systemInfo.statusBarHeight`；无菜单按钮时回退 `statusBarHeight + 44`
|
||||
- `capsulePaddingRight`：`systemInfo.windowWidth - menuButton.left + 10`，供标题右侧留白使用
|
||||
- 每个页面的**顶部占位条**高度设为 `navBarHeight`（px）；占位条内部若需区分状态栏与导航内容，可用 `padding-top: {{ statusBarHeight || 44 }}px`。
|
||||
- 页面 `onLoad`/`onShow` 时从 `getApp().globalData` 取 `navBarHeight`、`statusBarHeight` 写入页面 `data`，供 WXML 内联样式使用。
|
||||
|
||||
### 7.2 底部安全区
|
||||
|
||||
- **问题**：有底部刘海的设备上，固定底栏（如 TabBar、底部导航）会贴边，内容被遮挡。
|
||||
- **做法**：底部导航容器加 `padding-bottom: env(safe-area-inset-bottom)`（WXSS 或内联均可），无需额外 JS。
|
||||
|
||||
### 7.3 标题右侧不被胶囊遮挡
|
||||
|
||||
- **问题**：小程序右上角有胶囊按钮（…、首页），若标题或返回按钮延伸到右侧，会被遮挡或误触。
|
||||
- **做法**：
|
||||
- 所有带标题/返回/右侧按钮的**头部容器**必须预留右侧空白：
|
||||
- **方式 A**：全局样式 `.safe-header-right { padding-right: 200rpx; box-sizing: border-box; }`，头部容器加该类。
|
||||
- **方式 B**：内联 `style="padding-right: {{ capsulePaddingRight }}px"`，`capsulePaddingRight` 来自 `getApp().globalData.capsulePaddingRight`（在 onLaunch 中已计算）。
|
||||
- 若出现「标题或按钮被挡」，优先检查该头部是否加了上述留白，并确认 `app.js` 中已正确写入 `capsulePaddingRight`。
|
||||
|
||||
### 7.4 统一占位模板（可选）
|
||||
|
||||
- 无复杂导航的页面（如设置、关于、推广、购买记录等）建议使用**同一套**顶部安全区：占位条高度 `navBarHeight`，其内 `padding-top: statusBarHeight`，导航容器 `display: flex; flex-direction: column; justify-content: flex-end; box-sizing: border-box;`，并加 `.safe-header-right` 或 `capsulePaddingRight`，保证标题与返回按钮不被遮挡且右侧留白一致。
|
||||
|
||||
---
|
||||
|
||||
## 8. 构建与合并流程
|
||||
|
||||
1. 在 newpp 执行：`NODE_ENV=production npm run build:mp`。
|
||||
2. 将 `newpp/dist/mp/` 下生成的页面目录及 `common/` 复制/合并到 `miniprogram/`。
|
||||
@@ -100,11 +152,12 @@ appExtraConfig: {
|
||||
|
||||
---
|
||||
|
||||
## 8. 检查清单
|
||||
## 9. 检查清单
|
||||
|
||||
- [ ] miniprogram.config.js：每页单独 router，无 `other`；未配置原生 tabBar。
|
||||
- [ ] miniprogram.config.js：每页单独 router，无 `other`；**未配置原生 tabBar**，底部菜单沿用 Web 的自定义组件（主页面统一引入，显隐与跳转逻辑一致）。
|
||||
- [ ] webpack.mp.config.js：每页有 entry；isOptimize 按 NODE_ENV；中小型项目 splitChunks 为 false。
|
||||
- [ ] 适配层：env、request、storage、router 已实现并在业务中统一使用。
|
||||
- [ ] 功能开关与 Next 一致，来自同一 API。
|
||||
- [ ] 样式：无 Grid，Flex 已加 boxSizing/lineHeight；不支持特性已替代。
|
||||
- [ ] **安全区**：app.js 的 onLaunch 中已计算并写入 `navBarHeight`、`statusBarHeight`、`capsulePaddingRight`；每页顶部占位用 `navBarHeight`；底部导航有 `padding-bottom: env(safe-area-inset-bottom)`；带标题的头部有 `.safe-header-right` 或 `capsulePaddingRight` 留白，标题/按钮未被胶囊遮挡。
|
||||
- [ ] 合并后 app.js 未被错误覆盖，页面路径与 app.json 一致。
|
||||
|
||||
Reference in New Issue
Block a user