154 lines
4.3 KiB
Markdown
154 lines
4.3 KiB
Markdown
# H5→微信小程序迁移文档结构说明
|
||
|
||
## 📚 文档体系
|
||
|
||
### 主规范文档（1个）
|
||
|
||
**`docs/miniprogram-dev/h5-to-mp-bridge-v3.md`** - 主规范 v3.0（合并版）
|
||
|
||
- **第一部分（§1-4）**：执行规程
|
||
- 输入输出契约
|
||
- 项目级强制决策
|
||
- 能力分级（A/B/C 类）
|
||
- Tailwind CSS 行为说明
|
||
|
||
- **第二部分（§5-9）**：技术换算
|
||
- Spacing 换算表
|
||
- 字号与行高换算（含 line-height 关键发现）
|
||
- 颜色映射
|
||
- 布局类映射
|
||
- 装饰类映射
|
||
|
||
- **第三部分（§10-12）**：交互改造
|
||
- HTML→WXML 映射
|
||
- DOM 操作→数据驱动
|
||
- 浏览器 API→小程序 API
|
||
|
||
- **第四部分（§13-14）**：执行流程
|
||
- 10 步标准流程
|
||
- 附录文档索引
|
||
|
||
### 附录文档（5个）
|
||
|
||
位于 `docs/miniprogram-dev/New/`：
|
||
|
||
1. **`h5_to_wechat_miniprogram_migration_bridge_appendix_index_v3.md`** - 附录索引（v3.1）
|
||
2. **`appendix_a_spacing_and_sizing_dictionary_v3.md`** - 附录 A：Spacing 与尺寸字典
|
||
3. **`appendix_b_typography_and_text_dictionary_v3.md`** - 附录 B：字体与文本字典（v3.1）
|
||
4. **`appendix_c_color_dictionary_v3.md`** - 附录 C：颜色字典
|
||
5. **`appendix_d_layout_class_mapping_dictionary_v3.md`** - 附录 D：布局类映射字典
|
||
|
||
---
|
||
|
||
## 🎯 使用指南
|
||
|
||
### 对于 AI
|
||
|
||
**加载顺序**：
|
||
1. 加载主规范 `h5-to-mp-bridge-v3.md`（完整规范）
|
||
2. 加载附录索引 `h5_to_wechat_miniprogram_migration_bridge_appendix_index_v3.md`
|
||
3. 按需加载具体附录（A/B/C/D）
|
||
|
||
**执行流程**：
|
||
1. 按 §13 的 10 步标准流程执行迁移
|
||
2. 查表时参考 §5-9 和附录 A/B/C/D
|
||
3. 交互改造时参考 §10-12
|
||
4. 确保输出符合 §1.2 的要求
|
||
|
||
### 对于开发者
|
||
|
||
**快速上手**：
|
||
1. 先读主规范 §1-4 了解规则和决策
|
||
2. 需要时查阅 §5-12 的换算表和附录
|
||
3. 按 §13 的流程逐步完成迁移
|
||
4. 问题排查时回到对应章节
|
||
|
||
---
|
||
|
||
## 🔑 核心要点
|
||
|
||
### 1. 单位策略
|
||
- **rpx 为主**：布局、容器、间距
|
||
- **px 为辅**：发丝线、阴影、小图标
|
||
- **换算公式**：`rpx = px × 1.8204`
|
||
|
||
### 2. line-height 关键发现 ⚠️
|
||
- 微信小程序的 `<text>` 组件不能直接设置 `line-height`
|
||
- 必须在外层 `<view>` 上设置，text 会自动继承
|
||
- 详见主规范 §2.6 和 §6.2
|
||
|
||
### 3. 数据驱动
|
||
- 禁止使用 DOM 操作（`document.*`、`element.classList.*`）
|
||
- 所有交互改为 `setData` + 条件渲染
|
||
- 详见主规范 §11
|
||
|
||
### 4. 能力分级
|
||
- **A 类**：可直接使用（flex、transition、animation 等）
|
||
- **B 类**：有条件使用（sticky、grid、backdrop-filter 等）
|
||
- **C 类**：禁止直迁（DOM API、浏览器 API 等）
|
||
- 详见主规范 §3
|
||
|
||
---
|
||
|
||
## 📝 版本历史
|
||
|
||
### v3.0（2026-03-14）
|
||
- 合并 v1.0 技术换算基础和 v2.0 执行规范
|
||
- 补充 line-height 关键发现
|
||
- 统一文档结构，便于 AI 和开发者使用
|
||
|
||
### v2.0
|
||
- 执行规范，强化输入输出契约和能力分级
|
||
|
||
### v1.0
|
||
- 技术换算基础，建立完整的映射表
|
||
|
||
---
|
||
|
||
## 🗂️ 旧版文档（已归档）
|
||
|
||
以下文档已被 v3.0 主规范替代，保留作为参考：
|
||
|
||
- `docs/miniprogram-dev/h5-to-mp-bridge.md` - v1.0 技术换算基础
|
||
- `docs/prd/H5到微信小程序迁移桥接规范_可执行版_v2.md` - v2.0 执行规范
|
||
|
||
**建议**：新的迁移工作请使用 v3.0 主规范。
|
||
|
||
---
|
||
|
||
## 📊 文档统计
|
||
|
||
- **主规范**：约 1000+ 行，包含完整的执行规程、技术换算、交互改造、执行流程
|
||
- **附录 A**：181 行，Spacing 与尺寸字典
|
||
- **附录 B**：267 行，字体与文本字典（含 line-height 规则）
|
||
- **附录 C**：199 行，颜色字典
|
||
- **附录 D**：205 行，布局类映射字典
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 第一次使用
|
||
|
||
1. 阅读主规范 `h5-to-mp-bridge-v3.md` 的 §1-4
|
||
2. 了解输入输出契约和强制决策
|
||
3. 查看 §13 的 10 步标准流程
|
||
|
||
### 执行迁移
|
||
|
||
1. 按 §13 的流程逐步执行
|
||
2. 查表时参考 §5-9 和附录
|
||
3. 交互改造时参考 §10-12
|
||
4. 验证输出符合 §1.2 的要求
|
||
|
||
### 问题排查
|
||
|
||
1. Y 轴高度不对 → 检查 line-height（§2.6、§6.2）
|
||
2. 交互不工作 → 检查是否改为数据驱动（§11）
|
||
3. 样式不对 → 检查单位换算（§2.3、§5-9）
|
||
4. 页面跳转失败 → 检查 TabBar 页面是否用 switchTab（§11.7）
|
||
|
||
---
|
||
|
||
**文档完整，可以开始迁移！** 🎉
|