Skip to content

Commit 27fec0e

Browse files
MTtankkeodkwingsmtvictorsannielliette
authored
Add dedicated rubber band spring for overscroll recovery in BouncingScrollPhysics (flutter#187568)
> [!NOTE] > **Relanding** flutter#182426. > > Thank you for your review and guidance on the previous PR. > > I'm relanding this with the fix for the test failures that caused the issue before. *(I've updated the regression test to account for the faster convergence rate of the new physics.)* Fixes flutter#181752 *(for detailed analysis, measurements, and discussion, please refer to the original issue.)* This pull request implements a dedicated “rubber band” physics for overscroll snap-back in BouncingScrollPhysics on iOS to better match the native UIScrollView feel. <img width="1000" alt="546867255-4ad56291-9603-40c1-ae5a-3e319017c3c9" src="https://github.com/user-attachments/assets/8e72ebff-fb8f-4613-b042-7668db15bcf5" /> - - - > [!NOTE] > This change adjusts spring constants and simulation behavior > to improve iOS scroll fidelity. > > Given that this change primarily involves physics parameter tuning, > it may reasonably qualify as test-exempt. However, I am not entirely > certain what level of automated testing would be considered appropriate. > > Please let me know if additional tests are expected, > and I am happy to update the PR accordingly. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md --------- Co-authored-by: Tong Mu <[email protected]> Co-authored-by: Victor Sanni <[email protected]> Co-authored-by: Elliott Brooks <[email protected]>
1 parent 8f392c2 commit 27fec0e

5 files changed

Lines changed: 181 additions & 158 deletions

File tree

‎packages/flutter/examples/api/test/material/app_bar/sliver_app_bar.4_test.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ void main() {
3131
expect(find.widgetWithText(SliverAppBar, 'SliverAppBar'), findsOneWidget);
3232
expect(
3333
tester.getBottomLeft(find.text('SliverAppBar')).dy,
34-
187.63506380825314,
34+
185.41520737749101,
3535
);
3636

3737
await tester.tap(switchFinder);

‎packages/flutter/lib/src/widgets/scroll_physics.dart‎

Lines changed: 46 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -731,6 +731,47 @@ class BouncingScrollPhysics extends ScrollPhysics {
731731
/// Used to determine parameters for friction simulations.
732732
final ScrollDecelerationRate decelerationRate;
733733

734+
// Approximation of iOS native rubber band decay rate.
735+
static const double _rubberBandHalfLifeSeconds = 0.07;
736+
737+
// Decay constant (lambda) for rubber band spring simulation.
738+
static final double _rubberBandLambda = math.log(2) / _rubberBandHalfLifeSeconds;
739+
740+
/// Spring used to animate overscroll bounce from a stationary release in iOS
741+
/// native style.
742+
///
743+
/// Used in [createBallisticSimulation] depending on the conditions.
744+
///
745+
/// Research indicates that iOS employs a distinct decay function when a
746+
/// scrollable area is released in an overscroll and stationary state (zero
747+
/// initial velocity), conforming to an exponential decay model.
748+
//
749+
// ## Mathematical derivation
750+
//
751+
// A standard spring-damper system follows the second-order differential equation:
752+
// m*x'' + c*x' + k*x = 0
753+
//
754+
// To force this second-order system to behave like a first-order exponential
755+
// decay x(t) = C * e^(-lambda * t), we configure it as an overdamped spring
756+
// with two explicitly defined roots (r1 and r2) for its characteristic
757+
// equation:
758+
//
759+
// * r1 = -lambda (the primary root driving the visible exponential decay)
760+
// * r2 = -100000 * lambda (an extremely large negative root)
761+
//
762+
// Because r2 is massive and negative, its corresponding term in the exact
763+
// mathematical solution (C2 * e^(r2 * t)) decays to zero almost
764+
// instantaneously. The system movement becomes dominated by r1.
765+
//
766+
// Using Vieta's formulas for the characteristic equation r^2 + (c/m)r + (k/m) = 0:
767+
// * r1 + r2 = -c/m => damping (c) = -(r1 + r2) * m
768+
// * r1 * r2 = k/m => stiffness (k) = (r1 * r2) * m
769+
static final SpringDescription rubberBandSpring = SpringDescription(
770+
mass: 1.0,
771+
stiffness: 1e5 * _rubberBandLambda * _rubberBandLambda,
772+
damping: (1e5 + 1) * _rubberBandLambda,
773+
);
774+
734775
@override
735776
BouncingScrollPhysics applyTo(ScrollPhysics? ancestor) {
736777
return BouncingScrollPhysics(parent: buildParent(ancestor), decelerationRate: decelerationRate);
@@ -810,9 +851,12 @@ class BouncingScrollPhysics extends ScrollPhysics {
810851
@override
811852
Simulation? createBallisticSimulation(ScrollMetrics position, double velocity) {
812853
final Tolerance tolerance = toleranceFor(position);
813-
if (velocity.abs() >= tolerance.velocity || position.outOfRange) {
854+
final bool isStationary = velocity.abs() < tolerance.velocity;
855+
final bool isRubberBand = isStationary && position.outOfRange;
856+
857+
if (!isStationary || position.outOfRange) {
814858
return BouncingScrollSimulation(
815-
spring: spring,
859+
spring: isRubberBand ? rubberBandSpring : spring,
816860
position: position.pixels,
817861
velocity: velocity,
818862
leadingExtent: position.minScrollExtent,

‎packages/flutter/test/cupertino/refresh_test.dart‎

Lines changed: 67 additions & 154 deletions
Original file line numberDiff line numberDiff line change
@@ -150,34 +150,18 @@ void main() {
150150
refreshTriggerPullDistance: 100, // default value.
151151
refreshIndicatorExtent: 60, // default value.
152152
),
153-
if (debugDefaultTargetPlatformOverride == TargetPlatform.macOS)
154-
matchesBuilder(
155-
refreshState: RefreshIndicatorMode.drag,
156-
pulledExtent: moreOrLessEquals(48.07979523362715),
157-
refreshTriggerPullDistance: 100, // default value.
158-
refreshIndicatorExtent: 60, // default value.
159-
)
160-
else
161-
matchesBuilder(
162-
refreshState: RefreshIndicatorMode.drag,
163-
pulledExtent: moreOrLessEquals(48.36801747187993),
164-
refreshTriggerPullDistance: 100, // default value.
165-
refreshIndicatorExtent: 60, // default value.
166-
),
167-
if (debugDefaultTargetPlatformOverride == TargetPlatform.macOS)
168-
matchesBuilder(
169-
refreshState: RefreshIndicatorMode.drag,
170-
pulledExtent: moreOrLessEquals(43.98499220391114),
171-
refreshTriggerPullDistance: 100, // default value.
172-
refreshIndicatorExtent: 60, // default value.
173-
)
174-
else
175-
matchesBuilder(
176-
refreshState: RefreshIndicatorMode.drag,
177-
pulledExtent: moreOrLessEquals(44.63031931875867),
178-
refreshTriggerPullDistance: 100, // default value.
179-
refreshIndicatorExtent: 60, // default value.
180-
),
153+
matchesBuilder(
154+
refreshState: RefreshIndicatorMode.drag,
155+
pulledExtent: moreOrLessEquals(41.01717797216727),
156+
refreshTriggerPullDistance: 100, // default value.
157+
refreshIndicatorExtent: 60, // default value.
158+
),
159+
matchesBuilder(
160+
refreshState: RefreshIndicatorMode.drag,
161+
pulledExtent: moreOrLessEquals(33.64784129423112),
162+
refreshTriggerPullDistance: 100, // default value.
163+
refreshIndicatorExtent: 60, // default value.
164+
),
181165
]),
182166
);
183167
// The builder isn't called again when the sliver completely goes away.
@@ -319,20 +303,12 @@ void main() {
319303
refreshIndicatorExtent: 60, // Default value.
320304
),
321305
equals(const RefreshTaskInvocation()),
322-
if (debugDefaultTargetPlatformOverride == TargetPlatform.macOS)
323-
matchesBuilder(
324-
refreshState: RefreshIndicatorMode.armed,
325-
pulledExtent: moreOrLessEquals(124.87933920045268),
326-
refreshTriggerPullDistance: 100, // Default value.
327-
refreshIndicatorExtent: 60, // Default value.
328-
)
329-
else
330-
matchesBuilder(
331-
refreshState: RefreshIndicatorMode.armed,
332-
pulledExtent: moreOrLessEquals(127.10396988577114),
333-
refreshTriggerPullDistance: 100, // Default value.
334-
refreshIndicatorExtent: 60, // Default value.
335-
),
306+
matchesBuilder(
307+
refreshState: RefreshIndicatorMode.armed,
308+
pulledExtent: moreOrLessEquals(91.42693833475049),
309+
refreshTriggerPullDistance: 100, // Default value.
310+
refreshIndicatorExtent: 60, // Default value.
311+
),
336312
]),
337313
);
338314

@@ -382,9 +358,6 @@ void main() {
382358
(WidgetTester tester) async {
383359
final error = FlutterError('Oops');
384360
double errorCount = 0;
385-
final TargetPlatform? platform =
386-
debugDefaultTargetPlatformOverride; // Will not be correct within the zone.
387-
388361
runZonedGuarded(
389362
() async {
390363
mockHelper.refreshCompleter = Completer<void>.sync();
@@ -417,20 +390,12 @@ void main() {
417390
refreshTriggerPullDistance: 100, // Default value.
418391
),
419392
equals(const RefreshTaskInvocation()),
420-
if (platform == TargetPlatform.macOS)
421-
matchesBuilder(
422-
refreshState: RefreshIndicatorMode.armed,
423-
pulledExtent: moreOrLessEquals(124.87933920045268),
424-
refreshTriggerPullDistance: 100, // Default value.
425-
refreshIndicatorExtent: 60, // Default value.
426-
)
427-
else
428-
matchesBuilder(
429-
refreshState: RefreshIndicatorMode.armed,
430-
pulledExtent: moreOrLessEquals(127.10396988577114),
431-
refreshIndicatorExtent: 60, // Default value.
432-
refreshTriggerPullDistance: 100, // Default value.
433-
),
393+
matchesBuilder(
394+
refreshState: RefreshIndicatorMode.armed,
395+
pulledExtent: moreOrLessEquals(91.42693833475049),
396+
refreshIndicatorExtent: 60, // Default value.
397+
refreshTriggerPullDistance: 100, // Default value.
398+
),
434399
]),
435400
);
436401

@@ -762,47 +727,25 @@ void main() {
762727
// Waiting for refresh control to reach approximately 5% of height
763728
await tester.pump(const Duration(milliseconds: 400));
764729

765-
if (debugDefaultTargetPlatformOverride == TargetPlatform.macOS) {
766-
expect(
767-
tester.getRect(find.widgetWithText(Center, '0')).top,
768-
moreOrLessEquals(3.9543032206542765, epsilon: 4e-1),
769-
);
770-
expect(
771-
tester.getRect(find.widgetWithText(Center, '-1')).height,
772-
moreOrLessEquals(3.9543032206542765, epsilon: 4e-1),
773-
);
774-
expect(
775-
mockHelper.invocations,
776-
contains(
777-
matchesBuilder(
778-
refreshState: RefreshIndicatorMode.inactive,
779-
pulledExtent: 3.9543032206542765, // ~5% of 60.0
780-
refreshTriggerPullDistance: 100, // default value.
781-
refreshIndicatorExtent: 60, // default value.
782-
),
783-
),
784-
);
785-
} else {
786-
expect(
787-
tester.getRect(find.widgetWithText(Center, '0')).top,
788-
moreOrLessEquals(3.0, epsilon: 4e-1),
789-
);
790-
expect(
791-
tester.getRect(find.widgetWithText(Center, '-1')).height,
792-
moreOrLessEquals(3.0, epsilon: 4e-1),
793-
);
794-
expect(
795-
mockHelper.invocations,
796-
contains(
797-
matchesBuilder(
798-
refreshState: RefreshIndicatorMode.inactive,
799-
pulledExtent: 2.6980688300546443, // ~5% of 60.0
800-
refreshTriggerPullDistance: 100, // default value.
801-
refreshIndicatorExtent: 60, // default value.
802-
),
730+
expect(
731+
tester.getRect(find.widgetWithText(Center, '0')).top,
732+
moreOrLessEquals(1.1428367291871382, epsilon: 4e-1),
733+
);
734+
expect(
735+
tester.getRect(find.widgetWithText(Center, '-1')).height,
736+
moreOrLessEquals(1.1428367291871382, epsilon: 4e-1),
737+
);
738+
expect(
739+
mockHelper.invocations,
740+
contains(
741+
matchesBuilder(
742+
refreshState: RefreshIndicatorMode.inactive,
743+
pulledExtent: 1.1428367291871382,
744+
refreshTriggerPullDistance: 100, // default value.
745+
refreshIndicatorExtent: 60, // default value.
803746
),
804-
);
805-
}
747+
),
748+
);
806749
expect(find.text('-1'), findsOneWidget);
807750
},
808751
variant: const TargetPlatformVariant(<TargetPlatform>{
@@ -851,39 +794,21 @@ void main() {
851794
// Let it start going away but not fully.
852795
await tester.pump(const Duration(milliseconds: 100));
853796
// The refresh indicator is still building.
854-
if (debugDefaultTargetPlatformOverride == TargetPlatform.macOS) {
855-
expect(
856-
mockHelper.invocations,
857-
contains(
858-
matchesBuilder(
859-
refreshState: RefreshIndicatorMode.done,
860-
pulledExtent: 90.13497854600749,
861-
refreshTriggerPullDistance: 100, // default value.
862-
refreshIndicatorExtent: 60, // default value.
863-
),
864-
),
865-
);
866-
expect(
867-
tester.getBottomLeft(find.widgetWithText(Center, '-1')).dy,
868-
moreOrLessEquals(90.13497854600749),
869-
);
870-
} else {
871-
expect(
872-
mockHelper.invocations,
873-
contains(
874-
matchesBuilder(
875-
refreshState: RefreshIndicatorMode.done,
876-
pulledExtent: 91.31180913199277,
877-
refreshTriggerPullDistance: 100, // default value.
878-
refreshIndicatorExtent: 60, // default value.
879-
),
797+
expect(
798+
mockHelper.invocations,
799+
contains(
800+
matchesBuilder(
801+
refreshState: RefreshIndicatorMode.done,
802+
pulledExtent: 55.72534309610493,
803+
refreshTriggerPullDistance: 100, // default value.
804+
refreshIndicatorExtent: 60, // default value.
880805
),
881-
);
882-
expect(
883-
tester.getBottomLeft(find.widgetWithText(Center, '-1')).dy,
884-
moreOrLessEquals(91.311809131992776),
885-
);
886-
}
806+
),
807+
);
808+
expect(
809+
tester.getBottomLeft(find.widgetWithText(Center, '-1')).dy,
810+
moreOrLessEquals(55.72534309610493),
811+
);
887812

888813
// Start another drag by an amount that would have been enough to
889814
// trigger another refresh if it were in the right state.
@@ -904,7 +829,7 @@ void main() {
904829
contains(
905830
matchesBuilder(
906831
refreshState: RefreshIndicatorMode.done,
907-
pulledExtent: 118.29756539042118,
832+
pulledExtent: 87.81745749545563,
908833
refreshTriggerPullDistance: 100, // default value.
909834
refreshIndicatorExtent: 60, // default value.
910835
),
@@ -916,7 +841,7 @@ void main() {
916841
contains(
917842
matchesBuilder(
918843
refreshState: RefreshIndicatorMode.done,
919-
pulledExtent: 147.3772721631821,
844+
pulledExtent: 131.21929413745545,
920845
refreshTriggerPullDistance: 100, // default value.
921846
refreshIndicatorExtent: 60, // default value.
922847
),
@@ -1180,27 +1105,15 @@ void main() {
11801105

11811106
await tester.pump(const Duration(milliseconds: 10));
11821107

1183-
if (debugDefaultTargetPlatformOverride == TargetPlatform.macOS) {
1184-
expect(
1185-
mockHelper.invocations.last,
1186-
matchesBuilder(
1187-
refreshState: RefreshIndicatorMode.done,
1188-
pulledExtent: moreOrLessEquals(148.36088180097366),
1189-
refreshTriggerPullDistance: 100.0, // Default value.
1190-
refreshIndicatorExtent: 60.0, // Default value.
1191-
),
1192-
);
1193-
} else {
1194-
expect(
1195-
mockHelper.invocations.last,
1196-
matchesBuilder(
1197-
refreshState: RefreshIndicatorMode.done,
1198-
pulledExtent: moreOrLessEquals(148.6463892921364),
1199-
refreshTriggerPullDistance: 100.0, // Default value.
1200-
refreshIndicatorExtent: 60.0, // Default value.
1201-
),
1202-
);
1203-
}
1108+
expect(
1109+
mockHelper.invocations.last,
1110+
matchesBuilder(
1111+
refreshState: RefreshIndicatorMode.done,
1112+
pulledExtent: moreOrLessEquals(135.85990823867772),
1113+
refreshTriggerPullDistance: 100.0, // Default value.
1114+
refreshIndicatorExtent: 60.0, // Default value.
1115+
),
1116+
);
12041117

12051118
await tester.pump(const Duration(seconds: 5));
12061119
expect(find.text('-1'), findsNothing);

‎packages/flutter/test/widgets/range_maintaining_scroll_physics_test.dart‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -362,7 +362,9 @@ void main() {
362362
await drag2.up();
363363

364364
// verify there's a ballistic animation from overscroll
365-
expect(await tester.pumpAndSettle(), 9);
365+
// With the introduction of the new `rubberBandSpring` (exponential decay model),
366+
// the overscroll settle animation converges faster and takes 8 frames instead of 9.
367+
expect(await tester.pumpAndSettle(), 8);
366368
});
367369
}
368370

0 commit comments

Comments
 (0)