4.8 KiB
4.8 KiB
inclusion, fileMatchPattern, name, description
| inclusion | fileMatchPattern | name | description |
|---|---|---|---|
| fileMatch | **/*.wxml,**/*.wxss,**/h5_ui/**,**/miniprogram/miniprogram/pages/**,**/miniprogram-dev/** | mp-h5-dev | 小程序页面开发详细规范。读取 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 迁移模板
<view class="banner-bg">
<view class="banner-texture"></view> <!-- 替代 ::before -->
<view class="banner-glow"></view> <!-- 替代 ::after -->
<view class="banner-content"><!-- 内容 --></view>
</view>
SVG 处理决策树
- TDesign 有等价图标 →
<t-icon name="xxx"> - 品牌/自定义图标 → 导出到
assets/icons/<name>.svg，<image>引用 - CSS 背景
data:image/svg+xml→ 导出独立文件 - 简单几何图形 → 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 |