📢 【三方库】ohos_pull_to_refresh v2.1.3 鸿蒙平台稳定性与质量提升

ohos_pull_to_refresh v2.1.3 已发布。本次升级聚焦该库质量提升，新增 enableNestedScroll 嵌套滚动支持以解决半模态弹窗（bindSheet）下拉关闭手势冲突，并将全局 animateTo 替换为 uiContext.animateTo 以提升动画调用稳定性与上下文准确性，兼容升级，开发者无需修改现有代码即可享受本次改进。推荐所有该库用户升级至本版本。

版本概览

质量提升

PullToRefresh 支持下拉关闭半模态弹窗 #88

问题：当 PullToRefresh 被嵌套在半模态弹窗（bindSheet）中使用时，组件主体区域原先以 Column 承载 customList，并完全依赖 parallelGesture(PanGesture(...)) 处理下拉/上拉手势。该 PanGesture 会抢占顶层向下的手势，导致 bindSheet 原生的「下拉关闭弹窗」手势被拦截，用户无法通过下拉动作关闭半模态弹窗。

修复（library/src/main/ets/components/PullToRefresh/PullToRefresh.ets，约 94 行改动；PullToRefreshV2.ets 同步变更约 93 行）：

• 新增可选参数 enableNestedScroll?: boolean = false（V2 中为 @Param enableNestedScroll）。开启后，主体区域由 Column 切换为内置 Scroll(this.scroller) 承载内容，并应用 .edgeEffect(EdgeEffect.None) 与默认 .nestedScroll({ scrollForward: NestedScrollMode.SELF_FIRST, scrollBackward: NestedScrollMode.SELF_FIRST }) 配置，使滚动优先由内部 Scroll 处理、剩余手势向上传递给 bindSheet，从而让弹窗的下拉关闭手势恢复正常。
• 当 enableNestedScroll === true 时，PanGesture 的 onActionStart / onActionUpdate / onActionEnd 三个回调均 return 提前退出，避免下拉刷新抢占 Sheet 的下拉关闭手势。
• 上拉加载逻辑从原 PanGesture 路径迁移至 Scroll 的 .onReachEnd(...) 回调：内部以 this.refreshConfigurator?.getHasLoadMore() && this.onLoadMore && !this.isLoadingMore 作为触发条件，并新增 isLoadingMore 标志位防止重复触发；onLoadMore() 的 Promise resolve/reject 分支均先判断 if (this.isDestroyed) return; 再调用 closeLoad()，避免对已销毁组件执行动画。
• 新增 aboutToDisappear() 生命周期：置 this.isDestroyed = true 并在 this.timer !== undefined 时 clearInterval 且置空，防止组件销毁后定时器继续回调引发异常。

将 animateTo 改为 uiContext.animateTo #78

问题：closeRefresh() 与 closeLoad() 中原先直接调用全局 animateTo({ duration: ... }, () => {...})。该全局 API 依赖隐式取得的当前 UI 上下文，在组件所在 UIContext 与默认上下文不一致或上下文不可得的场景下，关闭刷新/加载的回弹动画可能不生效或行为异常；同时全局 animateTo 已不推荐使用。

修复（library/src/main/ets/components/PullToRefresh/PullToRefresh.ets，6 行改动；PullToRefreshV2.ets 同步变更 6 行）：

• 新增成员 uiContext: UIContext | undefined = undefined，并在 aboutToAppear() 中通过 this.uiContext = this.getUIContext() 显式获取并缓存当前组件的 UIContext。
• 将 closeRefresh() 与 closeLoad() 中的 animateTo({ duration: this.refreshConfigurator.getAnimDuration() }, () => { this.trYTop = 0; })（及 trYBottom 对应调用）替换为 this.uiContext?.animateTo({...}, () => {...})，使用可选链保证 uiContext 为空时安全跳过，2 处调用点均完成迁移。

兼容性说明

• 无 Breaking Changes，API 接口保持不变。
• enableNestedScroll 为新增可选参数，默认 false，未开启时组件行为与旧版本一致；animateTo 的替换为内部实现优化，对外无感知。
• 现有代码无需修改，从 v2.1.2 起升级至 v2.1.3 均为兼容性升级。

升级方式

• 鸿蒙原生：oh-package.json5 → "@ohos/pulltorefresh": "^2.1.3"，执行 ohpm install。

相关链接

• 文档：https://gitcode.com/CPF-ApplicationTPC/ohos_pull_to_refresh/blob/master/README.md
• CHANGELOG：https://gitcode.com/CPF-ApplicationTPC/ohos_pull_to_refresh/blob/master/changelog.md
• 反馈：https://gitcode.com/CPF-ApplicationTPC/ohos_pull_to_refresh/issues