更新小程序配置,重构页面结构,删除不再使用的地址管理和章节页面,优化项目结构以提升可维护性;调整全局样式,增强组件的可复用性和一致性。
This commit is contained in:
@@ -1,70 +1,65 @@
|
||||
# Web 转小程序 - 完整流程提示词
|
||||
|
||||
> **用法**:在对话中 @ 本文件(`scripts/Web转小程序并上传-提示词.md`),请 AI 按本提示词把**整个流程**处理完:先按当前 Web 项目 100% 完整转为小程序代码到 `miniprogram/`,转换完成后打开微信开发者工具。
|
||||
> **用法**:在对话中 @ 本文件(`scripts/Web转小程序并上传-提示词.md`),请 AI 按本提示词执行:**先枚举要转换的页面 → 按规则 100% 转为小程序 → 自检清单逐项通过 → 可选打开微信开发者工具**。
|
||||
|
||||
---
|
||||
|
||||
## 一、你的任务(当被 @ 本文件时)
|
||||
|
||||
1. **转换**:将当前项目中的 **Web 端(Next.js)** 页面与功能,**完整、一致**地转为微信小程序代码,输出到 **`miniprogram/`** 目录。**转换必须完整,样式、按钮、布局、交互等不得有任何丢失**(见下方「完整性要求」)。
|
||||
2. **检查**:转换完成后,自检 `miniprogram/` 是否可运行,并逐页对照 Web 端确认无遗漏(必要文件、路由、API、样式、按钮、链接、交互一致)。
|
||||
3. **打开微信开发者工具**:转换完成后,打开微信开发者工具并导入 `miniprogram/` 目录(可由 AI 代为执行 `start miniprogram` 或 `open miniprogram` 打开文件夹,用户将文件夹拖入微信开发者工具;或直接调用微信开发者工具 CLI 打开项目)。
|
||||
按**顺序**执行:
|
||||
|
||||
若用户只要求「转换」,则只执行步骤 1~2;若用户说「完整流程」或 @ 本文件且无特别说明,则执行上述三步。
|
||||
1. **枚举页面**:扫描 `app/` 下所有 `**/page.tsx`(排除 `app/api/`、`app/admin/`),得到需上小程序的页面列表及对应小程序路径(见二)。
|
||||
2. **转换**:将上述每个 Web 页面**完整、一致**转为小程序代码到 `miniprogram/`,**样式、按钮、布局、交互、图标零丢失**(见三、四)。
|
||||
3. **检查**:按「六、自检清单」逐项自检,确保可运行且与 Web 逐页对照无遗漏。
|
||||
4. **打开微信开发者工具**(可选):若用户未说「仅转换」,则执行 `start miniprogram`(Windows)或 `open miniprogram`(Mac),或调用微信开发者工具 CLI 打开 `miniprogram/`。
|
||||
|
||||
**触发约定**:用户只说「转换」或「只转」→ 只做 1~3;用户说「完整流程」或仅 @ 本文件 → 做 1~4。
|
||||
|
||||
---
|
||||
|
||||
## 二、项目结构对照(按规则推导,不写死页面)
|
||||
|
||||
**转换时请扫描当前仓库的 `app/` 目录,按以下规则生成小程序结构;有新增页面时同样适用。**
|
||||
**先扫描 `app/` 得到页面列表,再按规则生成小程序路径与四件套;新增 Web 页面时同样适用。**
|
||||
|
||||
1. **Web 路由 → 小程序页面路径**
|
||||
- 规则:`app/<path>/page.tsx` → 小程序页面路径 `pages/<name>/<name>`,其中 `<name>` 取该路由的**最后一层目录名**(或约定名称,见下)。
|
||||
- 通用:`app/<path>/page.tsx` → `pages/<name>/<name>`,`<name>` 取该路由**最后一层目录名**。
|
||||
- 特例:
|
||||
- `app/page.tsx`(根首页)→ `pages/index/index`。
|
||||
- `app/<a>/[id]/page.tsx` 等动态路由 → `pages/<a>/<a>`,页面内通过 `onLoad(options)` 的 `options.id` 等取参数。
|
||||
- 嵌套路由(如 `app/my/referral/page.tsx`)→ 小程序侧通常用单层页面名,如 `pages/referral/referral`(以功能命名,避免深层路径)。
|
||||
- **新增页面**:在 `app/` 下每增加一个需在小程序展示的路由(如 `app/xxx/page.tsx`),就应在 `miniprogram/pages/` 下新增 `pages/xxx/xxx` 四件套(.js/.json/.wxml/.wxss),并在 `app.json` 的 `pages` 中追加 `"pages/xxx/xxx"`。
|
||||
- `app/page.tsx` → `pages/index/index`。
|
||||
- 动态路由 `app/<a>/[id]/page.tsx` → `pages/<a>/<a>`,参数在 `onLoad(options)` 中取 `options.id` 等。
|
||||
- 嵌套路由(如 `app/my/referral/page.tsx`)→ 单层页面 `pages/referral/referral`,避免深层路径。
|
||||
- **新增**:每增加一个需上小程序的 `app/xxx/page.tsx`,就在 `miniprogram/pages/` 下新增 `pages/xxx/xxx` 四件套(.js/.json/.wxml/.wxss),并在 `app.json` 的 `pages` 中追加 `"pages/xxx/xxx"`。
|
||||
|
||||
2. **如何枚举要转换的页面**
|
||||
- 遍历 `app/` 下所有包含 `page.tsx` 的路径(排除 `app/api/`、`app/admin/` 等仅 Web 或后台用的路由,除非明确要上小程序)。
|
||||
- 对每个需上小程序的页面,按上面规则得到小程序页面路径,确保在 `miniprogram/pages/` 存在对应目录及四件套,并在 `app.json` 的 `pages` 中注册。
|
||||
2. **枚举要转换的页面**
|
||||
- 遍历 `app/` 下所有含 `page.tsx` 的路径,**排除**:`app/api/`、`app/admin/` 及仅 Web/后台用的路由。
|
||||
- 对每个需上小程序的页面,按上条得到路径,确保 `miniprogram/pages/<name>/` 存在四件套且已在 `app.json` 的 `pages` 中注册。
|
||||
|
||||
3. **API**
|
||||
- Web 的 `app/api/*` 不转为小程序代码;小程序通过 `wx.request` 调用**同域名**接口(如 `https://soul.quwanzhi.com/api/...`),与 `miniprogram/utils` 或现有 baseURL 配置一致,不写死 localhost。
|
||||
- `app/api/*` 不转为小程序代码;小程序用 `wx.request` 调**同域名**接口(与 `miniprogram/utils`、baseURL 一致),**不写死 localhost**。接口路径、参数、返回格式与 `app/api/` 保持一致。
|
||||
|
||||
4. **tabBar**
|
||||
- 仅对需要在底部 tab 展示的页面(如首页、目录、找伙伴、我的)配置 `app.json` 的 `tabBar.list`;其余为普通页面。若项目后续新增 tab,在 `tabBar.list` 中追加一项并在 `pages` 中注册该页。
|
||||
- 仅首页、目录、找伙伴、我的等需底部 tab 的页面配置 `app.json` 的 `tabBar.list`;其余为普通页面。新增 tab 时在 `tabBar.list` 与 `pages` 中同步追加。
|
||||
|
||||
---
|
||||
|
||||
## 三、转换规则(Web → 小程序)
|
||||
|
||||
### 完整性要求(零丢失)
|
||||
**原则**:以 Web 为唯一真相来源,逐块对照,不猜测、不省略;无法 1:1 处用最接近实现并注释说明。
|
||||
|
||||
- **样式**:颜色、字体、字号、行高、间距(margin/padding)、圆角、阴影、背景、边框等必须与 Web 一致,在 WXSS 中完整实现,不得省略或简化。
|
||||
- **按钮与可点击元素**:每个按钮、链接、可点击区域都要保留,文案、图标、点击跳转/弹窗/提交等行为与 Web 一致;禁用态、加载态等状态也要体现。
|
||||
- **布局与结构**:区块划分、顺序、折叠/展开、列表/卡片结构等与 Web 一致,不得漏掉任何一块内容或模块。
|
||||
- **图片与图标**:Web 中出现的图片、图标、占位图都要在小程序侧存在并正确引用;**菜单、列表项、统计项、标签、按钮等处的图标必须逐项对照补全**(可用 emoji 或图片),路径可用 `miniprogram/images/` 或 assets。
|
||||
- **表单与输入**:输入框、选择器、校验、提交逻辑与 Web 一致,不丢字段、不丢校验。
|
||||
- **若 Web 某块在小程序无法 100% 实现**(如复杂 CSS 或 DOM API),用最接近的实现并在此处加注释说明差异,不得直接删掉整块内容。
|
||||
### 3.1 完整性要求(零丢失)
|
||||
|
||||
### 组件与语法
|
||||
- **样式**:颜色、字体、字号、行高、间距、圆角、阴影、背景、边框与 Web 一致,在 WXSS 中完整实现。
|
||||
- **按钮与可点击**:每个按钮、链接、可点击区域保留,文案、图标、跳转/弹窗/提交与 Web 一致;禁用态、加载态需体现。
|
||||
- **布局与结构**:区块划分、顺序、折叠/展开、列表/卡片与 Web 一致,不漏模块。
|
||||
- **图片与图标**:Web 中出现的图片、图标、占位图在小程序侧存在并正确引用;**菜单、列表、统计、标签、按钮等处图标逐项对照补全**(可用 emoji 或图片),路径用 `miniprogram/images/` 或 assets。
|
||||
- **表单**:输入框、选择器、校验、提交与 Web 一致,不丢字段与校验。
|
||||
|
||||
1. **组件与语法**
|
||||
- React/JSX → WXML(`wx:if`、`wx:for`、`bindtap` 等)。
|
||||
- Tailwind/CSS 模块 → WXSS(**逐条对照 Web 样式**,可保留 class 名,样式写到 `.wxss` 或页面/组件内,确保视觉效果一致)。
|
||||
- `useState`/`useEffect` → 小程序 Page 的 `data`、`onLoad`、`onShow` 等。
|
||||
- 路由:`useRouter`/`Link` → `wx.navigateTo`、`wx.switchTab`(tab 页用 switchTab)。
|
||||
2. **页面与路由**
|
||||
- 新增/缺失的 Web 页面要在 `miniprogram/app.json` 的 `pages` 中注册,并在 `miniprogram/pages/` 下建立对应目录及四件套(.js/.json/.wxml/.wxss)。
|
||||
- tabBar 页:保持与现有 `app.json` 的 `tabBar.list` 一致(首页、目录、找伙伴、我的)。
|
||||
3. **接口与数据**
|
||||
- 请求统一走 `wx.request`,baseURL 用项目已有配置(如 `getApp().globalData.baseUrl` 或 `utils` 里封装的 request)。
|
||||
- 与 Web 共用的接口:路径、参数、返回格式与 `app/api/` 保持一致。
|
||||
4. **样式与资源**
|
||||
- 图片:放 `miniprogram/images/` 或现有 assets 目录,引用路径用相对路径或 `/images/xxx`。
|
||||
- 主题色/字体:与 Web 的 `globals.css` 或设计一致,在 WXSS 中实现。
|
||||
### 3.2 组件与语法
|
||||
|
||||
- **React/JSX → WXML**:`wx:if`、`wx:for`、`bindtap` 等;**禁止在 WXML 中写 JS 方法**(见 4.1)。
|
||||
- **Tailwind/CSS → WXSS**:逐条对照 Web 样式,可保留 class 名,视觉效果一致;主题色/字体与 `globals.css` 或设计一致。
|
||||
- **状态与生命周期**:`useState`/`useEffect` → Page 的 `data`、`onLoad`、`onShow` 等。
|
||||
- **路由**:`useRouter`/`Link` → `wx.navigateTo`、`wx.switchTab`(tab 页用 switchTab)。
|
||||
- **接口**:`wx.request` + 项目 baseURL;路径、参数、返回与 `app/api/` 一致。图片放 `miniprogram/images/` 或 assets,引用用相对路径或 `/images/xxx`。
|
||||
|
||||
---
|
||||
|
||||
@@ -74,8 +69,11 @@
|
||||
|
||||
### 4.1 WXML 禁止在模板里调用 JS 方法
|
||||
|
||||
- **问题**:WXML 中不能写 `{{ (user.earnings || 0).toFixed(2) }}`、`{{ user.nickname.charAt(0) }}`、`{{ user.id.slice(-8) }}`、`{{ authorInfo.name.charAt(0) }}` 等,会报 WXML 编译错误。
|
||||
- **做法**:在对应页的 `.js` 里(如 `onLoad`、`syncUser`、数据更新处)**先算好**需要展示的字符串,写入 `data`(如 `earningsText`、`userInitial`、`userIdSuffix`、`authorInitial`),WXML 中只引用 `{{ earningsText }}`、`{{ userInitial }}` 等。
|
||||
- **禁止**:WXML 中不得出现任何 JS 方法调用,例如:`{{ (user.earnings || 0).toFixed(2) }}`、`{{ user.nickname.charAt(0) }}`、`{{ user.id.slice(-8) }}`、`{{ authorInfo.name.charAt(0) }}`,会报「unexpected token」等编译错误。
|
||||
- **必须**:在对应页的 `.js` 中(`onLoad`、`onShow`、`syncUser`、数据更新处)**预先计算**展示用字符串,写入 `data`,WXML 只引用 data 变量。推荐命名示例:
|
||||
- 金额两位小数 → `earningsText`、`balanceText` 等;
|
||||
- 用户/作者首字 → `userInitial`、`authorInitial`;
|
||||
- 用户 ID 后几位 → `userIdSuffix`。
|
||||
|
||||
### 4.2 启动不阻塞、不因网络报错导致模拟器启动失败
|
||||
|
||||
@@ -92,10 +90,11 @@
|
||||
|
||||
### 4.4 顶部安全区:状态栏 + 胶囊会遮挡,必须预留
|
||||
|
||||
- **问题**:小程序使用 `navigationStyle: "custom"` 时,系统**状态栏**(时间、电池等)和右上角**胶囊按钮**会覆盖页面顶部,导致标题、返回、按钮被遮挡或点不到。
|
||||
- **做法**:
|
||||
- **顶部占位高度**:不用固定 `statusBarHeight + 44`,改用 **`navBarHeight`**。在 `App.getSystemInfo` 里用 `wx.getSystemInfoSync()` 和 `wx.getMenuButtonBoundingClientRect()` 计算 `navBarHeight`(状态栏 + 胶囊区域总高度),无菜单按钮时回退为 `statusBarHeight + 44`。每个页面的占位条/导航条高度设为 `{{ navBarHeight }}px`,并在 `onLoad`/`onShow` 中从 `getApp().globalData` 取 `navBarHeight`、`statusBarHeight` 写入页面的 `data`。
|
||||
- **头部右侧留白**:导航栏、标题栏等头部内容需预留胶囊右侧空间,避免被胶囊遮挡。做法:在 `app.wxss` 中定义 `.safe-header-right { padding-right: 200rpx; box-sizing: border-box; }`,所有带标题/按钮的头部容器加上该类;或使用 `globalData.capsulePaddingRight`(由 `windowWidth - menuButton.left + 8` 计算)做内联样式。
|
||||
- **问题**:`navigationStyle: "custom"` 时,**状态栏**和**胶囊按钮**会覆盖页面顶部,标题、返回、按钮被遮挡或点不到。
|
||||
- **必须**:
|
||||
- **占位高度**:统一使用 **`navBarHeight`**(不用固定 `statusBarHeight + 44`)。在 `App.getSystemInfo` 中用 `wx.getSystemInfoSync()` + `wx.getMenuButtonBoundingClientRect()` 计算 `navBarHeight`(状态栏 + 胶囊区域总高),无菜单按钮时回退 `statusBarHeight + 44`。每页占位条高度设为 `{{ navBarHeight }}px`,`onLoad`/`onShow` 从 `getApp().globalData` 取 `navBarHeight`、`statusBarHeight` 写入页面 `data`。
|
||||
- **头部右侧留白**:所有带标题/按钮的头部容器加 `.safe-header-right`(`app.wxss` 中定义 `padding-right: 200rpx; box-sizing: border-box;`),或使用 `globalData.capsulePaddingRight` 内联,避免被胶囊遮挡。
|
||||
- **占位页统一模板**:无复杂导航的页面(如 `address-edit`、`address-list`、`purchases`、`referral`、`settings`)必须使用**同一套**顶部安全区:顶部占位条高度 `navBarHeight`,其内 `padding-top: {{ statusBarHeight || 44 }}px`,导航容器使用 `display: flex; flex-direction: column; justify-content: flex-end; box-sizing: border-box;`,并加 `safe-header-right`,保证标题与返回按钮不被遮挡且右侧留白一致。
|
||||
|
||||
### 4.5 图标与样式逐页对照,不得遗漏
|
||||
|
||||
@@ -115,6 +114,10 @@
|
||||
- **卡片内标题行**:若为 flex 布局(如左侧标题 + 右侧链接),给容器加 `gap`、`min-width: 0`;左侧标题区加 `flex-shrink: 0`、`min-width: 0`,标题与链接加 `white-space: nowrap`,右侧链接加 `flex-shrink: 0`、`white-space: nowrap`,防止挤压、换行或重叠错位。
|
||||
- **全宽按钮**:卡片内的「全宽」按钮使用 `display: block`、`width: 100%`、`box-sizing: border-box`,保证与卡片内容区同宽、与上方内容左右对齐;不得因缺 box-sizing 或未 block 导致宽度计算错误而错位。
|
||||
|
||||
### 4.7 「我的」-「我的足迹」-「匹配记录」需随 matchEnabled 控制
|
||||
|
||||
- **要求**:与 Web 一致,当全局配置 `matchEnabled === false` 时,「我的」页「我的足迹」Tab 下的「匹配记录」区块**不展示**;仅当 `matchEnabled === true` 时展示。小程序侧从 `getApp().globalData.matchEnabled` 读取,在 WXML 中用 `wx:if="{{ matchEnabled }}"` 控制该区块显隐,并在 `onShow` 或数据刷新时同步该值到页面 `data`。
|
||||
|
||||
---
|
||||
|
||||
## 五、必须保留的小程序配置
|
||||
@@ -128,14 +131,15 @@
|
||||
|
||||
## 六、转换完成后的自检清单
|
||||
|
||||
- [ ] `app.json` 中所有 `pages` 在 `miniprogram/pages/` 下均有对应目录及四件套。
|
||||
- [ ] 每个页面的 `.json` 中 `usingComponents` 与自定义组件引用正确(若有)。
|
||||
- [ ] 无语法错误:WXML 闭合、WXSS 合法、JS 中 Page() 注册正确;**WXML 中无 `.toFixed()`、`.charAt()`、`.slice()` 等 JS 方法调用**,均已改为 data 变量。
|
||||
- [ ] 接口 baseURL 为线上或配置项,非 localhost(除非仅本地调试)。
|
||||
- [ ] tabBar 与导航与 Web 端一级入口一致;**「找伙伴」默认隐藏,仅配置返回 matchEnabled 为 true 后再显示**。
|
||||
- [ ] **顶部安全区**:所有带自定义头部的页面使用 `navBarHeight` 作为顶部占位高度,头部内容使用 `safe-header-right` 或等效右侧留白,避免被状态栏和胶囊遮挡。
|
||||
- [ ] **卡片与按钮对齐**:含标题行+链接+全宽按钮的卡片(如「我的」页我的收益)使用 `box-sizing: border-box`,标题行防挤压/换行,全宽按钮 `display: block`、`width: 100%`、`box-sizing: border-box`,与卡片内容区左右对齐、无错位。
|
||||
- [ ] **完整性**:逐页对照 Web,确认样式(颜色、间距、字体等)、按钮、链接、图片、**图标**、表单、列表/卡片等无遗漏;若有无法 1:1 实现处,已用最接近方式实现并注释说明。
|
||||
- [ ] **页面注册**:`app.json` 的 `pages` 与 `miniprogram/pages/` 下目录、四件套一一对应,无缺页。
|
||||
- [ ] **组件引用**:各页 `.json` 的 `usingComponents` 与自定义组件路径正确(若有)。
|
||||
- [ ] **WXML 合规**:无语法错误;**WXML 中无 `.toFixed()`、`.charAt()`、`.slice()` 等 JS 方法**,展示用数值/字符串均已预先写入 data 并在模板中引用。
|
||||
- [ ] **接口**:baseURL 为线上或配置项,非 localhost(仅本地调试可例外)。
|
||||
- [ ] **tabBar**:与 Web 一级入口一致;**「找伙伴」项默认 `hidden: true`,仅当接口返回 `matchEnabled === true` 后显示**(见 4.3)。
|
||||
- [ ] **顶部安全区**:所有自定义头部页使用 `navBarHeight` 占位,头部容器加 `safe-header-right`;占位页(address-edit、address-list、purchases、referral、settings)使用统一顶部安全区模板(见 4.4)。
|
||||
- [ ] **卡片与按钮**:含标题行+链接+全宽按钮的卡片使用 `box-sizing: border-box`,标题行防挤压/换行,全宽按钮 `display: block`、`width: 100%`、`box-sizing: border-box`,与内容区左右对齐无错位(见 4.6)。
|
||||
- [ ] **「我的足迹」-「匹配记录」**:该区块随 `globalData.matchEnabled` 显隐,`matchEnabled === false` 时不展示(见 4.7)。
|
||||
- [ ] **完整性**:逐页对照 Web,样式、按钮、链接、图片、**图标**、表单、列表/卡片无遗漏;无法 1:1 处已用最接近实现并注释说明。
|
||||
|
||||
---
|
||||
|
||||
@@ -152,11 +156,11 @@
|
||||
|
||||
## 八、参考文件位置
|
||||
|
||||
- Web 页面:`app/**/page.tsx`、`components/`
|
||||
- 小程序现有结构:`miniprogram/app.json`、`miniprogram/pages/`、`miniprogram/utils/`、`miniprogram/custom-tab-bar/`、`miniprogram/app.js`
|
||||
- 上传脚本:`scripts/autosysc-weixin.py`(项目根运行,需先配置 `miniprogram/private.key`)
|
||||
- 小程序配置说明:`miniprogram/小程序快速配置指南.md`、`miniprogram/小程序部署说明.md`
|
||||
- **Web 对照**:`app/**/page.tsx`、`components/`;接口路径、参数、返回格式参照 `app/api/`,保证与 Web 一致。
|
||||
- **小程序结构**:`miniprogram/app.json`、`miniprogram/pages/`、`miniprogram/utils/`、`miniprogram/custom-tab-bar/`、`miniprogram/app.js`。
|
||||
- **上传**:`scripts/autosysc-weixin.py`(项目根运行,需先配置 `miniprogram/private.key`)。
|
||||
- **配置说明**:`miniprogram/小程序快速配置指南.md`、`miniprogram/小程序部署说明.md`。
|
||||
|
||||
---
|
||||
|
||||
**当你被 @ 本文件时**:按「一、你的任务」执行完整流程(转换 → 检查 → 打开微信开发者工具),并严格遵循二~六的对照、规则与踩坑必做项。
|
||||
**当你被 @ 本文件时**:按「一、你的任务」顺序执行(枚举页面 → 转换 → 自检 → 可选打开开发者工具),并**严格遵循**二(结构对照)、三(转换规则)、四(踩坑必做项)、五(配置保留)、六(自检清单);四、六中的条目为必做项,不可省略。
|
||||
|
||||
Reference in New Issue
Block a user