raidenfc/my-skills / html-to-miniprogram
html-to-miniprogram
Verified将 HTML/React/Vue 等前端 Demo 页面转换为微信小程序原生开发项目。重点是转换前端页面和简单交互(页面跳转、提醒等),不涉及业务逻辑,数据集中在 mock.js 中管理。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 25.6 KB |
SKILL.md
View on GitHub---
name: html-to-miniprogram
description: 将 HTML/React/Vue 等前端 Demo 页面转换为微信小程序原生开发项目。重点是转换前端页面和简单交互(页面跳转、提醒等),不涉及业务逻辑,数据集中在 mock.js 中管理。
---
# HTML Demo 转微信小程序 Skill
将任意前端 Demo(HTML/React/Vue 单文件或多文件)转换为**微信小程序原生开发**项目,精准还原 UI 和简单交互。
> [!IMPORTANT]
> **转换范围**:仅转换前端页面 UI 和简单交互(页面跳转、Tab 切换、Toast 提醒、弹窗等),**不实现业务逻辑**(如网络请求、用户认证、数据持久化等)。所有页面用到的数据统一整合在 `utils/mock.js` 中管理。
> [!IMPORTANT]
> **交互语言**:与用户的所有对话、确认、提问、说明必须使用**中文**。包括但不限于:任务描述、设计决策询问、进度汇报、问题反馈等。代码中的变量名、文件路径等技术标识符保留英文。
> [!CAUTION]
> **连续执行**:用户确认设计决策(阶段 1)后,阶段 2 ~ 5(生成蓝图、初始化骨架、逐页转换、验证)必须**一口气连续完成**,中间不得暂停等待用户确认。不要在完成几个页面后就停下来汇报进度或请求继续——**所有页面必须连续完成后再进入验证阶段**。只有在遇到**无法自主决策的问题**时才暂停询问用户。
---
## 一、转换流程(按顺序执行)
### 阶段 1:分析源文件 → 确认设计决策
1. **通读 Demo 源码**,提取以下信息:
- **页面数量与路由结构**(识别所有"视图/路由/Tab")
- 组件层级关系
- 样式体系(CSS 变量、设计系统、色板)
- 图标方案(SVG / icon font / 图片),列出所有使用的图标名称和颜色
- 交互逻辑(点击事件、Tab 切换、页面跳转、弹窗提醒等简单交互)
- 数据模型(用于 Mock 数据的结构)
> [!CAUTION]
> **页面提取是最关键的步骤,遗漏页面会导致最终产物缺页。** 必须通过以下方式**交叉验证**,确保不遗漏任何页面:
>
> 1. **路由配置**:检查 Router 配置、hash 路由、Tab 定义等,提取所有注册的路由
> 2. **导航链接**:搜索源码中所有 `href`、`to`、`router.push`、`navigate` 等跳转目标
> 3. **JS 事件跳转**:搜索 `onClick`、`handleClick` 等事件处理函数中的页面跳转逻辑
> 4. **条件渲染的视图**:检查 `v-if`、`v-show`、`{condition && <Component>}` 等条件渲染,识别隐藏的子视图/页面
> 5. **HTML 页面结构**:如果是单 HTML 文件,搜索所有 `section`/`div` 中通过 CSS `display:none` 或 JS 切换显示的独立视图
>
> 分析完成后,**必须明确告知用户总页面数**(如"共发现 13 个页面:4 个 TabBar 页面 + 9 个子页面"),让用户确认是否有遗漏。
2. **在生成蓝图之前,必须先与用户确认以下设计决策**:
> [!CAUTION]
> 以下决策直接影响蓝图内容和后续实现方式,**必须在蓝图创建前完成确认**,避免蓝图与实际执行脱节。
- **页面完整性**:告知用户发现的页面总数和清单,确认是否有遗漏(使用固定模板)
- **TabBar 样式**:系统默认 or 自定义(浮动胶囊等特殊设计需自定义)
- **导航栏样式**:默认 or 自定义
- **图标方案**(向用户说明两种方案的优劣,让用户选择):
- **方案 A:Emoji 占位**(快速原型)— 无需额外资源,开发速度快,适合快速验证布局,后续可替换为真实图标
- **方案 B:SVG 转 PNG 图片** — 视觉效果精准,需要生成图标资源文件,适合对图标质量有要求的项目
页面完整性确认模板(必须原样输出结构):
```markdown
已识别页面总数:N(TabBar: X,子页面: Y)
TabBar 页面:
- pages/xxx/xxx
- pages/xxx/xxx
子页面:
- pages/xxx/xxx
- pages/xxx/xxx
疑似遗漏页面(若无则写“无”):
- ...
```
### 阶段 2:生成转换蓝图
根据阶段 1 的分析结果和用户确认的设计决策,**创建转换蓝图文件** `conversion-blueprint.md`,置于项目根目录。
> [!IMPORTANT]
> 蓝图是整个转换过程的**单一事实来源**。蓝图内容必须与用户确认的设计决策一致。
蓝图包含以下内容:
```markdown
# [项目名] 转换蓝图
## 一、页面清单
| 序号 | 页面名称 | 路径 | 类型 |
|------|---------|------|------|
| 1 | 首页 | pages/home/home | TabBar |
| 2 | 详情页 | pages/detail/detail | 子页面 |
| ... | ... | ... | ... |
## 二、路由结构
- TabBar 页面:[列表]
- 子页面:[列表]
- 页面间跳转关系:[描述]
## 三、组件层级
- 全局组件:[列表]
- 页面私有组件:[列表]
## 四、样式体系
- CSS 变量/设计 Token:[列出关键变量]
- 色板:[主色、辅色、背景色等]
- 字体:[字号体系]
## 五、图标方案:[Emoji / PNG]
<!-- 根据用户选择的方案填写不同内容 -->
### 如果选择 Emoji 方案:
| 原图标名称 | Emoji 字符 | 使用位置 |
|-----------|-----------|--------|
| chevron-left | ‹ | 所有子页面返回按钮 |
| home | 🏠 | TabBar-首页 |
| ... | ... | ... |
### 如果选择 PNG 方案:
| 图标名称 | 颜色 (Hex) | 文件名 | 使用位置 |
|---------|-----------|--------|--------|
| house | #94a3b8 | house.png | TabBar |
| ... | ... | ... | ... |
## 六、交互逻辑
| 交互类型 | 描述 | 所在页面 |
|---------|------|--------|
| Tab 切换 | 底部 TabBar 导航 | 全局 |
| 页面跳转 | 点击卡片进入详情 | 首页 |
| Toast 提醒 | 点击按钮弹出提醒 | ... |
| ... | ... | ... |
## 七、Mock 数据结构
- [列出每个页面需要的 Mock 数据字段和结构]
```
### 阶段 3:初始化项目骨架
> [!IMPORTANT]
> 小程序项目必须生成在一个**单独的 `miniprogram` 文件夹**中,与源 Demo 文件分离,避免混淆。
按以下顺序创建文件:
```
miniprogram/
├── app.js # 全局入口
├── app.json # 页面注册 + TabBar + window 配置
├── app.wxss # 全局样式(CSS 变量 + 工具类)
├── project.config.json
├── sitemap.json
├── custom-tab-bar/ # 如需自定义 TabBar
│ ├── index.js / index.json / index.wxml / index.wxss
├── assets/
│ └── icons/ # 图标资源
├── utils/
│ ├── mock.js # 所有 Mock 数据集中管理
│ └── util.js # 工具函数
└── pages/ # 每个页面 4 个文件
├── page-name/
│ ├── page-name.js
│ ├── page-name.json
│ ├── page-name.wxml
│ └── page-name.wxss
```
> [!IMPORTANT]
> `project.config.json` 必须配置 `"miniprogramRoot": "miniprogram/"`,确保微信开发者工具正确识别源码目录。
### 阶段 4:逐页转换(先 TabBar 页面,再子页面)
- 严格按照蓝图中的页面清单顺序逐页转换
- 所有页面数据从 `utils/mock.js` 引入
- 交互逻辑仅实现简单交互(跳转用 `wx.navigateTo` / `wx.switchTab`,提醒用 `wx.showToast` / `wx.showModal`)
- 业务逻辑部分用 `wx.showToast({ title: '功能开发中', icon: 'none' })` 占位
**单个页面的转换步骤:**
1. **`.json`(配置)**:设置页面标题、导航栏样式、引用的自定义组件等(组件声明是后续 WXML 中使用自定义组件的前提)
2. **`.wxml`(结构)**:对照 Demo 源码逐元素转换,按标签映射表替换标签
3. **`.wxss`(样式)**:迁移对应 CSS,按样式转换规则处理单位、选择器和布局
4. **`.js`(数据 + 交互)**:从 `mock.js` 引入数据,在 `onLoad` 中 `setData`,绑定简单交互事件
### 阶段 5:逐项验证
按照蓝图文件进行逐步验证(详见 **第七节 验证流程**)。
---
## 二、核心转换规则
### 2.1 标签映射
| HTML / React | 微信小程序 | 说明 |
|---|---|---|
| `<div>` | `<view>` | 通用容器 |
| `<span>` / `<p>` | `<text>` | 文本必须包在 text 中 |
| `<img>` | `<image>` | 必须设宽高;常用 mode:`aspectFill`(裁剪填充)、`aspectFit`(完整显示)、`widthFix`(宽度固定高度自适应)、`scaleToFill`(默认拉伸) |
| `<input>` | `<input>` | 保留,但事件名不同 |
| `<textarea>` | `<textarea>` | 原生组件,层级最高 |
| `<button>` | `<button>` / `<view>` | 视需求选择 |
| `<a href>` | `<navigator>` / 事件 | 小程序无 a 标签 |
| `<ul>` / `<li>` | `<view>` + `wx:for` | 列表渲染 |
| `<svg>` | ❌ 不支持 | 用 image 替代(见图标方案)|
| `<select>` | `<picker>` | 选择器组件 |
| `<form>` | `<form>` | 保留,事件名变化 |
| `<scroll-view>` | `<scroll-view>` | 必须设固定高度才能滚动 |
| 轮播图(JS 库) | `<swiper>` + `<swiper-item>` | 内置轮播组件,支持自动播放和循环 |
| `<video>` | `<video>` | 原生组件,需用 cover-view 覆盖 |
| `<audio>` | `<audio>` / `wx.createInnerAudioContext` | 推荐用 API 方式 |
| `<input type="radio">` | `<radio-group>` + `<radio>` | 单选框 |
| `<input type="checkbox">` | `<checkbox-group>` + `<checkbox>` | 多选框 |
| toggle / switch | `<switch>` | 开关组件 |
| `<input type="range">` | `<slider>` | 滑块组件 |
| 富文本 HTML 内容 | `<rich-text nodes="{{html}}">` | 支持部分 HTML 标签渲染 |
| 覆盖原生组件的浮层 | `<cover-view>` / `<cover-image>` | 用于覆盖 video 等原生组件 |
### 2.2 事件映射
| Web 事件 | 小程序事件 | 说明 |
|---|---|---|
| `onClick` | `bindtap` | 点击事件(冒泡) |
| `onClick`(阻止冒泡) | `catchtap` | 点击事件(阻止冒泡) |
| 长按 | `bindlongpress` | 超过 350ms 触发,推荐代替 longtap |
| `onTouchStart` | `bindtouchstart` | 手指触摸开始 |
| `onTouchMove` | `bindtouchmove` | 手指触摸后移动 |
| `onTouchEnd` | `bindtouchend` | 手指触摸结束 |
| `onChange`(input) | `bindinput` | 输入框内容变化 |
| `onChange`(picker/switch) | `bindchange` | picker、switch、slider 等值变化 |
| `onFocus` | `bindfocus` | 输入框获取焦点 |
| `onBlur` | `bindblur` | 输入框失去焦点 |
| `onSubmit` | `bindsubmit` | 表单提交 |
| `onScroll` | `bindscroll` | 滚动事件(scroll-view) |
| `onLoad`(img) | `bindload` | 图片/视频加载成功 |
| `onError`(img) | `binderror` | 图片/视频加载失败 |
**属性映射**(非事件,但转换时同样重要):
| Web 属性 | 小程序属性 | 说明 |
|---|---|---|
| `className` | `class` | 类名属性 |
| `style={{}}` | `style=""` | 内联样式(字符串格式) |
| `dangerouslySetInnerHTML` | `<rich-text nodes>` | 富文本渲染 |
| `hidden` / `v-show` | `hidden="{{bool}}"` | 控制显隐(不销毁节点,比 `wx:if` 性能更好适合频繁切换) |
| `data-*` | `data-*` | 自定义数据属性,通过 `e.currentTarget.dataset` 获取 |
> [!TIP]
> **事件冒泡机制**:`bind` 前缀允许事件冒泡,`catch` 前缀阻止冒泡。需要阻止父元素响应事件时用 `catch`(如弹窗遮罩的点击穿透问题)。
### 2.3 样式转换(CSS → WXSS)
**核心规则:**
1. **单位转换**:`px` → `rpx`(1px = 2rpx),除以下情况保留 `px`:
- `border`:细边框保留 `1px`(避免在高分屏上过粗),粗边框正常按 1px=2rpx 换算
- 与系统 API 返回值配合的尺寸(如 statusBarHeight)
- `font-size` 可酌情使用 `rpx` 或 `px`
2. **选择器支持情况**:
- ✅ 类选择器(`.class {}`)
- ✅ ID 选择器(`#id {}`)
- ✅ 后代选择器、子选择器(`>`)、兄弟选择器(`~`、`+`)
- ✅ 伪类:`:active`、`:first-child`、`:last-child`、`:not`、`:nth-child`
- ✅ 伪元素:`::before`、`::after`(仅这两个)
- ❌ 标签选择器(`div {}`, `span {}`)
- ❌ `*` 通配符选择器
- ❌ 属性选择器(`[attr]`、`[type="text"]`)
3. **不支持或受限的布局属性**:
- ⚠️ `float`:支持但在 Flex 容器内失效,**推荐用 Flex 布局替代**
- ⚠️ `display: inline-block`:行为可能与 Web 不完全一致,**推荐用 Flex 布局替代**
- ⚠️ `position: fixed`:支持,但父元素有 `transform` 时会失效;仅支持相对视口定位
- ⚠️ `overflow: scroll`:支持不稳定且受渲染引擎影响,**推荐使用 `<scroll-view>` 组件**实现可靠滚动
- ❌ WXSS 中不支持引入**本地字体文件和本地图片**,必须使用在线资源或 Base64 编码
4. **支持的现代 CSS**:
- ✅ `display: flex` 全系列(**推荐首选布局方式**)
- ✅ `display: grid` / `grid-template-columns`
- ✅ `backdrop-filter: blur()`
- ✅ `linear-gradient()`
- ✅ `box-shadow`
- ✅ CSS 变量 `var(--xxx)`(在 `page {}` 中定义,非 `:root`)
- ✅ `border-radius`
- ✅ `position: sticky`
- ✅ `@import` 导入外部样式表
5. **Tailwind CSS 迁移**:将工具类转为等效 WXSS:
- 提取颜色为 CSS 变量定义在 `app.wxss` 的 `page {}` 选择器中
- 将 `flex`, `grid`, `gap`, `rounded` 等转为对应属性
- `hover:` 伪类可用 `.active` 类 + `bindtouchstart/end` 模拟,或省略
6. **全局样式策略**:
- CSS 变量定义在 `app.wxss` 的 `page {}` 中(**不是 `:root`**)
- 通用工具类(flex 布局、文本截断等)定义在 `app.wxss`
- 页面私有样式写在各自的 `.wxss` 文件中
- 自定义组件默认启用**样式隔离**,组件内外样式互不影响
### 2.4 路由与导航
| Web 路由方式 | 小程序对应 |
|--------------------------|------------------------------|
| React Router / hash 路由 | `app.json` 的 `pages` 注册 |
| Tab 切换 | `wx.switchTab({ url })` |
| 页面跳转 | `wx.navigateTo({ url })` |
| 页面重定向(替换当前页) | `wx.redirectTo({ url })` |
| 返回上一页 | `wx.navigateBack()` |
| 参数传递(query string) | `options` 参数 / `globalData` |
**路由类型判断:**
- 底部 Tab 对应的页面 → 注册为 TabBar 页面
- 其他页面 → 注册为普通页面
- Tab 间跳转必须用 `switchTab`,不能用 `navigateTo`
> [!WARNING]
> **页面栈限制**:小程序页面栈最多 **10 层**,超过后 `navigateTo` 会失败。深层级跳转考虑用 `redirectTo`(替换当前页,不增加栈)。
### 2.5 数据与逻辑
| Web 概念 | 小程序对应 |
|----------------------------|-----------------------------------|
| `useState` / `data()` | `Page({ data: {} })` |
| `setState` / 赋值 | `this.setData({ key: value })` |
| `useEffect` / `mounted` | `onLoad()` / `onShow()` |
| `props` | 组件的 `properties` |
| `context` / `provide` | `getApp().globalData` |
| `fetch` / `axios` | Mock 数据直接引入(不实现真实请求)|
| `localStorage` | `wx.setStorageSync()` / `getStorageSync()` |
| 条件渲染 `{cond && <X/>}` | `wx:if="{{cond}}"` |
| 列表渲染 `.map()` | `wx:for="{{list}}" wx:key="id"` |
| 模板字符串 | `{{}}` 数据绑定 |
> [!TIP]
> **`wx:key` 用法**:值为列表项的**属性名字符串**(不加 `item.` 前缀),如 `wx:key="id"`。如果列表项本身是唯一字符串/数字,可用 `wx:key="*this"`。不设 `wx:key` 会触发警告且影响渲染性能。
**Mock 数据策略:**
> [!NOTE]
> 所有页面数据统一在 `utils/mock.js` 中定义和导出,页面 JS 通过 `const mock = require('../../utils/mock.js')` 引入,在 `onLoad` 中 `setData`。**不实现 `wx.request` 等网络请求**。
### 2.6 图标处理方案
微信小程序**不支持 SVG 标签**,需要替换方案。图标方案应在**阶段 1 中与用户确认**,蓝图内容根据用户选择适配。
#### 方案 A:Emoji 占位(快速原型)
使用 Emoji 字符代替图标,无需额外资源文件,适合快速验证布局。
**实施规范:**
1. **全局样式**:在 `app.wxss` 中定义通用 Emoji 图标类:
```css
/* Emoji 图标通用样式 */
.emoji-icon {
display: inline-flex;
align-items: center;
justify-content: center;
text-align: center;
line-height: 1;
}
```
2. **WXML 写法**:使用 `<text>` 标签包裹 Emoji,同时添加 `emoji-icon` 基础类和具体图标类:
```html
<!-- 返回按钮(使用 Unicode 字符) -->
<text class="emoji-icon back-icon">‹</text>
<!-- 普通 Emoji 图标 -->
<text class="emoji-icon phone-icon">📞</text>
<!-- 右箭头 -->
<text class="emoji-icon arrow-icon">›</text>
```
3. **WXSS 规则**:图标样式使用 `font-size` 控制大小(**不是** `width`/`height`):
```css
/* ✅ 正确:用 font-size 控制 Emoji 大小 */
.back-icon {
font-size: 56rpx;
color: var(--slate-800);
}
/* ❌ 错误:width/height 对文本无效 */
.back-icon {
width: 52rpx;
height: 52rpx;
}
```
4. **常用 Emoji 映射参考**:
| 原图标用途 | 推荐 Emoji / 字符 | 说明 |
|-----------|------------------|------|
| 返回按钮 | `‹`(U+2039) | Unicode 单左尖括号,比 `<` 更美观 |
| 右箭头 | `›`(U+203A) | Unicode 单右尖括号 |
| 首页 | 🏠 | |
| 搜索 | 🔍 | |
| 用户/头像 | 👤 | |
| 设置 | ⚙️ | |
| 电话 | 📞 | |
| 编辑 | ✏️ | |
| 删除 | 🗑️ | |
| 添加 | ➕ | |
| 已认证/通过 | ✅ | |
| 禁止/下架 | 🚫 | |
| 文档 | 📄 | |
| 日历 | 📅 | |
| 位置 | 📍 | |
| 图表 | 📊 | |
> [!TIP]
> 蓝图中应包含完整的**图标名称 → Emoji 字符映射表**,确保全项目一致性。
#### 方案 B:SVG 转 PNG 图片
如果用户选择精准视觉还原,使用以下工具将 SVG 图标转换为 PNG:
**工具 1:Shell 脚本方式(`generate_icons.sh`)**
从 Lucide 等图标库下载 SVG,替换颜色后用 `sips` 转为 PNG:
```bash
#!/bin/bash
set -euo pipefail
# 定义图标数组,格式:"图标名:颜色:文件名"
ICONS=(
"house:#94a3b8:house.png"
"house:#ffffff:house-active.png"
# ... 按蓝图中的图标清单填写
)
mkdir -p miniprogram/assets/icons
for item in "${ICONS[@]}"; do
IFS=':' read -r name color filename <<< "$item"
if ! curl -s -L -f "https://unpkg.com/lucide-static@latest/icons/$name.svg" -o temp.svg; then
echo "下载失败: $name" >&2
continue
fi
sed "s/currentColor/$color/g" temp.svg > colored.svg
sips -s format png colored.svg --out "miniprogram/assets/icons/$filename" -z 64 64 > /dev/null
rm temp.svg colored.svg
done
```
> [!NOTE]
> 上述脚本依赖 `sips`(macOS)。非 macOS 环境可改用 `magick colored.svg "miniprogram/assets/icons/$filename"` 生成 PNG。
**工具 2:HTML 页面方式(`icon_generator.html`)**
在浏览器中用 Lucide JS 库渲染 SVG 到 Canvas,导出 PNG 的 base64 数据:
```javascript
const ICONS_TO_GENERATE = [
{ name: 'house', color: '#94a3b8', filename: 'house.png' },
// ... 按蓝图中的图标清单填写
];
// 通过 Canvas 绘制 SVG 并导出 base64 PNG
```
> [!TIP]
> 两种工具可按需在项目的 `tools/` 目录下创建,根据蓝图中的图标清单填充具体的图标列表。
---
## 三、自定义 TabBar 实现要点
当 Demo 的 TabBar 不是标准样式时(如浮动胶囊、异形底栏),需使用自定义 TabBar:
1. `app.json` 中设置 `"tabBar": { "custom": true, ... }`
2. 在项目根目录创建 `custom-tab-bar/` 组件(固定路径名)
3. 每个 TabBar 页面的 `onShow` 中更新选中态:
```javascript
onShow() {
if (typeof this.getTabBar === 'function' && this.getTabBar()) {
this.getTabBar().setData({ selected: 0 }) // 当前页索引
}
}
```
4. **注意**:即使 `custom: true`,`app.json` 的 `tabBar.list` 仍需完整配置(框架要求)
---
## 四、自定义导航栏实现要点
当页面需要自定义顶部导航栏(渐变背景、大标题等):
1. 页面 JSON 设置 `"navigationStyle": "custom"`
2. `app.js` 的 `onLaunch` 中获取系统信息:
```javascript
const systemInfo = wx.getWindowInfo()
this.globalData.statusBarHeight = systemInfo.statusBarHeight
const menuButton = wx.getMenuButtonBoundingClientRect()
this.globalData.navBarHeight = (menuButton.top - systemInfo.statusBarHeight) * 2 + menuButton.height
```
3. 页面顶部避让状态栏时,使用数据绑定到 `style`(不要把 `{{}}` 写进 `.wxss`):
```html
<view class="nav-wrap" style="padding-top: {{statusBarHeight}}px;">
...
</view>
```
```javascript
const app = getApp()
Page({
data: { statusBarHeight: 0 },
onLoad() {
this.setData({ statusBarHeight: app.globalData.statusBarHeight || 0 })
}
})
```
---
## 五、Mock 数据管理
所有页面数据集中在 `utils/mock.js` 中管理:
```javascript
// utils/mock.js
// 首页数据
const homeData = {
banners: [ /* ... */ ],
categories: [ /* ... */ ],
hotItems: [ /* ... */ ],
};
// 其他页面数据...
const profileData = { /* ... */ };
module.exports = {
homeData,
profileData,
// ...
};
```
**页面中引用方式:**
```javascript
// pages/home/home.js
const mock = require('../../utils/mock.js')
Page({
data: {},
onLoad() {
this.setData(mock.homeData)
},
// 简单交互
onItemTap(e) {
const id = e.currentTarget.dataset.id
wx.navigateTo({ url: `/pages/detail/detail?id=${id}` })
},
onButtonTap() {
wx.showToast({ title: '功能开发中', icon: 'none' })
}
})
```
---
## 六、常见陷阱与注意事项
1. **文本必须包裹在 `<text>` 中**,裸文本在某些场景样式不生效
2. **`wx:for` 的默认变量**是 `item` 和 `index`,可通过 `wx:for-item` / `wx:for-index` 重命名
3. **`image` 组件必须设宽高**,否则默认 320×240
4. **WXSS 不支持标签选择器**,所有样式必须用类选择器
5. **`scroll-view` 必须设固定高度**才能触发滚动
6. **页面文件名与文件夹名必须一致**:`pages/home/home.js`
7. **小程序包体积限制 2MB**(主包),大图片应使用网络地址
8. **`textarea` 是原生组件**,层级最高,样式覆盖需注意
9. **CSS 动画支持有限**,复杂动画推荐使用关键帧动画 `this.animate()` 或 WXS 响应事件(`wx.createAnimation()` 已不推荐使用)
10. **数据绑定是单向的**,表单双向绑定需手动 `bindinput` + `setData`
11. **`setData` 性能**:单次 `setData` 数据量不宜过大,避免传入整个大对象;尽量只更新变化的字段
12. **`wx:if` vs `hidden`**:`wx:if` 会销毁/重建节点,`hidden` 仅控制显隐不销毁。频繁切换时用 `hidden` 性能更好
13. **`onLoad` vs `onShow`**:`onLoad` 仅在页面首次加载时执行一次,`onShow` 每次页面显示都执行(TabBar 页面切换回来时也会触发 `onShow`)
---
## 七、验证流程
完成所有页面转换后,结合蓝图文件 `conversion-blueprint.md` 进行逐项验证:
### 7.1 页面完整性验证
逐一核对蓝图中的**页面清单**,确认:
- [ ] 每个页面的 4 个文件(.js / .json / .wxml / .wxss)是否齐全
- [ ] `app.json` 中页面注册是否完整
- [ ] TabBar 配置是否正确
### 7.2 路由验证
核对蓝图中的**路由结构**,确认:
- [ ] TabBar 页面间切换正常(`switchTab`)
- [ ] 子页面跳转正常(`navigateTo`)
- [ ] 页面返回正常(`navigateBack`)
- [ ] 参数传递正确
### 7.3 样式验证
核对蓝图中的**样式体系**,确认:
- [ ] CSS 变量定义完整(对照色板和设计 Token)
- [ ] 全局工具类齐全
- [ ] 各页面视觉还原度与 Demo 一致
### 7.4 图标验证
核对蓝图中的**图标清单**,根据所选方案进行验证:
**Emoji 方案验证项:**
- [ ] `app.wxss` 中已定义 `.emoji-icon` 全局样式
- [ ] 所有**图标类** `<image>` 标签已替换为 `<text class="emoji-icon ...">` 标签(非图标的图片如 banner、头像等仍使用 `<image>`)
- [ ] Emoji 字符与蓝图映射表一致
- [ ] WXSS 中图标样式使用 `font-size`(非 `width`/`height`)
- [ ] 各页面 Emoji 显示正常、对齐无偏移
**PNG 方案验证项:**
- [ ] 所有图标资源文件存在于 `assets/icons/`
- [ ] 图标颜色和尺寸正确
- [ ] 各页面中图标引用路径正确
### 7.5 交互验证
核对蓝图中的**交互逻辑**,确认:
- [ ] 所有简单交互(跳转、切换、提醒)正常工作
- [ ] 业务逻辑部分已用 Toast 占位
- [ ] Mock 数据正确显示
### 7.6 数据验证
核对蓝图中的 **Mock 数据结构**,确认:
- [ ] `utils/mock.js` 包含所有页面的数据
- [ ] 各页面数据引用和渲染正确
> [!TIP]
> 验证过程中每完成一项,仅在 `conversion-blueprint.md` 的验证清单中标记 `[x]`。发现问题立即修复后再继续。
---
## 八、执行优先级
转换时按以下优先级推进:
1. **先蓝图后编码**:先完成阶段 1 的分析蓝图,确认后再开始编码
2. **先骨架后血肉**:先创建项目配置和全局样式,再逐页转换
3. **先 TabBar 后子页面**:TabBar 页面是主入口,优先实现
4. **先 UI 后交互**:先精准还原 UI 和样式,再接入简单交互和 Mock 数据
5. **先整体后细节**:先保证页面结构正确,再微调间距、颜色、阴影等
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |