feat(router): Add feature provider for enabling hash navigation (#48301)

atscott · thePunderWoman · commit f58ad86e5181 · 2022-12-13T08:28:38.000-08:00
The argument against this feature: Firstly, this isn't a navigation strategy that's very commonly desired. Secondly, the hash strategy is a location configuration in `@angular/common` and you can use it outside of the Router or with any custom router implementations. So while the net effect of using the router is that it updates the URL which is controlled by the strategy, this feature provider doesn't necessarily need to exist in the Router. The location strategy is an application-wide configuration and affects anything that imports `Location`. Of course, the Router does this in a few places but plenty of other things might as well. The argument for this feature: * Discoverability. While `LocationStrategy` is technically in `@angular/common`, the most common use-case _is_ when using it with the Router. * Precedence in the `RouterModule.forRoot([], {useHash: true})` * Precedence in other routing libraries (`createWebHashHistory` in VueJS and `HashRouter` in React, for example) * The implementation of `withHashLocation` is much more clear than `useHash` was. You can look at the function and see that all it's doing is adding the `HashLocationStrategy` to the providers list. resolves #48295 / #47986 PR Close #48301
diff --git a/goldens/public-api/router/index.md b/goldens/public-api/router/index.md
@@ -750,6 +750,9 @@ export interface RouterFeature<FeatureKind extends RouterFeatureKind> {
 // @public
 export type RouterFeatures = PreloadingFeature | DebugTracingFeature | InitialNavigationFeature | InMemoryScrollingFeature | RouterConfigurationFeature;
 
+// @public
+export type RouterHashLocationFeature = RouterFeature<RouterFeatureKind.RouterHashLocationFeature>;
+
 // @public
 class RouterLink implements OnChanges, OnDestroy {
     constructor(router: Router, route: ActivatedRoute, tabIndexAttribute: string | null | undefined, renderer: Renderer2, el: ElementRef, locationStrategy?: LocationStrategy | undefined);
@@ -1068,6 +1071,9 @@ export function withDisabledInitialNavigation(): DisabledInitialNavigationFeatur
 // @public
 export function withEnabledBlockingInitialNavigation(): EnabledBlockingInitialNavigationFeature;
 
+// @public
+export function withHashLocation(): RouterConfigurationFeature;
+
 // @public
 export function withInMemoryScrolling(options?: InMemoryScrollingOptions): InMemoryScrollingFeature;
 
diff --git a/packages/router/src/index.ts b/packages/router/src/index.ts
@@ -15,7 +15,7 @@ export {ActivationEnd, ActivationStart, ChildActivationEnd, ChildActivationStart
 export {CanActivate, CanActivateChild, CanActivateChildFn, CanActivateFn, CanDeactivate, CanDeactivateFn, CanLoad, CanLoadFn, CanMatch, CanMatchFn, Data, DefaultExport, LoadChildren, LoadChildrenCallback, NavigationBehaviorOptions, OnSameUrlNavigation, QueryParamsHandling, Resolve, ResolveData, ResolveFn, Route, Routes, RunGuardsAndResolvers, UrlMatcher, UrlMatchResult} from './models';
 export {Navigation, NavigationExtras, UrlCreationOptions} from './navigation_transition';
 export {DefaultTitleStrategy, TitleStrategy} from './page_title_strategy';
-export {DebugTracingFeature, DisabledInitialNavigationFeature, EnabledBlockingInitialNavigationFeature, InitialNavigationFeature, InMemoryScrollingFeature, PreloadingFeature, provideRouter, provideRoutes, RouterConfigurationFeature, RouterFeature, RouterFeatures, withDebugTracing, withDisabledInitialNavigation, withEnabledBlockingInitialNavigation, withInMemoryScrolling, withPreloading, withRouterConfig} from './provide_router';
+export {DebugTracingFeature, DisabledInitialNavigationFeature, EnabledBlockingInitialNavigationFeature, InitialNavigationFeature, InMemoryScrollingFeature, PreloadingFeature, provideRouter, provideRoutes, RouterConfigurationFeature, RouterFeature, RouterFeatures, RouterHashLocationFeature, withDebugTracing, withDisabledInitialNavigation, withEnabledBlockingInitialNavigation, withHashLocation, withInMemoryScrolling, withPreloading, withRouterConfig} from './provide_router';
 export {BaseRouteReuseStrategy, DetachedRouteHandle, RouteReuseStrategy} from './route_reuse_strategy';
 export {Router} from './router';
 export {ExtraOptions, InitialNavigation, InMemoryScrollingOptions, ROUTER_CONFIGURATION, RouterConfigOptions} from './router_config';
diff --git a/packages/router/src/provide_router.ts b/packages/router/src/provide_router.ts
@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {LOCATION_INITIALIZED, ViewportScroller} from '@angular/common';
+import {HashLocationStrategy, LOCATION_INITIALIZED, LocationStrategy, ViewportScroller} from '@angular/common';
 import {APP_BOOTSTRAP_LISTENER, APP_INITIALIZER, ApplicationRef, ComponentRef, ENVIRONMENT_INITIALIZER, EnvironmentProviders, inject, InjectFlags, InjectionToken, Injector, makeEnvironmentProviders, NgZone, Provider, Type} from '@angular/core';
 import {of, Subject} from 'rxjs';
 import {filter, map, take} from 'rxjs/operators';
@@ -580,6 +580,47 @@ export function withRouterConfig(options: RouterConfigOptions): RouterConfigurat
   return routerFeature(RouterFeatureKind.RouterConfigurationFeature, providers);
 }
 
+/**
+ * A type alias for providers returned by `withHashLocation` for use with `provideRouter`.
+ *
+ * @see `withHashLocation`
+ * @see `provideRouter`
+ *
+ * @publicApi
+ */
+export type RouterHashLocationFeature = RouterFeature<RouterFeatureKind.RouterHashLocationFeature>;
+
+/**
+ * Provides the location strategy that uses the URL fragment instead of the history API.
+ *
+ * @usageNotes
+ *
+ * Basic example of how you can use the hash location option:
+ * ```
+ * const appRoutes: Routes = [];
+ * bootstrapApplication(AppComponent,
+ *   {
+ *     providers: [
+ *       provideRouter(appRoutes, withHashLocation()
+ *     ]
+ *   }
+ * );
+ * ```
+ *
+ * @see `provideRouter`
+ * @see `HashLocationStrategy`
+ *
+ * @returns A set of providers for use with `provideRouter`.
+ *
+ * @publicApi
+ */
+export function withHashLocation(): RouterConfigurationFeature {
+  const providers = [
+    {provide: LocationStrategy, useClass: HashLocationStrategy},
+  ];
+  return routerFeature(RouterFeatureKind.RouterConfigurationFeature, providers);
+}
+
 /**
  * A type alias that represents all Router features available for use with `provideRouter`.
  * Features can be enabled by adding special functions to the `provideRouter` call.
@@ -602,5 +643,6 @@ export const enum RouterFeatureKind {
   EnabledBlockingInitialNavigationFeature,
   DisabledInitialNavigationFeature,
   InMemoryScrollingFeature,
-  RouterConfigurationFeature
+  RouterConfigurationFeature,
+  RouterHashLocationFeature
 }
