From ab230d6cfb74a06be1b52f5f751127a315d952f7 Mon Sep 17 00:00:00 2001 From: cchis Date: Mon, 29 Jun 2026 15:50:26 +0800 Subject: [PATCH] =?UTF-8?q?=E5=AD=98=E6=A1=A3:=E9=A6=96=E9=A1=B5=20tab/?= =?UTF-8?q?=E9=BB=91=E8=BE=B9=E9=98=B6=E6=AE=B5=E6=94=B9=E5=8A=A8=20+=20?= =?UTF-8?q?=E8=87=AA=E9=80=82=E5=BA=94=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - home-page: 底部 tab 贴屏幕底、全新系列角标归位、画布铺满宽修左侧黑边 (首页仍是过程态,后续按「540容器 + 流式」最简方案重构) - AGENTS.md: 自适应规范(给 codex / 同事,三规则 + 三不要 + 验证法) - README.md(外层): 项目总览 + 启动 + 当前进度 Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 70 ++++++++++++++++++++++++++++++ vtubermini/AGENTS.md | 43 ++++++++++++++++++ vtubermini/src/pages/home-page.tsx | 18 +------- 3 files changed, 115 insertions(+), 16 deletions(-) create mode 100644 README.md create mode 100644 vtubermini/AGENTS.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..0344b1e --- /dev/null +++ b/README.md @@ -0,0 +1,70 @@ +# VTuber Mini + +540px 宽的移动端 H5 —— 单 VTuber 粉丝养成 app(养宠物、抽卡、纪念日提醒、商城兑换)。一套模板服务一个 VTuber,可换皮。 + +## 技术栈 + +React 19 + Vite 8 + Tailwind CSS 4 + TypeScript;Capacitor 8 打包 Android。包管理用 **pnpm**。 + +## 目录结构 + +``` +. +├── vtubermini/ # 前端主工程(代码都在这) +│ ├── src/ # 源码(pages / components / lib / services) +│ ├── docs/ # 工程文档(Android 构建、接口契约等) +│ ├── AGENTS.md # ⭐ 自适应布局规范(给 codex/AI 调页面用,改 UI 前必读) +│ ├── android/ # Capacitor Android 工程 +│ └── package.json +├── design/ # 设计稿 +├── assets/ # 素材 +├── Product-Spec.md # 产品规格 +├── DEV-PLAN.md # 开发计划 +├── *-Breakdown.md / *.mmd # 需求拆解 / UX 流程图 +└── .codex-logs/ # codex 运行日志 +``` + +## 快速启动(本地预览) + +```bash +cd vtubermini +pnpm install # 首次需要 +pnpm dev # 启动,浏览器打开终端显示的 http://localhost:5173/ +``` + +- 打开后先是登录页 → 点 **「进入花园」** 进首页。 +- 看不同手机宽度:Chrome 按 `F12` → 设备工具栏 → 选 360 / 390 / 414。 +- 桌面不开设备模拟时,页面是一个 **540 宽的竖条居中**显示(已去掉手机外壳)。 + +## 构建 / Android 打包 + +```bash +cd vtubermini +pnpm build # 类型检查 + 产出 dist/ +pnpm cap:sync # 把 web 资源同步到 Android 工程 +``` + +Android 打 APK 需要 JDK 17 + Android Studio + `ANDROID_HOME`,详细步骤见 `vtubermini/docs/android-build.md`。 + +## 当前进度(自适应改造) + +正在把全站从「固定比例画布 + 百分比绝对定位」改造为「540 宽标准移动布局」,解决**手机宽度变化导致布局错乱**的问题。 + +- ✅ **首页** `src/pages/home-page.tsx`:540 容器居中、去手机外壳、底部 tab 贴屏幕底 + - ⚠️ 首页 tab 样式仍在和需求对齐中(早期方案绕复杂了,正收敛到最简逻辑) +- ✅ **自适应规范**已沉淀到 `vtubermini/AGENTS.md`(三条规则 + 两个亲测的坑 + 验证方法)——后续同事用 codex 调其他页照此执行,保证全站做法统一 +- ⬜ **其他页面**(anniversary / shop / my / album / pet …)待逐页按规范调整 + +核心规则(详见 `vtubermini/AGENTS.md`): +1. 容器宽 `min(100vw, 540px)` 居中; +2. **不用百分比绝对定位**(宽度一变就乱)——用 flex / 文档流 + 贴边; +3. 导航 tab 贴屏幕底。 + +## 关键文档 + +| 文档 | 用途 | +|---|---| +| `vtubermini/AGENTS.md` | 自适应布局规范(改任何页面 UI 前必读) | +| `vtubermini/docs/android-build.md` | Android 构建步骤 | +| `vtubermini/docs/api-contract.md` | 前后端接口契约 | +| `Product-Spec.md` / `DEV-PLAN.md` | 产品规格 / 开发计划 | diff --git a/vtubermini/AGENTS.md b/vtubermini/AGENTS.md new file mode 100644 index 0000000..24afb56 --- /dev/null +++ b/vtubermini/AGENTS.md @@ -0,0 +1,43 @@ +# AGENTS.md — VTuber Mini + +> 给 codex / AI agent:在本项目调整页面**自适应布局**时,遵循本文件。 +> 目标:任何同事用 codex 微调任意页面,做法都统一、不再各搞一套。 + +## 这是什么项目 +540px 宽的移动端 H5(单 VTuber 粉丝养成 app)。React 19 + Vite + Tailwind 4 + Capacitor(Android)。 +在桌面浏览器里看 = 一个 540 宽的竖条居中显示。 + +## 自适应三条规则(就这么简单,别搞复杂) +1. **容器**:页面根容器宽 = `min(100vw, 540px)`,水平居中,高 = `100dvh`。窄屏(<540)自动占满 100%。 + - 全局 `.device-stage` 已是这个规则,页面挂在它里面即可。 +2. **不要用百分比绝对定位**。元素位置别用 `style={{ left: 'X%', top: 'Y%' }}` 这种绝对定位——手机宽度一变就错乱(这是本项目布局乱的根因)。 + - 用正常 flex / 文档流;或贴边的 `absolute`(`bottom-0` / `top-0` / `inset-x-0`)。 +3. **导航 / tab 贴屏幕底**:`absolute inset-x-0 bottom-0` + 内部 flex 等分。背景美术用 `object-cover` 铺满容器。 + +## 两个必避的坑(亲测,栽过) +1. **Tailwind 4 会静默丢弃自定义 CSS 类里的 `cqw / cqh / container-type`**(Lightning CSS 把整条规则删掉,不报错)。 + → 关键尺寸**别写自定义 CSS 类,直接写 inline style,用 `vw/vh`**。例: + ```tsx +
+ ``` +2. **`npm run build` 通过 ≠ 生效**。自定义 CSS 可能编译过但运行时根本没渲染(本项目曾让画布 `height` 塌成 0 却一直没发现,误以为成功)。 + → 改完**必须实测元素几何**,不能只看编译过。 + +## 改完怎么验证(别跳过) +```bash +npm run build # 1) 先编译过 +CI=true npm run dev # 2) 跑起来(CI=true 避免后台进程因 stdin 退出) +``` +然后在浏览器实测关键元素的 `getBoundingClientRect()`,确认: +- 容器宽 = `min(屏宽, 540)`、`height ≠ 0`; +- tab bar 的 `bottom` ≈ 屏幕高(真的贴底)、宽 = 屏幕宽; +- 换几个宽度(360 / 400 / 540)布局都不乱。 + +> 提示:首页有登录 gate(`!isLoggedIn` → LoginPage,见 `App.tsx`),临时验证可把 `isLoggedIn` 初值改 `true`,**验证后还原**。 + +## 参考实现 +- `src/pages/home-page.tsx`:首页已按上面三条改过(540 容器、去手机外壳、底部 tab 贴屏幕底)——可作为其他页的样板,但**以本文件的规则为准,不要照搬其中的临时痕迹**。 +- 其他页(anniversary / shop / my / album / pet …)尚未逐页核对,按本规则调整即可。 + +## 已废弃 +`docs/adaptive-architecture.md` 是早期的复杂方案(9:16 固定画布 / scale 缩放 / 分层 / cqw),**已废弃、勿参考**,一切以本文件为准。 diff --git a/vtubermini/src/pages/home-page.tsx b/vtubermini/src/pages/home-page.tsx index 8872aac..065befa 100644 --- a/vtubermini/src/pages/home-page.tsx +++ b/vtubermini/src/pages/home-page.tsx @@ -454,7 +454,7 @@ export function HomePage({ return (
-
+
- +
{[{ route: "shop", icon: shopIcon, left: "8.1%" }, { route: "moments", icon: momentsIcon, left: "33.7%" }, { route: "pet", icon: petIcon, left: "56.6%" }, { route: "album", icon: albumIcon, left: "80%" }].map((t) => ())}
) }