1029 lines
28 KiB
Markdown
1029 lines
28 KiB
Markdown
# H5 原型迁移到微信小程序页面手册（PRD + 技术规范）
|
||
|
||
版本：v1.0
|
||
适用项目：球房运营助手 H5 原型 → 原生微信小程序页面
|
||
依据：对上传原型代码包的静态审阅（24 个 HTML 页面、6 个 CSS、8 个 JS、1 个图片资源）+ 微信小程序 / Tailwind 官方文档调研
|
||
|
||
---
|
||
|
||
## 1. 文档目标
|
||
|
||
本手册用于指导将现有 H5 原型页面迁移为**原生微信小程序页面**，目标是：
|
||
|
||
1. 仅关注**前端页面层**迁移，不讨论后端真实联调。
|
||
2. 除字体渲染差异外，尽量做到**视觉样式、布局、动效、交互反馈的 1:1 还原**。
|
||
3. 当前原型的验收基准设备等效宽度为 **412px**，迁移后以该宽度为第一验收基准。
|
||
4. 先完成 Tailwind/H5 表达方式到 WXML/WXSS/小程序 JS 的等价改写，再进入接口联调阶段。
|
||
|
||
---
|
||
|
||
## 2. 原型项目现状审阅结论
|
||
|
||
### 2.1 页面与模块盘点
|
||
|
||
经静态审阅，原型共包含以下主要页面：
|
||
|
||
#### 账号与权限
|
||
- `login.html` 登录
|
||
- `apply.html` 账号申请
|
||
- `reviewing.html` 审核中
|
||
- `no-permission.html` 无权限
|
||
- `home-settings.html` 首页设置
|
||
- `my-profile.html` 我的
|
||
|
||
#### 任务与客户维护
|
||
- `task-list.html` 任务列表
|
||
- `task-detail.html` 任务详情（主版）
|
||
- `task-detail-priority.html` 任务详情（优先召回）
|
||
- `task-detail-callback.html` 任务详情（客户回访）
|
||
- `task-detail-relationship.html` 任务详情（关系构建）
|
||
- `notes.html` 备注
|
||
- `chat.html` 助手对话
|
||
- `chat-history.html` 助手对话记录
|
||
|
||
#### 看板与数据
|
||
- `board-finance.html` 财务看板
|
||
- `board-customer.html` 客户看板
|
||
- `board-coach.html` 助教看板
|
||
|
||
#### 业绩与服务
|
||
- `performance.html` 业绩详情
|
||
- `performance-records.html` 业绩明细
|
||
- `customer-service-records.html` 客户服务记录
|
||
- `coach-detail.html` 助教详情
|
||
- `customer-detail.html` 客户详情
|
||
|
||
#### 其他
|
||
- `benchmark.html` 基准测试页
|
||
- `ai-icon-demo.html` AI 图标演示页
|
||
|
||
### 2.2 Tailwind 使用特征（基于代码扫描）
|
||
|
||
项目中 Tailwind 用法整体偏“静态 UI utility class”，迁移难度低于常见 React/Vue + Tailwind 项目：
|
||
|
||
- 唯一 class 数约 **788**。
|
||
- 大多数是**基础 utility**，如：`flex`、`px-4`、`rounded-xl`、`text-sm`、`shadow-sm`、`bg-white`。
|
||
- 存在少量 **arbitrary value**，如：
|
||
- `text-[9px]`
|
||
- `top-[44px]`
|
||
- `flex-[2]`
|
||
- `max-h-[70vh]`
|
||
- 存在少量状态变体：
|
||
- `hover:*`
|
||
- `focus:*`
|
||
- `active:*`
|
||
- `group-hover:*`
|
||
- **几乎未发现响应式断点类**（例如 `sm:` / `md:` / `lg:`），这对小程序迁移是利好。
|
||
- 页面还混用了较多**内联 style**与页面内 `<style>` 自定义 CSS。
|
||
- 交互主要依赖：
|
||
- `onclick`
|
||
- `addEventListener`
|
||
- `querySelector`
|
||
- `classList`
|
||
- `getBoundingClientRect`
|
||
- `window.scrollY`
|
||
- `history.back()`
|
||
|
||
### 2.3 项目级风险判断
|
||
|
||
**结论：可迁移，而且是中等复杂度，不是高危重构。**
|
||
|
||
原因：
|
||
|
||
1. Tailwind 并没有被用到很深的响应式系统，主要是静态视觉表达。
|
||
2. 大量视觉效果本质仍是普通 CSS：圆角、阴影、渐变、sticky、safe-area、卡片、标签、徽章、列表。
|
||
3. 真正需要重写的是**DOM 事件与状态切换方式**，不是颜色和间距本身。
|
||
4. 高风险点集中在：
|
||
- 安全区与导航高度
|
||
- 长按菜单
|
||
- 滚动联动吸顶/隐藏筛选栏
|
||
- 评分拖动
|
||
- 动画/过渡
|
||
- `hover/group-hover/backdrop-blur/sticky` 等特性在小程序上的表现差异
|
||
|
||
---
|
||
|
||
## 3. 迁移目标定义（PRD 口径）
|
||
|
||
## 3.1 目标
|
||
|
||
将现有 H5 原型页面迁移为原生微信小程序页面，满足以下目标：
|
||
|
||
### A. 视觉目标
|
||
- 在验收基准机型（等效宽度 412px）上，页面视觉与原型对齐。
|
||
- 除字体渲染差异外，颜色、圆角、阴影、间距、层级、边框、图标、插画、Safe Area 处理必须尽可能一致。
|
||
- 卡片、标签、列表、弹窗、Toast、浮层、筛选器、看板区块的版式必须保持一致。
|
||
|
||
### B. 交互目标
|
||
- 页面切换逻辑、点击反馈、弹窗开合、滚动联动、吸顶、长按、复制、备注填写、评分、筛选切换等交互必须在小程序中按原型还原。
|
||
- 原型中的 CSS 动画 / 过渡动画，优先使用 WXSS transition/animation 或小程序动画 API 还原。
|
||
- 关键路径交互不允许出现明显掉帧、闪烁、层级错乱。
|
||
|
||
### C. 工程目标
|
||
- 不在小程序中继续依赖 Tailwind 运行时。
|
||
- 页面最终产物为：`wxml + wxss + js + json` 的原生页面结构。
|
||
- 建立统一设计 token、页面骨架规范、组件命名规范、数据字段命名规范。
|
||
- 为后续接口联调预留稳定的数据结构。
|
||
|
||
### D. 非目标
|
||
- 本阶段不做后端真实联调。
|
||
- 本阶段不处理业务规则正确性，只保证页面需要的数据结构和状态位定义完整。
|
||
- 本阶段不追求“复用 H5 DOM 代码”，而追求“可维护的小程序产物”。
|
||
|
||
---
|
||
|
||
## 4. 微信小程序技术边界（必须纳入迁移设计）
|
||
|
||
微信小程序的页面由 `WXML + WXSS + JS + JSON` 构成；其中 WXML 负责结构，WXSS 负责样式，JS 负责逻辑与数据更新。小程序运行环境分为**逻辑层**和**渲染层**，二者分线程管理，通信通过宿主转发，因此 Web DOM 式写法不能直接照搬。
|
||
参考：
|
||
- WXML 模板：https://www.tencentcloud.com/zh/document/product/1219/60345
|
||
- WXSS 样式：https://www.tencentcloud.com/zh/document/product/1219/60346
|
||
- 小程序宿主环境：https://www.tencentcloud.com/zh/document/product/1219/61737
|
||
|
||
### 4.1 必须接受的基础事实
|
||
|
||
1. **不能直接操作浏览器 DOM**
|
||
- H5 中的 `document.querySelector`、`classList.add/remove`、`createElement`、`history.back()` 都不能原样迁入。
|
||
- 需要改为：
|
||
- 结构：WXML 条件渲染 / 列表渲染
|
||
- 事件：`bindtap`、`bindinput`、`catchtouchmove` 等
|
||
- 状态：`setData` / 页面数据驱动
|
||
- 导航：`wx.navigateTo` / `wx.navigateBack`
|
||
|
||
2. **WXSS 不是完整 CSS**
|
||
- 支持类选择器、id 选择器、元素选择器、`::before`、`::after`，但选择器能力明显比 Web 更保守。
|
||
- 复杂后代/兄弟选择器、依赖 hover 链路的样式方案，不应作为主要实现方式。
|
||
- 样式应尽量转成“显式 class + 数据状态位”。
|
||
|
||
3. **尺寸体系建议转为 rpx**
|
||
- WXSS 引入 `rpx`，在 375 物理像素宽度下 `1rpx = 1px`，用于适配不同屏宽。
|
||
- 你的验收基准是 **412px**，因此本项目建议建立“412px 原型稿 → rpx”的专用换算规则，而不是照抄 375 的 H5 px 值。
|
||
|
||
4. **动画可用，但实现方式要改**
|
||
- 简单过渡优先用 WXSS transition/animation。
|
||
- 复杂过程动画可用 `wx.createAnimation`。
|
||
- 官方说明中也明确提示：连续用 `setData` 做动画通常会造成延迟或卡顿，应避免作为常规方案。
|
||
- 参考：
|
||
- 动画 API：https://www.tencentcloud.com/zh/document/product/1219/57764
|
||
- 渲染层 / 动画说明：https://www.tencentcloud.com/zh/document/product/1219/61744
|
||
|
||
5. **调试方式不同于浏览器**
|
||
- 小程序开发者工具提供 Wxml、Network、Appdata、Mock、Compatibility 等能力；Wxml 面板可实时查看转换后的页面结构和样式。
|
||
- 参考：https://www.tencentcloud.com/zh/document/product/1219/61764
|
||
|
||
---
|
||
|
||
## 5. 适配基线：以 412px 为验收稿的尺寸换算规范
|
||
|
||
## 5.1 换算原则
|
||
|
||
原型验收基准宽度：**412px**
|
||
小程序全宽：**750rpx**
|
||
|
||
因此推荐主换算公式：
|
||
|
||
```text
|
||
rpx = H5_px × (750 / 412)
|
||
≈ H5_px × 1.820388
|
||
```
|
||
|
||
常用换算表：
|
||
|
||
| H5 px | WXSS rpx（建议） |
|
||
|---|---:|
|
||
| 1 | 2rpx |
|
||
| 2 | 4rpx |
|
||
| 4 | 8rpx |
|
||
| 6 | 11rpx |
|
||
| 8 | 15rpx |
|
||
| 10 | 18rpx |
|
||
| 12 | 22rpx |
|
||
| 14 | 25rpx |
|
||
| 16 | 29rpx |
|
||
| 18 | 33rpx |
|
||
| 20 | 36rpx |
|
||
| 24 | 44rpx |
|
||
| 28 | 51rpx |
|
||
| 32 | 58rpx |
|
||
| 36 | 66rpx |
|
||
| 40 | 73rpx |
|
||
| 44 | 80rpx |
|
||
| 48 | 87rpx |
|
||
|
||
## 5.2 尺寸使用建议
|
||
|
||
### 推荐用 rpx 的场景
|
||
- 宽高
|
||
- padding / margin
|
||
- 圆角
|
||
- 定位偏移
|
||
- 字号（多数文本）
|
||
- 列表项高度
|
||
- 卡片尺寸
|
||
- 筛选器高度
|
||
- 顶部安全区以下的视觉结构
|
||
|
||
### 保留 px 的场景
|
||
- 1px 发丝线（边框）
|
||
- 阴影模糊半径微调
|
||
- 小图标描边
|
||
- 少量动画位移的精细校准
|
||
- 受宿主影响的真实像素边界校准
|
||
|
||
### 禁止做法
|
||
- 页面里同时大量混用 px / rpx / rem / vw / vh，导致统一性失控。
|
||
- 直接把 Tailwind `px-*` 数值等比抄到 WXSS 中。
|
||
- 不经校准地把 `top-[44px]`、`text-[9px]` 这类 arbitrary value 逐个硬搬。
|
||
|
||
---
|
||
|
||
## 6. Tailwind → WXSS 的迁移策略
|
||
|
||
Tailwind 本身是根据源码中的类名生成 CSS，而不是一张固定大样式表；同时它支持 `@apply` 将 utility 内联为普通 CSS 类。
|
||
参考：
|
||
- Styling with utility classes：https://tailwindcss.com/docs/styling-with-utility-classes
|
||
- Functions and directives (`@apply`)：https://tailwindcss.com/docs/functions-and-directives
|
||
- Responsive design：https://tailwindcss.com/docs/responsive-design
|
||
- Hover/focus/states：https://tailwindcss.com/docs/hover-focus-and-other-states
|
||
|
||
## 6.1 不建议的做法
|
||
|
||
### 方案 X：逐页面手工把 class 翻译成散装 WXSS
|
||
问题：
|
||
- 重复劳动巨大
|
||
- 样式 token 不统一
|
||
- 后续维护困难
|
||
- 同一个 `rounded-xl` 会被翻译成多个版本
|
||
|
||
## 6.2 建议的做法
|
||
|
||
### 方案 Y：先做“语义层收敛”，再做 WXSS 落地
|
||
|
||
步骤：
|
||
|
||
1. **抽取设计 token**
|
||
- 颜色
|
||
- 间距
|
||
- 字号
|
||
- 圆角
|
||
- 阴影
|
||
- 层级
|
||
- 渐变
|
||
- 安全区参数
|
||
|
||
2. **抽取公共组件 class**
|
||
- `card`
|
||
- `tag`
|
||
- `metric`
|
||
- `section-title`
|
||
- `filter-chip`
|
||
- `sheet`
|
||
- `modal`
|
||
- `toast`
|
||
- `avatar`
|
||
- `list-cell`
|
||
- `sticky-bar`
|
||
|
||
3. **将 Tailwind utility 合并成语义类**
|
||
- 例如：
|
||
- `bg-white rounded-xl shadow-sm p-4` → `.card`
|
||
- `px-2 py-0.5 text-xs rounded-full` → `.pill`
|
||
- `flex items-center justify-between` → `.row-between`
|
||
|
||
4. **在小程序侧用语义类重新实现**
|
||
- 不是把 `px-4 py-3 text-sm` 直接变成 `.px-4` `.py-3` `.text-sm` 的 utility 体系。
|
||
- 而是重新组织为“组件样式 + 状态类”。
|
||
|
||
## 6.3 Tailwind 映射原则
|
||
|
||
### 低风险：可以直接映射
|
||
- `flex` / `items-center` / `justify-between`
|
||
- `rounded-*`
|
||
- `shadow-*`
|
||
- `border`
|
||
- `text-*`
|
||
- `font-*`
|
||
- `bg-*`
|
||
- `p-*` / `m-*`
|
||
- `w-*` / `h-*`
|
||
- `overflow-hidden`
|
||
- `truncate`
|
||
- `absolute` / `relative`
|
||
- `z-*`
|
||
|
||
### 中风险：需要验收校准
|
||
- `sticky`
|
||
- `backdrop-blur-*`
|
||
- 渐变背景
|
||
- `min-h-screen`
|
||
- `object-cover`
|
||
- 安全区相关 `env(safe-area-inset-*)`
|
||
- 精细字号（`text-[9px]` 等）
|
||
|
||
### 高风险：必须改写交互方案
|
||
- `hover:*`
|
||
- `group-hover:*`
|
||
- `focus:*`
|
||
- `active:*`（要确认组件是否支持按压态或改为显式状态）
|
||
- 依赖复杂结构关系的选择器
|
||
- 任意复杂 selector / arbitrary variant
|
||
- 用 DOM 操作实现的 class 切换
|
||
|
||
---
|
||
|
||
## 7. 页面结构迁移规范
|
||
|
||
## 7.1 HTML → WXML 标签映射
|
||
|
||
建议的基础映射：
|
||
|
||
| H5 标签 | 小程序建议组件 |
|
||
|---|---|
|
||
| `div` | `view` |
|
||
| `span` | `text` 或 `view` |
|
||
| `img` | `image` |
|
||
| `a` | `navigator` 或 `view + bindtap` |
|
||
| `button` | `button` 或 `view + bindtap` |
|
||
| `input` | `input` |
|
||
| `textarea` | `textarea` |
|
||
| `svg` | 优先转图片 / iconfont / 组件化 SVG 方案 |
|
||
|
||
说明：
|
||
- 你的原型中 SVG 使用非常多，建议优先做“图标资产整理”，不要在页面里散落大量内联 SVG。
|
||
- 高频图标应统一为：
|
||
1. 字体图标
|
||
2. SVG 组件化
|
||
3. PNG/WebP 资源
|
||
三选一，不建议混乱并存。
|
||
|
||
## 7.2 页面目录规范（建议）
|
||
|
||
```text
|
||
miniprogram/
|
||
app.js
|
||
app.json
|
||
app.wxss
|
||
styles/
|
||
tokens.wxss
|
||
mixins.wxss
|
||
components.wxss
|
||
components/
|
||
nav-bar/
|
||
bottom-tab/
|
||
card/
|
||
metric-card/
|
||
modal/
|
||
toast/
|
||
score-stars/
|
||
filter-sheet/
|
||
pages/
|
||
login/
|
||
apply/
|
||
reviewing/
|
||
no-permission/
|
||
home-settings/
|
||
my-profile/
|
||
task-list/
|
||
task-detail/
|
||
task-detail-priority/
|
||
task-detail-callback/
|
||
task-detail-relationship/
|
||
notes/
|
||
chat/
|
||
chat-history/
|
||
board-finance/
|
||
board-customer/
|
||
board-coach/
|
||
performance/
|
||
performance-records/
|
||
customer-service-records/
|
||
coach-detail/
|
||
customer-detail/
|
||
```
|
||
|
||
## 7.3 组件拆分建议
|
||
|
||
### 必拆公共组件
|
||
- 顶部导航栏
|
||
- 底部 TabBar / 自定义底部导航
|
||
- 通用卡片
|
||
- 标签 / badge / pill
|
||
- Toast
|
||
- Modal / Bottom Sheet
|
||
- AI 图标组件
|
||
- 客户/助教头像组件
|
||
- 评分星级组件
|
||
- 筛选条
|
||
- 数据指标块
|
||
- 空状态
|
||
- 无权限/审核状态卡片
|
||
|
||
### 不建议过早组件化
|
||
- 只在一个页面出现一次且结构极度特殊的业务块
|
||
- 尚未稳定的数据看板 section
|
||
|
||
---
|
||
|
||
## 8. 交互迁移规范
|
||
|
||
## 8.1 原型里的交互类型
|
||
|
||
代码审阅后，原型中的核心交互包括：
|
||
|
||
1. 点击跳转
|
||
2. Tab 切换
|
||
3. 筛选器展开/收起
|
||
4. 吸顶与滚动隐藏/显示
|
||
5. 长按弹出上下文菜单
|
||
6. 备注弹窗
|
||
7. 放弃客户弹窗
|
||
8. Toast 提示
|
||
9. AI 对话复制
|
||
10. 星级评分拖动
|
||
11. 月份切换
|
||
12. 比较开关
|
||
13. “展开更多/收起”
|
||
14. 底部导航激活态
|
||
15. 模态遮罩点按关闭
|
||
|
||
## 8.2 H5 DOM 交互 → 小程序数据驱动规范
|
||
|
||
### 禁止
|
||
- `document.querySelector`
|
||
- `element.classList.add/remove`
|
||
- `createElement` 生成 UI
|
||
- `innerHTML` 拼接界面
|
||
- `history.back()`
|
||
- 直接依赖浏览器事件模型
|
||
|
||
### 统一改法
|
||
- 页面 data 维护 UI 状态：
|
||
- `showModal`
|
||
- `activeTab`
|
||
- `showFilter`
|
||
- `selectedSort`
|
||
- `selectedTimeRange`
|
||
- `showToast`
|
||
- `toastText`
|
||
- `noteDraft`
|
||
- `animationState`
|
||
- WXML 用条件渲染：
|
||
- `wx:if`
|
||
- `hidden`
|
||
- `wx:for`
|
||
- 事件统一使用：
|
||
- `bindtap`
|
||
- `bindinput`
|
||
- `bindchange`
|
||
- `bindscroll`
|
||
- `catchtouchmove`
|
||
|
||
## 8.3 长按菜单迁移
|
||
|
||
原型中 `task-list.html` 存在长按任务卡弹出上下文菜单的逻辑，且带“超过阈值判定移动、避免滑动误触”的处理。
|
||
|
||
### 风险
|
||
- 小程序端长按与滚动手势容易冲突。
|
||
- 不同机型触摸响应差异会更明显。
|
||
- 如果实现方式不对，列表滚动会卡或误触发频繁。
|
||
|
||
### 规范
|
||
1. 首选使用小程序支持的长按事件能力或触摸起止时序封装。
|
||
2. 菜单位置不要依赖浏览器 `clientX/clientY` 原样逻辑，改为：
|
||
- 卡片锚点定位
|
||
- 或简化为底部 action sheet
|
||
3. 若一定要做“锚点浮出菜单”，需用 selectorQuery 获取节点位置信息后定位。
|
||
4. 长按菜单必须有：
|
||
- 遮罩点击关闭
|
||
- 滚动时自动关闭
|
||
- 跳页时自动关闭
|
||
- 二次确认动作（例如放弃）
|
||
|
||
**建议：**
|
||
业务上允许的话，优先改成**底部 action sheet**，兼容性和可维护性更高。
|
||
|
||
## 8.4 吸顶 / 滚动联动筛选栏迁移
|
||
|
||
看板页中存在较复杂的：
|
||
- sticky 区块
|
||
- 下滑显示 / 上滑隐藏
|
||
- 阈值触发
|
||
- section 感知
|
||
- 导航同步
|
||
|
||
### 风险
|
||
- 小程序的滚动事件节奏与浏览器不同。
|
||
- 高频 `setData` 会引发掉帧。
|
||
- 如果把滚动值持续同步到很多节点，性能会明显下降。
|
||
|
||
### 规范
|
||
1. 先确认是否能纯 CSS / sticky 完成。
|
||
2. 必须 JS 联动时，只更新少量状态位：
|
||
- `showFilterBar`
|
||
- `currentSectionIndex`
|
||
- `stickyTitle`
|
||
3. 滚动事件里要做节流，避免每帧 `setData`。
|
||
4. 将复杂 section 计算封装为单独工具函数。
|
||
5. 验收重点放在：
|
||
- 回弹时状态是否抖动
|
||
- 快速滑动是否闪烁
|
||
- iOS / Android 表现是否一致
|
||
|
||
## 8.5 评分拖动迁移
|
||
|
||
原型中的星级评分通过 `touchstart/touchmove` + `getBoundingClientRect` 计算。
|
||
|
||
### 风险
|
||
- 小程序可实现，但细节容易出现触摸偏移。
|
||
- 如果星星是循环渲染，需要注意 index 与坐标换算一致。
|
||
- 拖动评分时要阻止页面滚动干扰。
|
||
|
||
### 规范
|
||
1. 保留“点击即评分”作为基本能力。
|
||
2. 拖动评分作为增强能力。
|
||
3. 星级区单独封装组件。
|
||
4. 组件输出：
|
||
- `score`
|
||
- `onChange`
|
||
5. 如拖动体验不稳定，可退化为“点击打分”，但点击命中精度必须足够。
|
||
|
||
## 8.6 动画与过渡迁移
|
||
|
||
### 原型现状
|
||
原型中有：
|
||
- `transition`
|
||
- `@keyframes`
|
||
- `opacity`
|
||
- `transform`
|
||
- `scale`
|
||
- `translateY`
|
||
- badge 动画
|
||
- 下拉浮层出现动画
|
||
- 浮动图形动画
|
||
|
||
### 建议实现优先级
|
||
1. **第一优先**：WXSS transition / animation
|
||
2. **第二优先**：`wx.createAnimation`
|
||
3. **第三优先**：必要时再考虑更复杂的方案
|
||
|
||
### 原则
|
||
- 能用样式动画解决的，不用 JS 驱动。
|
||
- 不要用连续 `setData` 逐帧更新位置。
|
||
- 复杂动画仅应用于关键体验点，不要全页过度动效。
|
||
|
||
---
|
||
|
||
## 9. 样式系统规范
|
||
|
||
## 9.1 设计 token（建议首批固化）
|
||
|
||
### 颜色
|
||
根据原型中的 Tailwind config，建议建立如下 token：
|
||
|
||
```css
|
||
--color-primary: #0052d9;
|
||
--color-primary-light: #ecf2fe;
|
||
--color-success: #00a870;
|
||
--color-warning: #ed7b2f;
|
||
--color-error: #e34d59;
|
||
|
||
--color-gray-1: #f3f3f3;
|
||
--color-gray-2: #eeeeee;
|
||
--color-gray-3: #e7e7e7;
|
||
--color-gray-4: #dcdcdc;
|
||
--color-gray-5: #c5c5c5;
|
||
--color-gray-6: #a6a6a6;
|
||
--color-gray-7: #8b8b8b;
|
||
--color-gray-8: #777777;
|
||
--color-gray-9: #5e5e5e;
|
||
--color-gray-10: #4b4b4b;
|
||
--color-gray-11: #393939;
|
||
--color-gray-12: #2c2c2c;
|
||
--color-gray-13: #242424;
|
||
```
|
||
|
||
### 圆角
|
||
- `radius-sm = 8rpx`
|
||
- `radius-md = 12rpx`
|
||
- `radius-lg = 16rpx`
|
||
- `radius-xl = 24rpx`
|
||
- `radius-2xl = 32rpx`
|
||
- `radius-pill = 999rpx`
|
||
|
||
### 间距
|
||
以 412px → 750rpx 换算后建立 4 进制或 2 进制 spacing system。
|
||
|
||
### 阴影
|
||
建议收敛为 3 档：
|
||
- `shadow-sm`
|
||
- `shadow-md`
|
||
- `shadow-lg`
|
||
|
||
### 字号
|
||
建议固定 8 档，不要维持太多 arbitrary 值：
|
||
- 20rpx
|
||
- 22rpx
|
||
- 24rpx
|
||
- 26rpx
|
||
- 28rpx
|
||
- 30rpx
|
||
- 32rpx
|
||
- 36rpx
|
||
|
||
## 9.2 页面级样式原则
|
||
|
||
1. 页面不得继续散落大量 utility class 的“翻译遗迹”。
|
||
2. 页面样式必须优先引用公共 token 与公共组件样式。
|
||
3. 同一种卡片在所有页面必须同源。
|
||
4. 渐变必须统一沉淀为命名类，不得每页重复抄写。
|
||
5. 模态层 / 遮罩层 / Toast / Sheet 的层级必须全局统一。
|
||
|
||
---
|
||
|
||
## 10. 本项目的高风险点清单（结合原型）
|
||
|
||
## 10.1 安全区与顶部导航
|
||
|
||
原型大量使用：
|
||
|
||
- `env(safe-area-inset-top, 44px)`
|
||
- sticky 顶部区
|
||
- 自定义导航高度 44px
|
||
|
||
### 风险
|
||
- 不同设备安全区表现不同。
|
||
- 真实小程序导航栏处理与浏览器不同。
|
||
- 若自定义导航方案不统一，页面顶部将出现抖动或错位。
|
||
|
||
### 处理规范
|
||
1. 全项目统一导航方案：
|
||
- 使用系统导航
|
||
- 或使用 `navigationStyle: custom` + 自定义导航
|
||
二选一，不要混用。
|
||
2. 若用自定义导航，需统一读取状态栏高度并建立全局变量。
|
||
3. 所有带 safe-area 的页面共用同一套 nav 容器组件。
|
||
|
||
## 10.2 `backdrop-blur`
|
||
|
||
原型多处用到半透明毛玻璃头像框、信息面板、徽章背景。
|
||
|
||
### 风险
|
||
- 小程序端不同基础库 / 机型表现不稳定。
|
||
- 部分场景模糊成本高，可能影响滚动性能。
|
||
- 很难保证和 H5 一样细腻。
|
||
|
||
### 策略
|
||
1. 先评估是否必须保留真实 blur。
|
||
2. 若视觉允许，优先退化为：
|
||
- 半透明纯色
|
||
- 半透明渐变
|
||
- 轻阴影 + 边框
|
||
3. 只在头图等少数关键区域保留 blur。
|
||
|
||
## 10.3 Sticky + 滚动吸附
|
||
|
||
看板页、聊天页、备注页都存在 sticky 或接近 sticky 的体验。
|
||
|
||
### 风险
|
||
- 多层 sticky 套叠时容易层级错乱。
|
||
- 自定义导航 + sticky + scroll-view 容器组合易出 bug。
|
||
- 开发工具表现和真机可能不同。
|
||
|
||
### 策略
|
||
- 每页只保留必要的 sticky 层。
|
||
- 能用页面自然滚动就不要强行塞进多层 `scroll-view`。
|
||
- 验收以真机为主，开发者工具仅作辅助。
|
||
|
||
## 10.4 SVG 图标资产
|
||
|
||
原型内联 SVG 很多。
|
||
|
||
### 风险
|
||
- 直接原封不动搬运会导致 WXML 臃肿。
|
||
- 图标难统一管理。
|
||
- 不利于后续主题化和复用。
|
||
|
||
### 策略
|
||
建立统一图标资产目录，按以下优先级处理：
|
||
1. 高频图标 → 组件化
|
||
2. 装饰图标 → 静态资源
|
||
3. AI 图标体系 → 单独组件封装
|
||
|
||
## 10.5 `hover` / `group-hover`
|
||
|
||
原型中虽不多，但确实存在。
|
||
|
||
### 风险
|
||
- 小程序主场景是触屏，不应依赖 hover 作为交互成立条件。
|
||
- 原型中的 hover 只能作为 Web 辅助状态，迁移时要改为：
|
||
- 常态
|
||
- 按压态
|
||
- 激活态
|
||
的显式逻辑
|
||
|
||
## 10.6 长列表与看板性能
|
||
|
||
财务、客户、助教看板都可能发展成长列表与大卡片页面。
|
||
|
||
### 风险
|
||
- 频繁 setData
|
||
- 过多阴影与渐变
|
||
- 多个 sticky / 浮层并存
|
||
- 展开收起 section 太多
|
||
|
||
### 策略
|
||
- 首屏只渲染必要内容
|
||
- 分区加载
|
||
- 列表项组件化
|
||
- 节流滚动联动
|
||
- 长列表必要时评估虚拟列表方案
|
||
|
||
---
|
||
|
||
## 11. 推荐实施步骤（项目执行手册）
|
||
|
||
## 第 0 步：冻结 H5 原型基准
|
||
### 目标
|
||
防止迁移过程中原型继续变化。
|
||
|
||
### 要做的事
|
||
- 冻结当前原型压缩包版本
|
||
- 输出页面清单与验收截图
|
||
- 明确哪些页面是 MVP、哪些是次优先级
|
||
- 固定验收机型：412px 宽设备为主，辅以 iPhone 标准宽度机型
|
||
|
||
### 风险
|
||
- 原型边迁边改，导致样式和接口字段同时漂移
|
||
- 页面名称与业务含义不一致
|
||
|
||
---
|
||
|
||
## 第 1 步：做视觉 Token 提取
|
||
### 目标
|
||
把 Tailwind/H5 样式还原成项目设计系统。
|
||
|
||
### 要做的事
|
||
- 抽颜色
|
||
- 抽字号
|
||
- 抽圆角
|
||
- 抽阴影
|
||
- 抽间距
|
||
- 抽渐变
|
||
- 抽层级
|
||
- 抽导航与安全区尺寸
|
||
|
||
### 产出
|
||
- `tokens.wxss`
|
||
- 尺寸换算表
|
||
- 视觉基线文档
|
||
|
||
### 风险
|
||
- 过早写页面，后面全局返工
|
||
- 相同样式在不同页面出现多个版本
|
||
|
||
---
|
||
|
||
## 第 2 步：做 Tailwind Class 收敛
|
||
### 目标
|
||
把散装 utility 组织成可维护的语义类。
|
||
|
||
### 要做的事
|
||
- 抽取卡片、标签、标题、数值块、筛选器、Toast、Modal 等公共样式
|
||
- 将内联 style 能抽的全部抽离
|
||
- 处理 arbitrary value 的统一口径
|
||
|
||
### 产出
|
||
- `components.wxss`
|
||
- 样式命名规范
|
||
|
||
### 风险
|
||
- 直接 page-by-page 硬写，后续无法复用
|
||
- 状态类命名混乱
|
||
|
||
---
|
||
|
||
## 第 3 步：先迁页面骨架，不做真实数据
|
||
### 目标
|
||
先得到“静态 1:1 视觉页”。
|
||
|
||
### 要做的事
|
||
- HTML 结构改写为 WXML
|
||
- 导航改为小程序导航模型
|
||
- 页面中所有文本、图片、徽章、图标、卡片、列表按静态数据渲染
|
||
- 完成 Safe Area / Sticky / 层级方案
|
||
|
||
### 产出
|
||
- 每个页面的 WXML + WXSS 静态版
|
||
- 验收截图
|
||
|
||
### 风险
|
||
- 一开始就接接口，定位问题困难
|
||
- 结构不稳定导致后面样式返工
|
||
|
||
---
|
||
|
||
## 第 4 步：迁交互层
|
||
### 目标
|
||
让静态页具备与原型一致的交互。
|
||
|
||
### 要做的事
|
||
- Tab 切换
|
||
- 展开收起
|
||
- Toast
|
||
- Modal
|
||
- 筛选器
|
||
- 长按菜单
|
||
- 评分
|
||
- 复制
|
||
- 页面跳转
|
||
- 滚动联动
|
||
|
||
### 产出
|
||
- 可演示的小程序原型版
|
||
|
||
### 风险
|
||
- 用 setData 粗暴驱动动画
|
||
- 高频滚动联动掉帧
|
||
- 多个弹层状态互相打架
|
||
|
||
---
|
||
|
||
## 第 5 步：替换 Mock 数据模型
|
||
### 目标
|
||
建立与未来接口一致的数据结构。
|
||
|
||
### 要做的事
|
||
- 每页梳理字段来源
|
||
- 区分：
|
||
- 后端返回
|
||
- 前端枚举
|
||
- 前端派生展示
|
||
- 统一 mock JSON 结构
|
||
- 统一时间、金额、状态、标签、头像、空态规则
|
||
|
||
### 产出
|
||
- 数据需求 PRD
|
||
- mock schema
|
||
- 字段字典
|
||
|
||
### 风险
|
||
- 页面先写死文案，后续接口接不进去
|
||
- 同一字段不同页面命名不一致
|
||
|
||
---
|
||
|
||
## 第 6 步：真机验收与回归
|
||
### 目标
|
||
确保 1:1 还原真的成立。
|
||
|
||
### 要做的事
|
||
- 以 412px 验收机型对照 H5 原型逐页截图比对
|
||
- 再测 375 宽和 Android 常见宽度
|
||
- 回归以下场景：
|
||
- 顶部安全区
|
||
- 长列表滚动
|
||
- 弹窗层级
|
||
- 筛选器浮层
|
||
- 长按
|
||
- 评分
|
||
- 字号密度
|
||
- 底部安全区
|
||
- 页面切换动画
|
||
|
||
### 风险
|
||
- 只看开发者工具，不看真机
|
||
- 只验静态，不验滚动与交互
|
||
|
||
---
|
||
|
||
## 12. 页面优先级建议
|
||
|
||
## P0（第一批必须先做）
|
||
1. `login`
|
||
2. `apply`
|
||
3. `reviewing`
|
||
4. `no-permission`
|
||
5. `task-list`
|
||
6. `task-detail`（含三种变体）
|
||
7. `chat`
|
||
8. `chat-history`
|
||
9. `notes`
|
||
10. `my-profile`
|
||
11. `home-settings`
|
||
|
||
理由：这是最短业务闭环。
|
||
|
||
## P1（第二批）
|
||
1. `customer-detail`
|
||
2. `coach-detail`
|
||
3. `performance`
|
||
4. `performance-records`
|
||
5. `customer-service-records`
|
||
|
||
## P2（第三批）
|
||
1. `board-finance`
|
||
2. `board-customer`
|
||
3. `board-coach`
|
||
|
||
理由：看板页视觉复杂、滚动联动重、字段也更依赖接口。
|
||
|
||
---
|
||
|
||
## 13. 验收标准（必须可落地）
|
||
|
||
## 13.1 视觉验收
|
||
- 同页截图对比，结构、颜色、圆角、阴影、间距、图标位置一致
|
||
- 关键卡片与标签误差控制在可感知差异最小范围内
|
||
- 412px 宽基准机型优先通过
|
||
|
||
## 13.2 交互验收
|
||
- 点击区域与原型一致
|
||
- 浮层开合方向、速度、遮罩、层级正确
|
||
- 长按、评分、切换、展开收起行为正确
|
||
- Toast 与弹窗文案与原型一致
|
||
|
||
## 13.3 性能验收
|
||
- 首屏不卡顿
|
||
- 长列表滚动不卡顿
|
||
- 吸顶与筛选滚动联动不闪烁
|
||
- 无明显白屏、抖动、错层
|
||
|
||
## 13.4 工程验收
|
||
- 无 Tailwind 运行时依赖
|
||
- 公共样式与公共组件已抽离
|
||
- 页面字段已按数据文档接 Mock
|
||
- 可以切换到真实接口而不重写页面结构
|
||
|
||
---
|
||
|
||
## 14. 本项目的落地建议（直接结论）
|
||
|
||
1. **可以做 1:1 迁移。**
|
||
2. **不应该把任务理解成“Tailwind 转 CSS”这么简单。** 真正的工作量在于：把 H5 DOM 交互改成小程序的数据驱动交互。
|
||
3. **你的项目比普通 H5 原型更适合迁移。**
|
||
- 因为 Tailwind 用法并不激进；
|
||
- 几乎没有断点响应式；
|
||
- 页面主要是移动端单栏布局；
|
||
- 复杂度集中在交互与数据编排，而不是页面骨架本身。
|
||
4. **最关键的成功因素只有三个：**
|
||
- 先抽 Token 和公共组件
|
||
- 先静态还原，再迁交互
|
||
- 先定义数据结构，再接接口
|
||
|
||
---
|
||
|
||
## 15. 必要参考文档地址
|
||
|
||
### 微信小程序
|
||
- WXML 模板
|
||
https://www.tencentcloud.com/zh/document/product/1219/60345
|
||
- WXSS 样式
|
||
https://www.tencentcloud.com/zh/document/product/1219/60346
|
||
- 小程序宿主环境（逻辑层 / 渲染层）
|
||
https://www.tencentcloud.com/zh/document/product/1219/61737
|
||
- 动画（`wx.createAnimation`）
|
||
https://www.tencentcloud.com/zh/document/product/1219/57764
|
||
- 渲染层 / 交互动画说明
|
||
https://www.tencentcloud.com/zh/document/product/1219/61744
|
||
- 小程序调试工具
|
||
https://www.tencentcloud.com/zh/document/product/1219/61764
|
||
|
||
### Tailwind CSS
|
||
- Styling with utility classes
|
||
https://tailwindcss.com/docs/styling-with-utility-classes
|
||
- Functions and directives (`@apply`)
|
||
https://tailwindcss.com/docs/functions-and-directives
|
||
- Responsive design
|
||
https://tailwindcss.com/docs/responsive-design
|
||
- Hover, focus, and other states
|
||
https://tailwindcss.com/docs/hover-focus-and-other-states
|
||
|
||
---
|
||
|
||
## 16. 附录：建议的页面命名映射
|
||
|
||
| H5 文件 | 小程序页面目录建议 |
|
||
|---|---|
|
||
| `login.html` | `pages/login/index` |
|
||
| `apply.html` | `pages/apply/index` |
|
||
| `reviewing.html` | `pages/reviewing/index` |
|
||
| `no-permission.html` | `pages/no-permission/index` |
|
||
| `home-settings.html` | `pages/home-settings/index` |
|
||
| `my-profile.html` | `pages/my-profile/index` |
|
||
| `task-list.html` | `pages/task-list/index` |
|
||
| `task-detail.html` | `pages/task-detail/index` |
|
||
| `task-detail-priority.html` | `pages/task-detail-priority/index` |
|
||
| `task-detail-callback.html` | `pages/task-detail-callback/index` |
|
||
| `task-detail-relationship.html` | `pages/task-detail-relationship/index` |
|
||
| `notes.html` | `pages/notes/index` |
|
||
| `chat.html` | `pages/chat/index` |
|
||
| `chat-history.html` | `pages/chat-history/index` |
|
||
| `board-finance.html` | `pages/board-finance/index` |
|
||
| `board-customer.html` | `pages/board-customer/index` |
|
||
| `board-coach.html` | `pages/board-coach/index` |
|
||
| `performance.html` | `pages/performance/index` |
|
||
| `performance-records.html` | `pages/performance-records/index` |
|
||
| `customer-service-records.html` | `pages/customer-service-records/index` |
|
||
| `coach-detail.html` | `pages/coach-detail/index` |
|
||
| `customer-detail.html` | `pages/customer-detail/index` |
|