Skip to content

fix(h5): 修复 pageScrollTo 动画越过目标位置 - #19584

Merged
Single-Dancer merged 1 commit into
NervJS:mainfrom
Jarvis636431:fix/h5-scroll-target
Nov 2, 2026
Merged

Single-Dancer merged 1 commit into
NervJS:mainfrom
Jarvis636431:fix/h5-scroll-target

Conversation

@Jarvis636431

@Jarvis636431 Jarvis636431 commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

这个 PR 做了什么?

H5 pageScrollTo 的动画帧上限与缓动函数的归一化区间不一致,最后几帧会使用超过 1 的进度值。从 0 滚到 200,duration=300 时最终写入约 200.429;duration=34 时最终写入 1000。

按向上取整的帧数计算进度,在终帧精确写入目标位置,使中间位置保持在起点和目标之间。覆盖元素及 Window 滚动,保留 selector/offsetTop 定位。连续调用时的取消结算和同时传入 scrollTop/selector 的优先级不在本次范围。

Closes #16609

这个 PR 是什么类型?

  • 错误修复 (Bugfix)

这个 PR 涉及以下平台:

  • Web 端(H5)

验证

  • 新增 20 个回归用例,原实现 12 个失败、8 个通过;修复后全部通过。
  • 覆盖 0/1/17/18/34/51/300ms、向上及向下滚动、精确终点、中间位置不越界、成功/完成回调只调用一次、selector 偏移及已在目标处。
  • pnpm --filter @tarojs/taro-h5 run test:ci --watchman=false:30 个套件、263 个用例通过,退出码 0。
  • pnpm --filter @tarojs/taro-h5 run build:通过,退出码 0;存在未修改的 previewImage/Swiper 类型及 Sass 弃用告警。沙箱构建生成产物后残留空闲进程,清理后在正常权限下重跑通过。
  • 修改源码及新测试 ESLint(--no-ignore)、差异空白检查(保留原文件 CRLF)通过。

Node.js 22.18.0 / pnpm 10.0.0。分支独立基于上游 main 0493b5251da,仅包含滚动源码和回归测试。测试使用真实源码、JSDOM 与可控计时器,未运行完整浏览器应用或真机验证;未修改依赖及锁文件。

Summary by CodeRabbit

  • Bug Fixes
    • 修复页面滚动在不同持续时间下无法准确到达目标位置的问题;滚动结束时会精确停在目标位置,向上滚动可到达页面顶部,已到达目标时则保持当前位置。
    • 修复滚动至选择器目标并应用偏移量后的定位表现。
  • Tests
    • 补充页面滚动行为测试,覆盖不同滚动模式、目标位置及回调结果。

@coderabbitai

coderabbitai Bot commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: dcebd213-dbad-46fa-a9f6-1f234b11ec3e
Commits

Reviewing files that changed from the base of the PR and between 562e713 and ff9b345.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review

No actionable comments were generated in the recent review.

Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: ce3f4bbb-3880-467a-9668-0ed825fb22a0
Commits

Reviewing files that changed from the base of the PR and between 0493b52 and 562e713.

Files selected for processing: 2
  • packages/taro-h5/__tests__/ui/scroll.test.ts
  • packages/taro-h5/src/api/ui/scroll/index.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

Walkthrough

pageScrollTo 现在向上取整计算帧数,并在结束帧直接滚动到目标位置。新增测试覆盖两种窗口滚动配置下的位置、回调和计时器行为。

Changes

H5 页面滚动

Layer / File(s) Summary
滚动结束位置与验证
packages/taro-h5/src/api/ui/scroll/index.ts, packages/taro-h5/__tests__/ui/scroll.test.ts
帧数改为向上取整,缓动采样数设为帧数加一。达到帧数上限时直接滚动到目标位置并完成。测试覆盖到达目标、滚动至零、目标位置不变、选择器偏移、回调和计时器清理。

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Low

Suggested reviewers: zakarycode, tutuxxx

Merge Risk: Minimal · previous review 562e7

The scroll fix has no identified merge-blocking risk.

Pre-merge checks: Passed 5
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed 标题准确概括了主要变更:修复 H5 pageScrollTo 动画越过目标位置的问题。
Linked Issues check Passed [#16609] 要求 H5 pageScrollTo 滚动准确,不得多滚一帧。问题根因是最后一帧使 easeFunc(frame) 的 frame 等于 frameCnt,进度超过 1。

源码差异(基线 0493b52 至 head 562e713)显示:
- frameCnt = Math.ceil(duration / FRAME_DURATION)。
- `e…
Out of Scope Changes check Passed 已检查的源码差异仅修改 packages/taro-h5/src/api/ui/scroll/index.ts 中的 pageScrollTo 帧计算与终帧逻辑。该改动直接对应 #16609 的过冲问题。PR 描述与 raw summary 提到的新增测试 packages/taro-h5/__tests__/ui/scroll.test.ts 用于验证同一行为,属于支持性测试,与目标…
Docstring Coverage Passed No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Full details: Linked Issues check

Explanation

[#16609] 要求 H5 pageScrollTo 滚动准确,不得多滚一帧。问题根因是最后一帧使 easeFunc(frame) 的 frame 等于 frameCnt,进度超过 1。

源码差异(基线 0493b52 至 head 562e713)显示:

  • frameCnt = Math.ceil(duration / FRAME_DURATION)。
  • easeFunc = getTimingFunc(easeInOut, frameCnt + 1)。getTimingFunc 的进度为 x / (N - 1),因此有效进度为 frame / frameCnt。
  • 当 frame < frameCnt 时,进度落在 [0, 1) 内,写入值位于起点与目标之间。
  • 当 frame >= frameCnt 时,执行 scrollFunc(to) 精确写入目标,随后调用 handle.success。
  • duration 为 0 时,frameCnt 为 0,直接写入目标并成功返回。

PR 采用的方案与 issue 建议不同:issue 建议把 scrollFunc(dest) 移入 frame < frameCnt 条件内,PR 改为先判断终帧再写入精确目标。两者都满足 issue 的目标结果(不越界、终点准确)。usingWindowScroll 与元素滚动分支均通过同一 scrollFunc 写入,行为一致。

未核实:新增测试文件的内容未逐行检查,测试通过结果以 PR 描述为准。该结论不影响需求满足判断。

Full details: Out of Scope Changes check

Explanation

已检查的源码差异仅修改 packages/taro-h5/src/api/ui/scroll/index.ts 中的 pageScrollTo 帧计算与终帧逻辑。该改动直接对应 #16609 的过冲问题。PR 描述与 raw summary 提到的新增测试 packages/taro-h5/__tests__/ui/scroll.test.ts 用于验证同一行为,属于支持性测试,与目标相关。

PR 明确排除了连续调用时的取消结算,以及 scrollTop 与 selector 同时传入时的优先级。源码差异中未见对这两部分的改动。

未核实:仓库文件列表被截断,无法完整枚举 PR 的全部变更文件。判定基于已检查的源码差异与 PR 描述,未发现与 #16609 无关的改动。

Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 2 files.

Finishing Touches
Generate unit tests (beta)
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

兔子蹦到滚动边,
逐帧轻点不越线。
终点稳稳停下来,
回调响起计时歇。
月光照着页面眠。

@coderabbitai
coderabbitai Bot requested review from ZakaryCode and tutuxxx October 31, 2026 05:08
@codecov

codecov Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 57.75%. Comparing base (32ef70b) to head (ff9b345).

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main   #19584      +/-   ##
==========================================
+ Coverage   57.57%   57.75%   +0.17%     
==========================================
  Files         470      470              
  Lines       25966    25966              
  Branches     6512     6495      -17     
==========================================
+ Hits        14951    14996      +45     
+ Misses       9221     9032     -189     
- Partials     1794     1938     +144     
Flag Coverage Δ
taro-cli 59.69% <ø> (ø)
taro-runtime 66.00% <ø> (ø)
taro-web 66.90% <100.00%> (+1.13%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
packages/taro-h5/src/api/ui/scroll/index.ts 90.19% <100.00%> (+80.39%) ⬆️

... and 44 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@Single-Dancer Single-Dancer left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

审查通过,未发现阻断合并的问题。

固定审查 head:562e7136473854719763e3f4da3b750ba53fc8cc。
已追踪 pageScrollTo → getTimingFunc/easeInOut → MethodHandler,以及元素/Window 两种滚动路径。向上取整后的帧数与 getTimingFunc 的 frameCnt - 1 分母保持一致,终帧直接写入目标值,修复越界且不修改公共 API、selector/offsetTop 计算或回调协议。

独立验证(隔离源码快照,复用本地已安装依赖):

  • 同一批新增回归测试在旧实现上 12 失败、8 通过;修复后 20/20 通过。
  • H5 全量 Jest:30 个套件、263 个用例全部通过。
  • 真实 Chromium 中,直接执行真实滚动源码、缓动函数与 MethodHandler,使用最小 runtime 适配;元素和 Window 滚动共 20 个场景通过。duration=34ms、0→200px 的场景,旧实现终点 1000px,新实现终点 200px。
  • GitHub 当前检查均成功或跳过,PR 已包含当前 main,不需要 rebase。

验证边界:未运行完整 Taro 应用、Safari/移动端浏览器或本地生产构建。连续调用取消结算和 scrollTop/selector 同传优先级为既有行为,不作为本次修复的新增问题。

@Single-Dancer Single-Dancer added this to the 4.3.2 milestone Nov 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Taro.pageScrollTo 滚动位置不准确

2 participants