Add ability to control scroll animation duration for Android

[dannycochran]

Motivation

This is one of the more sought after feature requests for RN:
https://react-native.canny.io/feature-requests/p/add-speed-attribute-to-scrollto

This PR adds the support to add a "duration" whenever using "scrollTo" or "scrollToEnd" with
a scrollView. Currently this only exists for Android as the iOS implementation will be somewhat more involved.

This PR is also backwards compatible and does not yet deprecate the "animated" boolean. It may not make sense to ever deprecate "animated", as it could be the flag that is used when devs want the system default duration (which is 250ms for Android). I'm not sure what it is for iOS. It would simplify things to remove "animated", though.

Test Plan

1. Create a ScollView component that overflows the bounds of the container, e.g.:

  render() {
    return (
      <View style={styles.container}>
        <Button onPress={this.scrollToPosition} title="Scroll to Position" color="#841584" />
        <ScrollView style={styles.scrollView} ref={scrollView => this.scrollView = scrollView}>
          {items.map(item => {
            return <View key={item.key} style={styles.scrollViewItem}><Text>{item.text}</Text></View>
          })}
        </ScrollView>
      </View>
    );
  }

2. Using the "scrollView" ref and the Button callback, scroll to a position with a desired duration speed, e.g:

scrollToPosition = () => {
  this.scrollView && this.scrollView.scrollTo({
    y: 500
    duration: 1000
  });
};

3. Ensure the legacy "animated" boolean works as expected:

scrollToPosition = () => {
  this.scrollView && this.scrollView.scrollTo({
    y: 500
    animated: true
  });
};

4. Test that you can animate the x position as well (change the ScrollView to be horizontal).
5. Test that the scroll animation is canceled when touching on the scroll view in the middle of an animation.
6. Test that repeated calls to animate the scrollView don't queue up (e.g. smashing the in the example above, and then tapping into the scrollView should cancel any animation movement).

Vertical scroll:
https://drive.google.com/file/d/1VhaolHx63GOv0YWTg7ay0GtzW1nIk635/view?usp=sharing

Horizontal scroll:
https://drive.google.com/file/d/1yq5P1k4-KPPu9BhS6B9liL-NRGX1Z4gA/view?usp=sharing

Related PRs

Abandoned PR to bring "duration" to iOS:
#1334

Updated docs on react-native-website:
facebook/react-native-website#115

Release Notes

[ANDROID] [ENHANCEMENT] [ScrollView] - Added support for controlling animation duration speed for methods "scrollTo" and "scrollToEnd"

[facebook-github-bot]

Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have you on file. In order for us to review and merge your code, please sign up at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need the corporate CLA signed.

If you have received this in error or have any questions, please contact us at [email protected]. Thanks!

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks!

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks!

[janicduplessis]

Thanks for working on this!

Got a few questions just to make sure, does the technique you used to animate the scroll position is exactly the same as ScrollView#smoothScrollTo (same animation easing curve, etc) and have you tested cancelling animations (either tapping or starting a second animation while the first is still running)?

[dannycochran]

@janicduplessis thanks for the response. I imagine we'll have to go through a few iterations here as this is my first PR with react-native :-)

1. The duration should be the same as "smoothScrollTo" (which calls startScroll, which defaults to a 250ms duration), but I'm not sure the easing curve is. If we wanted to, I could use the existing "smoothScrollTo" for when users specify {animated: true}, but if we just look at duration things get a little simpler from a code complexity perspective.

2. I need to test this some more. What should the desired behavior be? If a user drags the scrollView in the middle of an animation, should it cancel the existing animation? That probably is the best behavior, and if devs want to prevent an animation from being canceled they set "pointerEvents='none'".

[dannycochran]

@janicduplessis I fixed it so that repeated calls to animate the ScrollView would cancel the previous animation, as well as canceling an animation that was interrupted by a touch event.

As for the interpolation, it looks like "smoothScrollTo" used ViscousFluidInterpolator, which is not public:
https://android.googlesource.com/platform/frameworks/base.git/+/master/core/java/android/widget/Scroller.java#561

Whereas ObjectAnimator defaults to the AccelerateDecelerateInterpolator:
https://developer.android.com/reference/android/view/animation/AccelerateDecelerateInterpolator.html

We could either just go with AccelerateDecelerateInterpolator, or copy in the ViscousFluidInterpolator code. I'm fine with either approach. The existing "smoothScrollTo" animation duration is so fast it's pretty difficult to notice the difference between interpolation methods.

[dannycochran]

@janicduplessis Anything else needed on my end? The failing Android test appears to be unrelated.

[alpamys-qanybet]

@dannycochran, Hi there,
I have implemented your code for Android, everything works ok, built from source, now I need to implement it in ios.
pull request for ios seems to be on forked project, not react-native itself.
#1334
how can I implement it for ios?

[alpamys-qanybet]

@dannycochran,
I implemented the code for iOS, however I do not know iOS with this commit, also, there is your code too.
Can you or somebody else who know iOS check the code?

Especially this part

     [UIView animateWithDuration:duration
          delay:0
        options:UIViewAnimationOptionBeginFromCurrentState
     animations:^(void) {
       [_scrollView setContentOffset:offset];
     } completion:^(__unused BOOL finished) {
     }];

[sahrens]

cc @shergin for iOS code.

[sahrens]

cc @skevy as well since he wrote the original implementation.

[dannycochran]

Pinging anyone who might be available to review :-) @janicduplessis @sahrens @skevy @shergin

[sahrens]

I have no idea if this Animator object is legit - @janicduplessis or @mdvacca?

[dannycochran]

It has support from API 11:

https://developer.android.com/reference/android/animation/ObjectAnimator.html

FWIW we've been using this ScrollView (via overwriting the ScrollView package in MainApplication.Java) in production for the past 6 weeks, in production / release. We also use it in a fairly expensive SectionList which does all sorts of crazy optimizations and is a good stress test for performance.

[sahrens]

I would still like signoff from someone that knows our android codebase...@janicduplessis, @mdvacca, or @axe-fb?

[dannycochran]

Sounds good.

[sahrens]

duration || 0 seems wrong - should probably just send the null. I could imagine people explicitly setting 0 as an equivalent to animated: false.

[dannycochran]

I was following the existing pattern with this API where a default value is always provided.

In ReactScrollViewCommandHelper.java, a duration of zero is effectively ignored.

It's tricky, though, because we want to support the existing animated API so this is backwards compatible. So what happens if a user says "animated: true, duration: 0", or "animated: false, duration: 250"? In ReactScrollViewCommandHelper, I defer first to duration value. If duration is non-zero, we animate with that duration. Otherwise, if animated is true, we use the legacy animation duration (250).

[sahrens]

Sorry, thought I replied earlier.

I'm not too concerned about cases where users give ambiguous input. If a user says "animated: true, duration: 0" there is no right answer, so we can do whatever - undefined behavior.

If the user calls scrollTo({y, duration: 0}) it's very clear that they don't want it to animate, and we should respect that clear intention and not animate it rather than making them figure out they should set animated: false instead. At the very least we could add an invariant that catches that case

[dannycochran]

Ah I see, I was missing the part where animated defaults to true in this code, and we'd probably want to preserve that, but then not respect it if a user passes duration: 0.

[dannycochran]

@sahrens any update here? I replied to your comments above. I'm happy to make some changes if you'd like but it'd be nice if we could have a more regular back and forth cadence :)

[sahrens]

again, let's just pass null instead of 0 by default and ignore it so that 0 is a valid input that effectively disables animation.

[sahrens]

This is not a good example because it's unclear what this should do.

[dannycochran]

Added a separate example just for duration.

[dannycochran]

@mdvacca you know it made a lot more sense to just put the "mAnimator" object inside the ScrollView itself, and have the managers call "animateScroll". That way the ScrollView can use its "onTouchEvent" to cancel the mAnimator if there's one currently in flight:

6161dd8

Tested locally and it's working on both vertical / horizontal scroll views.

[dannycochran]

@mdvacca @sahrens Anything else needed here? Would love to get this merged :-)

[dannycochran]

@grabbou pinging for help here on a reviewer as well. I seem to have gotten sign off on the JS and Android side of things, but still need an official approval.

[grabbou]

Would be great to have a word from @janicduplessis before landing as he did some comments previously.

CC: @hramos this PR has been already approved by few developers and is looking for official (and final) approval to land it. Would you be able to help or find someone who can look into it?

[hramos]

Can you open a PR that applies these same changes to https://github.com/facebook/react-native-website/blob/master/docs/scrollview.md ?

These comments are not synced. At some point we need to update these comments with links to the generated docs at http://facebook.github.io/react-native instead (I've done this with a few source files already but had not gotten to ScrollView yet).

[dannycochran]

Done:

facebook/react-native-website#115

[hramos]

Looks good to me, but looks like we'd need confirmation from @janicduplessis and others.

Please reach out to them via Slack or other means.

[facebook-github-bot]

@dannycochran I tried to find reviewers for this pull request and wanted to ping them to take another look. However, based on the blame information for the files in this pull request I couldn't find any reviewers. This sometimes happens when the files in the pull request are new or don't exist on master anymore. Is this pull request still relevant? If yes could you please rebase? In case you know who has context on this code feel free to mention them in a comment (one person is fine). Thanks for reading and hope you will continue contributing to the project.

[dannycochran]

@facebook-github-bot @janicduplessis I've rebased changes here. This change remains relevant and one of the most upvoted feature requests in Canny.

[janicduplessis]

Could you make this so that it uses smoothScrollTo when using the default duration (just {animated: true})? I'd rather keep the default android behavior and this will avoid changing the scrolling behavior in subtle ways.

Looking at the source for smoothScrollTo it seems to do a lot more than just animating the scroll position. See https://android.googlesource.com/platform/frameworks/base/+/jb-release/core/java/android/widget/ScrollView.java#1103 and https://android.googlesource.com/platform/frameworks/base/+/refs/heads/master/core/java/android/widget/OverScroller.java. Sadly there isn't a way to customize the OverScroll instance easily (maybe possible with some crazy reflection stuff).

[janicduplessis]

Also cc @mdvacca :)

[facebook-github-bot]

@dannycochran I tried to find reviewers for this pull request and wanted to ping them to take another look. However, based on the blame information for the files in this pull request I couldn't find any reviewers. This sometimes happens when the files in the pull request are new or don't exist on master anymore. Is this pull request still relevant? If yes could you please rebase? In case you know who has context on this code feel free to mention them in a comment (one person is fine). Thanks for reading and hope you will continue contributing to the project.

[sahrens]

Thanks for reviewing, @janicduplessis!

@dannycochran: can you make those changes? I agree this would be a nice improvement :)

[evanjmg]

Any update on this? @dannycochran can you fix your conflicts?

[kabus202]

Any updates on this?

[paulmand3l]

Ping. This is so close, it would be a shame for it to get dropped now.

[osdnk]

I would love to have it merged, @janicduplessis @mdvacca @dannycochran

[hramos]

In cases like this, where a pull request has been thoroughly reviewed but still remains in a "Changes Requested" state, I'd encourage the community to "commandeer" the PR by creating their own pull request that incorporates the requested changes. If anyone does this, please ping me or Spencer and we'll take a look.

[hramos]

Thanks @osdnk for picking up the work: #22884 is a copy of this PR with resolved conflicts.

[cpojer]

Closing in favor of #22884.

[avinashpatnaik]

Was this released? It doesnt seem to work in Android when I get the react-native from 'https://github.com/expo/react-native/archive/sdk-36.0.0.tar.gz'. I checked the ReactScrollViewCommandHelper(I am assumimg this is where the changes happened) and there is no duration variable available yet. Am I missing something here?

I am verifying my changes in an Android emulator.

[vadim-tarasenko]

You can use reanimated to make it work.

const offsetY = useSharedValue(0);

const animatedProps = useAnimatedProps<FlatListProps<unknown>>(() => {
  return {
    contentOffset: {
      x: 0,
      y: offsetY.value,
    },
  };
});

const handleScroll = () => {
  offsetY.value = withTiming(targetIndex * CARD_HEIGHT, {
    duration: YOUR_DURATION_HERE,
  });
}

return <Animated.FlatList animatedProps={animatedProps} ... />