153 lines
6.5 KiB
Markdown
153 lines
6.5 KiB
Markdown
---
|
||
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 工作流见第十一章。
|