docs: README 重写为完整仓库导览(结构 / 公式 / 三套食谱差异 / 改食谱方法 / Git 教学 / 时间线)
This commit is contained in:
@@ -1,36 +1,241 @@
|
|||||||
# bmi-tdee-calculator
|
# bmi-tdee-calculator
|
||||||
|
|
||||||
BMI 计算与每日热量需求(BMR/TDEE)计算器
|
BMI 计算与每日热量需求(BMR / TDEE)计算器 —— 网页版(千禧年闪亮风)+ 命令行版 + React 组件源码。
|
||||||
|
|
||||||
## 文件说明
|
> 一句话:算出你一天该吃多少千卡,再给你三套「减重 / 维持 / 增重」可选可替换的一日食谱。
|
||||||
|
|
||||||
| 文件 | 说明 |
|
---
|
||||||
| --- | --- |
|
|
||||||
| `index.html` | 网页版「每日热量需求与膳食计算器」,直接打开即可使用(React + Tailwind,免构建) |
|
|
||||||
| `CalorieCalculator.jsx` | 网页所用的 React 组件源码,需要接入打包项目时可直接引用 |
|
|
||||||
| `bmi_calculator.py` | 命令行版 BMI 计算器 |
|
|
||||||
|
|
||||||
> 说明:原先的 `tdee_calculator.py` 其实是一段 React 代码(扩展名写错了),
|
## 一、目录结构(4 个文件)
|
||||||
> 现已整理为 `CalorieCalculator.jsx`,并做成了可直接打开的 `index.html`。
|
|
||||||
|
|
||||||
## 网页版功能
|
| 文件 | 大小 | 作用 | 打开方式 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| `index.html` | 约 38 KB | **主程序**。单文件网页,浏览器直接打开就能用 | 双击,或部署到 Pages |
|
||||||
|
| `CalorieCalculator.jsx` | 约 24 KB | React 组件源码(想接进 React 项目时引用) | 需要构建工具 |
|
||||||
|
| `bmi_calculator.py` | 约 1.3 KB | 命令行版 BMI 计算器(最早的原型) | `python3 bmi_calculator.py` |
|
||||||
|
| `README.md` | 本文件 | 说明书 | 直接看 |
|
||||||
|
|
||||||
- 输入性别 / 年龄 / 身高 / 体重 / 每日步数
|
> 说明:早期有个 `tdee_calculator.py`,其实是 React 代码误用了 `.py` 后缀,已改名为 `CalorieCalculator.jsx`。
|
||||||
- Mifflin-St Jeor 公式算 BMR,结合步数区间系数得到 TDEE,并给出「维持热量 + 300 千卡」的增重目标
|
> `index.html` 是当前唯一的「正式入口」,另外两个文件是历史版本 / 备用形态,**改功能只需要改 `index.html`**。
|
||||||
- 蛋白质 / 脂肪 / 碳水三大产能营养素目标
|
|
||||||
- 早餐 / 午餐 / 晚餐 / 加餐:每餐可点选替换食材,实时汇总热量与营养素
|
|
||||||
- 膳食纤维、钙、铁、锌、维生素 A / C、水分的摄入量与参考值进度条
|
|
||||||
|
|
||||||
## 使用方式
|
`index.html` 的运行方式(没有构建步骤):
|
||||||
|
|
||||||
直接双击打开 `index.html` 即可(首次加载需联网获取 CDN 上的 React / Tailwind)。
|
```
|
||||||
|
cdnjs:React 18.3.1 UMD ×2 + babel-standalone 7.26.4
|
||||||
|
└─ <style> Y2K 荧光样式(星空 / 跑马灯 / 流星雨 / 卡片)
|
||||||
|
└─ <script type="text/babel"> 逻辑与界面
|
||||||
|
FOODS → 成分表(49 项食材)
|
||||||
|
GOALS → 三种模式(减重 / 维持 / 增重)
|
||||||
|
PLANS → 三套食谱(每餐 = 若干「可替换 slot」)
|
||||||
|
METEORS → 流星参数
|
||||||
|
CalorieCalculator() → 全部界面
|
||||||
|
```
|
||||||
|
|
||||||
## 部署为网站
|
---
|
||||||
|
|
||||||
在仓库「设置 → 页面(Page)」中启用站点,分支选 `main`、目录填根目录 `/`,保存后即可通过 Pages 地址访问。
|
## 二、快速开始
|
||||||
|
|
||||||
## 命令行版
|
### 1. 网页版(推荐)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://gitea.compute-thinking.cn/class07f17/bmi-tdee-calculator.git
|
||||||
|
cd bmi-tdee-calculator
|
||||||
|
# 方案 A:直接双击 index.html(最简单)
|
||||||
|
# 方案 B:起一个本地服务器(更接近线上环境)
|
||||||
|
python3 -m http.server 8000
|
||||||
|
# 然后浏览器打开 http://localhost:8000
|
||||||
|
```
|
||||||
|
|
||||||
|
首次打开需要联网(从 cdnjs 取 React / Babel)。页面已经**内置默认值**,打开即可看到结果。
|
||||||
|
|
||||||
|
### 2. 命令行版
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python3 bmi_calculator.py
|
python3 bmi_calculator.py
|
||||||
|
# 输入身高(cm) 体重(kg) → 输出 BMI 与体型判定
|
||||||
```
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 三、页面怎么用(四步走)
|
||||||
|
|
||||||
|
| 步骤 | 要做什么 | 得到什么 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| 第一步 · 基本信息 | 选性别,填年龄 / 身高 / 体重 | BMI + 体型分类 + 理想体重区间 + BMR |
|
||||||
|
| 第二步 · 活动量 | 按每天步数选一档(5 档) | TDEE(每日总消耗) |
|
||||||
|
| 第三步 · 目标模式 | 选减重 / 维持 / 增重,填目标体重,选节奏 | 每日热量目标、还需增减多少 kg、预计用时、目标 BMI |
|
||||||
|
| 第四步 · 今日食谱 | 每格点一个食材 | 每餐与全天合计、与目标差值、七大营养素进度 |
|
||||||
|
|
||||||
|
页脚有个「差值卡」:全天合计与目标热量相差 ±50 千卡以内会变绿,说明今天配得刚刚好。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 四、计算依据(公式与阈值)
|
||||||
|
|
||||||
|
### BMI
|
||||||
|
|
||||||
|
```
|
||||||
|
BMI = 体重(kg) / 身高(m)²
|
||||||
|
```
|
||||||
|
|
||||||
|
中国成人标准(`bmi_calculator.py` 与网页用同一套阈值):
|
||||||
|
|
||||||
|
| BMI | 分类 |
|
||||||
|
| --- | --- |
|
||||||
|
| < 18.5 | 偏瘦 |
|
||||||
|
| 18.5 ~ 23.9 | 健康 |
|
||||||
|
| 24 ~ 27.9 | 超重 |
|
||||||
|
| ≥ 28 | 肥胖 |
|
||||||
|
|
||||||
|
### 基础代谢 BMR —— Mifflin-St Jeor
|
||||||
|
|
||||||
|
```
|
||||||
|
男:BMR = 10×体重 + 6.25×身高(cm) − 5×年龄 + 5
|
||||||
|
女:BMR = 10×体重 + 6.25×身高(cm) − 5×年龄 − 161
|
||||||
|
```
|
||||||
|
|
||||||
|
### 每日总消耗 TDEE
|
||||||
|
|
||||||
|
```
|
||||||
|
TDEE = BMR × 活动系数
|
||||||
|
```
|
||||||
|
|
||||||
|
| 档位 | 步数 | 系数 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| 几乎不动 / 久坐 | < 4000 | 1.2 |
|
||||||
|
| 轻度活动 | 4000 ~ 8000 | 1.375 |
|
||||||
|
| 中度活动 | 8000 ~ 12000 | 1.55 |
|
||||||
|
| 高度活动 | 12000 ~ 16000 | 1.65 |
|
||||||
|
| 超高度活动 | > 16000 / 体力劳动 | 1.8 |
|
||||||
|
|
||||||
|
### 目标热量
|
||||||
|
|
||||||
|
```
|
||||||
|
1 kg 体重 ≈ 7700 千卡
|
||||||
|
每天增减 = 周速率(kg/周) × 7700 ÷ 7
|
||||||
|
|
||||||
|
减重:目标 = TDEE − 每天增减 下限 女 1200 / 男 1500 千卡
|
||||||
|
维持:目标 = TDEE
|
||||||
|
增重:目标 = TDEE + 每天增减
|
||||||
|
```
|
||||||
|
|
||||||
|
低于下限时页面会按安全下限显示,并弹出橙色警告 —— **长期低于下限是危险的**。
|
||||||
|
|
||||||
|
### 三大营养素目标
|
||||||
|
|
||||||
|
| 模式 | 蛋白质 | 脂肪 | 碳水 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| 减重 | 2.0 g/kg 体重 | 25% 热量 | 剩余全给碳水 |
|
||||||
|
| 维持 | 1.6 g/kg 体重 | 28% 热量 | 剩余全给碳水 |
|
||||||
|
| 增重 | 1.8 g/kg 体重 | 28% 热量 | 剩余全给碳水 |
|
||||||
|
|
||||||
|
### 七大营养素参考值(进度条变绿 = 达到 80% 以上)
|
||||||
|
|
||||||
|
| 项目 | 参考值 |
|
||||||
|
| --- | --- |
|
||||||
|
| 膳食纤维 | 减重 / 增重 30 g,维持 25 g |
|
||||||
|
| 钙 | 1000 mg |
|
||||||
|
| 铁 | 女 20 mg / 男 12 mg |
|
||||||
|
| 锌 | 女 7.5 mg / 男 12.5 mg |
|
||||||
|
| 维生素 A | 女 700 µg / 男 900 µg |
|
||||||
|
| 维生素 C | 100 mg |
|
||||||
|
| 水(食物水分) | 减重 女 2000 / 男 2200,维持 女 1500 / 男 1700,增重 女 1700 / 男 1900 ml |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 五、三套食谱差在哪(不是复制粘贴)
|
||||||
|
|
||||||
|
| | 减重 📉 | 维持 ⚖️ | 增重 📈 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| 默认全天热量 | 约 1400 千卡 | 约 1900 千卡 | 约 3100 千卡 |
|
||||||
|
| 主食 | 燕麦 / 全麦 1 片 / 糙米 / 藜麦 / 玉米 / 红薯 | 全麦 2 片 / 肉包 / 白米饭 200g / 馒头 / 面条 | 燕麦+全脂奶 / 白米饭 300g / 意面 350g |
|
||||||
|
| 蛋白 | 鸡胸 / 龙利鱼 / 豆腐 / 虾仁 / 无糖希腊酸奶 | 番茄炒蛋 / 鸡腿 / 三文鱼 / 全脂酸奶 | 黄油煎蛋 3 个 + 芝士 / 瘦牛肉 / 番茄牛腩 / 三文鱼 |
|
||||||
|
| 独特结构 | 无额外加料格,全部低脂低热量 | **独有「汤」格**(紫菜蛋花汤 / 番茄) | **独有「加料 · 热量」格**(花生酱 / 坚果 / 牛油果 / 芝士) |
|
||||||
|
| 加餐 | 坚果 10g / 蛋白粉 | 全脂酸奶+蜂蜜 / 坚果 30g | 花生酱香蕉三明治 / 全脂奶 300ml |
|
||||||
|
|
||||||
|
结构上的差异是有意做的:**多一格、少一格**,比「换几个食材名字」更能防止三套食谱长得一模一样。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 六、想改食谱?改这三层就够
|
||||||
|
|
||||||
|
```
|
||||||
|
GOALS → 每种模式的「参数」:蛋白 g/kg、脂肪占比、纤维、可选速率、饮水、说明文字
|
||||||
|
PLANS → 每种模式的「菜单」:早餐 / 午餐 / 晚餐 / 加餐,每餐若干 slot,每个 slot 是候选食材 id 数组
|
||||||
|
FOODS → 「食材成分表」:每个 id 的营养数值(k 千卡 / p 蛋白 / c 碳水 / f 脂肪 / b 纤维 / ca 钙 / fe 铁 / zn 锌 / va 维A / vc 维C / w 水分)
|
||||||
|
```
|
||||||
|
|
||||||
|
**加一种新食材**(例:加「鸡蛋白 3 个」):
|
||||||
|
|
||||||
|
1. 在 `FOODS` 里加一行:`eggWhite3:{n:'鸡蛋白 3 个',k:51,p:10.8,c:0.6,f:0.3,b:0,ca:6,fe:0.1,zn:0,va:0,vc:0,w:66},`
|
||||||
|
2. 在 `PLANS` 里找到想放它的 slot,把 `'eggWhite3'` 加进 `options` 数组
|
||||||
|
3. 保存刷新 —— 卡片、每餐合计、全天合计、营养素进度条会自动带上它(代码是遍历 `FOODS` 的字段求和的,不用手改公式)
|
||||||
|
|
||||||
|
**改默认选中项**:把 `options` 数组的第一项换成你想要的那个 id(默认选 `options[0]`)。
|
||||||
|
**改流星**:调 `METEORS` 的 `top/left/w/dur/delay/c`;方向要同时改 CSS 的 `rotate(135deg)` 和 `@keyframes meteor` 里的 `translate3d(-85vw,85vh,0)`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 七、Git / Gitea 常用操作
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone <仓库地址> # 第一次:把仓库拷到本地
|
||||||
|
git status # 看哪些文件改了
|
||||||
|
git diff # 看具体改了哪几行
|
||||||
|
git add index.html # 把改动放进「待提交」
|
||||||
|
git commit -m "feat: 加流星雨特效" # 存成一个提交快照
|
||||||
|
git push # 推回 Gitea
|
||||||
|
|
||||||
|
git log --oneline --graph # 用一行一条的图看历史
|
||||||
|
git pull # 更新本地
|
||||||
|
git revert <提交号> # 撤销某次提交(安全,不删历史)
|
||||||
|
```
|
||||||
|
|
||||||
|
约定俗成的提交前缀(本仓库一直在用):
|
||||||
|
|
||||||
|
| 前缀 | 含义 |
|
||||||
|
| --- | --- |
|
||||||
|
| `feat:` | 新功能 |
|
||||||
|
| `fix:` | 修 bug / 修问题 |
|
||||||
|
| `docs:` | 只改文档 |
|
||||||
|
| `chore:` | 杂事(改名、清理) |
|
||||||
|
|
||||||
|
想稳妥一点时走分支 + 合并请求(PR):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git checkout -b feat/shake # 开一条新分支做实验,main 不受影响
|
||||||
|
# ...改代码、提交...
|
||||||
|
git push -u origin feat/shake # 推上去
|
||||||
|
# 在 Gitea 网页上点「新建合并请求」→ 自己审一遍 diff → 合并
|
||||||
|
```
|
||||||
|
|
||||||
|
**部署为在线网页**:仓库「设置 → 页面(Pages)」启用站点,分支选 `main`、目录填 `/`,保存后即可用 Pages 地址访问 `index.html`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 八、这个仓库的来路(提交时间线)
|
||||||
|
|
||||||
|
| 日期 | 做了什么 |
|
||||||
|
| --- | --- |
|
||||||
|
| 2026-09-22 | 初始提交 → 命令行版 BMI → 按减脂算每日热量(`.py` 文件名) |
|
||||||
|
| 2026-09-24 | 改成增重目标 → 加一日食谱 → 食谱改为可点选替换 → 加入七大营养素 → 做成可打开的网页 → 纠正 `.py` 其实是 React → 补文档 |
|
||||||
|
| 2026-10-08 | 千禧年闪亮风格改版 → 新增减重/维持/增重三模式 + 目标体重 + 分模式食谱 → 三套食谱彻底区分 → 加流星雨特效 |
|
||||||
|
|
||||||
|
15 次提交,1 条分支 `main`,还没有标签 / 发行版。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 九、已知限制
|
||||||
|
|
||||||
|
- **依赖网络**:React 与 Babel 来自 cdnjs,离线打不开(要做离线版就把依赖下载到仓库里)。
|
||||||
|
- **不保存输入**:刷新页面会回到默认值(想保存可加 `localStorage`)。
|
||||||
|
- **食物数据是常见估值**:不同品牌、不同做法差别很大,只当数量级参考。
|
||||||
|
- **公式是通用公式**:不算体脂率、不算肌肉量,个体差异真实存在。
|
||||||
|
- 预览用的 artifact 是仓库文件的快照,**改了仓库不会自动同步**,需要重新生成或部署 Pages。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 十、免责声明
|
||||||
|
|
||||||
|
本仓库是科普与估算工具,结果基于通用公式与常见食物成分值,仅供参考,**不构成医疗或营养建议**。
|
||||||
|
孕产期、慢性疾病、进食障碍等情况请遵医嘱并咨询注册营养师。
|
||||||
|
|||||||
Reference in New Issue
Block a user