feat: add scroll top mask, unify page top spacing and docs

2026-08-08 03:57:47 +08:00
parent 38045073b0
commit a3c3005c04
73 changed files with 1350 additions and 169 deletions
@@ -0,0 +1,33 @@
+# 商品 页面设计规范
+
+## 基本信息
+
+- 路由：`pages/shop/index`
+- 分类：`A类`
+- 标题文本：智绘精选
+- TabBar：是
+
+## 组件调用
+
+- **ScrollTopMask**
+  - `title="智绘精选"`
+  - `targetSelector=".shop-header"`
+  - `showBack`：`否`
+- **CustomTabBar**：自动显示，页面无需手动调用。
+
+## 设计要点
+
+- 顶部字距：statusBarHeight + 12px（已统一）。
+- 底部安全区：避让 TabBar + env(safe-area-inset-bottom)。
+- TopMask 出现阈值由 `.shop-header` 测量决定；滚动后标题淡入，位置遵循所在分类通用规范。
+
+## 页面特有说明
+
+商品网格信息流；标题带副文案，副文案随主标题上移后保留。
+
+## 验收要点
+
+- [ ] 顶部字距符合 class 通用规范
+- [ ] TopMask 标题/返回按钮符合预期
+- [ ] 浅色/深色主题正常
+- [ ] iOS / Android 真机表现一致
@@ -0,0 +1,33 @@
+# 我的 页面设计规范
+
+## 基本信息
+
+- 路由：`pages/profile/index`
+- 分类：`A类`
+- 标题文本：我的
+- TabBar：是
+
+## 组件调用
+
+- **ScrollTopMask**
+  - `title="我的"`
+  - `targetSelector=".profile-header"`
+  - `showBack`：`否`
+- **CustomTabBar**：自动显示，页面无需手动调用。
+
+## 设计要点
+
+- 顶部字距：statusBarHeight + 12px（已统一）。
+- 底部安全区：避让 TabBar + env(safe-area-inset-bottom)。
+- TopMask 出现阈值由 `.profile-header` 测量决定；滚动后标题淡入，位置遵循所在分类通用规范。
+
+## 页面特有说明
+
+登录卡片/用户区；无大标题，TopMask 标题用“我的”。
+
+## 验收要点
+
+- [ ] 顶部字距符合 class 通用规范
+- [ ] TopMask 标题/返回按钮符合预期
+- [ ] 浅色/深色主题正常
+- [ ] iOS / Android 真机表现一致
@@ -0,0 +1,33 @@
+# 订单 页面设计规范
+
+## 基本信息
+
+- 路由：`pages/orders/index`
+- 分类：`A类`
+- 标题文本：我的订单
+- TabBar：是
+
+## 组件调用
+
+- **ScrollTopMask**
+  - `title="我的订单"`
+  - `targetSelector=".orders-page .page-header"`
+  - `showBack`：`否`
+- **CustomTabBar**：自动显示，页面无需手动调用。
+
+## 设计要点
+
+- 顶部字距：statusBarHeight + 12px（已统一）。
+- 底部安全区：避让 TabBar + env(safe-area-inset-bottom)。
+- TopMask 出现阈值由 `.orders-page .page-header` 测量决定；滚动后标题淡入，位置遵循所在分类通用规范。
+
+## 页面特有说明
+
+ScrollView 列表 + tab 筛选；当前为 marginTop，统一时保持布局起点一致。
+
+## 验收要点
+
+- [ ] 顶部字距符合 class 通用规范
+- [ ] TopMask 标题/返回按钮符合预期
+- [ ] 浅色/深色主题正常
+- [ ] iOS / Android 真机表现一致
@@ -0,0 +1,33 @@
+# 设计清单 页面设计规范
+
+## 基本信息
+
+- 路由：`pages/designList/index`
+- 分类：`A类`
+- 标题文本：我的设计清单
+- TabBar：是
+
+## 组件调用
+
+- **ScrollTopMask**
+  - `title="我的设计清单"`
+  - `targetSelector=".page-header.design-header"`
+  - `showBack`：`否`
+- **CustomTabBar**：自动显示，页面无需手动调用。
+
+## 设计要点
+
+- 顶部字距：statusBarHeight + 12px（已统一）。
+- 底部安全区：避让 TabBar + env(safe-area-inset-bottom)。
+- TopMask 出现阈值由 `.page-header.design-header` 测量决定；滚动后标题淡入，位置遵循所在分类通用规范。
+
+## 页面特有说明
+
+ScrollView 列表 + 顶部 tab 筛选；批量管理模式注意遮罩不影响顶部操作。
+
+## 验收要点
+
+- [ ] 顶部字距符合 class 通用规范
+- [ ] TopMask 标题/返回按钮符合预期
+- [ ] 浅色/深色主题正常
+- [ ] iOS / Android 真机表现一致
@@ -0,0 +1,46 @@
+# A 类 - 根内容页（Tab）通用规范
+
+## 页面列表
+
+| 页面 | 路由 |
+|---|---|
+| 首页 | `pages/index/index` |
+| 商品 | `pages/shop/index` |
+| 设计清单 | `pages/designList/index` |
+| 订单 | `pages/orders/index` |
+| 我的 | `pages/profile/index` |
+
+## 组件调用
+
+- **TabBar**：显示。由 `app.config.ts` 的 `tabBar.custom: true` 自动挂载，页面内不需要调用组件，也不要渲染自己的底部栏。
+- **TopMask**：调用，`showBack={false}`；标题使用页面左上角大标题文本。
+- **useStatusBar / ThemedPageMeta**：按现有页面模式保留。
+
+## 设计规范
+
+- 顶部字距：`paddingTop（或 marginTop）= statusBarHeight + 12px`，标题在左上角，不需要避开右上角胶囊。
+- 大标题：页面左上角，字重与字号遵循各页面现有样式，不做渐变/缩放/吸顶。
+- 底部：内容区必须为 TabBar 预留空间，滚动类页面底部保留 `padding-bottom`（含 `env(safe-area-inset-bottom)`）。
+- 遮罩：滚动后顶部出现分层模糊 + 渐变，标题淡入在遮罩下 1/4 区域；无返回按钮。
+
+## 接入示例
+
+```tsx
+<View className={`theme-${resolvedTheme}`}>
+  <ThemedPageMeta />
+  <ScrollTopMask title="页面标题" targetSelector=".xxx-header" />
+  <View className="page">
+    <View className="xxx-header" style={{ paddingTop: `${safe.statusBarHeight + 12}px` }}>
+      <Text className="page-title">页面标题</Text>
+    </View>
+  </View>
+</View>
+```
+
+## 验收清单
+
+- [ ] 顶部字距为 `statusBarHeight + 12px`，iOS/Android 视觉效果一致
+- [ ] TabBar 正常显示，内容底部不被遮挡
+- [ ] 滚动后 TopMask 淡入，标题居中淡入，无返回按钮
+- [ ] 浅色/深色主题均正常
+
@@ -0,0 +1,33 @@
+# 首页 页面设计规范
+
+## 基本信息
+
+- 路由：`pages/index/index`
+- 分类：`A类`
+- 标题文本：智绘微刻
+- TabBar：是
+
+## 组件调用
+
+- **ScrollTopMask**
+  - `title="智绘微刻"`
+  - `targetSelector=".home-header"`
+  - `showBack`：`否`
+- **CustomTabBar**：自动显示，页面无需手动调用。
+
+## 设计要点
+
+- 顶部字距：statusBarHeight + 12px（已实现）。
+- 底部安全区：避让 TabBar + env(safe-area-inset-bottom)。
+- TopMask 出现阈值由 `.home-header` 测量决定；滚动后标题淡入，位置遵循所在分类通用规范。
+
+## 页面特有说明
+
+大标题左上角；轮播/搜索/分类卡片内容流较长，滚动后 TopMask 淡入。
+
+## 验收要点
+
+- [ ] 顶部字距符合 class 通用规范
+- [ ] TopMask 标题/返回按钮符合预期
+- [ ] 浅色/深色主题正常
+- [ ] iOS / Android 真机表现一致