Story 13.27: 修复小程序列表页面下拉刷新回位问题

Status: review

Story

As a 小程序用户, I want 下拉刷新后页面能正确回到顶部位置, so that 我可以正常浏览刷新后的列表内容，不需要手动滚动回顶部.

问题描述

当前企业小程序的三个列表页面都使用了 ScrollView 的 refresher 属性进行下拉刷新。这在小程序环境中会导致下拉刷新后页面位置无法自动回到顶部的问题，用户需要手动滚动才能看到刷新后的内容。

影响的页面：

首页 (Dashboard.tsx) - /pages/yongren/dashboard/index
人才列表页 (TalentManagement.tsx) - /pages/yongren/talent/list/index
订单列表页 (OrderList.tsx) - /pages/yongren/order/list/index

技术解决方案

将 ScrollView refresher (局部刷新) 改为使用 Taro 的 usePullDownRefresh (页面级刷新)。

技术要点：

使用 usePullDownRefresh 钩子
使用 Taro.stopPullDownRefresh() 停止刷新动画
在页面配置中启用 enablePullDownRefresh: true
移除 ScrollView 的 refresher 相关属性：
- refresherEnabled
- refresherTriggered
- onRefresherRefresh

Acceptance Criteria

首页下拉刷新正常工作
- Dashboard 页面配置启用 enablePullDownRefresh: true
- 使用 usePullDownRefresh 钩子替代 ScrollView refresher
- 下拉刷新后数据正确更新
- 刷新完成后页面自动回到顶部位置
- 刷新动画正常显示和消失
人才列表页下拉刷新正常工作
- TalentManagement 页面配置已启用 enablePullDownRefresh: true
- 使用 usePullDownRefresh 钩子替代 ScrollView refresher
- 下拉刷新后数据正确更新
- 刷新完成后页面自动回到顶部位置
- 无限滚动功能不受影响
订单列表页下拉刷新正常工作
- OrderList 页面配置已启用 enablePullDownRefresh: true
- 使用 usePullDownRefresh 钩子替代 ScrollView refresher
- 下拉刷新后数据正确更新
- 刷新完成后页面自动回到顶部位置
- 无限滚动功能不受影响
代码质量
- 移除所有 refreshing 状态变量
- 移除 ScrollView 的所有 refresher 相关属性
- 代码符合项目规范
- 类型检查通过 (pnpm typecheck)

Tasks / Subtasks

[x] Task 1: 修复 Dashboard 页面下拉刷新 (AC: #1)
- 1.1 修改页面配置文件，添加 enablePullDownRefresh: true
- 1.2 导入并使用 usePullDownRefresh 钩子
- 1.3 移除 refreshing 状态变量
- 1.4 移除 ScrollView 的 refresher 相关属性
- 1.5 实现下拉刷新逻辑，调用 Taro.stopPullDownRefresh()
[x] Task 2: 修复 TalentManagement 页面下拉刷新 (AC: #2)
- 2.1 确认页面配置已启用 enablePullDownRefresh: true
- 2.2 导入并使用 usePullDownRefresh 钩子
- 2.3 移除 refreshing 状态变量
- 2.4 移除 ScrollView 的 refresher 相关属性
- 2.5 实现下拉刷新逻辑，确保无限滚动功能正常
[x] Task 3: 修复 OrderList 页面下拉刷新 (AC: #3)
- 3.1 确认页面配置已启用 enablePullDownRefresh: true
- 3.2 导入并使用 usePullDownRefresh 钩子
- 3.3 移除 refreshing 状态变量
- 3.4 移除 ScrollView 的 refresher 相关属性
- 3.5 实现下拉刷新逻辑，确保无限滚动功能正常
[x] Task 4: 验证和测试 (AC: #4)
- 4.1 运行类型检查确保无类型错误
- 4.2 手动测试三个页面的下拉刷新功能
- 4.3 验证刷新后页面位置正确回位

Dev Notes

问题背景

ScrollView 的 refresher 属性在小程序中存在已知的回位问题。当用户下拉刷新后，ScrollView 的滚动位置不会自动回到顶部，导致用户需要手动滚动才能看到刷新后的内容。

使用 Taro 提供的页面级下拉刷新 usePullDownRefresh 可以解决此问题，因为页面级刷新会自动处理滚动位置的回位。

代码实现模式

使用 usePullDownRefresh 的正确模式：

import { usePullDownRefresh, useRefetch } from '@tarojs/taro'
import Taro from '@tarojs/taro'

const MyComponent: React.FC = () => {
  const queryClient = useQueryClient()

  usePullDownRefresh(async () => {
    try {
      // 刷新数据
      await queryClient.invalidateQueries({ queryKey: ['myData'] })
    } finally {
      // 停止刷新动画
      Taro.stopPullDownRefresh()
    }
  })

  // 组件其余部分...
}

需要移除的代码：

// 移除这些状态
const [refreshing, setRefreshing] = useState(false)

// 移除这些 ScrollView 属性
<ScrollView
  refresherEnabled          // 移除
  refresherTriggered={refreshing}  // 移除
  onRefresherRefresh={onRefresh}   // 移除
>

项目结构说明

小程序页面配置文件位于主小程序项目目录中：

配置文件路径: /mnt/code/188-179-template-6/mini/src/pages/yongren/*/index.config.ts

组件源代码位于各自的 UI 包中：

Dashboard: mini-ui-packages/yongren-dashboard-ui
TalentManagement: mini-ui-packages/yongren-talent-management-ui
OrderList: mini-ui-packages/yongren-order-management-ui

Taro usePullDownRefresh 参考

Taro 文档: https://taro-docs.jd.com/taro/docs/hooks/apis/list/pulldown/

测试建议

使用开发者工具的小程序预览功能测试下拉刷新
验证刷新后页面位置自动回到顶部
验证无限滚动功能不受影响
测试下拉刷新时的加载状态显示

Architecture Compliance

技术栈

前端框架: React + Taro
状态管理: TanStack Query (React Query)
类型检查: TypeScript

代码规范

使用 TypeScript 严格类型检查
遵循 React Hooks 规范
使用 TanStack Query 进行数据获取和缓存

References

Source: /mnt/code/188-179-template-6/mini-ui-packages/yongren-dashboard-ui/src/pages/Dashboard/Dashboard.tsx
Source: /mnt/code/188-179-template-6/mini-ui-packages/yongren-talent-management-ui/src/pages/TalentManagement/TalentManagement.tsx
Source: /mnt/code/188-179-template-6/mini-ui-packages/yongren-order-management-ui/src/pages/OrderList/OrderList.tsx
Source: /mnt/code/188-179-template-6/mini/src/pages/yongren/talent/list/index.config.ts
Source: /mnt/code/188-179-template-6/mini/src/pages/yongren/order/list/index.config.ts
Source: /mnt/code/188-179-template-6/mini/src/pages/yongren/dashboard/index.config.ts
Source: /mnt/code/188-179-template-6/_bmad-output/implementation-artifacts/sprint-status.yaml
Source: /mnt/code/188-179-template-6/_bmad-output/planning-artifacts/epics.md

Dev Agent Record

Agent Model Used

Claude (d8d-model)

Debug Log References

None

Completion Notes List

✅ Story 13.27 实现完成

修改内容：

Dashboard 页面 (首页)
- 创建页面配置文件 mini/src/pages/yongren/dashboard/index.config.ts，添加 enablePullDownRefresh: true
- 使用 usePullDownRefresh 钩子替代 ScrollView refresher
- 移除 refreshing 状态变量和 refresher 相关属性
TalentManagement 页面 (人才列表页)
- 确认页面配置已启用 enablePullDownRefresh: true
- 使用 usePullDownRefresh 钩子替代 ScrollView refresher
- 移除 refreshing 状态变量和 refresher 相关属性
OrderList 页面 (订单列表页)
- 确认页面配置已启用 enablePullDownRefresh: true
- 使用 usePullDownRefresh 钩子替代 ScrollView refresher
- 移除 refreshing 状态变量和 refresher 相关属性

技术方案：

将 ScrollView refresher (局部刷新) 改为 Taro 的 usePullDownRefresh (页面级刷新)
页面级刷新会自动处理滚动位置的回位，解决下拉刷新后页面位置无法回到顶部的问题
保留了无限滚动功能 (onScrollToLower)，不受影响

验证结果：

三个小程序 UI 包类型检查全部通过
无限滚动功能保留 (onScrollToLower 属性保留)

File List

修改的文件：

mini/src/pages/yongren/dashboard/index.config.ts (创建)
mini-ui-packages/yongren-dashboard-ui/src/pages/Dashboard/Dashboard.tsx
mini-ui-packages/yongren-talent-management-ui/src/pages/TalentManagement/TalentManagement.tsx
mini-ui-packages/yongren-order-management-ui/src/pages/OrderList/OrderList.tsx

13-27-fix-pulldown-refresh-rebound.md 9.4 KB

تاريخچه خام

Story 13.27: 修复小程序列表页面下拉刷新回位问题

Story

问题描述

技术解决方案

Acceptance Criteria

Tasks / Subtasks

Dev Notes

问题背景

相关文件路径

代码实现模式

项目结构说明

Taro usePullDownRefresh 参考

测试建议

Architecture Compliance

技术栈

代码规范

References

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

13-27-fix-pulldown-refresh-rebound.md 9.4 KB تاريخچه خام

Story 13.27: 修复小程序列表页面下拉刷新回位问题

Story

问题描述

技术解决方案

Acceptance Criteria

Tasks / Subtasks

Dev Notes

问题背景

相关文件路径

代码实现模式

项目结构说明

Taro usePullDownRefresh 参考

测试建议

Architecture Compliance

技术栈

代码规范

References

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

13-27-fix-pulldown-refresh-rebound.md 9.4 KB

تاريخچه خام