4.3 KiB
4.3 KiB
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/：
h5_to_wechat_miniprogram_migration_bridge_appendix_index_v3.md- 附录索引（v3.1）appendix_a_spacing_and_sizing_dictionary_v3.md- 附录 A：Spacing 与尺寸字典appendix_b_typography_and_text_dictionary_v3.md- 附录 B：字体与文本字典（v3.1）appendix_c_color_dictionary_v3.md- 附录 C：颜色字典appendix_d_layout_class_mapping_dictionary_v3.md- 附录 D：布局类映射字典
🎯 使用指南
对于 AI
加载顺序：
- 加载主规范
h5-to-mp-bridge-v3.md（完整规范） - 加载附录索引
h5_to_wechat_miniprogram_migration_bridge_appendix_index_v3.md - 按需加载具体附录（A/B/C/D）
执行流程：
- 按 §13 的 10 步标准流程执行迁移
- 查表时参考 §5-9 和附录 A/B/C/D
- 交互改造时参考 §10-12
- 确保输出符合 §1.2 的要求
对于开发者
快速上手：
- 先读主规范 §1-4 了解规则和决策
- 需要时查阅 §5-12 的换算表和附录
- 按 §13 的流程逐步完成迁移
- 问题排查时回到对应章节
🔑 核心要点
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 行，布局类映射字典
🚀 快速开始
第一次使用
- 阅读主规范
h5-to-mp-bridge-v3.md的 §1-4 - 了解输入输出契约和强制决策
- 查看 §13 的 10 步标准流程
执行迁移
- 按 §13 的流程逐步执行
- 查表时参考 §5-9 和附录
- 交互改造时参考 §10-12
- 验证输出符合 §1.2 的要求
问题排查
- Y 轴高度不对 → 检查 line-height（§2.6、§6.2）
- 交互不工作 → 检查是否改为数据驱动（§11）
- 样式不对 → 检查单位换算（§2.3、§5-9）
- 页面跳转失败 → 检查 TabBar 页面是否用 switchTab（§11.7）
文档完整，可以开始迁移！ 🎉