diff --git a/packages/router/src/config.ts b/packages/router/src/config.ts index c7722bc83b..a6db3affb2 100644 --- a/packages/router/src/config.ts +++ b/packages/router/src/config.ts @@ -16,53 +16,134 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree'; /** - * @description + * Represents a route configuration for the Router service. + * An array of `Route` objects, used in `Router.config` and for nested route configurations + * in `Route.children`. * - * Represents router configuration. + * @see `Route` + * @see `Router` + */ +export type Routes = Route[]; + +/** + * Represents the result of matching URLs with a custom matching function. * - * `Routes` is an array of route configurations. Each one has the following properties: + * * `consumed` is an array of the consumed URL segments. + * * `posParams` is a map of positional parameters. * - * - `path` is a string that uses the route matcher DSL. - * - `pathMatch` is a string that specifies the matching strategy. Options are `prefix` (default) - * and `full`. See [Matching Strategy](#matching-strategy) below for more information. - * - `matcher` defines a custom strategy for path matching and supersedes `path` and `pathMatch`. - * - `component` is a component type. - * - `redirectTo` is the url fragment which will replace the current matched segment. - * - `outlet` is the name of the outlet the component should be placed into. - * - `canActivate` is an array of DI tokens used to look up CanActivate handlers. See - * `CanActivate` for more info. - * - `canActivateChild` is an array of DI tokens used to look up CanActivateChild handlers. See - * `CanActivateChild` for more info. - * - `canDeactivate` is an array of DI tokens used to look up CanDeactivate handlers. See - * `CanDeactivate` for more info. - * - `canLoad` is an array of DI tokens used to look up CanLoad handlers. See - * `CanLoad` for more info. - * - `data` is additional data provided to the component via `ActivatedRoute`. - * - `resolve` is a map of DI tokens used to look up data resolvers. See `Resolve` for more - * info. - * - `runGuardsAndResolvers` defines when guards and resolvers will be run. By default they run only - * when the matrix parameters of the route change. Options include: - * - `paramsChange` (default) - Run guards and resolvers when path or matrix params change. This - * mode ignores query param changes. - * - `paramsOrQueryParamsChange` - Guards and resolvers will run when any parameters change. This - * includes path, matrix, and query params. - * - `pathParamsChange` - Run guards and resolvers path or any path params change. This mode is - * useful if you want to ignore changes to all optional parameters such as query *and* matrix - * params. - * - `pathParamsOrQueryParamsChange` - Same as `pathParamsChange`, but also rerun when any query - * param changes - * - `always` - Run guards and resolvers on every navigation. - * - (from: ActivatedRouteSnapshot, to: ActivatedRouteSnapshot) => boolean - Use a predicate - * function when none of the pre-configured modes fit the needs of the application. An example - * might be when you need to ignore updates to a param such as `sortDirection`, but need to - * reload guards and resolvers when changing the `searchRoot` param. - * - `children` is an array of child route definitions. - * - `loadChildren` is a reference to lazy loaded child routes. See `LoadChildren` for more - * info. + * @see `UrlMatcher()` + * + */ +export type UrlMatchResult = { + consumed: UrlSegment[]; posParams?: {[name: string]: UrlSegment}; +}; + +/** + * A function for matching a route against URLs. Implement a custom URL matcher + * for `Route.matcher` when a combination of `path` and `pathMatch` + * is not expressive enough. + * + * @param segments An array of URL segments. + * @param group A segment group. + * @param route The route to match against. + * @returns The match-result, * * @usageNotes + * + * The following matcher matches HTML files. + * + * ``` + * export function htmlFiles(url: UrlSegment[]) { + * return url.length === 1 && url[0].path.endsWith('.html') ? ({consumed: url}) : null; + * } + * + * export const routes = [{ matcher: htmlFiles, component: AnyComponent }]; + * ``` + * + */ +export type UrlMatcher = (segments: UrlSegment[], group: UrlSegmentGroup, route: Route) => + UrlMatchResult; + +/** + * + * Represents static data associated with a particular route. + * + * @see `Route#data` + * + */ +export type Data = { + [name: string]: any +}; + +/** + * + * Represents the resolved data associated with a particular route. + * + * @see `Route#resolve`. + * + */ +export type ResolveData = { + [name: string]: any +}; + +/** + * + * A function that is called to resolve a collection of lazy-loaded routes. + * + * @see `Route#loadChildren`. + * + */ +export type LoadChildrenCallback = () => + Type| NgModuleFactory| Promise>| Observable>; + +/** + * + * A string of the form `path/to/file#exportName` that acts as a URL for a set of routes to load, + * or a function that returns such a set. + * + * @see `Route#loadChildren`. + * + */ +export type LoadChildren = string | LoadChildrenCallback; + +/** + * + * How to handle query parameters in a router link. + * One of: + * - `merge` : Merge new with current parameters. + * - `preserve` : Preserve current parameters. + * + * @see `RouterLink#queryParamsHandling`. + * + */ +export type QueryParamsHandling = 'merge' | 'preserve' | ''; + +/** + * + * A policy for when to run guards and resolvers on a route. + * + * @see `Route#runGuardsAndResolvers` + */ +export type RunGuardsAndResolvers = 'pathParamsChange' | 'pathParamsOrQueryParamsChange' | + 'paramsChange' | 'paramsOrQueryParamsChange' | 'always' | + ((from: ActivatedRouteSnapshot, to: ActivatedRouteSnapshot) => boolean); + +/** + * Collects and stores the properties of a navigation route. + * A set of routes collected in a `Routes` object defines a router configuration. + * + * Supports static, parameterized, redirect, and wildcard routes, as well as + * custom route data and resolve methods. + * + * For detailed usage information, see the [Routing Guide](guide/router). + * + * @usageNotes + * * ### Simple Configuration * + * When navigating to `/team/11/user/bob`, the router will create the team component with the user + * component in it. + * * ``` * [{ * path: 'team/:id', @@ -74,11 +155,11 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree'; * }] * ``` * - * When navigating to `/team/11/user/bob`, the router will create the team component with the user - * component in it. - * * ### Multiple Outlets * + * When navigating to `/team/11(aux:chat/jim)`, the router will create the team component next to + * the chat component. The chat component will be placed into the aux outlet. + * * ``` * [{ * path: 'team/:id', @@ -90,11 +171,11 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree'; * }] * ``` * - * When navigating to `/team/11(aux:chat/jim)`, the router will create the team component next to - * the chat component. The chat component will be placed into the aux outlet. * * ### Wild Cards * + * Regardless of where you navigate to, the router will instantiate the sink component. + * * ``` * [{ * path: '**', @@ -102,10 +183,12 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree'; * }] * ``` * - * Regardless of where you navigate to, the router will instantiate the sink component. - * * ### Redirects * + * When navigating to '/team/11/legacy/user/jim', the router will change the URL to + * '/team/11/user/jim', and then instantiate the team component with the user component + * in it. + * * ``` * [{ * path: 'team/:id', @@ -120,17 +203,15 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree'; * }] * ``` * - * When navigating to '/team/11/legacy/user/jim', the router will change the url to - * '/team/11/user/jim', and then will instantiate the team component with the user component - * in it. - * - * If the `redirectTo` value starts with a '/', then it is an absolute redirect. E.g., if in the - * example above we change the `redirectTo` to `/user/:name`, the result url will be '/user/jim'. - * + * Note that if the `redirectTo` value starts with a '/', then it is an absolute redirect. + * If we change the `redirectTo` in the example to `/user/:name`, the result URL + * is '/user/jim'. + * ### Empty Path * * Empty-path route configurations can be used to instantiate components that do not 'consume' - * any url segments. Let's look at the following configuration: + * any URL segments. In the following configuration, when navigating to + * `/team/11`, the router will instantiate the 'AllUsers' component. * * ``` * [{ @@ -146,9 +227,11 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree'; * }] * ``` * - * When navigating to `/team/11`, the router will instantiate the AllUsers component. + * Empty-path routes can have children. In the following example, when navigating + * to `/team/11/user/jim`, the router will instantiate the wrapper component with + * the user component in it. * - * Empty-path routes can have children. + * Note that an empty path route inherits its parent's parameters and data. * * ``` * [{ @@ -165,21 +248,11 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree'; * }] * ``` * - * When navigating to `/team/11/user/jim`, the router will instantiate the wrapper component with - * the user component in it. - * - * An empty path route inherits its parent's params and data. This is because it cannot have its - * own params, and, as a result, it often uses its parent's params and data as its own. - * * ### Matching Strategy * - * By default the router will look at what is left in the url, and check if it starts with - * the specified path (e.g., `/team/11/user` starts with `team/:id`). - * - * We can change the matching strategy to make sure that the path covers the whole unconsumed url, - * which is akin to `unconsumedUrl === path` or `$` regular expressions. - * - * This is particularly important when redirecting empty-path routes. + * The default path-match strategy is 'prefix', which means that the router + * checks URL elements from the left to see if the URL matches a specified path. + * For example, '/team/11/user' matches 'team/:id'. * * ``` * [{ @@ -192,11 +265,14 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree'; * }] * ``` * - * Since an empty path is a prefix of any url, even when navigating to '/main', the router will - * still apply the redirect. + * You can specify the path-match strategy 'full' to make sure that the path + * covers the whole unconsumed URL. It is important to do this when redirecting + * empty-path routes. Otherwise, because an empty path is a prefix of any URL, + * the router would apply the redirect even when navigating to the redirect destination, + * creating an endless loop. * - * If `pathMatch: full` is provided, the router will apply the redirect if and only if navigating to - * '/'. + * In the following example, supplying the 'full' `patchMatch` strategy ensures + * that the router applies the redirect if and only if navigating to '/'. * * ``` * [{ @@ -211,13 +287,15 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree'; * * ### Componentless Routes * - * It is useful at times to have the ability to share parameters between sibling components. + * You can share parameters between sibling components. + * For example, suppose that two sibling components should go next to each other, + * and both of them require an ID parameter. You can accomplish this using a route + * that does not specify a component at the top level. * - * Say we have two components--ChildCmp and AuxCmp--that we want to put next to each other and both - * of them require some id parameter. - * - * One way to do that would be to have a bogus parent component, so both the siblings can get the id - * parameter from it. This is not ideal. Instead, you can use a componentless route. + * In the following example, 'ChildCmp' and 'AuxCmp' are siblings. + * When navigating to 'parent/10/(a//aux:b)', the route instantiates + * the main child and aux child components next to each other. + * For this to work, the application component must have the primary and aux outlets defined. * * ``` * [{ @@ -229,15 +307,13 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree'; * }] * ``` * - * So when navigating to `parent/10/(a//aux:b)`, the route will instantiate the main child and aux - * child components next to each other. In this example, the application component - * has to have the primary and aux outlets defined. + * The router merges the parameters, data, and resolve of the componentless + * parent into the parameters, data, and resolve of the children. * - * The router will also merge the `params`, `data`, and `resolve` of the componentless parent into - * the `params`, `data`, and `resolve` of the children. This is done because there is no component - * that can inject the activated route of the componentless parent. - * - * This is especially useful when child components are defined as follows: + * This is especially useful when child components are defined + * with an empty path string, as in the following example. + * With this configuration, navigating to '/parent/10' creates + * the main child and aux components. * * ``` * [{ @@ -249,14 +325,16 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree'; * }] * ``` * - * With this configuration in place, navigating to '/parent/10' will create the main child and aux - * components. - * * ### Lazy Loading * - * Lazy loading speeds up our application load time by splitting it into multiple bundles, and - * loading them on demand. The router is designed to make lazy loading simple and easy. Instead of - * providing the children property, you can provide the `loadChildren` property, as follows: + * Lazy loading speeds up application load time by splitting the application + * into multiple bundles and loading them on demand. + * To use lazy loading, provide the `loadChildren` property instead of the `children` property. + * + * Given the following example route, the router uses the registered + * `NgModuleFactoryLoader` to fetch an NgModule associated with 'team'. + * It then extracts the set of routes defined in that NgModule, + * and transparently adds those routes to the main configuration. * * ``` * [{ @@ -266,140 +344,100 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree'; * }] * ``` * - * The router will use registered NgModuleFactoryLoader to fetch an NgModule associated with 'team'. - * Then it will extract the set of routes defined in that NgModule, and will transparently add - * those routes to the main configuration. - * - * @publicApi - */ -export type Routes = Route[]; - -/** - * @description Represents the results of the URL matching. - * - * * `consumed` is an array of the consumed URL segments. - * * `posParams` is a map of positional parameters. - * - * @publicApi - */ -export type UrlMatchResult = { - consumed: UrlSegment[]; posParams?: {[name: string]: UrlSegment}; -}; - -/** - * @description - * - * A function matching URLs - * - * A custom URL matcher can be provided when a combination of `path` and `pathMatch` isn't - * expressive enough. - * - * For instance, the following matcher matches html files. - * - * ``` - * export function htmlFiles(url: UrlSegment[]) { - * return url.length === 1 && url[0].path.endsWith('.html') ? ({consumed: url}) : null; - * } - * - * export const routes = [{ matcher: htmlFiles, component: AnyComponent }]; - * ``` - * - * @publicApi - */ -export type UrlMatcher = (segments: UrlSegment[], group: UrlSegmentGroup, route: Route) => - UrlMatchResult; - -/** - * @description - * - * Represents the static data associated with a particular route. - * - * See `Routes` for more details. - * - * @publicApi - */ -export type Data = { - [name: string]: any -}; - -/** - * @description - * - * Represents the resolved data associated with a particular route. - * - * See `Routes` for more details. - * - * @publicApi - */ -export type ResolveData = { - [name: string]: any -}; - -/** - * @description - * - * The type of `loadChildren`. - * - * See `Routes` for more details. - * - * @publicApi - */ -export type LoadChildrenCallback = () => - Type| NgModuleFactory| Promise>| Observable>; - -/** - * @description - * - * The type of `loadChildren`. - * - * See `Routes` for more details. - * - * @publicApi - */ -export type LoadChildren = string | LoadChildrenCallback; - -/** - * @description - * - * The type of `queryParamsHandling`. - * - * See `RouterLink` for more details. - * - */ -export type QueryParamsHandling = 'merge' | 'preserve' | ''; - -/** - * @description - * - * The type of `runGuardsAndResolvers`. - * - * See `Routes` for more details. - * @publicApi - */ -export type RunGuardsAndResolvers = 'pathParamsChange' | 'pathParamsOrQueryParamsChange' | - 'paramsChange' | 'paramsOrQueryParamsChange' | 'always' | - ((from: ActivatedRouteSnapshot, to: ActivatedRouteSnapshot) => boolean); - -/** - * See `Routes` for more details. - * - * @publicApi */ export interface Route { + /** + * The path to match against, a URL string that uses router matching notation. + * Can include wild-card characters (*). [where is that defined?] + * Default is "/" (the root path). + */ path?: string; + /** + * The path-matching strategy, one of 'prefix' or 'full'. + * Default is 'prefix'. + * + * By default, the router checks URL elements from the left to see if the URL + * matches a given path, and stops when there is a match. For example, + * '/team/11/user' matches 'team/:id'. + * The path-match strategy 'full' matches against the entire URL. + * It is important to do this when redirecting empty-path routes. + * Otherwise, because an empty path is a prefix of any URL, + * the router would apply the redirect even when navigating + * to the redirect destination, creating an endless loop. + * + */ pathMatch?: string; + /** + * A URL-matching function to use as a custom strategy for path matching. + * If present, supersedes `path` and `pathMatch`. + */ matcher?: UrlMatcher; + /** + * The component to instantiate when the path matches. + * Can be empty if child routes specify components. + */ component?: Type; + /** + * A URL to which to redirect when a the path matches. + * Absolute if the URL begins with a slash (/), otherwise relative to the path URL. + * When not present, router does not redirect. + */ redirectTo?: string; + /** + * Name of a `RouterOutlet` object where the component can be placed + * when the path matches. + */ outlet?: string; + /** + * An array of dependency-injection tokens used to look up `CanActivate()` + * handlers, in order to determine if the current user is allowed to + * activate the component. By default, any user can activate. + */ canActivate?: any[]; + /** + * An array of DI tokens used to look up `CanActivateChild()` handlers, + * in order to determine if the current user is allowed to activate + * a child of the component. By default, any user can activate a child. + */ canActivateChild?: any[]; + /** + * An array of DI tokens used to look up `CanDeactivate()` + * handlers, in order to determine if the current user is allowed to + * deactivate the component. By default, any user can deactivate. + * + */ canDeactivate?: any[]; + /** + * An array of DI tokens used to look up `CanLoad()` + * handlers, in order to determine if the current user is allowed to + * load the component. By default, any user can load. + */ canLoad?: any[]; + /** + * Additional developer-defined data provided to the component via + * `ActivatedRoute`. By default, no additional data is passed. + */ data?: Data; + /** + * A map of DI tokens used to look up data resolvers. See `Resolve`. + */ resolve?: ResolveData; + /** + * An array of child `Route` objects that specifies a nested route + * configuration. + */ children?: Routes; + /** + * A `LoadChildren` object specifying lazy-loaded child routes. + */ loadChildren?: LoadChildren; + /** + * Defines when guards and resolvers will be run. One of + * - `paramsOrQueryParamsChange` : Run when query parameters change. + * - `always` : Run on every execution. + * By default, guards and resolvers run only when the matrix + * parameters of the route change. + */ runGuardsAndResolvers?: RunGuardsAndResolvers; /** * Filled for routes with `loadChildren` once the module has been loaded diff --git a/packages/router/src/router.ts b/packages/router/src/router.ts index 270ff37414..db8c189ed4 100644 --- a/packages/router/src/router.ts +++ b/packages/router/src/router.ts @@ -36,7 +36,7 @@ import {isUrlTree} from './utils/type_guards'; /** * @description * - * Represents the extra options used during navigation. + * Options that modify the navigation strategy. * * @publicApi */ @@ -96,9 +96,8 @@ export interface NavigationExtras { fragment?: string; /** - * Preserves the query parameters for the next navigation. - * - * deprecated, use `queryParamsHandling` instead + * DEPRECATED: Use `queryParamsHandling` instead to preserve + * query parameters for the next navigation. * * ``` * // Preserve query params from /results?page=1 to /view?page=1 @@ -110,7 +109,7 @@ export interface NavigationExtras { preserveQueryParams?: boolean; /** - * config strategy to handle the query parameters for the next navigation. + * Configuration strategy for how to handle query parameters for the next navigation. * * ``` * // from /results?page=1 to /view?page=1&page=2 @@ -280,9 +279,10 @@ function defaultRouterHook(snapshot: RouterStateSnapshot, runExtras: { /** * @description * - * Provides the navigation and url manipulation capabilities. + * An NgModule that provides navigation and URL manipulation capabilities. * - * See `Routes` for more details and examples. + * @see `Route`. + * @see [Routing and Navigation Guide](guide/router). * * @ngModule RouterModule * @@ -305,13 +305,17 @@ export class Router { private console: Console; private isNgZoneEnabled: boolean = false; + /** + * An event stream for routing events in this NgModule. + */ public readonly events: Observable = new Subject(); + /** + * The current state of routing in this NgModule. + */ public readonly routerState: RouterState; /** - * Error handler that is invoked when a navigation errors. - * - * See `ErrorHandler` for more information. + * A handler for navigation errors in this NgModule. */ errorHandler: ErrorHandler = defaultErrorHandler; @@ -325,14 +329,17 @@ export class Router { url: string) => UrlTree = defaultMalformedUriErrorHandler; /** - * Indicates if at least one navigation happened. + * True if at least one navigation event has occurred, + * false otherwise. */ navigated: boolean = false; private lastSuccessfulId: number = -1; /** - * Used by RouterModule. This allows us to - * pause the navigation either before preactivation or after it. + * Hooks that enable you to pause navigation, + * either before or after the preactivation phase. + * Used by `RouterModule`. + * * @internal */ hooks: {beforePreactivation: RouterHook, afterPreactivation: RouterHook} = { @@ -345,23 +352,26 @@ export class Router { */ urlHandlingStrategy: UrlHandlingStrategy = new DefaultUrlHandlingStrategy(); + /** + * The strategy for re-using routes. + */ routeReuseStrategy: RouteReuseStrategy = new DefaultRouteReuseStrategy(); /** - * Define what the router should do if it receives a navigation request to the current URL. - * By default, the router will ignore this navigation. However, this prevents features such - * as a "refresh" button. Use this option to configure the behavior when navigating to the - * current URL. Default is 'ignore'. + * How to handle a navigation request to the current URL. One of: + * - `'ignore'` : The router ignores the request. + * - `'reload'` : The router reloads the URL. Use to implement a "refresh" feature. */ onSameUrlNavigation: 'reload'|'ignore' = 'ignore'; /** - * Defines how the router merges params, data and resolved data from parent to child - * routes. Available options are: + * How to merge parameters, data, and resolved data from parent to child + * routes. One of: * - * - `'emptyOnly'`, the default, only inherits parent params for path-less or component-less - * routes. - * - `'always'`, enables unconditional inheritance of parent params. + * - `'emptyOnly'` : Inherit parent parameters, data, and resolved data + * for path-less or component-less routes. + * - `'always'` : Inherit parent parameters, data, and resolved data + * for all child routes. */ paramsInheritanceStrategy: 'emptyOnly'|'always' = 'emptyOnly'; @@ -519,7 +529,7 @@ export class Router { t.id, this.serializeUrl(t.extractedUrl), this.serializeUrl(t.urlAfterRedirects), t.targetSnapshot !); eventsSubject.next(routesRecognized); - }), ); + })); } else { const processPreviousUrl = urlTransition && this.rawUrlTree && this.urlHandlingStrategy.shouldProcessUrl(this.rawUrlTree); @@ -631,7 +641,7 @@ export class Router { t.id, this.serializeUrl(t.extractedUrl), this.serializeUrl(t.urlAfterRedirects), t.targetSnapshot !); this.triggerEvent(resolveEnd); - }), ); + })); } return undefined; }), @@ -747,7 +757,7 @@ export class Router { } } return EMPTY; - }), ); + })); // TODO(jasonaden): remove cast once g3 is on updated TypeScript })) as any as Observable; } @@ -799,7 +809,7 @@ export class Router { } } - /** The current url */ + /** The current URL. */ get url(): string { return this.serializeUrl(this.currentUrlTree); } /** The current Navigation object if one exists */ @@ -811,9 +821,9 @@ export class Router { /** * Resets the configuration used for navigation and generating links. * - * @usageNotes + * @param config The route array for the new configuration. * - * ### Example + * @usageNotes * * ``` * router.resetConfig([ @@ -834,7 +844,7 @@ export class Router { /** @docsNotRequired */ ngOnDestroy(): void { this.dispose(); } - /** Disposes of the router */ + /** Disposes of the router. */ dispose(): void { if (this.locationSubscription) { this.locationSubscription.unsubscribe(); @@ -843,14 +853,16 @@ export class Router { } /** - * Applies an array of commands to the current url tree and creates a new url tree. + * Applies an array of commands to the current URL tree and creates a new URL tree. * * When given an activate route, applies the given commands starting from the route. * When not given a route, applies the given command starting from the root. * - * @usageNotes + * @param commands An array of commands to apply. + * @param navigationExtras + * @returns The new URL tree. * - * ### Example + * @usageNotes * * ``` * // create /team/33/user/11 @@ -915,12 +927,15 @@ export class Router { } /** - * Navigate based on the provided url. This navigation is always absolute. + * Navigate based on the provided URL, which must be absolute. * - * Returns a promise that: - * - resolves to 'true' when navigation succeeds, - * - resolves to 'false' when navigation fails, - * - is rejected when an error happens. + * @param url An absolute URL. The function does not apply any delta to the current URL. + * @param extras An object containing properties that modify the navigation strategy. + * The function ignores any properties in the `NavigationExtras` that would change the + * provided URL. + * + * @returns A Promise that resolves to 'true' when navigation succeeds, + * to 'false' when navigation fails, or is rejected on error. * * @usageNotes * @@ -933,10 +948,6 @@ export class Router { * router.navigateByUrl("/team/33/user/11", { skipLocationChange: true }); * ``` * - * Since `navigateByUrl()` takes an absolute URL as the first parameter, - * it will not apply any delta to the current URL and ignores any properties - * in the second parameter (the `NavigationExtras`) that would change the - * provided URL. */ navigateByUrl(url: string|UrlTree, extras: NavigationExtras = {skipLocationChange: false}): Promise {