Files

2026-03-18 05:14:35 +08:00

34 KiB

Raw Permalink Blame History

H5 原型 → 微信小程序迁移桥接规范（主规范 v3.0）

版本：v3.0
适用对象：人工开发、AI 批量迁移、代码审查、验收回归
适用范围：本项目 docs/h5_ui/ 原型页面到微信原生小程序的迁移
目标：实现页面与交互的高还原迁移，样式、层级、动效、状态切换、页面流转 1:1 对齐 H5 验收原型

📖 文档使用指南

本文档定位

这是执行规程，不是知识笔记。使用本规范时，AI 或开发者必须做到：

能从单个 H5 页面产出对应的小程序页面文件
能明确哪些能力可直接迁移，哪些必须降级，哪些禁止直迁
能在不使用 DOM API 的前提下，把 H5 交互改造成小程序的数据驱动实现
能输出可交付物，而不是停留在"分析建议"

文档结构

第一部分（§1-4）：执行规程 - 输入输出、强制决策、能力分级
第二部分（§5-9）：技术换算 - 尺寸、字号、颜色、布局、装饰
第三部分（§10-12）：交互改造 - WXML 映射、数据驱动、API 替换
第四部分（§13）：执行流程 - 10 步标准流程
附录引用（§14）：4 个附录字典的索引

配套文档

附录 A：Spacing 与尺寸字典
附录 B：字体与文本字典（v3.1，含 line-height 规则）
附录 C：颜色字典
附录 D：布局类映射字典
附录索引：docs/miniprogram-dev/New/h5_to_wechat_miniprogram_migration_bridge_appendix_index_v3.md

第一部分：执行规程

1. 输入输出契约

1.1 输入物

单页迁移时，输入物必须至少包含：

对应 H5 页面 HTML 文件
该页面引用的 CSS（页面内 <style>、独立 css 文件、Tailwind utility）
该页面引用的 JS
该页面依赖的图片 / 图标 / SVG / JSON Mock
页面跳转关系和入口参数

1.2 输出物

每个页面迁移后，必须至少产出：

pages/<route>/<route>.wxml
pages/<route>/<route>.wxss
pages/<route>/<route>.js
pages/<route>/<route>.json
该页面使用到的 mock 数据文件或页面内 mock 常量
迁移说明（至少包含：状态变量、事件、待确认项、降级项）

1.3 不允许的输出

以下结果视为未完成：

只给"迁移思路"，不产出页面文件
只把 Tailwind class 翻译成 CSS，不改 WXML / 交互
继续依赖 document.*、window.*、history.*、localStorage 等浏览器 API
以"兼容性未知"为由保留 H5 写法不处理
把高风险 CSS 特性原样搬过去，且不写降级方案

2. 项目级强制决策

2.1 框架与运行时

必须使用微信原生小程序页面体系：WXML + WXSS + JS + JSON
禁止继续在小程序端运行 Tailwind CDN / 浏览器脚本
禁止使用 DOM 驱动交互，页面必须改为数据驱动
不引入 Taro / uni-app / WebView 兜底，本规范面向原生小程序页面迁移

2.2 验收基准

H5 原型的主要验收基准宽度为 412 CSS px
小程序以 412 宽设备的视觉效果为主验收目标
其他常见宽度设备允许比例差异，但不得出现：文本溢出、遮挡、错层、关键按钮点击区域异常、吸顶/弹层错位

2.3 单位策略

采用 rpx 为主、px 为辅 的混合单位方案。

优先 rpx：

页面宽度、横向布局、卡片尺寸
主容器 padding / margin、列表间距、栅格
吸顶区高度、块级间距

优先 px：

1px 发丝线、阴影 blur/spread
小图标、绝对定位微调、小控件尺寸
状态栏 / 安全区补偿、细描边

按效果决定：

字号、圆角、局部 padding、某些 transform 位移

换算基准：

rpx = H5_CSS_px × (750 / 412)
    ≈ H5_CSS_px × 1.8204

取整规则：

普通布局值：四舍五入到整数 rpx
高频 token：沉淀成统一变量表（见附录 A），保持全项目一致
视觉敏感值：以真机截图比对微调，不强行套公式

2.4 页面滚动策略

默认使用 页面自然滚动
只有在必须做局部滚动区域时，才使用 scroll-view
吸顶、滚动联动、section 感知优先围绕页面滚动实现；不要无必要把整页包进 scroll-view

2.5 样式组织策略

全局 token、复用组件样式放 app.wxss 或公共样式文件
页面私有样式放页面同名 .wxss
样式优先使用 class，动态值用内联 style 绑定
不以 CSS 变量作为唯一运行前提；优先输出静态色值 / 静态 token

2.6 文本与行高策略 ⚠️

关键发现：微信小程序的 <text> 组件不能直接设置 line-height，必须通过外层 <view> 设置。

全局设置（推荐）：

page {
  line-height: 1.5; /* Tailwind 默认行高 */
}

view {
  line-height: inherit; /* view 继承 page 的 line-height */
}

/* text 会自动继承外层 view 的 line-height，不需要额外设置 */

局部覆盖：

.section-title {
  font-size: 26rpx;
  line-height: 36rpx; /* 在 view 的 class 上设置，text 会继承 */
  font-weight: 600;
}

<view class="section-title">
  <text>标题文本</text>
</view>

错误做法：

/* ❌ 直接在 text 上设置 line-height 无效 */
text {
  line-height: 36rpx; /* 不会生效 */
}

执行规则：

所有文本类样式必须同时设置 font-size 和 line-height
line-height 必须在外层 <view> 的 class 上设置，不能在 <text> 上设置
标准字号的 line-height 换算参考附录 B.3
若发现 Y 轴高度与 H5 端不一致，优先检查 line-height 是否正确设置

2.7 SVG / 图标策略

禁止把 H5 的内联 <svg>...</svg> 直接当 WXML DOM 搬运
资源层允许 svg 文件进入小程序项目包，但页面显示是否稳定，必须以目标设备实测为准
默认执行顺序：
- 简单静态图标：优先导出为独立资源文件
- 若 svg 渲染不稳定：转为 png
- 高频单色图标：允许改为 iconfont / 组件化图标
动态换色的 SVG 不要临时拼接字符串；应改为多份资源、图标组件或样式控制的等价实现

3. 能力分级（A/B/C 类）

3.1 A 类：可直接使用

以下能力在当前项目中视为稳定迁移能力：

app.wxss / 页面 wxss / @import
rpx
.class、#id、元素选择器、::before、::after
flex、position: relative/absolute/fixed
box-shadow、border-radius、linear-gradient
opacity、常规 transform
transition、animation
动态内联样式绑定
onPageScroll
wx.createAnimation()
wx.createSelectorQuery()
wx.createIntersectionObserver()
navigator / wx.navigateTo / wx.redirectTo / wx.switchTab / wx.navigateBack
view / navigator 的 hover-class

3.2 B 类：有条件使用，必须带回退或验证

以下能力允许使用，但不能把它们当成项目硬依赖：

position: sticky
grid
filter: blur()
backdrop-filter
clip-path
vh
line-clamp
复杂组合选择器
资源型 svg
CSS 变量

执行规则：

使用前必须确认该页面已有回退方案
若页面对视觉或交互依赖度高，则必须做真机验证
若 B 类能力失效，不得阻塞交付，必须切换为本规范定义的降级实现

3.3 C 类：禁止直迁

以下能力不得原样从 H5 搬到小程序：

document.getElementById/querySelector/querySelectorAll
classList.add/remove/toggle
直接改 element.style.xxx
innerHTML / textContent 方式渲染视图
window.scrollY / window.scrollTo
history.back
localStorage / sessionStorage
alert / confirm
CSS env(safe-area-inset-*)
:hover / group-hover:*
依赖浏览器焦点模型的 :focus / :active 交互
依赖 :first-child/:last-child/:nth-child 才能成立的视觉规则

4. Tailwind CSS 在本项目中的行为

4.1 Tailwind CSS 渲染机制

本项目 H5 原型使用 <script src="https://cdn.tailwindcss.com"></script>（Tailwind CSS v3 CDN Play 模式）。

Tailwind v3 默认主题中，大量 spacing、font-size、border-radius token 主要使用 rem 体系。在浏览器默认根字号 1rem = 16px 且页面未主动改写 html { font-size } 的前提下，这些 rem 体系的 utility 会计算成固定 CSS px 值。

关键事实：Tailwind 默认 rem 体系的 utility class 在任何设备上都会计算为固定的 CSS px 值，与设备布局宽度无关。

4.2 微信 rpx 的精确定义

来源：微信官方 WXSS 文档

rpx（responsive pixel）：可以根据屏幕宽度进行自适应。规定屏幕宽为 750rpx。

换算公式：

1rpx = 屏幕宽度px / 750
1px  = 750 / 屏幕宽度px × rpx

官方示例：

设备	屏幕宽度	1rpx = ?px	1px = ?rpx
iPhone 5	320px	0.42px	2.34rpx
iPhone 6	375px	0.5px	2rpx
iPhone 6 Plus	414px	0.552px	1.81rpx

4.3 本项目的换算链路

验收基准设备：等效宽度 412px

完整链路：Tailwind class → CSS 计算值(px) → rpx

rpx = CSS_px × (750 / 412)
    = CSS_px × 1.82039...

（待续：第二部分将包含详细的技术换算表）

📚 快速导航

执行规程：§1-4（当前部分）
技术换算：§5-9（见下文）
交互改造：§10-12（见下文）
执行流程：§13（见下文）
附录索引：§14（见下文）

版本历史

v3.0（2026-03-14）：合并 v1.0 技术换算基础和 v2.0 执行规范，补充 line-height 关键发现
v2.0：执行规范，强化输入输出契约和能力分级
v1.0：技术换算基础，建立完整的映射表

H5 原型 → 微信小程序迁移桥接规范（主规范 v3.0 - 第二部分）

接续第一部分，本部分包含：§5-9 技术换算基础

第二部分：技术换算基础

5. Tailwind Spacing → rpx 完整换算表

Tailwind v3 的 spacing scale 基于 0.25rem = 4px 步进。以下是本项目原型中实际使用的所有 spacing 值的精确换算。这些 rpx 值已在已迁移页面中使用，作为项目统一 token，后续页面应保持一致。

5.1 Tailwind spacing scale（默认）

Tailwind 值	rem	CSS px	rpx（项目 token）	常见用途
`0.5`	0.125rem	2px	4rpx	gap-0.5, p-0.5, mt-0.5
`px`	1px	1px	2rpx	py-px, w-px
`1`	0.25rem	4px	8rpx	gap-1, p-1, mt-1, mb-1
`1.5`	0.375rem	6px	12rpx	gap-1.5, p-1.5, mt-1.5
`2`	0.5rem	8px	14rpx	gap-2, p-2, mt-2, mb-2
`2.5`	0.625rem	10px	18rpx	gap-2.5, p-2.5, mb-2.5
`3`	0.75rem	12px	22rpx	gap-3, p-3, mb-3, pl-3
`3.5`	0.875rem	14px	26rpx	p-3.5, h-3.5, w-3.5
`4`	1rem	16px	30rpx	gap-4, p-4, px-4, mb-4
`5`	1.25rem	20px	36rpx	p-5, px-5, mb-5, pb-5
`6`	1.5rem	24px	44rpx	gap-6, p-6, px-6, mb-6
`7`	1.75rem	28px	52rpx	h-7, w-7
`8`	2rem	32px	58rpx	px-8, mb-8, pb-8, h-8
`10`	2.5rem	40px	72rpx	h-10, w-10, pb-10
`12`	3rem	48px	88rpx	h-12, w-12, pb-12
`16`	4rem	64px	116rpx	h-16, w-16
`20`	5rem	80px	146rpx	h-20, w-20, top-20
`24`	6rem	96px	174rpx	h-24, w-24
`32`	8rem	128px	232rpx	h-32, w-32
`40`	10rem	160px	292rpx	bottom-40, top-40

详细完整表格：参见附录 A

6. Tailwind 字号 → WXSS font-size + line-height 完整换算表

6.1 核心规则

Tailwind v3 的字号类（text-xs、text-sm 等）同时设置 font-size 和 line-height。

例如 text-sm 生成的 CSS 是：

font-size: 0.875rem;    /* 14px */
line-height: 1.25rem;   /* 20px */

强制规则：每个 Tailwind 字号类转 WXSS 时，必须同时写 font-size 和 line-height。

6.2 微信小程序 text 组件的 line-height 限制 ⚠️

关键发现：微信小程序的 <text> 组件不能直接设置 line-height，必须通过外层 <view> 设置。

正确做法：参见 §2.6

原因：微信小程序的 <text> 是特殊的内联组件，直接设置 line-height 不生效，必须在外层 <view> 上设置。

验证方法：在开发者工具的 Computed 面板中，text 元素不会显示 line-height 属性，但外层 view 的 height 值会包含行高效果。

6.3 标准字号类换算表

Tailwind class	font-size (px)	line-height (px)	WXSS font-size	WXSS line-height
`text-xs`	12px	16px	22rpx	29rpx
`text-sm`	14px	20px	26rpx	36rpx
`text-base`	16px	24px	30rpx	44rpx
`text-lg`	18px	28px	33rpx	51rpx
`text-xl`	20px	28px	36rpx	51rpx
`text-2xl`	24px	32px	44rpx	58rpx
`text-3xl`	30px	36px	54rpx	66rpx

换算公式：

font-size(rpx) = font-size(px) × 1.8204
line-height(rpx) = line-height(px) × 1.8204

详细完整表格：参见附录 B

6.4 font-weight 映射

Tailwind class	CSS font-weight	WXSS
`font-normal`	400	`font-weight: 400`
`font-medium`	500	`font-weight: 500`
`font-semibold`	600	`font-weight: 600`
`font-bold`	700	`font-weight: 700`

注意：font-medium 是 500 不是 600。这是常见错误。

6.5 其他文本属性

Tailwind class	WXSS
`text-center`	`text-align: center`
`text-right`	`text-align: right`
`text-left`	`text-align: left`
`truncate`	`overflow: hidden; text-overflow: ellipsis; white-space: nowrap`
`line-clamp-2`	`display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; overflow: hidden`
`whitespace-nowrap`	`white-space: nowrap`
`underline`	`text-decoration: underline`
`line-through`	`text-decoration: line-through`

7. Tailwind 颜色 → WXSS 颜色完整映射

7.1 项目自定义颜色

每个 HTML 页面的 <script> 中定义了相同的自定义颜色扩展：

Tailwind 名称	色值	WXSS 变量
`primary`	`#0052d9`	`var(--color-primary)`
`primary-light`	`#ecf2fe`	`var(--color-primary-light)`
`success`	`#00a870`	`var(--color-success)`
`warning`	`#ed7b2f`	`var(--color-warning)`
`error`	`#e34d59`	`var(--color-error)`
`gray-1`	`#f3f3f3`	`var(--color-gray-1)`
`gray-7`	`#8b8b8b`	`var(--color-gray-7)`
`gray-9`	`#5e5e5e`	`var(--color-gray-9)`
`gray-13`	`#242424`	`var(--color-gray-13)`

详细完整表格：参见附录 C

7.2 透明度变体

原型大量使用 Tailwind 的透明度修饰符（/N），如 bg-primary/10、text-white/60。

WXSS 映射方式：使用 rgba() 或直接写带透明度的色值。

透明度后缀	alpha 值	示例
`/10`	0.10	`bg-primary/10` → `rgba(0, 82, 217, 0.10)`
`/20`	0.20	`bg-white/20` → `rgba(255, 255, 255, 0.20)`
`/50`	0.50	`bg-black/50` → `rgba(0, 0, 0, 0.50)`
`/80`	0.80	`bg-white/80` → `rgba(255, 255, 255, 0.80)`

8. Tailwind 布局类 → WXSS 完整映射

8.1 Flexbox

Tailwind class	CSS	WXSS
`flex`	`display: flex`	`display: flex`
`flex-col`	`flex-direction: column`	`flex-direction: column`
`flex-1`	`flex: 1 1 0%`	`flex: 1`
`flex-shrink-0`	`flex-shrink: 0`	`flex-shrink: 0`
`flex-wrap`	`flex-wrap: wrap`	`flex-wrap: wrap`
`items-center`	`align-items: center`	`align-items: center`
`items-start`	`align-items: flex-start`	`align-items: flex-start`
`justify-between`	`justify-content: space-between`	`justify-content: space-between`
`justify-center`	`justify-content: center`	`justify-content: center`

8.2 Grid

Tailwind class	CSS	WXSS
`grid`	`display: grid`	`display: grid`
`grid-cols-2`	`grid-template-columns: repeat(2, minmax(0, 1fr))`	`grid-template-columns: repeat(2, minmax(0, 1fr))`
`grid-cols-3`	`grid-template-columns: repeat(3, minmax(0, 1fr))`	`grid-template-columns: repeat(3, minmax(0, 1fr))`
`grid-cols-4`	`grid-template-columns: repeat(4, minmax(0, 1fr))`	`grid-template-columns: repeat(4, minmax(0, 1fr))`

8.3 Gap（间距）

Tailwind class	CSS	WXSS
`gap-1`	`gap: 4px`	`gap: 8rpx`
`gap-2`	`gap: 8px`	`gap: 14rpx`
`gap-3`	`gap: 12px`	`gap: 22rpx`
`gap-4`	`gap: 16px`	`gap: 30rpx`
`gap-x-3`	`column-gap: 12px`	`column-gap: 22rpx`
`gap-y-2`	`row-gap: 8px`	`row-gap: 14rpx`

8.4 定位

Tailwind class	CSS	WXSS
`relative`	`position: relative`	`position: relative`
`absolute`	`position: absolute`	`position: absolute`
`fixed`	`position: fixed`	`position: fixed`
`sticky`	`position: sticky`	见 §3.2 兼容性说明
`inset-0`	`inset: 0`	`top: 0; right: 0; bottom: 0; left: 0`
`top-0`	`top: 0`	`top: 0`
`z-10`	`z-index: 10`	`z-index: 10`
`z-50`	`z-index: 50`	`z-index: 50`

8.5 尺寸

Tailwind class	CSS	WXSS
`w-full`	`width: 100%`	`width: 100%`
`h-full`	`height: 100%`	`height: 100%`
`w-1/2`	`width: 50%`	`width: 50%`
`min-h-screen`	`min-height: 100vh`	`min-height: 100vh`

详细完整表格：参见附录 D

9. Tailwind 装饰类 → WXSS 完整映射

9.1 圆角

Tailwind class	CSS	WXSS
`rounded`	`border-radius: 4px`	`border-radius: 8rpx`
`rounded-lg`	`border-radius: 8px`	`border-radius: 14rpx`
`rounded-xl`	`border-radius: 12px`	`border-radius: 22rpx`
`rounded-2xl`	`border-radius: 16px`	`border-radius: 30rpx`
`rounded-full`	`border-radius: 9999px`	`border-radius: 50%` 或 `border-radius: 999rpx`

9.2 阴影

Tailwind class	CSS	WXSS
`shadow-sm`	`box-shadow: 0 1px 2px 0 rgba(0,0,0,0.05)`	`box-shadow: 0 2rpx 4rpx 0 rgba(0,0,0,0.05)`
`shadow-lg`	`box-shadow: 0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -4px rgba(0,0,0,0.1)`	`box-shadow: 0 18rpx 28rpx -6rpx rgba(0,0,0,0.1), 0 8rpx 12rpx -8rpx rgba(0,0,0,0.1)`

9.3 边框

Tailwind class	CSS	WXSS
`border`	`border: 1px solid`	`border: 1px solid`
`border-2`	`border: 2px solid`	`border: 2px solid`
`border-b`	`border-bottom: 1px solid`	`border-bottom: 1px solid`
`border-t`	`border-top: 1px solid`	`border-top: 1px solid`

9.4 渐变

Tailwind class	CSS	WXSS
`bg-gradient-to-r`	`background-image: linear-gradient(to right, ...)`	`background: linear-gradient(to right, ...)`
`bg-gradient-to-br`	`background-image: linear-gradient(to bottom right, ...)`	`background: linear-gradient(to bottom right, ...)`
`from-X`	渐变起始色	渐变第一个色值
`to-X`	渐变结束色	渐变最后一个色值

示例：bg-gradient-to-br from-blue-400 to-blue-500
→ WXSS: background: linear-gradient(to bottom right, #60a5fa, #3b82f6)

9.5 透明度与模糊

Tailwind class	CSS	WXSS	小程序兼容性
`opacity-30`	`opacity: 0.3`	`opacity: 0.3`	✓
`opacity-60`	`opacity: 0.6`	`opacity: 0.6`	✓
`backdrop-blur-md`	`backdrop-filter: blur(12px)`	见 §3.2	⚠️ 部分支持
`blur-xl`	`filter: blur(24px)`	`filter: blur(24px)`	✓

（待续：第三部分将包含交互改造）

📚 快速导航

执行规程：§1-4（见第一部分）
技术换算：§5-9（当前部分）
交互改造：§10-12（见第三部分）
执行流程：§13（见第三部分）
附录索引：§14（见第三部分）

H5 原型 → 微信小程序迁移桥接规范（主规范 v3.0 - 第三部分）

接续第二部分，本部分包含：§10-12 交互改造、§13 执行流程、§14 附录索引

第三部分：交互改造

10. HTML 标签 → WXML 组件映射

10.1 基础标签映射

H5 标签	WXML 组件	说明
`<div>`	`<view>`	通用容器
`<span>`	`<text>`	行内文本。注意：`<text>` 内只能嵌套 `<text>`，不能嵌套 `<view>`
`<p>`	`<view>` 或 `<text>`	段落
`<img>`	`<image>`	图片。必须指定 `mode` 属性
`<a>`	`<navigator>` 或 `<view bindtap>`	链接/跳转
`<button>`	`<button>` 或 `<view bindtap>`	按钮
`<input>`	`<input>`	输入框
`<textarea>`	`<textarea>`	多行输入
`<svg>`	`<image src="xxx.svg">`	小程序不支持内联 SVG
`<ul>` / `<ol>` / `<li>`	`<view>`	列表容器

10.2 image 组件的 mode 属性

H5 CSS	image mode
`object-fit: cover`	`mode="aspectFill"`
`object-fit: contain`	`mode="aspectFit"`
无特殊设置	`mode="widthFix"`（宽度撑满，高度自适应）

10.3 事件属性映射

H5 事件	WXML 事件	说明
`onclick`	`bindtap`	点击
`onchange`	`bindchange`	值变化
`oninput`	`bindinput`	输入
`onscroll`	`bindscroll`（scroll-view）或 `onPageScroll`（页面）	滚动
`ontouchstart`	`bindtouchstart`	触摸开始
`ontouchend`	`bindtouchend`	触摸结束
`oncontextmenu`	`bindlongpress`	长按

注意：

bind 前缀事件会冒泡
catch 前缀事件会阻止冒泡（等同于 e.stopPropagation()）
catchtouchmove：阻止触摸移动冒泡（常用于遮罩层阻止背景滚动）

11. JS DOM 操作 → 小程序数据驱动完整映射

11.1 总体原则

H5 模式：用户操作 → JS 查询 DOM → 修改 DOM 属性/样式/内容 → 视觉变化

小程序模式：用户操作 → 事件处理函数 → setData 更新数据 → WXML 自动重渲染 → 视觉变化

禁止在小程序中使用的 H5 API：

document.getElementById()
document.querySelector() / querySelectorAll()
element.classList.add/remove/toggle/contains
element.style.xxx = yyy
element.innerHTML / textContent
document.createElement() / appendChild()

11.2 模式 A：显示/隐藏切换

H5 写法：

document.getElementById('modal').classList.remove('hidden')
document.getElementById('modal').classList.add('flex')

小程序写法：

// JS
Page({
  data: { showModal: false },
  openModal() { this.setData({ showModal: true }) },
  closeModal() { this.setData({ showModal: false }) }
})

<!-- WXML -->
<view wx:if="{{showModal}}" class="modal-overlay" catchtouchmove bindtap="closeModal">
  <view class="modal-content" catchtap>
    <!-- 弹窗内容 -->
  </view>
</view>

11.3 模式 B：Tab/状态切换

H5 写法：

function switchTab(tabName) {
  document.querySelectorAll('.tab').forEach(t => t.classList.remove('active'))
  document.getElementById('tab-' + tabName).classList.add('active')
}

小程序写法：

Page({
  data: { activeTab: 'basic' },
  onTabChange(e) {
    this.setData({ activeTab: e.currentTarget.dataset.tab })
  }
})

<view class="tab {{activeTab === 'basic' ? 'tab--active' : ''}}"
      data-tab="basic" bindtap="onTabChange">基础课</view>
<view class="tab {{activeTab === 'vip' ? 'tab--active' : ''}}"
      data-tab="vip" bindtap="onTabChange">VIP课</view>

<view wx:if="{{activeTab === 'basic'}}">基础课内容</view>
<view wx:if="{{activeTab === 'vip'}}">VIP课内容</view>

11.4 模式 C：展开/收起

H5 写法：

function toggleExpand(id) {
  const el = document.getElementById(id)
  el.classList.toggle('hidden')
}

小程序写法：

Page({
  data: { expandedSections: {} },
  toggleSection(e) {
    const key = e.currentTarget.dataset.key
    this.setData({ [`expandedSections.${key}`]: !this.data.expandedSections[key] })
  }
})

<view bindtap="toggleSection" data-key="detail">
  <text>{{expandedSections.detail ? '收起' : '展开更多'}}</text>
</view>
<view wx:if="{{expandedSections.detail}}">
  <!-- 展开内容 -->
</view>

11.5 模式 D：内容动态更新

H5 写法：

document.getElementById('total').textContent = '¥12,345'
document.getElementById('list').innerHTML = items.map(i => `<div>${i.name}</div>`).join('')

小程序写法：

Page({
  data: { total: '¥12,345', items: [] },
  loadData() {
    this.setData({
      total: '¥12,345',
      items: [{ name: '台桌' }, { name: '酒水' }]
    })
  }
})

<text>{{total}}</text>
<view wx:for="{{items}}" wx:key="name">
  <text>{{item.name}}</text>
</view>

11.6 模式 E：滚动联动

H5 写法：

window.addEventListener('scroll', () => {
  const currentY = window.scrollY
  if (currentY > 100) {
    filterBar.classList.add('filter-bar-hidden')
  }
})

小程序写法：

Page({
  data: { filterBarVisible: true },
  _lastScrollTop: 0,
  _throttleTimer: null,

  onPageScroll(e) {
    // 节流：避免每帧 setData
    if (this._throttleTimer) return
    this._throttleTimer = setTimeout(() => {
      this._throttleTimer = null
    }, 100)

    const scrollTop = e.scrollTop
    const shouldHide = scrollTop > 100

    // 只在状态真正变化时 setData
    if (shouldHide !== !this.data.filterBarVisible) {
      this.setData({ filterBarVisible: !shouldHide })
    }
  }
})

关键规则：

滚动事件处理函数中必须做节流（100ms 以上）
只在状态真正变化时调用 setData，避免无意义的重渲染
不要在滚动事件中更新大量数据或触发复杂计算

11.7 模式 F：页面导航

H5 写法：

window.location.href = 'task-detail.html?id=123'
history.back()

小程序写法：

// 普通页面跳转
wx.navigateTo({ url: '/pages/task-detail/task-detail?id=123' })

// 返回上一页
wx.navigateBack()

// TabBar 页面跳转
wx.switchTab({ url: '/pages/task-list/task-list' })

// 重定向（替换当前页）
wx.redirectTo({ url: '/pages/login/login' })

关键规则：TabBar 页面（在 app.json 的 tabBar.list 中定义的）必须用 wx.switchTab，用 navigateTo 会静默失败。

12. 浏览器 API → 微信小程序 API 完整映射

12.1 导航

H5 API	小程序 API	说明
`window.location.href = url`	`wx.navigateTo({ url })`	普通页面跳转
`window.location.replace(url)`	`wx.redirectTo({ url })`	替换当前页
`history.back()`	`wx.navigateBack()`	返回上一页
—	`wx.switchTab({ url })`	TabBar 页面跳转（必须用这个）

12.2 滚动

H5 API	小程序 API	说明
`window.scrollY`	`onPageScroll(e)` 中 `e.scrollTop`	页面滚动位置
`window.scrollTo(0, y)`	`wx.pageScrollTo({ scrollTop: y })`	滚动到指定位置
`element.scrollIntoView()`	`scroll-view` 的 `scroll-into-view="{{id}}"`	滚动到指定元素
`element.getBoundingClientRect()`	`wx.createSelectorQuery().select('.cls').boundingClientRect()`	获取元素位置（异步）

12.3 存储

H5 API	小程序 API	说明
`localStorage.setItem(k, v)`	`wx.setStorageSync(k, v)`	同步写入
`localStorage.getItem(k)`	`wx.getStorageSync(k)`	同步读取
`localStorage.removeItem(k)`	`wx.removeStorageSync(k)`	同步删除
`localStorage.clear()`	`wx.clearStorageSync()`	清空全部

12.4 剪贴板

H5 API	小程序 API
`navigator.clipboard.writeText(text)`	`wx.setClipboardData({ data: text })`
`navigator.clipboard.readText()`	`wx.getClipboardData()`

12.5 对话框

H5 API	小程序 API
`alert(msg)`	`wx.showModal({ title: '', content: msg, showCancel: false })`
`confirm(msg)`	`wx.showModal({ title: '提示', content: msg })`
—	`wx.showToast({ title: msg, icon: 'success' })`

12.6 系统信息

需求	小程序 API
状态栏高度	`wx.getSystemInfoSync().statusBarHeight`
屏幕宽度	`wx.getSystemInfoSync().windowWidth`
安全区域	`wx.getSystemInfoSync().safeArea`
底部安全区高度	`screenHeight - safeArea.bottom`

第四部分：执行流程

13. 页面转换的标准执行流程（10 步）

每迁移 1 个页面，都必须按以下顺序执行。

步骤 1：页面资产盘点

输入：HTML / CSS / JS / 图片资源

动作：

抽取页面标题、路由名、入口参数、返回路径
列出页面块：顶部、卡片区、列表区、底部操作区、弹层、浮层、Toast
列出页面状态：默认态、空态、加载态、错误态、选中态、展开态、禁用态
列出页面动效：淡入、位移、缩放、吸顶、滚动联动、长按、评分拖动

输出：页面迁移卡

步骤 2：结构改写为 WXML 语义树

动作：

div → view
文本优先用 text
图片用 image
链接/跳转用 navigator 或 bindtap
表单元素替换为原生小程序组件
列表一律改为 wx:for
条件显示一律改为 wx:if / hidden / 条件 class

禁止：

保留 H5 DOM 层级只是把标签名替换一下
在 text 内嵌套 view
用字符串拼接 HTML 片段

步骤 3：Tailwind 与自定义 CSS 拆解

动作：

先按视觉功能拆成：布局、尺寸、文本、颜色、装饰、状态、动画
再判断每个值使用 rpx 还是 px
统一抽出公共 token，不允许每页各自发散命名

要求：

不保留"一长串 utility class 直接照搬"的中间态
对频繁出现的组合样式抽成语义类，如 .card、.section-title、.tab--active

步骤 4：交互从 DOM 驱动改为数据驱动

动作：

把所有 DOM 查询改成状态变量
把显隐、激活、展开、选中、校验、加载都改成 data 驱动
把滚动联动改成 onPageScroll + 节流 + 仅在状态变化时 setData

输出：状态表

状态表至少包含：

状态变量名
默认值
可选值
受哪个事件修改
影响哪些视图

步骤 5：页面级动效实现

执行规则：

纯显隐 / 透明度 / 位移 / 简单位移动画：优先 transition / animation
需要顺序编排、组合变换、受事件精确驱动：用 wx.createAnimation()
高频交互不要每帧 setData

步骤 6：导航与参数改造

动作：

普通页面：wx.navigateTo
替换当前页：wx.redirectTo
tabBar 页面：wx.switchTab
返回：wx.navigateBack
页面参数：统一在 onLoad(query) 中读取

步骤 7：安全区与导航栏补偿

动作：

禁止使用 env(safe-area-inset-*)
通过系统信息计算状态栏与底部安全区
自定义导航栏页面必须统一实现，不得一页一套

步骤 8：Mock 数据接入

动作：

页面先用 mock 跑通
模板静态文案与后端数据字段分开
所有列表、徽标、状态标签都要有 mock

步骤 9：真机回归与像素微调

动作：

先看 412 宽主验收设备
再看至少一台 375 宽设备
出现不对齐时优先微调局部 px/rpx，不要推翻整体单位策略

步骤 10：记录迁移说明

每页必须输出迁移说明，至少包含：

页面依赖资源
迁移状态变量
高风险点
已做降级项

14. 附录文档索引

14.1 附录清单

位于 docs/miniprogram-dev/New/：

附录索引：h5_to_wechat_miniprogram_migration_bridge_appendix_index_v3.md（v3.1）
附录 A：appendix_a_spacing_and_sizing_dictionary_v3.md - Spacing 与尺寸字典
附录 B：appendix_b_typography_and_text_dictionary_v3.md（v3.1）- 字体与文本字典
附录 C：appendix_c_color_dictionary_v3.md - 颜色字典
附录 D：appendix_d_layout_class_mapping_dictionary_v3.md - 布局类映射字典

14.2 使用方式

AI 使用顺序：

加载本主规范（v3.0）
加载附录索引
按需加载具体附录（A/B/C/D）
执行迁移

开发者使用顺序：

先读本主规范了解整体流程和规则
迁移时查阅附录进行 token 映射
遇到问题时回到主规范查找解决方案

14.3 附录更新记录

v3.1（2026-03-14）：附录 B 补充 text 组件的 line-height 设置规则
v3.0：初始版本，建立附录索引和四个附录字典

📚 完整导航

第一部分：执行规程（§1-4）
- 输入输出契约
- 项目级强制决策
- 能力分级（A/B/C 类）
- Tailwind CSS 行为说明
第二部分：技术换算（§5-9）
- Spacing 换算表
- 字号与行高换算
- 颜色映射
- 布局类映射
- 装饰类映射
第三部分：交互改造（§10-12）
- HTML→WXML 映射
- DOM 操作→数据驱动
- 浏览器 API→小程序 API
第四部分：执行流程（§13-14）
- 10 步标准流程
- 附录文档索引

版本历史

v3.0（2026-03-14）：合并 v1.0 技术换算基础和 v2.0 执行规范，补充 line-height 关键发现
v2.0：执行规范，强化输入输出契约和能力分级
v1.0：技术换算基础，建立完整的映射表

📖 使用建议

对于 AI

首次加载：加载本主规范全文 + 附录索引
执行迁移：按 §13 的 10 步流程执行
查表映射：按需加载附录 A/B/C/D
验证输出：确保符合 §1.2 的输出物要求

对于开发者

快速上手：先读 §1-4 了解规则和决策
技术细节：需要时查阅 §5-12 的换算表
执行迁移：按 §13 的流程逐步完成
问题排查：回到对应章节查找解决方案

文档完整，可以开始迁移！ 🚀

34 KiB Raw Permalink Blame History Unescape Escape

H5 原型 → 微信小程序迁移桥接规范（主规范 v3.0）

📖 文档使用指南

本文档定位

文档结构

配套文档

第一部分：执行规程

1. 输入输出契约

1.1 输入物

1.2 输出物

1.3 不允许的输出

2. 项目级强制决策

2.1 框架与运行时

2.2 验收基准

2.3 单位策略

2.4 页面滚动策略

2.5 样式组织策略

2.6 文本与行高策略 ⚠️

2.7 SVG / 图标策略

3. 能力分级（A/B/C 类）

3.1 A 类：可直接使用

3.2 B 类：有条件使用，必须带回退或验证

3.3 C 类：禁止直迁

4. Tailwind CSS 在本项目中的行为

4.1 Tailwind CSS 渲染机制

4.2 微信 rpx 的精确定义

4.3 本项目的换算链路

📚 快速导航

版本历史

H5 原型 → 微信小程序迁移桥接规范（主规范 v3.0 - 第二部分）

第二部分：技术换算基础

5. Tailwind Spacing → rpx 完整换算表

5.1 Tailwind spacing scale（默认）

6. Tailwind 字号 → WXSS font-size + line-height 完整换算表

6.1 核心规则

6.2 微信小程序 text 组件的 line-height 限制 ⚠️

6.3 标准字号类换算表

6.4 font-weight 映射

6.5 其他文本属性

7. Tailwind 颜色 → WXSS 颜色完整映射

7.1 项目自定义颜色

7.2 透明度变体

8. Tailwind 布局类 → WXSS 完整映射

8.1 Flexbox

8.2 Grid

8.3 Gap（间距）

8.4 定位

8.5 尺寸

9. Tailwind 装饰类 → WXSS 完整映射

9.1 圆角

9.2 阴影

9.3 边框

9.4 渐变

9.5 透明度与模糊

📚 快速导航

H5 原型 → 微信小程序迁移桥接规范（主规范 v3.0 - 第三部分）

第三部分：交互改造

10. HTML 标签 → WXML 组件映射

10.1 基础标签映射

10.2 image 组件的 mode 属性

10.3 事件属性映射

11. JS DOM 操作 → 小程序数据驱动完整映射

11.1 总体原则

11.2 模式 A：显示/隐藏切换

11.3 模式 B：Tab/状态切换

11.4 模式 C：展开/收起

11.5 模式 D：内容动态更新

11.6 模式 E：滚动联动

11.7 模式 F：页面导航

12. 浏览器 API → 微信小程序 API 完整映射

12.1 导航

12.2 滚动

12.3 存储

12.4 剪贴板

12.5 对话框

12.6 系统信息

第四部分：执行流程

13. 页面转换的标准执行流程（10 步）

步骤 1：页面资产盘点

步骤 2：结构改写为 WXML 语义树

34 KiB

Raw Permalink Blame History