docs: add home top mask design

2026-08-08 01:14:43 +08:00
parent 61f1217384
commit 5e7046f935
1 changed files with 64 additions and 0 deletions
@@ -0,0 +1,64 @@
 # 首页滚动顶部渐变遮罩设计
 ## 背景
 当前小程序使用 `navigationStyle: 'custom'`，首页内容全屏铺开，顶部的时间、电量等状态栏信息在浅色/图片内容经过时缺少稳定的层级衬托。目标是在用户上滑接近首页大标题距离时，让顶部自然形成一层柔和遮罩：既能让状态栏信息更清楚，又能形成类似 iOS 26 的层级感。
 ## 范围
 本次只改首页：
 - `/Users/broccoli/Project/wechat_wc/src/pages/index/index.tsx`
 - `/Users/broccoli/Project/wechat_wc/src/pages/index/index.scss`
 商城、订单、我的等其他 Tab 页暂不处理。
 ## 选定方案
 使用页面级滚动监听 + 固定渐变层：
 1. 首页加载后通过 `Taro.createSelectorQuery()` 测量首页大标题节点位置，得到标题底部相对视口的距离。
 2. 用 Taro 页面滚动能力监听当前页面的滚动距离。
 3. 顶部放置一个 `position: fixed` 的渐变遮罩层，覆盖状态栏与胶囊按钮附近区域，并向下渐隐。
 4. 根据滚动距离和测量结果计算 `0~1` 的遮罩透明度进度，设置到遮罩层上。
 5. 遮罩层设置 `pointer-events: none`，不影响页面点击。
 不采用毛玻璃和标题吸顶/缩放，以保证真机兼容性，并保持首页大标题自然滚走。
 ## 交互细节
 - 页面初始位置：遮罩完全透明。
 - 开始上滑到大标题接近状态栏区域时：遮罩逐渐显现。
 - 继续滚动约一个标题高度的过渡距离后：遮罩达到完整强度。
 - 下拉回顶部：遮罩按相同进度淡出。
 - `智绘微刻` 大标题继续随页面自然滚动，不吸顶、不缩小、不变色。
 ## 视觉细节
 - 遮罩使用柔和线性渐变，不使用 `blur`。
 - 浅色模式顶部使用页面背景色 `#faf7f2`，向下过渡到透明。
 - 深色模式顶部使用页面背景色 `#191919`，向下过渡到透明。
 - 渐变层高度覆盖安全区顶部和自定义导航区域，并额外向下延伸一段距离，使边缘柔和。
 - 初始通过样式保持透明，避免首屏闪烁。
 ## 适配与约束
 - 复用现有 `useSafeArea()` 获取 `statusBarHeight`、`headerPaddingTop` 等信息。
 - 继续使用现有 `useStatusBar(resolvedTheme)` 控制状态栏文字颜色。
 - 阈值通过节点测量计算，不写死具体机型像素。
 - 若节点测量失败，使用保守回退：从约一个首页标题高度附近开始过渡。
 ## 测试要点
 - 首页从顶部上滑时，遮罩在接近标题位置自然出现。
 - 下拉回顶部时，遮罩自然消失。
 - 搜索框、轮播卡片和分类卡片点击不受遮罩影响。
 - 浅色/深色主题下状态栏信息都清晰可见。
 - 不同刘海屏/胶囊按钮位置下遮罩覆盖范围正常。
 ## 非目标
 - 不抽公共顶部遮罩组件。
 - 不修改其他页面。
 - 不做毛玻璃效果。
 - 不改变首页大标题本身的布局和滚动行为。