Skip to content

Commit 0a8b8a6

Browse files
atscottdylhunn
atscott
authored and
dylhunn
committed
docs(router): Deprecate public members of Router that are meant to be configured elsewhere (#48006)
None of the public properties of the `Router` are meant to be writeable. They should all be configured using other methods, all of which have been documented. DEPRECATED: router writable properties The following strategies are meant to be configured by registering the application strategy in DI via the `providers` in the root `NgModule` or `bootstrapApplication`: * `routeReuseStrategy` * `titleStrategy` * `urlHandlingStrategy` The following options are meant to be configured using the options available in `RouterModule.forRoot` or `provideRouter`. * `onSameUrlNavigation` * `paramsInheritanceStrategy` * `urlUpdateStrategy` * `canceledNavigationResolution` The following options are available in `RouterModule.forRoot` but not available in `provideRouter`: * `malformedUriErrorHandler` - This was found to not be used anywhere internally. * `errorHandler` - Developers can instead subscribe to `Router.events` and filter for `NavigationError`. PR Close #48006
1 parent 02b18dc commit 0a8b8a6

3 files changed

Lines changed: 71 additions & 0 deletions

File tree

‎aio/content/guide/deprecations.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,7 @@ v15 - v18
115115
| `@angular/common` | [`DatePipe` - `DATE_PIPE_DEFAULT_TIMEZONE`](api/common/DATE_PIPE_DEFAULT_TIMEZONE) | v15 | v17 |
116116
| `@angular/core` | NgModule and `'any'` options for [`providedIn`](#core) | v15 | v17 |
117117
| `@angular/router` | [`RouterLinkWithHref` directive](#router) | v15 | v17 |
118+
| `@angular/router` | [Router writeable properties](#router-writable-properties) | v15.1 | v17 |
118119

119120
### Deprecated features with no planned removal version
120121

@@ -375,6 +376,33 @@ The injector no longer requires the Reflect polyfill, reducing application size
375376

376377
<code-example path="deprecation-guide/src/app/app.component.ts" language="typescript" region="static-injector-example"></code-example>
377378

379+
<a id="router-writable-properties"></a>
380+
381+
None of the public properties of the `Router` are meant to be writeable.
382+
They should all be configured using other methods, all of which have been
383+
documented.
384+
385+
The following strategies are meant to be configured by registering the
386+
application strategy in DI via the `providers` in the root `NgModule` or
387+
`bootstrapApplication`:
388+
* `routeReuseStrategy`
389+
* `titleStrategy`
390+
* `urlHandlingStrategy`
391+
392+
The following options are meant to be configured using the options
393+
available in `RouterModule.forRoot` or `provideRouter` and `withRouterConfig`.
394+
* `onSameUrlNavigation`
395+
* `paramsInheritanceStrategy`
396+
* `urlUpdateStrategy`
397+
* `canceledNavigationResolution`
398+
399+
The following options are available in `RouterModule.forRoot` but not
400+
available in `provideRouter`:
401+
* `malformedUriErrorHandler` - This was not found to be used by anyone.
402+
There are currently no plans to make this available in `provideRouter`.
403+
* `errorHandler` - Developers should instead subscribe to `Router.events`
404+
and filter for `NavigationError`.
405+
378406
<a id="relativeLinkResolution"></a>
379407

380408
The `relativeLinkResolution` option is deprecated and being removed.

‎goldens/public-api/router/index.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -630,35 +630,44 @@ export class RouteConfigLoadStart {
630630
// @public
631631
export class Router {
632632
constructor(rootComponentType: Type<any> | null, urlSerializer: UrlSerializer, rootContexts: ChildrenOutletContexts, location: Location_2, injector: Injector, compiler: Compiler, config: Routes);
633+
// @deprecated
633634
canceledNavigationResolution: 'replace' | 'computed';
634635
// (undocumented)
635636
config: Routes;
636637
createUrlTree(commands: any[], navigationExtras?: UrlCreationOptions): UrlTree;
637638
dispose(): void;
639+
// @deprecated
638640
errorHandler: ErrorHandler;
639641
readonly events: Observable<Event_2>;
640642
getCurrentNavigation(): Navigation | null;
641643
initialNavigation(): void;
642644
// @deprecated
643645
isActive(url: string | UrlTree, exact: boolean): boolean;
644646
isActive(url: string | UrlTree, matchOptions: IsActiveMatchOptions): boolean;
647+
// @deprecated
645648
malformedUriErrorHandler: (error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree;
646649
navigate(commands: any[], extras?: NavigationExtras): Promise<boolean>;
647650
navigateByUrl(url: string | UrlTree, extras?: NavigationBehaviorOptions): Promise<boolean>;
648651
navigated: boolean;
649652
// (undocumented)
650653
ngOnDestroy(): void;
654+
// @deprecated
651655
onSameUrlNavigation: 'reload' | 'ignore';
656+
// @deprecated
652657
paramsInheritanceStrategy: 'emptyOnly' | 'always';
653658
parseUrl(url: string): UrlTree;
654659
resetConfig(config: Routes): void;
660+
// @deprecated
655661
routeReuseStrategy: RouteReuseStrategy;
656662
readonly routerState: RouterState;
657663
serializeUrl(url: UrlTree): string;
658664
setUpLocationChangeListener(): void;
665+
// @deprecated
659666
titleStrategy?: TitleStrategy;
660667
get url(): string;
668+
// @deprecated
661669
urlHandlingStrategy: UrlHandlingStrategy;
670+
// @deprecated
662671
urlUpdateStrategy: 'deferred' | 'eager';
663672
// (undocumented)
664673
static ɵfac: i0.ɵɵFactoryDeclaration<Router, never>;

‎packages/router/src/router.ts‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -429,6 +429,8 @@ export class Router {
429429

430430
/**
431431
* A handler for navigation errors in this NgModule.
432+
*
433+
* @deprecated Subscribe to the `Router` events and watch for `NavigationError` instead.
432434
*/
433435
errorHandler: ErrorHandler = defaultErrorHandler;
434436

@@ -437,6 +439,10 @@ export class Router {
437439
* when `url` contains an invalid character.
438440
* The most common case is a `%` sign
439441
* that's not encoded and is not part of a percent encoded sequence.
442+
*
443+
* @deprecated Configure this through `RouterModule.forRoot` instead:
444+
* `RouterModule.forRoot(routes, {malformedUriErrorHandler: myHandler})`
445+
* @see `RouterModule`
440446
*/
441447
malformedUriErrorHandler:
442448
(error: URIError, urlSerializer: UrlSerializer,
@@ -460,16 +466,25 @@ export class Router {
460466
/**
461467
* A strategy for extracting and merging URLs.
462468
* Used for AngularJS to Angular migrations.
469+
*
470+
* @deprecated Configure using `providers` instead:
471+
* `{provide: UrlHandlingStrategy, useClass: MyStrategy}`.
463472
*/
464473
urlHandlingStrategy = inject(UrlHandlingStrategy);
465474

466475
/**
467476
* A strategy for re-using routes.
477+
*
478+
* @deprecated Configure using `providers` instead:
479+
* `{provide: RouteReuseStrategy, useClass: MyStrategy}`.
468480
*/
469481
routeReuseStrategy = inject(RouteReuseStrategy);
470482

471483
/**
472484
* A strategy for setting the title based on the `routerState`.
485+
*
486+
* @deprecated Configure using `providers` instead:
487+
* `{provide: TitleStrategy, useClass: MyStrategy}`.
473488
*/
474489
titleStrategy?: TitleStrategy = inject(TitleStrategy);
475490

@@ -485,6 +500,11 @@ export class Router {
485500
* component first. This behavior is configured by the `RouteReuseStrategy`. In order to reload
486501
* routed components on same url navigation, you need to set `onSameUrlNavigation` to `'reload'`
487502
* _and_ provide a `RouteReuseStrategy` which returns `false` for `shouldReuseRoute`.
503+
*
504+
* @deprecated Configure this through `provideRouter` or `RouterModule.forRoot` instead.
505+
* @see `withRouterConfig`
506+
* @see `provideRouter`
507+
* @see `RouterModule`
488508
*/
489509
onSameUrlNavigation: 'reload'|'ignore' = 'ignore';
490510

@@ -496,6 +516,11 @@ export class Router {
496516
* for path-less or component-less routes.
497517
* - `'always'` : Inherit parent parameters, data, and resolved data
498518
* for all child routes.
519+
*
520+
* @deprecated Configure this through `provideRouter` or `RouterModule.forRoot` instead.
521+
* @see `withRouterConfig`
522+
* @see `provideRouter`
523+
* @see `RouterModule`
499524
*/
500525
paramsInheritanceStrategy: 'emptyOnly'|'always' = 'emptyOnly';
501526

@@ -505,6 +530,11 @@ export class Router {
505530
* Set to `'eager'` to update the browser URL at the beginning of navigation.
506531
* You can choose to update early so that, if navigation fails,
507532
* you can show an error message with the URL that failed.
533+
*
534+
* @deprecated Configure this through `provideRouter` or `RouterModule.forRoot` instead.
535+
* @see `withRouterConfig`
536+
* @see `provideRouter`
537+
* @see `RouterModule`
508538
*/
509539
urlUpdateStrategy: 'deferred'|'eager' = 'deferred';
510540

@@ -529,6 +559,10 @@ export class Router {
529559
*
530560
* The default value is `replace`.
531561
*
562+
* @deprecated Configure this through `provideRouter` or `RouterModule.forRoot` instead.
563+
* @see `withRouterConfig`
564+
* @see `provideRouter`
565+
* @see `RouterModule`
532566
*/
533567
canceledNavigationResolution: 'replace'|'computed' = 'replace';
534568

0 commit comments

Comments
 (0)