6.5 KiB
6.5 KiB
inclusion, fileMatchPattern, name, description
| inclusion | fileMatchPattern | name | description |
|---|---|---|---|
| fileMatch | **/miniprogram/miniprogram/pages/**,**/miniprogram/miniprogram/components/**,**/h5_ui/** | miniprogram-h5-conversion | H5 原型转微信小程序的强制规范。读到小程序页面/组件或 H5 原型文件时自动加载。 |
H5 → 微信小程序转换规范（强制）
本规范适用于所有将 docs/h5_ui/pages/*.html 转换为小程序页面的任务。
一、转换前强制加载
每次转换页面前，必须加载以下资源（按顺序）：
wechat-miniprogramPower 的 steering 文件：view-layer.md、tdesign.md、builtin-components.md- 目标页面的交互说明：
docs/h5_ui/interactions/<page>.md - 设计 Token：
docs/h5_ui/design-tokens.json - 图标映射表：
docs/h5_ui/icon-mapping.md - 目标页面的 H5 源码：
docs/h5_ui/pages/<page>.html - 计算样式（如有）：
docs/h5_ui/computed-styles.json中对应页面的 key - 截图（如用户提供）：
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.showModallocalStorage改为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 工作流见第十一章。