` | `` | 文本必须包在 text 中 | | `` | `` | 必须设宽高；常用 mode：`aspectFill`（裁剪填充）、`aspectFit`（完整显示）、`widthFix`（宽度固定高度自适应）、`scaleToFill`（默认拉伸） | | `` | `` | 保留，但事件名不同 | | `` | `<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. **先整体后细节**：先保证页面结构正确，再微调间距、颜色、阴影等