Neo-ZQYY/_DEL/mp-h5-rules.md

name, description

name	description
mp-h5-rules	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)