131 lines
4.8 KiB
Markdown
131 lines
4.8 KiB
Markdown
---
|
||
inclusion: fileMatch
|
||
fileMatchPattern: "**/*.wxml,**/*.wxss,**/h5_ui/**,**/miniprogram/miniprogram/pages/**,**/miniprogram-dev/**"
|
||
name: mp-h5-dev
|
||
description: 小程序页面开发详细规范。读取 wxml/wxss/h5_ui/miniprogram 页面文件时自动加载。
|
||
---
|
||
|
||
# 小程序页面开发详细规范
|
||
|
||
硬性规则见 always-on steering `mp-h5-rules.md`。本文件补充开发流程和详细参考值。
|
||
|
||
## 完整颜色灰阶（13 级）
|
||
|
||
| Token | Hex | 用途 |
|
||
|-------|-----|------|
|
||
| gray-1 | #f3f3f3 | 页面背景 |
|
||
| gray-2 | #eeeeee | 分隔线 |
|
||
| gray-3 | #e7e7e7 | 边框 |
|
||
| gray-4 | #dcdcdc | 禁用态 |
|
||
| gray-5 | #c5c5c5 | — |
|
||
| gray-6 | #a6a6a6 | 辅助文字 |
|
||
| gray-7 | #8b8b8b | TabBar 默认色 |
|
||
| gray-8 | #777777 | — |
|
||
| gray-9 | #5e5e5e | 次要文字 |
|
||
| gray-10 | #4b4b4b | — |
|
||
| gray-11 | #393939 | — |
|
||
| gray-12 | #2c2c2c | — |
|
||
| gray-13 | #242424 | 主文字 |
|
||
|
||
## border-radius 标准值
|
||
|
||
sm 8rpx(rounded) | md 16rpx(rounded-lg) | lg 24rpx(rounded-xl) | xl 32rpx(rounded-2xl) | 3xl 48rpx(rounded-3xl)
|
||
|
||
## 阴影标准值
|
||
|
||
lg: `0 8rpx 32rpx rgba(0,0,0,0.06)` | xl: `0 16rpx 48rpx rgba(0,0,0,0.08)`
|
||
|
||
## 固定高度元素（切断 rpx 取整累积漂移）
|
||
|
||
Tab 栏 84rpx | 筛选栏 120rpx | 列表项 96rpx(标准)/112rpx(含副标题) | 按钮 80rpx | 底部操作区 112rpx
|
||
|
||
## 页面模式（截图裁剪）
|
||
|
||
模式 A（系统 navBar，无需裁剪）：board-finance, board-coach, board-customer, task-list, my-profile
|
||
模式 B（自定义 navBar，裁剪头部 96px）：task-detail 系列, coach-detail, customer-detail, performance, notes, chat, chat-history, customer-service-records, performance-records
|
||
|
||
## Sticky 高度
|
||
|
||
board-finance 116px | board-coach 110px | board-customer 110px | 其他 0
|
||
|
||
## 全局结构处理
|
||
|
||
| H5 元素 | MP 处理 |
|
||
|---------|---------|
|
||
| `.safe-area-top` | 去除 padding-top，MP 由 navigationBar 处理 |
|
||
| `#bottomNav` | 不迁移，MP 用原生 tabBar |
|
||
| `.ai-float-btn-container` | `wx:if="{{false}}"` |
|
||
| `<dev-fab />` | `wx:if="{{false}}"` |
|
||
| `::before/::after` 视觉元素 | 额外 `<view>` 绝对定位模拟 |
|
||
| Tab 指示线 `::after` | 额外 `<view>` 模拟 |
|
||
| 气泡尖角 `::after` | 绝对定位 `<view>` + `transform: rotate(45deg)` |
|
||
|
||
## 复杂视觉元素分层策略
|
||
|
||
| 复杂度 | 示例 | 方案 |
|
||
|--------|------|------|
|
||
| L1 简单 | 纯色标签、单色图标 | WXSS 原生 |
|
||
| L2 中等 | 渐变标签、多层 gradient | WXSS 多层渐变 |
|
||
| L3 复杂 | 伪元素纹理、SVG data URI | 导出为图片/SVG 文件 |
|
||
| L4 不可迁移 | `background-clip:text`、`conic-gradient` | 降级为近似纯色 |
|
||
|
||
## Banner 迁移模板
|
||
|
||
```xml
|
||
<view class="banner-bg">
|
||
<view class="banner-texture"></view> <!-- 替代 ::before -->
|
||
<view class="banner-glow"></view> <!-- 替代 ::after -->
|
||
<view class="banner-content"><!-- 内容 --></view>
|
||
</view>
|
||
```
|
||
|
||
## SVG 处理决策树
|
||
|
||
1. TDesign 有等价图标 → `<t-icon name="xxx">`
|
||
2. 品牌/自定义图标 → 导出到 `assets/icons/<name>.svg`，`<image>` 引用
|
||
3. CSS 背景 `data:image/svg+xml` → 导出独立文件
|
||
4. 简单几何图形 → WXSS border/transform 替代
|
||
|
||
## 不可消除差异白名单
|
||
|
||
字体渲染差异(Chromium vs WebView) | 行内元素高度偏小~7% | 抗锯齿差异 | 环比箭头(SVG vs 文字↑↓) | CSS 渐变文字→纯色
|
||
|
||
## CSS 风险特性速查
|
||
|
||
| 特性 | 出现页面 | 替代方案 |
|
||
|------|---------|---------|
|
||
| `backdrop-filter: blur()` | board-finance | `rgba(255,255,255,0.95)` |
|
||
| `-webkit-background-clip: text` | board-customer | 纯色文字 |
|
||
| `data:image/svg+xml` | reviewing, no-permission | 导出 PNG/SVG |
|
||
| `position: fixed` | board-finance/coach/customer, task-list | `position: sticky` 或页面级 fixed |
|
||
| `@font-face` 远程 | 所有页面 | 系统字体（推荐） |
|
||
|
||
## 新页面 Checklist
|
||
|
||
- [ ] 无 HTML 标签残留（div/span/p/a/img）
|
||
- [ ] 内联 SVG 已提取为文件
|
||
- [ ] 样式全部 WXSS（rpx 单位）
|
||
- [ ] 不支持的 CSS 已替代
|
||
- [ ] 事件 `bindtap`，传参 `data-*`
|
||
- [ ] TDesign 组件在 .json 注册
|
||
- [ ] 安全区适配（JS statusBarHeight）
|
||
- [ ] `getDiagnostics` 零错误
|
||
- [ ] `wx:key` 已添加
|
||
- [ ] 布尔属性用 `{{}}` 包裹
|
||
- [ ] mock 数据与 H5 一致
|
||
|
||
## 关联资源路径
|
||
|
||
| 资源 | 路径 |
|
||
|------|------|
|
||
| H5 原型 | `docs/h5_ui/pages/*.html` |
|
||
| 设计 Token | `docs/h5_ui/design-tokens.json` |
|
||
| 图标映射 | `docs/h5_ui/icon-mapping.md` |
|
||
| 交互说明 | `docs/h5_ui/interactions/<page>.md` |
|
||
| 截图产物 | `docs/h5_ui/compare/<page>/` |
|
||
| MP 源码 | `apps/miniprogram/miniprogram/pages/` |
|
||
| 迁移进度 | `docs/miniprogram-dev/04-audit/PROGRESS.md` |
|
||
| 踩坑速查 | `docs/miniprogram-dev/05-lessons/pitfalls.md` |
|
||
| 收敛模式 | `docs/miniprogram-dev/05-lessons/convergence-patterns.md` |
|
||
| 页面结构速查 | `docs/miniprogram-dev/03-reference/page-structure-map.md` |
|