---
inclusion: fileMatch
fileMatchPattern: "**/miniprogram/miniprogram/pages/**,**/miniprogram/miniprogram/components/**,**/h5_ui/**"
name: miniprogram-h5-conversion
description: H5 原型转微信小程序的强制规范。读到小程序页面/组件或 H5 原型文件时自动加载。
---

# H5 → 微信小程序转换规范（强制）

本规范适用于所有将 `docs/h5_ui/pages/*.html` 转换为小程序页面的任务。

## 一、转换前强制加载

每次转换页面前，必须加载以下资源（按顺序）：

1. `wechat-miniprogram` Power 的 steering 文件：`view-layer.md`、`tdesign.md`、`builtin-components.md`
2. 目标页面的交互说明：`docs/h5_ui/interactions/<page>.md`
3. 设计 Token：`docs/h5_ui/design-tokens.json`
4. 图标映射表：`docs/h5_ui/icon-mapping.md`
5. 目标页面的 H5 源码：`docs/h5_ui/pages/<page>.html`
6. 计算样式（如有）：`docs/h5_ui/computed-styles.json` 中对应页面的 key
7. 截图（如用户提供）：`docs/h5_ui/screenshots/<page>--*.png`

## 二、原型忠实度（最高优先级）

- `docs/h5_ui/pages/*.html` 中的结构、层次、元素、配色、间距、交互行为是唯一视觉真相
- 任何偏离原型的实现都需要用户明确确认
- 截图是校验还原度的唯一视觉参考

## 三、标签映射（硬性规则）

| HTML | WXML | 说明 |
|------|------|------|
| `<div>` | `<view>` | 容器 |
| `<span>` / `<p>` | `<text>` | 文本必须用 `<text>` 包裹 |
| `<a>` | `<navigator>` | 或 `wx.navigateTo()` |
| `<img>` | `<image mode="">` | 必须指定 `mode` 和宽高 |
| `<svg>` 内联 | `<image src="xx.svg">` | 不支持内联 SVG |
| `<ul>/<li>` | `<view wx:for>` | 无列表语义标签 |
| `<select>` | `<t-picker>` | 完全不同的交互 |
| `<button>` | `<t-button>` | TDesign 优先 |
| `<input>` | `<t-input>` | TDesign 优先 |

严禁在 WXML 中使用 HTML 标签（div/span/p/a/img 等）。

## 四、样式规则

### rpx 换算
- 基准：屏幕宽度 = 750rpx，设计稿以 375px 宽为基准
- 换算公式：H5 的 px 值 × 2 = rpx 值
- 严禁同一类间距混用 rpx 和 px

### 设计 Token 引用
颜色、间距、圆角、字号、阴影必须参照 `docs/h5_ui/design-tokens.json`，不得凭记忆硬编码。

### 不支持的 CSS
| CSS 特性 | 替代方案 |
|----------|---------|
| `backdrop-filter: blur()` | 半透明背景色 `rgba()` |
| `*` 通配符选择器 | 逐个元素设置 |
| 远程 `@font-face` | `wx.loadFontFace()` |

### 样式隔离
- `app.wxss` = 全局样式
- 页面 `.wxss` = 自动隔离
- 组件 `.wxss` = 默认隔离，穿透用外部样式类或 CSS 变量

## 五、TDesign 优先原则

- 凡 TDesign 组件库能覆盖的 UI 元素，必须使用 TDesign 组件
- 自定义实现仅限 TDesign 无法覆盖的场景
- TDesign 样式覆盖优先用 CSS 变量，其次外部样式类，最后 `!important`
- 组件必须在页面 `.json` 的 `usingComponents` 中注册

## 六、事件系统

- 不能在 `bindtap` 中传参：用 `data-*` 属性
- 取值路径：`e.detail.value`（非 `event.target.value`）
- 阻止冒泡：用 `catchtap`（非 `preventDefault`）
- `data-` 属性名自动转换：连字符转驼峰，大写转小写

## 七、数据与状态

- 用 `this.setData()` 驱动视图更新，无 DOM API
- `wx:if` 中不支持复杂 JS 表达式，需在 JS 中预处理
- 布尔属性必须用 `{{}}` 包裹：`checked="{{true}}"`
- 列表渲染必须加 `wx:key`

## 八、导航与路由

- 页面栈最多 10 层，`navigateTo` 超过会静默失败
- 跳转 tabBar 页面必须用 `switchTab`
- 路径以 `/` 开头，不带 `.wxml` 后缀
- 登录/登出场景用 `reLaunch`

## 九、Mock 数据策略（纯 UI 阶段）

后端 API 未就绪时，使用 mock 数据：
- 在页面 JS 的 `onLoad` 中用 `this.setData()` 设置 mock 数据
- mock 数据结构必须贴近真实 API 返回格式（参考对应 Spec 的接口定义）
- mock 数据用 `// TODO: 替换为真实 API 调用` 注释标记
- 联调时只需替换数据获取逻辑，不改动 WXML/WXSS

## 十、新页面开发 Checklist

- [ ] HTML 标签全部替换为 WXML 组件
- [ ] 内联 SVG 提取为文件，改用 `<image>` 或 `<t-icon>`
- [ ] Tailwind 类全部手写为 WXSS（px × 2 = rpx）
- [ ] 不支持的 CSS 改为替代方案
- [ ] 事件绑定改为 `bindtap` / `bind:change`，传参用 `data-*`
- [ ] `alert/confirm` 改为 `wx.showToast` / `wx.showModal`
- [ ] `localStorage` 改为 `wx.setStorageSync`
- [ ] 路由跳转改为 `wx.navigateTo` / `wx.reLaunch` 等
- [ ] 图片设置 `mode` 属性
- [ ] 列表渲染加 `wx:key`
- [ ] 布尔属性用 `{{}}` 包裹
- [ ] TDesign 组件在页面 `.json` 中注册
- [ ] 安全区适配：JS `wx.getSystemInfoSync().statusBarHeight` 动态 padding-top（禁止用 `env(safe-area-inset-top)`）
- [ ] 页面配置：`navigationBarTitleText` 等

## 十一、验收标准

- 视觉还原度：与 H5 截图对比，布局/间距/颜色/字号一致
- 交互完整性：交互说明中的所有状态和操作均已实现
- 空状态/加载态/错误态：均有处理
- TDesign 组件正确使用，无原生 HTML 标签残留

## 十二、实战踩坑速查

> 完整记录见 `docs/prd/MIGRATION-PLAYBOOK.md` 第六章。

### WXML 模板
- **禁止在 `{{}}` 中调用 JS 方法**（`.toFixed()`、`.map()` 等）→ 用 WXS 模块 `utils/format.wxs`
- **TabBar 页面跳转必须用 `wx.switchTab`**（task-list、board-finance、my-profile），`navigateTo` 会静默失败

### 样式与布局
- **一屏页面**（login、reviewing、no-permission 等）：`height: 100vh` + `box-sizing: border-box`，不用 `min-height: 100vh`
- **状态栏适配**：用 JS `wx.getSystemInfoSync().statusBarHeight` 动态设置 `padding-top`，禁止用 `env(safe-area-inset-top)`
- **padding-top + 100vh**：必须配合 `box-sizing: border-box`，否则底部内容溢出

### TDesign 组件
- **`t-button icon="xxx"` 只支持内置图标**：品牌图标（微信 logo 等）必须导出 SVG，用 `<view>` + `<image>` 组合
- **TDesign 默认样式优先级高**：与原型差异大时，直接用原生 `<view>` 实现，绕开样式干扰

### 资源引用
- **所有 H5 内联 SVG 必须导出为独立 `.svg` 文件**，存放 `assets/icons/`，用 `<image>` 引用
- **引用不存在的图片会 500 错误**：用 CSS 渐变、emoji、`<t-icon>` 替代

---

> 以上内容已整合至 `docs/prd/MIGRATION-PLAYBOOK.md`（唯一权威迁移文档）。
> 避坑清单见第六章，迁移流程见第二章，输入素材见第十二章，AI 工作流见第十一章。