---
name: mp-h5-rules
description: H5→微信小程序转换硬性规则（核心约束，始终生效）
---

# H5 → 微信小程序转换硬性规则

本规则在所有涉及小程序前端开发的 session 中始终生效。详细操作手册见 Power `miniprogram-h5-conversion`。

## 视觉真相

- `docs/h5_ui/pages/*.html` 是唯一视觉参考，任何偏离需用户确认
- 颜色/间距/字号标准值见 `docs/h5_ui/design-tokens.json`，禁止凭记忆硬编码

## 标签映射（严禁在 WXML 中使用 HTML 标签）

`<div>`→`<view>` | `<span>/<p>`→`<text>` | `<img>`→`<image mode="">` | `<svg>`内联→`<image src="xx.svg">` | `<button>`→`<t-button>` | `<input>`→`<t-input>`

## rpx 换算

- 精确公式：`rpx = px × 2 × 0.875`（取偶数）
- 圆角例外：`border-radius = px × 2`
- Tailwind 字号必须同步 line-height：text-xs→22/28rpx | text-sm→24/34rpx | text-base→28/42rpx | text-lg→32/48rpx | text-xl→36/48rpx | text-2xl→42/56rpx

## 颜色灰阶（禁止使用 #333/#666/#999 等非标准值）

gray-1 #f3f3f3(页面背景) | gray-6 #a6a6a6(辅助文字) | gray-9 #5e5e5e(次要文字) | gray-13 #242424(主文字) | primary #0052d9 | success #00a870 | warning #ed7b2f | error #e34d59

## TDesign 优先

凡 TDesign 组件能覆盖的 UI 元素必须使用 TDesign。`t-button icon="xxx"` 只支持内置图标，品牌图标用 `<view>+<image>` 组合。

## 不支持的 CSS

`backdrop-filter`→`rgba()` | `::before/::after`→额外`<view>`绝对定位 | `background-clip:text`→纯色 | `data:image/svg+xml`→导出独立文件 | `*`通配符→逐个设置

## 截图规则

- H5：必须 `browser_run_code` 创建 DPR=1.5 context（禁止 `browser_take_screenshot`/分步流程）
- MP：导航一律 `relaunch`（禁止 `switch_tab`/`navigate_to`）；模式 B（自定义 navBar）裁剪头部 96px
- 双端对比基准：645×1128
- 截图后禁止用 PIL/pixelmatch/image-compare 做像素 diff，改用结构化拆解+逐级测量+偏差审计
- `image-compare` MCP 已移除（2026-03-12），禁止调用

## 偏差判定

≤2rpx 通过 | >2rpx且≤4rpx 警告(P4-P7) | >4rpx 不通过(P0-P3)

## 事件与数据

- 传参用 `data-*`，取值 `e.detail.value`，阻止冒泡用 `catchtap`
- `this.setData()` 驱动视图，布尔属性用 `{{}}`，列表加 `wx:key`
- mock 数据必须与 H5 硬编码值完全一致，标记 `// TODO: 替换为真实 API 调用`

## 安全区

JS `wx.getSystemInfoSync().statusBarHeight` 动态 padding-top，禁止 `env(safe-area-inset-top)`