188 lines
6.2 KiB
Markdown
188 lines
6.2 KiB
Markdown
# 微信小程序开发文档
|
||
|
||
> H5 → 微信小程序迁移规范 + VI 设计系统
|
||
> 最后更新：2026-03-17
|
||
|
||
---
|
||
|
||
## 📚 文档导航
|
||
|
||
### 🚀 快速开始
|
||
|
||
**首次使用？** 从这里开始：
|
||
|
||
1. **AI 代码生成**：查阅 [`QUICK-REFERENCE.md`](./QUICK-REFERENCE.md)
|
||
- 颜色速查表、单位换算、类名映射、常见模式
|
||
- 精简版，适合快速查询
|
||
|
||
2. **完整迁移规范**：查阅 [`h5-migration/h5-to-mp-bridge.md`](./h5-migration/h5-to-mp-bridge.md)
|
||
- 执行规程、技术换算、交互改造、10步标准流程
|
||
- 详细版，适合深入理解
|
||
|
||
3. **VI 设计系统**：查阅 [`design-system/VI-DESIGN-SYSTEM.md`](./design-system/VI-DESIGN-SYSTEM.md)
|
||
- 颜色系统、组件规范、配色建议
|
||
- 设计师和开发者参考
|
||
|
||
---
|
||
|
||
## 📂 文档结构
|
||
|
||
```
|
||
docs/miniprogram-dev/
|
||
├── README.md ← 你在这里
|
||
├── QUICK-REFERENCE.md ← AI 快速参考（推荐首选）
|
||
│
|
||
├── h5-migration/ ← H5 迁移文档
|
||
│ ├── h5-to-mp-bridge.md ← 完整迁移规范（1081行）
|
||
│ ├── README.md ← 迁移文档说明
|
||
│ └── appendix/ ← 详细字典
|
||
│ ├── index.md ← 附录索引
|
||
│ ├── spacing-dictionary.md ← Spacing 与尺寸字典
|
||
│ ├── typography-dictionary.md ← 字体与文本字典
|
||
│ ├── color-dictionary.md ← 颜色字典
|
||
│ └── layout-dictionary.md ← 布局类映射字典
|
||
│
|
||
└── design-system/ ← VI 设计系统
|
||
├── VI-DESIGN-SYSTEM.md ← 完整设计系统规范（397行）
|
||
├── vi-guide.html ← 可视化指南（设计师用）
|
||
└── QUICK-REFERENCE.md ← 颜色速查表
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 按场景查阅
|
||
|
||
### 场景1：AI 代码生成迁移页面
|
||
|
||
**推荐流程**：
|
||
1. 打开 [`QUICK-REFERENCE.md`](./QUICK-REFERENCE.md)
|
||
2. 查阅颜色、单位、类名速查表
|
||
3. 参考常见迁移模式
|
||
4. 需要详细说明时，查阅 [`h5-migration/h5-to-mp-bridge.md`](./h5-migration/h5-to-mp-bridge.md)
|
||
|
||
**关键文件**：
|
||
- `QUICK-REFERENCE.md` - 核心参考
|
||
- `h5-migration/h5-to-mp-bridge.md` - 完整规范
|
||
- `h5-migration/appendix/` - 详细字典
|
||
|
||
---
|
||
|
||
### 场景2：前端开发手工迁移
|
||
|
||
**推荐流程**：
|
||
1. 阅读 [`h5-migration/h5-to-mp-bridge.md`](./h5-migration/h5-to-mp-bridge.md) 的 §1-4（执行规程）
|
||
2. 了解输入输出契约和强制决策
|
||
3. 按 §13 的 10 步标准流程执行
|
||
4. 查表时参考 §5-9 和附录 A/B/C/D
|
||
|
||
**关键文件**：
|
||
- `h5-migration/h5-to-mp-bridge.md` - 完整规范
|
||
- `h5-migration/appendix/` - 详细字典
|
||
|
||
---
|
||
|
||
### 场景3：设计师查看配色规范
|
||
|
||
**推荐流程**：
|
||
1. 打开 [`design-system/vi-guide.html`](./design-system/vi-guide.html)（可视化指南）
|
||
2. 查看各个模块的颜色预览
|
||
3. 需要详细说明时，查阅 [`design-system/VI-DESIGN-SYSTEM.md`](./design-system/VI-DESIGN-SYSTEM.md)
|
||
|
||
**关键文件**：
|
||
- `design-system/vi-guide.html` - 可视化指南
|
||
- `design-system/VI-DESIGN-SYSTEM.md` - 完整规范
|
||
|
||
---
|
||
|
||
### 场景4：查询特定内容
|
||
|
||
| 需要查询 | 查阅文件 |
|
||
|---------|---------|
|
||
| 颜色值 | `QUICK-REFERENCE.md` 或 `h5-migration/appendix/color-dictionary.md` |
|
||
| 单位换算 | `QUICK-REFERENCE.md` 或 `h5-migration/appendix/spacing-dictionary.md` |
|
||
| 字号/行高 | `h5-migration/appendix/typography-dictionary.md` |
|
||
| 布局类名 | `h5-migration/appendix/layout-dictionary.md` |
|
||
| 迁移流程 | `h5-migration/h5-to-mp-bridge.md` §13 |
|
||
| 能力分级 | `h5-migration/h5-to-mp-bridge.md` §3 |
|
||
| VI 规范 | `design-system/VI-DESIGN-SYSTEM.md` |
|
||
|
||
---
|
||
|
||
## 📊 文档统计
|
||
|
||
| 文档 | 行数 | 用途 |
|
||
|------|------|------|
|
||
| QUICK-REFERENCE.md | 210 | AI 快速参考 |
|
||
| h5-to-mp-bridge.md | 1081 | 完整迁移规范 |
|
||
| spacing-dictionary.md | 181 | Spacing 字典 |
|
||
| typography-dictionary.md | 267 | 字体字典 |
|
||
| color-dictionary.md | 199 | 颜色字典 |
|
||
| layout-dictionary.md | 205 | 布局字典 |
|
||
| VI-DESIGN-SYSTEM.md | 397 | VI 设计系统 |
|
||
| **总计** | **2740** | - |
|
||
|
||
---
|
||
|
||
## 🔑 核心概念速览
|
||
|
||
### 单位策略
|
||
- **rpx 为主**：布局、容器、间距（换算公式：`rpx = px × 1.8204`）
|
||
- **px 为辅**：发丝线、阴影、小图标
|
||
|
||
### 交互改造
|
||
- **禁止 DOM 操作**：`document.*`、`classList.*` 等
|
||
- **改为数据驱动**：`setData` + 条件渲染
|
||
|
||
### 能力分级
|
||
- **A 类**：可直迁（flex、transition、animation 等）
|
||
- **B 类**：条件迁（sticky、grid、backdrop-filter 等）
|
||
- **C 类**：禁迁（DOM API、浏览器 API 等）
|
||
|
||
### 颜色系统
|
||
- **任务分类**：4 种（高优先、优先、回访、关系）
|
||
- **客户标签**：6 种（基础、消费、玩法、促销、社交、反馈）
|
||
- **关系等级**：4 种（很好、良好、一般、待发展）
|
||
- **AI 图标**：6 种配色（Red、Orange、Yellow、Blue、Indigo、Purple）
|
||
|
||
---
|
||
|
||
## ⚠️ 常见问题
|
||
|
||
### Q: 我应该从哪个文档开始？
|
||
**A**:
|
||
- 如果是 AI 代码生成：`QUICK-REFERENCE.md`
|
||
- 如果是手工迁移：`h5-migration/h5-to-mp-bridge.md`
|
||
- 如果是查颜色：`design-system/VI-DESIGN-SYSTEM.md`
|
||
|
||
### Q: 文档太多了，怎么快速找到我需要的？
|
||
**A**: 使用上面的"按场景查阅"表格，或者用 Ctrl+F 搜索关键词。
|
||
|
||
### Q: 为什么要分这么多文件？
|
||
**A**: 为了避免超大文件导致 AI 处理时超过 token 限制。每个文件都是独立的，可以按需加载。
|
||
|
||
### Q: 旧文档在哪里？
|
||
**A**: 已归档。新的迁移工作请使用本文档体系。
|
||
|
||
---
|
||
|
||
## 📝 版本历史
|
||
|
||
### v1.0（2026-03-17）
|
||
- 整理文档结构
|
||
- 创建 QUICK-REFERENCE.md（AI 快速参考）
|
||
- 统一 README.md 作为总索引
|
||
- 分类 h5-migration 和 design-system
|
||
|
||
---
|
||
|
||
## 🚀 快速链接
|
||
|
||
- [AI 快速参考](./QUICK-REFERENCE.md) - 颜色、单位、类名速查
|
||
- [完整迁移规范](./h5-migration/h5-to-mp-bridge.md) - 详细执行规程
|
||
- [VI 设计系统](./design-system/VI-DESIGN-SYSTEM.md) - 颜色和组件规范
|
||
- [可视化指南](./design-system/vi-guide.html) - 设计师参考
|
||
|
||
---
|
||
|
||
**需要帮助？** 查阅对应的文档，或按"按场景查阅"表格找到你需要的内容。
|