351 lines
11 KiB
Markdown
351 lines
11 KiB
Markdown
# Square Tab 滚动行为差异化实现计划
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** 在 `square.vue` 页面中,让 星河 / 星榜 / 广场 三个 tab 拥有差异化的滚动行为:星河完全禁用滚动,星榜只允许 HotCategoryBlock 内部 grid 区域滚动,广场保持当前整体滚动。
|
|
|
|
**Architecture:** 复用现有外层 `<scroll-view>`,仅通过动态绑定 `:scroll-y="activeContentTab === 'guangchang'"` 控制外层是否可滚;给 `HotCategoryBlock` 内部加一个独立的 `<scroll-view>` 包裹 grid 区域;切 tab 时重置外层 scrollTop。
|
|
|
|
**Tech Stack:** Vue 3 (Composition API)、uni-app、SCSS。
|
|
|
|
**Spec:** `docs/superpowers/specs/2026-06-11-square-tab-scroll-behavior-design.md`
|
|
|
|
---
|
|
|
|
## 涉及文件
|
|
|
|
| 文件 | 改动 |
|
|
| --- | --- |
|
|
| `frontend/pages/square/square.vue` | scroll-view 加 `:scroll-y` 动态绑定、加 watch 重置 scrollTop、`.hot-category-wrapper` 加固定高度 |
|
|
| `frontend/pages/square/components/HotCategoryBlock.vue` | grid 区域包到内部 scroll-view、加 `.content-scroll` 样式、改 `.hot-category-block` 为 flex 布局 |
|
|
|
|
**明确不动:**
|
|
- `frontend/pages/square/components/StarGalaxy/*` (任何文件)
|
|
- `frontend/pages/square/components/CreationGrid.vue`
|
|
- `frontend/pages/square/components/BannerCarousel.vue`
|
|
- `frontend/pages/square/components/ContentTabs.vue`
|
|
|
|
---
|
|
|
|
## 实施说明
|
|
|
|
此计划涉及纯 UI 滚动行为调整,无独立可单元测试的纯函数,故采用**手动验证 + 浏览器/H5 调试**作为验证手段,不用 vitest/jest 单测框架。Vue 文件改动后通过 `npm run dev:h5`(或项目实际启动命令)启动后,使用浏览器 DevTools 模拟手机视口验证。
|
|
|
|
---
|
|
|
|
### Task 1: 改造 HotCategoryBlock 加内部 scroll
|
|
|
|
**Files:**
|
|
- Modify: `frontend/pages/square/components/HotCategoryBlock.vue:1-118`(template 部分)
|
|
- Modify: `frontend/pages/square/components/HotCategoryBlock.vue`(style 部分)
|
|
|
|
#### 1.1 修改 template,把 grid 区域包到内部 scroll-view
|
|
|
|
**当前结构**(HotCategoryBlock.vue 大致如下,行号是参考):
|
|
|
|
```vue
|
|
<view class="hot-category-block">
|
|
<!-- Tab 栏 -->
|
|
<view class="ranking-tabs">...</view>
|
|
|
|
<!-- 骨架屏 -->
|
|
<view v-if="loading" class="grid-skeleton">
|
|
<view v-for="i in 11" ...>...</view>
|
|
</view>
|
|
|
|
<!-- 内容网格 -->
|
|
<view v-else class="items-grid">
|
|
<view v-for="(item, index) in items" ...>...</view>
|
|
</view>
|
|
</view>
|
|
```
|
|
|
|
**改造为:**
|
|
|
|
```vue
|
|
<view class="hot-category-block">
|
|
<!-- Tab 栏 (固定不滚) -->
|
|
<view class="ranking-tabs">...</view>
|
|
|
|
<!-- 内容区域: 内部 scroll -->
|
|
<scroll-view
|
|
class="content-scroll"
|
|
scroll-y
|
|
:show-scrollbar="false"
|
|
:bounce="false"
|
|
>
|
|
<!-- 骨架屏 -->
|
|
<view v-if="loading" class="grid-skeleton">
|
|
<view v-for="i in 11" ...>...</view>
|
|
</view>
|
|
|
|
<!-- 内容网格 -->
|
|
<view v-else class="items-grid">
|
|
<view v-for="(item, index) in items" ...>...</view>
|
|
</view>
|
|
</scroll-view>
|
|
</view>
|
|
```
|
|
|
|
**具体编辑步骤:**
|
|
|
|
1. Read the file to find the exact lines
|
|
2. 在 `</view>` (closing of `.ranking-tabs` div 之后,`<view v-if="loading">` 之前) 插入 `<scroll-view class="content-scroll" scroll-y :show-scrollbar="false" :bounce="false">`
|
|
3. 在 `<view v-else class="items-grid">` 闭合 `</view>` 之后,`</view>` (closing of `.hot-category-block`) 之前,插入 `</scroll-view>`
|
|
|
|
#### 1.2 修改 style,加 flex 布局和 `.content-scroll`
|
|
|
|
在 `<style scoped>` 中找到 `.hot-category-block` 相关样式,改为:
|
|
|
|
```scss
|
|
.hot-category-block {
|
|
height: 100%;
|
|
display: flex;
|
|
flex-direction: column;
|
|
overflow: hidden;
|
|
}
|
|
```
|
|
|
|
新增:
|
|
|
|
```scss
|
|
.content-scroll {
|
|
flex: 1;
|
|
min-height: 0; /* flex 子项需要 min-height: 0 才能正确伸缩 */
|
|
overflow: hidden;
|
|
}
|
|
```
|
|
|
|
#### 1.3 手动验证
|
|
|
|
- [ ] **Step 1: 启动 H5 调试模式**
|
|
|
|
Run: 在 `frontend/` 目录执行项目实际启动命令(通常是 `npm run dev:h5` 或 `npm run dev:mp-weixin`)
|
|
Expected: 开发服务器启动,无编译错误
|
|
|
|
- [ ] **Step 2: 浏览器 DevTools 切到手机视口**
|
|
|
|
在 Chrome DevTools 中切到 iPhone 12/13 视口(390x844),访问对应页面。
|
|
|
|
- [ ] **Step 3: 临时验证(此时还在外层 scroll 内,grid 区域还没独立滚)**
|
|
|
|
切换到 星榜 tab,确认页面正常渲染、grid 正常显示。
|
|
**注:** 此步 Task 1 完成后,grid 应该已经在外层 scroll-view 内,但 HotCategoryBlock 内部 scroll-view 可能因为高度为 0 不显示滚动条 —— 这是预期,等到 Task 2 给 `.hot-category-wrapper` 设了固定高度后才真正工作。
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add frontend/pages/square/components/HotCategoryBlock.vue
|
|
git commit -m "feat(square): wrap HotCategoryBlock grid area in internal scroll-view"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 2: 改造 square.vue 动态绑定 scroll-y + 加固定高度 + 重置 scrollTop
|
|
|
|
**Files:**
|
|
- Modify: `frontend/pages/square/square.vue:46-53`(template scroll-view 部分)
|
|
- Modify: `frontend/pages/square/square.vue:94-130`(script setup 部分,加 watch)
|
|
- Modify: `frontend/pages/square/square.vue:289-377`(style 部分,改 `.hot-category-wrapper`)
|
|
|
|
#### 2.1 把外层 scroll-view 的 `scroll-y` 改为动态绑定
|
|
|
|
**当前代码**(square.vue 第 46-53 行):
|
|
|
|
```vue
|
|
<scroll-view
|
|
class="content-wrapper"
|
|
scroll-y
|
|
:show-scrollbar="false"
|
|
:bounce="false"
|
|
@scroll="onScroll"
|
|
@scrolltolower="handleScrollToLower"
|
|
>
|
|
```
|
|
|
|
**改造为:**
|
|
|
|
```vue
|
|
<scroll-view
|
|
class="content-wrapper"
|
|
:scroll-y="activeContentTab === 'guangchang'"
|
|
:show-scrollbar="false"
|
|
:bounce="false"
|
|
@scroll="onScroll"
|
|
@scrolltolower="handleScrollToLower"
|
|
>
|
|
```
|
|
|
|
唯一改动:`scroll-y` → `:scroll-y="activeContentTab === 'guangchang'"`
|
|
|
|
#### 2.2 给 `.hot-category-wrapper` 加固定高度
|
|
|
|
在 `<style lang="scss" scoped>` 中找到 `.hot-category-wrapper`(原代码大约在第 349-352 行):
|
|
|
|
```scss
|
|
.hot-category-wrapper {
|
|
position: relative;
|
|
padding-bottom: 80rpx;
|
|
}
|
|
```
|
|
|
|
**改造为:**
|
|
|
|
```scss
|
|
.hot-category-wrapper {
|
|
position: relative;
|
|
/* 100vh - header(208rpx) - banner(360rpx) - tabs(88rpx) = 可用 body 高度 */
|
|
height: calc(100vh - 208rpx - 360rpx - 88rpx);
|
|
/* 移除 padding-bottom,改用内部 grid gap */
|
|
}
|
|
```
|
|
|
|
> **重要**:
|
|
> 1. `100vh` 在小程序里可能需要换成 `100%` (取决于 uni-app 平台);在 H5 中 `100vh` 工作正常。先按 H5 实现,小程序端如果有问题再调整。
|
|
> 2. 计算的三个高度值(208/360/88)对应:Header / BannerCarousel(`.banner-section` 的 360rpx) / ContentTabs。如有偏差,以实际渲染为准微调。
|
|
|
|
#### 2.3 加 watch 重置 scrollTop
|
|
|
|
在 `<script setup>` 中找到 `import` 行(大约第 95 行):
|
|
|
|
**当前:**
|
|
|
|
```javascript
|
|
import { ref, onMounted, onUnmounted } from "vue";
|
|
```
|
|
|
|
**改为:**
|
|
|
|
```javascript
|
|
import { ref, watch, onMounted, onUnmounted } from "vue";
|
|
```
|
|
|
|
找到 `const activeContentTab = ref("xinghe");` 这一行(大约第 117 行),在它**后面**新增:
|
|
|
|
```javascript
|
|
// 切 tab 时重置外层 scroll-view 的 scrollTop,避免残留滚动位置
|
|
watch(activeContentTab, () => {
|
|
// 星河/星榜 时 scroll-y=false,但 scrollTop 残留可能导致显示异常
|
|
uni.pageScrollTo({ scrollTop: 0, duration: 0 });
|
|
});
|
|
```
|
|
|
|
> **如果 `uni.pageScrollTo` 不生效**(它主要用于页面级滚动,对 scroll-view 不一定有效),可改用 ref 绑定方式:
|
|
>
|
|
> ```javascript
|
|
> const outerScrollTop = ref(0);
|
|
> watch(activeContentTab, () => { outerScrollTop.value = 0; });
|
|
> ```
|
|
>
|
|
> 然后在 scroll-view 上加 `:scroll-top="outerScrollTop"`。**先尝试 `uni.pageScrollTo` 简单方案**,不生效再切换。
|
|
|
|
#### 2.4 手动验证
|
|
|
|
- [ ] **Step 1: 重启开发服务器,确保无编译错误**
|
|
|
|
Expected: 启动无报错
|
|
|
|
- [ ] **Step 2: 验证 星河 tab**
|
|
|
|
- 进入 星河 tab
|
|
- 在 StarGalaxy 区域上下滑动
|
|
- 预期: 页面**完全不能滚动**(包括 banner、tabs、StarGalaxy 任何部分)
|
|
- 预期: StarGalaxy 顶部 `top: -128rpx` 仍然让星图略微与 banner 重叠(顶部 mask 透明渐变让 banner 透出),这是设计预期
|
|
|
|
- [ ] **Step 3: 验证 星榜 tab**
|
|
|
|
- 切换到 星榜 tab
|
|
- 在顶部 banner 区域上下滑动
|
|
- 预期: 顶部(banner + tabs)**不滚动**
|
|
- 在 grid 卡片区域上下滑动
|
|
- 预期: **grid 区域独立滚动**,顶部不动
|
|
|
|
- [ ] **Step 4: 验证 广场 tab**
|
|
|
|
- 切换到 广场 tab
|
|
- 上下滑动
|
|
- 预期: 整体页面**可滚动**(与改造前完全一致)
|
|
- 滚到中段时,banner 应消失
|
|
- 验证: `CreationGrid` 的"分类标签切 fixed"行为仍正常
|
|
|
|
- [ ] **Step 5: 验证切换 tab 重置 scrollTop**
|
|
|
|
- 在 广场 tab 滚到中段(banner 已消失)
|
|
- 切到 星河 → 切回 广场
|
|
- 预期: 页面回到顶部
|
|
|
|
- [ ] **Step 6: 验证双击点赞 / 单击跳转**
|
|
|
|
- 三个 tab 都尝试双击卡片
|
|
- 预期: 双击点赞动画 + 点赞 API 正常触发(行为与改造前一致)
|
|
|
|
- [ ] **Step 7: 验证 BannerCarousel 的 autoplay / 点击**
|
|
|
|
- 在 星河 / 星榜 tab,banner 仍能正常左右滑(因为 scroll-y=false 不影响 swiper 的横向滑动)
|
|
- 预期: 正常
|
|
|
|
- [ ] **Step 8: Commit**
|
|
|
|
```bash
|
|
git add frontend/pages/square/square.vue
|
|
git commit -m "feat(square): differentiate scroll behavior for xinghe/xingbang/guangchang tabs"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 3: 跨平台兼容性验证(如果项目支持多端)
|
|
|
|
**Files:** 无文件改动,仅验证
|
|
|
|
- [ ] **Step 1: 验证 H5 端**
|
|
|
|
Run: `npm run dev:h5`
|
|
Expected: 三个 tab 滚动行为符合预期(已 Task 2 Step 2-4 验证)
|
|
|
|
- [ ] **Step 2: 验证微信小程序端(如果项目支持)**
|
|
|
|
Run: `npm run dev:mp-weixin`(或对应命令)
|
|
Expected:
|
|
- 星河 / 星榜 滚动行为同 H5
|
|
- 广场 滚动行为同 H5
|
|
- **如果 `100vh` 在小程序中不生效**,把 `.hot-category-wrapper` 的 `height: calc(100vh - 656rpx)` 改为 `height: calc(100% - 656rpx)`,或者使用 `uni.getSystemInfoSync().windowHeight` 动态计算
|
|
- **如果 `uni.pageScrollTo` 不生效**,按 Task 2.3 注释中的备选方案切到 ref 绑定
|
|
|
|
- [ ] **Step 3: 验证 App 端(如果项目支持)**
|
|
|
|
Run: `npm run dev:app`(或对应命令)
|
|
Expected: 同 H5,如有差异按小程序方案调整
|
|
|
|
---
|
|
|
|
### Task 4: 收尾
|
|
|
|
- [ ] **Step 1: 检查所有改动文件**
|
|
|
|
Run: `git diff --stat HEAD~2`
|
|
Expected: 仅 `frontend/pages/square/square.vue` 和 `frontend/pages/square/components/HotCategoryBlock.vue` 两个文件有改动
|
|
|
|
- [ ] **Step 2: 整体回归**
|
|
|
|
- 三个 tab 切换流畅,无残留
|
|
- 滚动手感符合需求
|
|
- 横幅 / 分类标签 / 底部导航都正常
|
|
|
|
- [ ] **Step 3: 提交最终 commit(如果还有遗留改动)**
|
|
|
|
```bash
|
|
git status
|
|
git add -u
|
|
git commit -m "chore: final cleanup for square tab scroll behavior"
|
|
```
|
|
|
|
---
|
|
|
|
## 验证清单 (人工测试报告模板)
|
|
|
|
| Tab | 滚动行为 | 顶部 banner | 顶部 ContentTabs | 备注 |
|
|
| --- | --- | --- | --- | --- |
|
|
| 星河 | 完全禁用 ✓ | 固定 ✓ | 固定 ✓ | |
|
|
| 星榜 | 仅 HotCategoryBlock 内部滚 ✓ | 固定 ✓ | 固定 ✓ | |
|
|
| 广场 | 整体可滚 ✓ | 随滚消失 | 随滚消失 | 与改造前一致 |
|