feat(router): implement scrolling restoration service (#20030)

For documentation, see `RouterModule.scrollPositionRestoration`

Fixes #13636 #10929 #7791 #6595

PR Close #20030

packages/router/src/events.ts

@@ -401,6 +401,28 @@ export class ActivationEnd {
   }
 }
 
+/**
+ * @description
+ *
+ * Represents a scrolling event.
+ */
+export class Scroll {
+  constructor(
+      /** @docsNotRequired */
+      readonly routerEvent: NavigationEnd,
+
+      /** @docsNotRequired */
+      readonly position: [number, number]|null,
+
+      /** @docsNotRequired */
+      readonly anchor: string|null) {}
+
+  toString(): string {
+    const pos = this.position ? `${this.position[0]}, ${this.position[1]}` : null;
+    return `Scroll(anchor: '${this.anchor}', position: '${pos}')`;
+  }
+}
+
 /**
  * @description
  *
@@ -423,8 +445,9 @@ export class ActivationEnd {
  * - `NavigationEnd`,
  * - `NavigationCancel`,
  * - `NavigationError`
+ * - `Scroll`
  *
  *
  */
 export type Event = RouterEvent | RouteConfigLoadStart | RouteConfigLoadEnd | ChildActivationStart |
-    ChildActivationEnd | ActivationStart | ActivationEnd;
+    ChildActivationEnd | ActivationStart | ActivationEnd | Scroll;

packages/router/src/index.ts

@@ -11,7 +11,7 @@ export {Data, LoadChildren, LoadChildrenCallback, ResolveData, Route, Routes, Ru
 export {RouterLink, RouterLinkWithHref} from './directives/router_link';
 export {RouterLinkActive} from './directives/router_link_active';
 export {RouterOutlet} from './directives/router_outlet';
-export {ActivationEnd, ActivationStart, ChildActivationEnd, ChildActivationStart, Event, GuardsCheckEnd, GuardsCheckStart, NavigationCancel, NavigationEnd, NavigationError, NavigationStart, ResolveEnd, ResolveStart, RouteConfigLoadEnd, RouteConfigLoadStart, RouterEvent, RoutesRecognized} from './events';
+export {ActivationEnd, ActivationStart, ChildActivationEnd, ChildActivationStart, Event, GuardsCheckEnd, GuardsCheckStart, NavigationCancel, NavigationEnd, NavigationError, NavigationStart, ResolveEnd, ResolveStart, RouteConfigLoadEnd, RouteConfigLoadStart, RouterEvent, RoutesRecognized, Scroll} from './events';
 export {CanActivate, CanActivateChild, CanDeactivate, CanLoad, Resolve} from './interfaces';
 export {DetachedRouteHandle, RouteReuseStrategy} from './route_reuse_strategy';
 export {NavigationExtras, Router} from './router';

packages/router/src/router.ts

@@ -543,7 +543,6 @@ export class Router {
       rawUrl: UrlTree, source: NavigationTrigger, state: {navigationId: number}|null,
       extras: NavigationExtras): Promise<boolean> {
     const lastNavigation = this.navigations.value;
-
     // If the user triggers a navigation imperatively (e.g., by using navigateByUrl),
     // and that navigation results in 'replaceState' that leads to the same URL,
     // we should skip those.

packages/router/src/router_module.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {APP_BASE_HREF, HashLocationStrategy, LOCATION_INITIALIZED, Location, LocationStrategy, PathLocationStrategy, PlatformLocation} from '@angular/common';
+import {APP_BASE_HREF, HashLocationStrategy, LOCATION_INITIALIZED, Location, LocationStrategy, PathLocationStrategy, PlatformLocation, ViewportScroller} from '@angular/common';
 import {ANALYZE_FOR_ENTRY_COMPONENTS, APP_BOOTSTRAP_LISTENER, APP_INITIALIZER, ApplicationRef, Compiler, ComponentRef, Inject, Injectable, InjectionToken, Injector, ModuleWithProviders, NgModule, NgModuleFactoryLoader, NgProbeToken, Optional, Provider, SkipSelf, SystemJsNgModuleLoader} from '@angular/core';
 import {ɵgetDOM as getDOM} from '@angular/platform-browser';
 import {Subject, of } from 'rxjs';
@@ -21,6 +21,7 @@ import {ErrorHandler, Router} from './router';
 import {ROUTES} from './router_config_loader';
 import {ChildrenOutletContexts} from './router_outlet_context';
 import {NoPreloading, PreloadAllModules, PreloadingStrategy, RouterPreloader} from './router_preloader';
+import {RouterScroller} from './router_scroller';
 import {ActivatedRoute} from './router_state';
 import {UrlHandlingStrategy} from './url_handling_strategy';
 import {DefaultUrlSerializer, UrlSerializer} from './url_tree';
@@ -165,6 +166,11 @@ export class RouterModule {
             PlatformLocation, [new Inject(APP_BASE_HREF), new Optional()], ROUTER_CONFIGURATION
           ]
         },
+        {
+          provide: RouterScroller,
+          useFactory: createRouterScroller,
+          deps: [Router, ViewportScroller, ROUTER_CONFIGURATION]
+        },
         {
           provide: PreloadingStrategy,
           useExisting: config && config.preloadingStrategy ? config.preloadingStrategy :
@@ -184,6 +190,14 @@ export class RouterModule {
   }
 }
 
+export function createRouterScroller(
+    router: Router, viewportScroller: ViewportScroller, config: ExtraOptions): RouterScroller {
+  if (config.scrollOffset) {
+    viewportScroller.setOffset(config.scrollOffset);
+  }
+  return new RouterScroller(router, viewportScroller, config);
+}
+
 export function provideLocationStrategy(
     platformLocationStrategy: PlatformLocation, baseHref: string, options: ExtraOptions = {}) {
   return options.useHash ? new HashLocationStrategy(platformLocationStrategy, baseHref) :
@@ -291,6 +305,77 @@ export interface ExtraOptions {
    */
   onSameUrlNavigation?: 'reload'|'ignore';
 
+  /**
+   * Configures if the scroll position needs to be restored when navigating back.
+   *
+   * * 'disabled'--does nothing (default).
+   * * 'top'--set the scroll position to 0,0..
+   * * 'enabled'--set the scroll position to the stored position. This option will be the default in
+   * the future.
+   *
+   * When enabled, the router store store scroll positions when navigating forward, and will
+   * restore the stored positions whe navigating back (popstate). When navigating forward,
+   * the scroll position will be set to [0, 0], or to the anchor if one is provided.
+   *
+   * You can implement custom scroll restoration behavior as follows.
+   * ```typescript
+   * class AppModule {
+   *  constructor(router: Router, viewportScroller: ViewportScroller, store: Store<AppState>) {
+   *    router.events.pipe(filter(e => e instanceof Scroll), switchMap(e => {
+   *      return store.pipe(first(), timeout(200), map(() => e));
+   *    }).subscribe(e => {
+   *      if (e.position) {
+   *        viewportScroller.scrollToPosition(e.position);
+   *      } else if (e.anchor) {
+   *        viewportScroller.scrollToAnchor(e.anchor);
+   *      } else {
+   *        viewportScroller.scrollToPosition([0, 0]);
+   *      }
+   *    });
+   *  }
+   * }
+   * ```
+   *
+   * You can also implement component-specific scrolling like this:
+   *
+   * ```typescript
+   * class ListComponent {
+   *   list: any[];
+   *   constructor(router: Router, viewportScroller: ViewportScroller, fetcher: ListFetcher) {
+   *     const scrollEvents = router.events.filter(e => e instanceof Scroll);
+   *     listFetcher.fetch().pipe(withLatestFrom(scrollEvents)).subscribe(([list, e]) => {
+   *       this.list = list;
+   *       if (e.position) {
+   *         viewportScroller.scrollToPosition(e.position);
+   *       } else {
+   *         viewportScroller.scrollToPosition([0, 0]);
+   *       }
+   *     });
+   *   }
+   * }
+   */
+  scrollPositionRestoration?: 'disabled'|'enabled'|'top';
+
+  /**
+   * Configures if the router should scroll to the element when the url has a fragment.
+   *
+   * * 'disabled'--does nothing (default).
+   * * 'enabled'--scrolls to the element. This option will be the default in the future.
+   *
+   * Anchor scrolling does not happen on 'popstate'. Instead, we restore the position
+   * that we stored or scroll to the top.
+   */
+  anchorScrolling?: 'disabled'|'enabled';
+
+  /**
+   * Configures the scroll offset the router will use when scrolling to an element.
+   *
+   * When given a tuple with two numbers, the router will always use the numbers.
+   * When given a function, the router will invoke the function every time it restores scroll
+   * position.
+   */
+  scrollOffset?: [number, number]|(() => [number, number]);
+
   /**
    * Defines how the router merges params, data and resolved data from parent to child
    * routes. Available options are:
@@ -406,6 +491,7 @@ export class RouterInitializer {
   bootstrapListener(bootstrappedComponentRef: ComponentRef<any>): void {
     const opts = this.injector.get(ROUTER_CONFIGURATION);
     const preloader = this.injector.get(RouterPreloader);
+    const routerScroller = this.injector.get(RouterScroller);
     const router = this.injector.get(Router);
     const ref = this.injector.get<ApplicationRef>(ApplicationRef);
 
@@ -420,6 +506,7 @@ export class RouterInitializer {
     }
 
     preloader.setUpPreloading();
+    routerScroller.init();
     router.resetRootComponentType(ref.componentTypes[0]);
     this.resultOfPreactivationDone.next(null !);
     this.resultOfPreactivationDone.complete();

packages/router/src/router_scroller.ts

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {ViewportScroller} from '@angular/common';
+import {OnDestroy} from '@angular/core';
+import {Unsubscribable} from 'rxjs';
+
+import {NavigationEnd, NavigationStart, Scroll} from './events';
+import {Router} from './router';
+
+export class RouterScroller implements OnDestroy {
+  private routerEventsSubscription: Unsubscribable;
+  private scrollEventsSubscription: Unsubscribable;
+
+  private lastId = 0;
+  private lastSource: 'imperative'|'popstate'|'hashchange'|undefined = 'imperative';
+  private restoredId = 0;
+  private store: {[key: string]: [number, number]} = {};
+
+  constructor(
+      private router: Router,
+      /** @docsNotRequired */ public readonly viewportScroller: ViewportScroller, private options: {
+        scrollPositionRestoration?: 'disabled' | 'enabled' | 'top',
+        anchorScrolling?: 'disabled'|'enabled'
+      } = {}) {}
+
+  init(): void {
+    // we want to disable the automatic scrolling because having two places
+    // responsible for scrolling results race conditions, especially given
+    // that browser don't implement this behavior consistently
+    if (this.options.scrollPositionRestoration !== 'disabled') {
+      this.viewportScroller.setHistoryScrollRestoration('manual');
+    }
+    this.routerEventsSubscription = this.createScrollEvents();
+    this.scrollEventsSubscription = this.consumeScrollEvents();
+  }
+
+  private createScrollEvents() {
+    return this.router.events.subscribe(e => {
+      if (e instanceof NavigationStart) {
+        // store the scroll position of the current stable navigations.
+        this.store[this.lastId] = this.viewportScroller.getScrollPosition();
+        this.lastSource = e.navigationTrigger;
+        this.restoredId = e.restoredState ? e.restoredState.navigationId : 0;
+      } else if (e instanceof NavigationEnd) {
+        this.lastId = e.id;
+        this.scheduleScrollEvent(e, this.router.parseUrl(e.urlAfterRedirects).fragment);
+      }
+    });
+  }
+
+  private consumeScrollEvents() {
+    return this.router.events.subscribe(e => {
+      if (!(e instanceof Scroll)) return;
+      // a popstate event. The pop state event will always ignore anchor scrolling.
+      if (e.position) {
+        if (this.options.scrollPositionRestoration === 'top') {
+          this.viewportScroller.scrollToPosition([0, 0]);
+        } else if (this.options.scrollPositionRestoration === 'enabled') {
+          this.viewportScroller.scrollToPosition(e.position);
+        }
+        // imperative navigation "forward"
+      } else {
+        if (e.anchor && this.options.anchorScrolling === 'enabled') {
+          this.viewportScroller.scrollToAnchor(e.anchor);
+        } else if (this.options.scrollPositionRestoration !== 'disabled') {
+          this.viewportScroller.scrollToPosition([0, 0]);
+        }
+      }
+    });
+  }
+
+  private scheduleScrollEvent(routerEvent: NavigationEnd, anchor: string|null): void {
+    this.router.triggerEvent(new Scroll(
+        routerEvent, this.lastSource === 'popstate' ? this.store[this.restoredId] : null, anchor));
+  }
+
+  ngOnDestroy() {
+    if (this.routerEventsSubscription) {
+      this.routerEventsSubscription.unsubscribe();
+    }
+    if (this.scrollEventsSubscription) {
+      this.scrollEventsSubscription.unsubscribe();
+    }
+  }
+}