From b16d33293a4a36adf411dd9ef30d8fb796e25f42 Mon Sep 17 00:00:00 2001 From: Andrew Scott Date: Thu, 17 Nov 2022 07:26:09 -0800 Subject: [PATCH] docs(router): Further document rawUrlTree (#48108) Further document the rawUrlTree and how it's used internally in the Router. PR Close #48108 --- packages/router/src/router.ts | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/packages/router/src/router.ts b/packages/router/src/router.ts index 31971c26e68..1d90f1d55ab 100644 --- a/packages/router/src/router.ts +++ b/packages/router/src/router.ts @@ -369,6 +369,21 @@ export class Router { * rawUrlTree to be a combination of the urlAfterRedirects (again, this might only apply to part * of the initial url) and the rawUrl of the transition (which was the original navigation url in * its full form). + * + * Note that this is _only_ here to support `UrlHandlingStrategy.extract` and + * `UrlHandlingStrategy.shouldProcessUrl`. If those didn't exist, we could get by with + * `currentUrlTree` alone. If a new Router were to be provided (i.e. one that works with the + * browser navigation API), we should think about whether this complexity should be carried over. + * + * - extract: `rawUrlTree` is needed because `extract` may only return part + * of the navigation URL. Thus, `currentUrlTree` may only represent _part_ of the browser URL. + * When a navigation gets cancelled and we need to reset the URL or a new navigation occurs, we + * need to know the _whole_ browser URL, not just the part handled by UrlHandlingStrategy. + * - shouldProcessUrl: When this returns `false`, the router just ignores the navigation but still + * updates the `rawUrlTree` with the assumption that the navigation was caused by the location + * change listener due to a URL update by the AngularJS router. In this case, we still need to + * know what the browser's URL is for future navigations. + * */ private rawUrlTree: UrlTree; /**