405 lines
14 KiB
Markdown
405 lines
14 KiB
Markdown
# H5 → 小程序转换：输入材料准备指南
|
||
|
||
> 本文档规范了每次将 H5 原型页面转换为微信小程序时，应提供的输入材料清单、格式要求和操作步骤。
|
||
> 目标：提高 AI 转换还原度，减少颜色/间距换算错误、交互逻辑遗漏、图标处理失误。
|
||
|
||
---
|
||
|
||
## 一、HTML 文件规范
|
||
|
||
### 问题背景
|
||
|
||
当前 H5 原型是 Tailwind CDN + 内联 SVG + 原生 JS 的单文件结构，存在以下转换障碍：
|
||
|
||
- Tailwind 工具类需逐个手动展开为 WXSS，容易遗漏或换算错误
|
||
- 内联 SVG 在小程序中完全不可用，但混在 HTML 里容易被"直译"
|
||
- JS 交互逻辑和 DOM 操作对小程序没有参考价值，反而干扰判断
|
||
|
||
### 推荐做法
|
||
|
||
1. **提供渲染后的最终 DOM**（而非模板源码）
|
||
- 浏览器中打开页面 → 右键 `<body>` → Copy → Copy outerHTML
|
||
- 原因：Tailwind `tailwind.config` 中自定义颜色/间距在源码中只是类名，无法确定最终计算值
|
||
- 保存为 `docs/h5_ui/rendered/<page-name>.html`
|
||
|
||
2. **去掉所有 `<script>` 标签**
|
||
- JS 交互逻辑应单独用结构化文本描述（见第三节"交互描述规范"）
|
||
- 不要让 AI 从 DOM 操作代码中反推意图
|
||
|
||
3. **内联关键样式**（二选一）
|
||
|
||
**方式 A：手动记录（少量元素时）**
|
||
```
|
||
Chrome DevTools 操作：
|
||
1. 打开 H5 页面
|
||
2. 右键目标元素 → 检查
|
||
3. 在 Styles 面板中，点击 Computed 标签
|
||
4. 勾选 "Show all"
|
||
5. 记录以下关键属性的计算值：
|
||
- width / height / padding / margin / gap
|
||
- font-size / font-weight / line-height / color
|
||
- background / border-radius / box-shadow
|
||
- display / flex-direction / align-items / justify-content
|
||
```
|
||
|
||
**方式 B：脚本批量导出（推荐）**
|
||
在 Chrome Console 中执行以下脚本，批量导出关键元素的计算样式：
|
||
|
||
```javascript
|
||
function exportStyles() {
|
||
const props = [
|
||
'width','height','padding','margin','gap',
|
||
'fontSize','fontWeight','lineHeight','color',
|
||
'background','backgroundColor','borderRadius',
|
||
'boxShadow','display','flexDirection','alignItems',
|
||
'justifyContent','position','opacity'
|
||
];
|
||
const elements = document.querySelectorAll('[class]');
|
||
const result = [];
|
||
elements.forEach((el, i) => {
|
||
const cs = getComputedStyle(el);
|
||
const styles = {};
|
||
props.forEach(p => {
|
||
const v = cs[p];
|
||
if (v && v !== 'none' && v !== 'normal' && v !== '0px' && v !== 'auto') {
|
||
styles[p] = v;
|
||
}
|
||
});
|
||
if (Object.keys(styles).length > 0) {
|
||
result.push({
|
||
tag: el.tagName.toLowerCase(),
|
||
classes: el.className,
|
||
text: el.textContent?.trim().slice(0, 30),
|
||
styles
|
||
});
|
||
}
|
||
});
|
||
console.log(JSON.stringify(result, null, 2));
|
||
}
|
||
exportStyles();
|
||
```
|
||
|
||
将输出追加到 `docs/h5_ui/computed-styles.json`（按页面名分 key 存放）
|
||
|
||
|
||
---
|
||
|
||
## 二、CSS / 样式规范
|
||
|
||
### 当前状况
|
||
|
||
CSS 分两部分：Tailwind 工具类（占 90%）+ 少量自定义 `<style>` 块。无 SCSS/LESS 预处理器。
|
||
|
||
### 设计 Token 文件（做一次，全局复用）
|
||
|
||
将 Tailwind 自定义主题提取为设计 Token，保存为 `docs/h5_ui/design-tokens.json`：
|
||
|
||
```json
|
||
{
|
||
"colors": {
|
||
"primary": "#0052d9",
|
||
"primary-light": "#ecf2fe",
|
||
"success": "#00a870",
|
||
"warning": "#ed7b2f",
|
||
"error": "#e34d59",
|
||
"gray-1": "#f3f3f3",
|
||
"gray-2": "#eeeeee",
|
||
"gray-3": "#e7e7e7",
|
||
"gray-4": "#dcdcdc",
|
||
"gray-5": "#c5c5c5",
|
||
"gray-6": "#a6a6a6",
|
||
"gray-7": "#8b8b8b",
|
||
"gray-8": "#777777",
|
||
"gray-9": "#5e5e5e",
|
||
"gray-10": "#4b4b4b",
|
||
"gray-11": "#393939",
|
||
"gray-12": "#2c2c2c",
|
||
"gray-13": "#242424"
|
||
},
|
||
"spacing": {
|
||
"comment": "Tailwind 默认 1 unit = 4px = 8rpx（基于 750rpx 设计稿）",
|
||
"base": 8,
|
||
"unit": "rpx"
|
||
},
|
||
"borderRadius": {
|
||
"sm": "8rpx",
|
||
"md": "16rpx",
|
||
"lg": "24rpx",
|
||
"xl": "32rpx",
|
||
"2xl": "32rpx",
|
||
"3xl": "48rpx"
|
||
},
|
||
"fontSize": {
|
||
"xs": "24rpx",
|
||
"sm": "28rpx",
|
||
"base": "32rpx",
|
||
"lg": "36rpx",
|
||
"xl": "40rpx",
|
||
"2xl": "48rpx"
|
||
},
|
||
"shadows": {
|
||
"lg": "0 8rpx 32rpx rgba(0,0,0,0.06)",
|
||
"xl": "0 16rpx 48rpx rgba(0,0,0,0.08)"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 自定义动画标注
|
||
|
||
对 `<style>` 块中的自定义 CSS，需标注处理方式：
|
||
|
||
| CSS 特性 | 小程序支持 | 处理方式 |
|
||
|----------|-----------|----------|
|
||
| `@keyframes` + `animation` | ✅ 支持 | 直接迁移 |
|
||
| `transition` | ✅ 支持 | 直接迁移 |
|
||
| `linear-gradient` | ✅ 支持 | 直接迁移 |
|
||
| `backdrop-filter: blur()` | ❌ 不支持 | 改为半透明背景色 `rgba()` |
|
||
| `blur-xl`（Tailwind） | ❌ 不支持 | 去掉或改为纯色 |
|
||
| CSS 变量 `var()` | ✅ 支持 | 直接迁移（TDesign 大量使用） |
|
||
|
||
### 不需要做的事
|
||
|
||
- 不需要展开 SCSS/LESS（当前未使用预处理器）
|
||
- 不需要合并 CSS 文件（小程序每个页面有独立 `.wxss`）
|
||
|
||
---
|
||
|
||
## 三、交互描述规范
|
||
|
||
### 为什么需要单独描述
|
||
|
||
H5 原型中的 JS 交互（`addEventListener`、`classList.toggle`、`innerHTML` 等）在小程序中完全不可用。AI 需要从"用户意图"层面理解交互，而非从"DOM 操作"层面翻译。
|
||
|
||
### 格式模板
|
||
|
||
每个页面提供一份交互说明，保存为 `docs/h5_ui/interactions/<page-name>.md`：
|
||
|
||
```markdown
|
||
# 页面名：<page-name>
|
||
|
||
## 状态变量
|
||
| 变量名 | 类型 | 初始值 | 说明 |
|
||
|--------|------|--------|------|
|
||
| agreed | boolean | false | 协议勾选状态 |
|
||
| loading | boolean | false | 登录请求中 |
|
||
|
||
## 用户操作 → 响应
|
||
| 操作 | 触发条件 | 响应行为 | 目标状态 |
|
||
|------|----------|----------|----------|
|
||
| 点击协议勾选框 | 无 | 切换 agreed | agreed=!agreed |
|
||
| 点击"使用微信登录" | agreed=true | 调用登录API | loading=true → 跳转 |
|
||
| 点击"使用微信登录" | agreed=false | 无响应（按钮禁用态） | 不变 |
|
||
| 登录成功 | API返回 | 按用户状态跳转 | 见流程7.1 |
|
||
| 登录失败 | API报错 | Toast提示错误 | loading=false |
|
||
|
||
## 页面状态枚举
|
||
| 状态名 | 视觉表现 | 触发条件 |
|
||
|--------|----------|----------|
|
||
| 默认态 | 按钮灰色禁用 | agreed=false |
|
||
| 可登录态 | 按钮蓝色渐变+阴影 | agreed=true |
|
||
| 加载中 | 按钮显示loading | loading=true |
|
||
```
|
||
|
||
### 必须覆盖的状态（每个页面都要考虑）
|
||
|
||
| 状态 | 说明 | 视觉表现参考 |
|
||
|------|------|-------------|
|
||
| 正常态（有数据） | 页面主要功能正常展示 | 默认截图 |
|
||
| 空数据态 | 列表/卡片区域无数据 | 居中文案 `暂无数据` / `暂无任务` |
|
||
| 加载中态 | 数据请求中 | 区域文案 `加载中...` |
|
||
| 错误态 | 接口请求失败 | 文案 `加载失败，请点击重试` + 重试按钮 |
|
||
| 登录态差异 | 如果页面因登录状态有不同表现 | 按实际描述 |
|
||
|
||
---
|
||
|
||
## 四、视觉截图规范
|
||
|
||
### 截图是校验还原度的唯一视觉参考
|
||
|
||
### 分辨率
|
||
|
||
- 使用 iPhone 6/7/8 尺寸（375×667）
|
||
- 这是小程序 750rpx 设计基准的 1:1 对应
|
||
- Chrome DevTools → Toggle device toolbar → 选择 iPhone 6/7/8
|
||
|
||
### 每个页面至少截以下状态
|
||
|
||
| 状态 | 文件命名示例 | 说明 |
|
||
|------|-------------|------|
|
||
| 默认/正常态 | `login--default.png` | 有数据的主要展示 |
|
||
| 关键交互态 | `login--agreed.png` | 勾选协议后按钮变化 |
|
||
| 空数据态 | `task-list--empty.png` | 如果适用 |
|
||
| 弹窗/浮层 | `task-list--longpress-menu.png` | 弹窗打开状态 |
|
||
| 筛选展开 | `board-customer--filter-open.png` | 下拉筛选展开 |
|
||
|
||
### 命名规范
|
||
|
||
```
|
||
<page-name>--<state>.png
|
||
```
|
||
|
||
- 页面名用小写连字符：`board-customer`、`task-detail`、`my-profile`
|
||
- 状态名用小写连字符：`default`、`empty`、`loading`、`error`、`filter-open`、`longpress-menu`
|
||
|
||
### 存放目录
|
||
|
||
```
|
||
docs/h5_ui/screenshots/
|
||
```
|
||
|
||
### 长页面处理
|
||
|
||
如果页面有滚动内容，提供长截图：
|
||
- Chrome DevTools → Ctrl+Shift+P → 输入 "Capture full size screenshot"
|
||
|
||
### 不需要的截图
|
||
|
||
- 不需要暗色模式截图（PRD 无暗色模式需求）
|
||
- 不需要多设备截图（仅面向手机竖屏）
|
||
|
||
|
||
---
|
||
|
||
## 五、资源文件规范
|
||
|
||
### 当前状况
|
||
|
||
`docs/h5_ui/img/` 只有 2 张图片，大部分图标是内联 SVG。
|
||
|
||
### 图标处理优先级
|
||
|
||
1. **优先使用 TDesign 内置图标**（`<t-icon name="xxx">`），不需要提供文件
|
||
2. TDesign 没有的图标，提取为独立 SVG 文件
|
||
3. 复杂图形/Logo 使用 PNG/JPG 图片
|
||
|
||
### 图标文件规范
|
||
|
||
| 项目 | 规范 |
|
||
|------|------|
|
||
| 格式 | SVG（图标）、PNG（带透明图片）、JPG（照片类） |
|
||
| 命名 | `<category>-<name>.svg`，如 `icon-billiard.svg`、`icon-wechat.svg` |
|
||
| 目录 | `apps/miniprogram/miniprogram/assets/icons/`（图标） |
|
||
| | `apps/miniprogram/miniprogram/assets/images/`（图片） |
|
||
| 尺寸 | 图片提供 2x 版本（750px 宽设计稿对应的实际像素） |
|
||
|
||
### 图标映射表（每个页面提供）
|
||
|
||
```markdown
|
||
| H5 中的图标描述 | 处理方式 | 小程序引用 |
|
||
|----------------|----------|-----------|
|
||
| Logo 台球图标 | 自定义SVG | /assets/icons/icon-billiard.svg |
|
||
| 任务管理图标 | TDesign | <t-icon name="task" /> |
|
||
| 数据看板图标 | TDesign | <t-icon name="chart-bar" /> |
|
||
| 智能助手图标 | TDesign | <t-icon name="chat" /> |
|
||
| 微信图标 | 自定义SVG | /assets/icons/icon-wechat.svg |
|
||
| 返回箭头 | TDesign | <t-icon name="chevron-left" /> |
|
||
| 右箭头 | TDesign | <t-icon name="chevron-right" /> |
|
||
```
|
||
|
||
保存为 `docs/h5_ui/icon-mapping.md`，或在每个页面的交互说明中附带。
|
||
|
||
---
|
||
|
||
## 六、目录结构总览
|
||
|
||
准备完成后，`docs/h5_ui/` 目录结构应如下：
|
||
|
||
```
|
||
docs/h5_ui/
|
||
├── css/ # 原有：自定义 CSS 文件
|
||
├── img/ # 原有：图片资源
|
||
├── js/ # 原有：JS 文件
|
||
├── pages/ # 原有：H5 原型页面
|
||
│ ├── login.html
|
||
│ ├── board-customer.html
|
||
│ └── ...
|
||
├── rendered/ # 新增：渲染后的 DOM（可选）
|
||
│ ├── login.html
|
||
│ └── ...
|
||
├── computed-styles.json # 新增：计算样式（可选，按页面名分 key）
|
||
├── screenshots/ # 新增：页面截图（必须）
|
||
│ ├── login--default.png
|
||
│ ├── login--agreed.png
|
||
│ ├── task-list--default.png
|
||
│ ├── task-list--empty.png
|
||
│ └── ...
|
||
├── interactions/ # 新增：交互说明（必须）
|
||
│ ├── login.md
|
||
│ ├── task-list.md
|
||
│ └── ...
|
||
├── design-tokens.json # 新增：设计 Token（必须，做一次）
|
||
├── icon-mapping.md # 新增：图标映射表（必须，做一次）
|
||
└── index.html # 原有：入口页
|
||
```
|
||
|
||
---
|
||
|
||
## 七、操作步骤——"怎么喂料"
|
||
|
||
### 一次性准备（全局）
|
||
|
||
1. 创建 `docs/h5_ui/design-tokens.json`（从 `tailwind.config` 提取，见第二节）
|
||
2. 创建 `docs/h5_ui/icon-mapping.md`（全局图标映射表，见第五节）
|
||
3. 创建目录：`screenshots/`、`interactions/`、`rendered/`（可选）
|
||
|
||
### 每个页面的准备流程
|
||
|
||
#### Step 1：准备 HTML + 计算样式
|
||
1. 在 Chrome 中打开 `docs/h5_ui/pages/<page>.html`
|
||
2. 切换到 iPhone 6/7/8 设备模式（375×667）
|
||
3. 在 Console 中运行 `exportStyles()` 脚本（见第一节）
|
||
4. 将输出追加到 `docs/h5_ui/computed-styles.json`（以页面名为 key）
|
||
5. （可选）复制渲染后 DOM，保存为 `docs/h5_ui/rendered/<page>.html`
|
||
|
||
#### Step 2：截图
|
||
1. Chrome DevTools → Ctrl+Shift+P → "Capture screenshot"
|
||
2. 每个状态截一张，命名为 `<page>--<state>.png`
|
||
3. 放入 `docs/h5_ui/screenshots/`
|
||
|
||
#### Step 3：写交互说明
|
||
1. 按第三节格式模板，写出状态变量、操作→响应表、状态枚举
|
||
2. 保存为 `docs/h5_ui/interactions/<page>.md`
|
||
|
||
#### Step 4：标注图标/图片
|
||
1. 检查页面中的所有图标和图片
|
||
2. 在图标映射表中补充新图标的处理方式
|
||
3. 自定义资源放入小程序 `assets/` 对应目录
|
||
|
||
#### Step 5：喂给 AI
|
||
在对话中提供以下信息：
|
||
|
||
```
|
||
请将 <page-name> 页面转换为小程序。
|
||
- HTML：docs/h5_ui/pages/<page>.html
|
||
- 计算样式：docs/h5_ui/computed-styles.json（页面 key: <page>）
|
||
- 截图：docs/h5_ui/screenshots/<page>__default.png（拖入对话）
|
||
- 交互说明：docs/h5_ui/interactions/<page>.md
|
||
- PRD 参考：P<N> spec <章节号>
|
||
- 图标映射：全部使用 TDesign / 见 icon-mapping.md
|
||
```
|
||
|
||
---
|
||
|
||
## 八、最低限度清单
|
||
|
||
如果时间有限，以下三项是"必须提供"的底线：
|
||
|
||
| 优先级 | 材料 | 作用 | 频率 |
|
||
|--------|------|------|------|
|
||
| P0 | 截图（默认态，375px 宽） | 校验还原度的唯一视觉参考 | 每页 |
|
||
| P0 | 交互说明（状态变量 + 操作响应表） | 避免逻辑错误 | 每页 |
|
||
| P0 | 设计 Token JSON | 避免颜色/间距换算错误 | 一次 |
|
||
| P1 | 计算样式 JSON | 显著提高还原度 | 每页（可选） |
|
||
| P1 | 图标映射表 | 避免图标处理失误 | 一次 + 增量 |
|
||
| P2 | 渲染后 DOM | 复杂页面时有帮助 | 按需 |
|
||
|
||
---
|
||
|
||
## 附录：相关文档
|
||
|
||
- [H5 → 小程序转换避坑指南](./h5-to-miniprogram-pitfalls.md) — 标签映射、样式差异、事件系统、高频踩坑清单
|
||
- [小程序认证系统联调指南](./auth-integration-guide.md) — 前后端联调测试流程
|
||
- [产品需求文档](./prd.md) — 完整 PRD（页面级需求）
|
||
- PRD Specs — `docs/prd/specs/P1~P11`
|
||
- H5 原型 — `docs/h5_ui/pages/`
|