448 lines
12 KiB
Markdown
448 lines
12 KiB
Markdown
# 微信小程序从 0 到 1 入门项目
|
||
|
||
这是一个适合零基础开发者的 `Taro + React + TypeScript` 微信小程序项目模板。你后续会用 React 组件方式开发页面，再编译成微信小程序代码进行预览和发布。
|
||
|
||
当前首页已经改成了一版“设备绑定首页（无设备状态）”业务样式，方便你直接在这个基础上继续接真实接口和页面跳转。
|
||
项目里也已经开始整理公共能力：
|
||
|
||
- 颜色统一收口到全局主题变量，后续页面尽量不要再写散落的十六进制颜色
|
||
- 通用 UI 优先拆成可复用组件，方便后续多页面共用
|
||
|
||
当前项目还新增了一版“睡眠报告演示页”，用于展示宝宝睡眠评分、呼吸状态、HRV、异常统计和 AI 分析建议等完整报告结构。
|
||
同时也补上了一版“申请报修演示页”，用于展示设备报修表单、附件上传与提交成功后的详情页流程。
|
||
|
||
## 1. 目前已经包含什么
|
||
|
||
- `Taro + React + TypeScript` 项目骨架
|
||
- 首页设备绑定业务示例页面
|
||
- 睡眠报告演示页面
|
||
- 申请报修演示页面
|
||
- 小程序 `AppID` 配置
|
||
- `AGENTS.md` 协作规则文件
|
||
- 从开发到发布的中文说明
|
||
|
||
## 2. 项目结构说明
|
||
|
||
```text
|
||
.
|
||
├─ AGENTS.md
|
||
├─ README.md
|
||
├─ config
|
||
├─ package.json
|
||
├─ project.config.json
|
||
├─ tsconfig.json
|
||
└─ src
|
||
├─ app.config.ts
|
||
├─ app.scss
|
||
├─ app.tsx
|
||
├─ components
|
||
│ └─ report
|
||
│ ├─ chart-card.tsx
|
||
│ ├─ chip-group.tsx
|
||
│ ├─ daytime-prediction.tsx
|
||
│ ├─ distribution-card.tsx
|
||
│ ├─ insight-list.tsx
|
||
│ ├─ kv-list.tsx
|
||
│ ├─ metric-grid.tsx
|
||
│ ├─ page-header.tsx
|
||
│ ├─ score-overview.tsx
|
||
│ ├─ section-card.tsx
|
||
│ └─ summary-block.tsx
|
||
└─ pages
|
||
├─ index
|
||
│ ├─ index.config.ts
|
||
│ ├─ index.scss
|
||
│ └─ index.tsx
|
||
└─ report
|
||
├─ index.config.ts
|
||
├─ index.scss
|
||
├─ index.tsx
|
||
├─ mock.ts
|
||
├─ report-utils.ts
|
||
└─ types.ts
|
||
```
|
||
|
||
## 3. 你需要先准备什么
|
||
|
||
开发这个项目前，需要准备：
|
||
|
||
- 一个微信号
|
||
- 一个可登录的电脑
|
||
- 微信开发者工具
|
||
- 一个微信小程序账号
|
||
- Node.js 20 或更高版本
|
||
- npm 或 pnpm
|
||
|
||
微信开发者工具下载地址：
|
||
|
||
- [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)
|
||
|
||
微信公众平台地址：
|
||
|
||
- [微信公众平台](https://mp.weixin.qq.com/)
|
||
|
||
## 4. 小程序 AppID 是什么
|
||
|
||
`AppID` 可以理解为你的小程序项目唯一身份标识。
|
||
|
||
- 真机预览、上传版本、提交审核时，通常都需要真实 `AppID`
|
||
- 使用开发者工具时，也建议直接绑定自己的真实项目
|
||
- 真正要上线时，一定要使用你自己的 `AppID`
|
||
|
||
## 5. 如何申请小程序 AppID
|
||
|
||
1. 打开 [微信公众平台](https://mp.weixin.qq.com/)
|
||
2. 点击“立即注册”
|
||
3. 选择“小程序”
|
||
4. 按提示完成邮箱、主体、管理员等信息填写
|
||
5. 注册成功后，登录小程序后台
|
||
6. 在“设置”或“开发管理”相关页面找到 `AppID`
|
||
|
||
## 6. 如何配置 AppID
|
||
|
||
当前项目中，`AppID` 配置在：
|
||
|
||
- [project.config.json](C:/Users/a/Documents/New%20project%203/project.config.json)
|
||
|
||
当前已经配置为你的真实 `AppID`：
|
||
|
||
```json
|
||
"appid": "wx2e6e4000b0ef29d9"
|
||
```
|
||
|
||
注意：
|
||
|
||
- 这是你的小程序身份标识，请不要随便改成别人的
|
||
- 如果以后换项目主体，再替换为新的 `AppID`
|
||
|
||
## 7. 这个项目为什么要先编译
|
||
|
||
因为你要求使用 `React + TypeScript`，这里采用的是 `Taro`。
|
||
|
||
这意味着：
|
||
|
||
- 你平时编写的是 `src/` 里的 React 代码
|
||
- 然后用命令把 React 代码编译成微信小程序代码
|
||
- 微信开发者工具最终读取的是编译产物目录 `dist/`
|
||
|
||
## 8. 先安装依赖
|
||
|
||
先在项目根目录打开终端，执行：
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
如果你使用 `pnpm`，也可以执行：
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
## 9. 启动微信小程序开发编译
|
||
|
||
安装依赖完成后，执行：
|
||
|
||
```bash
|
||
npm run dev:weapp
|
||
```
|
||
|
||
这个命令会做两件事：
|
||
|
||
- 把 `src/` 里的 React + TypeScript 代码编译成微信小程序代码
|
||
- 持续监听文件变化，你改代码后会自动重新编译
|
||
|
||
首次编译成功后，会生成：
|
||
|
||
- `dist/`
|
||
|
||
## 10. 如何在微信开发者工具里打开项目
|
||
|
||
1. 安装并打开微信开发者工具
|
||
2. 选择“导入项目”
|
||
3. 项目目录选择当前文件夹：
|
||
`C:\Users\a\Documents\New project 3`
|
||
4. `AppID` 使用：
|
||
`wx2e6e4000b0ef29d9`
|
||
5. 导入项目
|
||
6. 如果开发者工具提示编译目录相关问题，确认你已经先运行过：
|
||
`npm run dev:weapp`
|
||
|
||
如果你要重点查看新增的睡眠报告页：
|
||
|
||
- 先进入首页
|
||
- 点击底部“报告”
|
||
- 或点击首页里的“查看睡眠报告”
|
||
|
||
## 11. 项目里的几个核心文件
|
||
|
||
- [package.json](C:/Users/a/Documents/New%20project%203/package.json)
|
||
项目依赖和命令入口
|
||
- [config/index.ts](C:/Users/a/Documents/New%20project%203/config/index.ts)
|
||
Taro 主构建配置
|
||
- [src/app.config.ts](C:/Users/a/Documents/New%20project%203/src/app.config.ts)
|
||
小程序页面注册和窗口配置
|
||
- [src/app.tsx](C:/Users/a/Documents/New%20project%203/src/app.tsx)
|
||
React 应用入口
|
||
- [src/pages/index/index.tsx](C:/Users/a/Documents/New%20project%203/src/pages/index/index.tsx)
|
||
首页 React 页面
|
||
- [src/pages/index/index.config.ts](C:/Users/a/Documents/New%20project%203/src/pages/index/index.config.ts)
|
||
首页配置
|
||
- [src/pages/index/index.scss](C:/Users/a/Documents/New%20project%203/src/pages/index/index.scss)
|
||
首页样式
|
||
|
||
## 12. 当前首页做了什么
|
||
|
||
现在首页已经不是默认演示页，而是一个“设备绑定首页（无设备状态）”业务页，包含：
|
||
|
||
- 顶部登录入口
|
||
- 已关联设备数量展示
|
||
- 扫码添加设备按钮
|
||
- 蓝牙搜索附近设备按钮
|
||
- 绑定状态展示区
|
||
- 绑定前提示卡片
|
||
- 底部导航视觉样式
|
||
|
||
当前首页已经接入了部分小程序能力：
|
||
|
||
- 扫码按钮会调用微信小程序扫码能力
|
||
- 蓝牙按钮会先检查定位权限，再尝试打开蓝牙搜索
|
||
- 如果开发环境中暂时搜不到真实设备，页面会用前端占位设备演示完整绑定流程
|
||
|
||
这些内容当前仍然属于前端演示和占位实现，方便你后续继续接：
|
||
|
||
- 登录页
|
||
- 扫码解析接口
|
||
- 真实蓝牙设备筛选与配对
|
||
- 设备列表
|
||
- 报告、消息、我的等页面
|
||
|
||
## 12.1 当前报告页做了什么
|
||
|
||
现在项目里已经新增一个独立的“睡眠报告页”，主要包含：
|
||
|
||
- 首页底部“报告”入口跳转
|
||
- 首页主体里的“查看睡眠报告”快捷入口
|
||
- `日报 / 周报 / 月报` 三种时间维度切换
|
||
- 日期、房间、设备三个筛选条件
|
||
- 睡眠评分总览
|
||
- 睡眠趋势图和睡眠分数趋势图
|
||
- 9 项核心指标卡片
|
||
- AI 睡眠分析和改善建议
|
||
- 异常统计、HRV、心率散点图、呼吸波形图
|
||
- 低氧统计、打鼾监测、异常事件散点图
|
||
- 睡眠结构、自主神经分析、日间状态预测
|
||
|
||
说明：
|
||
|
||
- 当前报告页使用本地 mock 数据驱动
|
||
- 图表是轻量前端演示实现，没有引入大型图表依赖
|
||
- 各板块尽量拆成了可复用组件，便于你继续改
|
||
- 分享功能当前还是前端占位提示，后续可再接真实能力
|
||
|
||
## 12.2 当前报修页做了什么
|
||
|
||
现在项目里已经把原来的“设备报修”占位页补成了一版可交互的“申请报修页”，主要包含：
|
||
|
||
- 使用小程序原生导航栏显示“申请报修”
|
||
- `体征监测设备 / AI摄像头` 两种设备类型切换
|
||
- 已绑定设备 ID 选择与设备参数自动带出
|
||
- 60 字以内的问题描述输入与实时字数统计
|
||
- 调用小程序 `chooseMedia` 选择图片或视频附件
|
||
- 图片最多 9 张、视频最多 1 个的前端限制
|
||
- 联系人和手机号填写
|
||
- 提交前必填校验与手机号格式校验
|
||
- mock 提交成功后跳转到“报修详情”占位页
|
||
|
||
说明：
|
||
|
||
- 当前报修页使用本地 mock 数据驱动
|
||
- 附件当前只做本地选择、预览和删除，不上传到真实服务器
|
||
- 历史记录按钮当前还是前端提示占位，后续可再接真实列表页
|
||
|
||
## 13. 你接下来最常做的开发动作
|
||
|
||
### 改公共主题色
|
||
|
||
编辑：
|
||
|
||
- [src/styles/theme.scss](C:/Users/a/Documents/New%20project%203/src/styles/theme.scss)
|
||
|
||
### 改通用组件
|
||
|
||
编辑：
|
||
|
||
- [src/components](C:/Users/a/Documents/New%20project%203/src/components)
|
||
|
||
### 改页面文案和逻辑
|
||
|
||
编辑：
|
||
|
||
- [src/pages/index/index.tsx](C:/Users/a/Documents/New%20project%203/src/pages/index/index.tsx)
|
||
|
||
### 改报告页
|
||
|
||
编辑：
|
||
|
||
- [src/pages/report/index.tsx](C:/Users/a/Documents/New%20project%203/src/pages/report/index.tsx)
|
||
|
||
### 改报告页 mock 数据
|
||
|
||
编辑：
|
||
|
||
- [src/pages/report/mock.ts](C:/Users/a/Documents/New%20project%203/src/pages/report/mock.ts)
|
||
|
||
### 改报告页组件
|
||
|
||
编辑：
|
||
|
||
- `src/components/report/` 目录下的组件文件
|
||
|
||
### 改报修页
|
||
|
||
编辑：
|
||
|
||
- [src/pages/repair/index.tsx](C:/Users/a/Documents/New%20project%203/src/pages/repair/index.tsx)
|
||
- [src/pages/repair-detail/index.tsx](C:/Users/a/Documents/New%20project%203/src/pages/repair-detail/index.tsx)
|
||
|
||
### 改全局样式
|
||
|
||
编辑：
|
||
|
||
- [src/app.scss](C:/Users/a/Documents/New%20project%203/src/app.scss)
|
||
|
||
### 新增页面
|
||
|
||
你以后可以在 `src/pages/` 下新增页面目录，比如：
|
||
|
||
```text
|
||
src
|
||
└─ pages
|
||
└─ profile
|
||
├─ index.config.ts
|
||
├─ index.scss
|
||
└─ index.tsx
|
||
```
|
||
|
||
然后记得在 [src/app.config.ts](C:/Users/a/Documents/New%20project%203/src/app.config.ts) 里注册页面路径。
|
||
|
||
## 14. 本地预览与真机调试
|
||
|
||
### 本地预览
|
||
|
||
- 保持 `npm run dev:weapp` 在运行
|
||
- 在微信开发者工具里查看编译后的模拟器效果
|
||
- 扫码和蓝牙相关能力更推荐使用真机调试，因为开发者工具里不一定能完整模拟真实权限和设备搜索环境
|
||
|
||
如果你在改报告页，推荐同步检查：
|
||
|
||
- 报表维度切换后数据有没有变化
|
||
- 日期、房间、设备切换后内容有没有同步
|
||
- 点击图表节点后提示值有没有更新
|
||
|
||
### 真机预览
|
||
|
||
1. 确保已填写真实 `AppID`
|
||
2. 点击开发者工具中的“预览”
|
||
3. 使用管理员或绑定开发者微信扫码
|
||
4. 在手机里查看效果
|
||
5. 如果要测试蓝牙绑定，请同时确认手机蓝牙和定位权限已经打开
|
||
|
||
## 15. 上传、提交审核和发布
|
||
|
||
当你开发完成后，一般流程如下：
|
||
|
||
1. 先执行生产编译：
|
||
|
||
```bash
|
||
npm run build:weapp
|
||
```
|
||
|
||
2. 在微信开发者工具中点击“上传”
|
||
3. 填写版本号，例如 `0.1.0`
|
||
4. 填写版本备注，例如“初版首页完成”
|
||
5. 登录微信公众平台
|
||
6. 在“版本管理”中找到刚上传的开发版本
|
||
7. 提交审核
|
||
8. 审核通过后，点击发布
|
||
|
||
## 16. 常见问题
|
||
|
||
### 1. `npm install` 失败怎么办
|
||
|
||
先确认：
|
||
|
||
- 电脑已安装 Node.js
|
||
- 网络可以访问 npm
|
||
- 终端运行目录是：
|
||
`C:\Users\a\Documents\New project 3`
|
||
|
||
### 2. 为什么微信开发者工具里看不到页面
|
||
|
||
常见原因有：
|
||
|
||
- 还没有先运行 `npm run dev:weapp`
|
||
- `dist/` 还没生成
|
||
- 编译报错导致输出失败
|
||
- 页面没有在 `src/app.config.ts` 里注册
|
||
|
||
### 3. 为什么上传不了
|
||
|
||
常见原因有：
|
||
|
||
- 当前微信号不是该小程序项目成员
|
||
- 小程序主体信息未完成
|
||
- 类目、服务内容或合规信息未补全
|
||
- 代码中仍有编译错误或配置问题
|
||
|
||
### 4. 为什么接口请求失败
|
||
|
||
如果以后你接后端接口，微信小程序通常要求：
|
||
|
||
- 配置合法域名
|
||
- HTTPS
|
||
- 后台服务正常可访问
|
||
|
||
### 5. 如何验证报告页里的纯逻辑
|
||
|
||
当前项目新增了一个最小测试命令，用来验证报告页里的纯逻辑函数，比如：
|
||
|
||
- 睡眠评分等级映射
|
||
- 状态颜色映射
|
||
- mock 数据选择逻辑
|
||
|
||
执行：
|
||
|
||
```bash
|
||
npm run test:report
|
||
```
|
||
|
||
如果你要验证报修页里的表单和附件规则纯逻辑，可以执行：
|
||
|
||
```bash
|
||
npm run test:repair
|
||
```
|
||
|
||
## 17. 建议你下一步怎么做
|
||
|
||
如果你是零基础，推荐按这个顺序继续：
|
||
|
||
1. 先跑通 `npm install`
|
||
2. 再跑通 `npm run dev:weapp`
|
||
3. 看懂首页 `index.tsx` 怎么写
|
||
4. 再加第二个页面
|
||
5. 再学页面跳转
|
||
6. 最后接接口和发布
|
||
|
||
## 18. 后续我可以继续帮你做什么
|
||
|
||
接下来你可以继续让我直接帮你：
|
||
|
||
- 改造成你真正想做的小程序业务
|
||
- 新增页面和底部导航
|
||
- 对接后端接口
|
||
- 加登录、表单、列表、详情页
|
||
- 配置发布前需要的内容
|
||
|
||
如果你愿意，我们下一步就可以直接开始做你的正式业务页面。
|