# 首页滚动顶部渐变遮罩设计

## 背景

当前小程序使用 `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)` 控制状态栏文字颜色。
- 阈值通过节点测量计算，不写死具体机型像素。
- 若节点测量失败，使用保守回退：从约一个首页标题高度附近开始过渡。

## 测试要点

- 首页从顶部上滑时，遮罩在接近标题位置自然出现。
- 下拉回顶部时，遮罩自然消失。
- 搜索框、轮播卡片和分类卡片点击不受遮罩影响。
- 浅色/深色主题下状态栏信息都清晰可见。
- 不同刘海屏/胶囊按钮位置下遮罩覆盖范围正常。

## 非目标

- 不抽公共顶部遮罩组件。
- 不修改其他页面。
- 不做毛玻璃效果。
- 不改变首页大标题本身的布局和滚动行为。