iSharkFly-Docs/angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: route interface and types doc example (#29012)

Browse Source 
PR Close #29012
This commit is contained in:
Judy Bogart 2018-05-29 12:25:26 -07:00 committed by Kara Erickson
parent d95e059480
commit 22c71b69ce
2 changed files with 302 additions and 253 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

462
packages/router/src/config.ts
View File

@ -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. * @see `UrlMatcher()`
* - `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`. export type UrlMatchResult = {
* - `component` is a component type. consumed: UrlSegment[]; posParams?: {[name: string]: UrlSegment};
* - `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. * A function for matching a route against URLs. Implement a custom URL matcher
* - `canActivateChild` is an array of DI tokens used to look up CanActivateChild handlers. See * for `Route.matcher` when a combination of `path` and `pathMatch`
* `CanActivateChild` for more info. * is not expressive enough.
* - `canDeactivate` is an array of DI tokens used to look up CanDeactivate handlers. See *
* `CanDeactivate` for more info. * @param segments An array of URL segments.
* - `canLoad` is an array of DI tokens used to look up CanLoad handlers. See * @param group A segment group.
* `CanLoad` for more info. * @param route The route to match against.
* - `data` is additional data provided to the component via `ActivatedRoute`. * @returns The match-result,
* - `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.
* *
* @usageNotes * @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<any>| NgModuleFactory<any>| Promise<Type<any>>| Observable<Type<any>>;
/**
*
* 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 * ### 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', * 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 * ### 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', * 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 * ### Wild Cards
* *
* Regardless of where you navigate to, the router will instantiate the sink component.
*
* ``` * ```
* [{ * [{
* path: '**', * 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 * ### 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', * 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 * Note that if the `redirectTo` value starts with a '/', then it is an absolute redirect.
* '/team/11/user/jim', and then will instantiate the team component with the user component * If we change the `redirectTo` in the example to `/user/:name`, the result URL
* in it. * is '/user/jim'.
*
* 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'.
*
* ### Empty Path * ### Empty Path
* *
* Empty-path route configurations can be used to instantiate components that do not 'consume' * 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 * ### Matching Strategy
* *
* By default the router will look at what is left in the url, and check if it starts with * The default path-match strategy is 'prefix', which means that the router
* the specified path (e.g., `/team/11/user` starts with `team/:id`). * checks URL elements from the left to see if the URL matches a specified path.
* * For example, '/team/11/user' matches '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.
* *
* ``` * ```
* [{ * [{
@ -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 * You can specify the path-match strategy 'full' to make sure that the path
* still apply the redirect. * 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 * ### 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 * In the following example, 'ChildCmp' and 'AuxCmp' are siblings.
* of them require some id parameter. * When navigating to 'parent/10/(a//aux:b)', the route instantiates
* * the main child and aux child components next to each other.
* One way to do that would be to have a bogus parent component, so both the siblings can get the id * For this to work, the application component must have the primary and aux outlets defined.
* parameter from it. This is not ideal. Instead, you can use a componentless route.
* *
* ``` * ```
* [{ * [{
@ -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 * The router merges the parameters, data, and resolve of the componentless
* child components next to each other. In this example, the application component * parent into the parameters, data, and resolve of the children.
* has to have the primary and aux outlets defined.
* *
* The router will also merge the `params`, `data`, and `resolve` of the componentless parent into * This is especially useful when child components are defined
* the `params`, `data`, and `resolve` of the children. This is done because there is no component * with an empty path string, as in the following example.
* that can inject the activated route of the componentless parent. * With this configuration, navigating to '/parent/10' creates
* * the main child and aux components.
* This is especially useful when child components are defined as follows:
* *
* ``` * ```
* [{ * [{
@ -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
* *
* Lazy loading speeds up our application load time by splitting it into multiple bundles, and * Lazy loading speeds up application load time by splitting the application
* loading them on demand. The router is designed to make lazy loading simple and easy. Instead of * into multiple bundles and loading them on demand.
* providing the children property, you can provide the `loadChildren` property, as follows: * 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<any>| NgModuleFactory<any>| Promise<Type<any>>| Observable<Type<any>>;
/**
* @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 { 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; 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; pathMatch?: string;
/**
* A URL-matching function to use as a custom strategy for path matching.
* If present, supersedes `path` and `pathMatch`.
*/
matcher?: UrlMatcher; matcher?: UrlMatcher;
/**
* The component to instantiate when the path matches.
* Can be empty if child routes specify components.
*/
component?: Type<any>; component?: Type<any>;
/**
* 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; redirectTo?: string;
/**
* Name of a `RouterOutlet` object where the component can be placed
* when the path matches.
*/
outlet?: string; 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[]; 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[]; 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[]; 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[]; canLoad?: any[];
/**
* Additional developer-defined data provided to the component via
* `ActivatedRoute`. By default, no additional data is passed.
*/
data?: Data; data?: Data;
/**
* A map of DI tokens used to look up data resolvers. See `Resolve`.
*/
resolve?: ResolveData; resolve?: ResolveData;
/**
* An array of child `Route` objects that specifies a nested route
* configuration.
*/
children?: Routes; children?: Routes;
/**
* A `LoadChildren` object specifying lazy-loaded child routes.
*/
loadChildren?: LoadChildren; 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; runGuardsAndResolvers?: RunGuardsAndResolvers;
/** /**
* Filled for routes with `loadChildren` once the module has been loaded * Filled for routes with `loadChildren` once the module has been loaded

93
packages/router/src/router.ts
View File

@ -36,7 +36,7 @@ import {isUrlTree} from './utils/type_guards';
/** /**
* @description * @description
* *
* Represents the extra options used during navigation. * Options that modify the navigation strategy.
* *
* @publicApi * @publicApi
*/ */
@ -96,9 +96,8 @@ export interface NavigationExtras {
fragment?: string; fragment?: string;
/** /**
* Preserves the query parameters for the next navigation. * DEPRECATED: Use `queryParamsHandling` instead to preserve
* * query parameters for the next navigation.
* deprecated, use `queryParamsHandling` instead
* *
* ``` * ```
* // Preserve query params from /results?page=1 to /view?page=1 * // Preserve query params from /results?page=1 to /view?page=1
@ -110,7 +109,7 @@ export interface NavigationExtras {
preserveQueryParams?: boolean; 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 * // from /results?page=1 to /view?page=1&page=2
@ -280,9 +279,10 @@ function defaultRouterHook(snapshot: RouterStateSnapshot, runExtras: {
/** /**
* @description * @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 * @ngModule RouterModule
* *
@ -305,13 +305,17 @@ export class Router {
private console: Console; private console: Console;
private isNgZoneEnabled: boolean = false; private isNgZoneEnabled: boolean = false;
/**
* An event stream for routing events in this NgModule.
*/
public readonly events: Observable<Event> = new Subject<Event>(); public readonly events: Observable<Event> = new Subject<Event>();
/**
* The current state of routing in this NgModule.
*/
public readonly routerState: RouterState; public readonly routerState: RouterState;
/** /**
* Error handler that is invoked when a navigation errors. * A handler for navigation errors in this NgModule.
*
* See `ErrorHandler` for more information.
*/ */
errorHandler: ErrorHandler = defaultErrorHandler; errorHandler: ErrorHandler = defaultErrorHandler;
@ -325,14 +329,17 @@ export class Router {
url: string) => UrlTree = defaultMalformedUriErrorHandler; 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; navigated: boolean = false;
private lastSuccessfulId: number = -1; private lastSuccessfulId: number = -1;
/** /**
* Used by RouterModule. This allows us to * Hooks that enable you to pause navigation,
* pause the navigation either before preactivation or after it. * either before or after the preactivation phase.
* Used by `RouterModule`.
*
* @internal * @internal
*/ */
hooks: {beforePreactivation: RouterHook, afterPreactivation: RouterHook} = { hooks: {beforePreactivation: RouterHook, afterPreactivation: RouterHook} = {
@ -345,23 +352,26 @@ export class Router {
*/ */
urlHandlingStrategy: UrlHandlingStrategy = new DefaultUrlHandlingStrategy(); urlHandlingStrategy: UrlHandlingStrategy = new DefaultUrlHandlingStrategy();
/**
* The strategy for re-using routes.
*/
routeReuseStrategy: RouteReuseStrategy = new DefaultRouteReuseStrategy(); routeReuseStrategy: RouteReuseStrategy = new DefaultRouteReuseStrategy();
/** /**
* Define what the router should do if it receives a navigation request to the current URL. * How to handle a navigation request to the current URL. One of:
* By default, the router will ignore this navigation. However, this prevents features such * - `'ignore'` : The router ignores the request.
* as a "refresh" button. Use this option to configure the behavior when navigating to the * - `'reload'` : The router reloads the URL. Use to implement a "refresh" feature.
* current URL. Default is 'ignore'.
*/ */
onSameUrlNavigation: 'reload'|'ignore' = 'ignore'; onSameUrlNavigation: 'reload'|'ignore' = 'ignore';
/** /**
* Defines how the router merges params, data and resolved data from parent to child * How to merge parameters, data, and resolved data from parent to child
* routes. Available options are: * routes. One of:
* *
* - `'emptyOnly'`, the default, only inherits parent params for path-less or component-less * - `'emptyOnly'` : Inherit parent parameters, data, and resolved data
* routes. * for path-less or component-less routes.
* - `'always'`, enables unconditional inheritance of parent params. * - `'always'` : Inherit parent parameters, data, and resolved data
* for all child routes.
*/ */
paramsInheritanceStrategy: 'emptyOnly'|'always' = 'emptyOnly'; paramsInheritanceStrategy: 'emptyOnly'|'always' = 'emptyOnly';
@ -519,7 +529,7 @@ export class Router {
t.id, this.serializeUrl(t.extractedUrl), t.id, this.serializeUrl(t.extractedUrl),
this.serializeUrl(t.urlAfterRedirects), t.targetSnapshot !); this.serializeUrl(t.urlAfterRedirects), t.targetSnapshot !);
eventsSubject.next(routesRecognized); eventsSubject.next(routesRecognized);
}), ); }));
} else { } else {
const processPreviousUrl = urlTransition && this.rawUrlTree && const processPreviousUrl = urlTransition && this.rawUrlTree &&
this.urlHandlingStrategy.shouldProcessUrl(this.rawUrlTree); this.urlHandlingStrategy.shouldProcessUrl(this.rawUrlTree);
@ -631,7 +641,7 @@ export class Router {
t.id, this.serializeUrl(t.extractedUrl), t.id, this.serializeUrl(t.extractedUrl),
this.serializeUrl(t.urlAfterRedirects), t.targetSnapshot !); this.serializeUrl(t.urlAfterRedirects), t.targetSnapshot !);
this.triggerEvent(resolveEnd); this.triggerEvent(resolveEnd);
}), ); }));
} }
return undefined; return undefined;
}), }),
@ -747,7 +757,7 @@ export class Router {
} }
} }
return EMPTY; return EMPTY;
}), ); }));
// TODO(jasonaden): remove cast once g3 is on updated TypeScript // TODO(jasonaden): remove cast once g3 is on updated TypeScript
})) as any as Observable<NavigationTransition>; })) as any as Observable<NavigationTransition>;
} }
@ -799,7 +809,7 @@ export class Router {
} }
} }
/** The current url */ /** The current URL. */
get url(): string { return this.serializeUrl(this.currentUrlTree); } get url(): string { return this.serializeUrl(this.currentUrlTree); }
/** The current Navigation object if one exists */ /** The current Navigation object if one exists */
@ -811,9 +821,9 @@ export class Router {
/** /**
* Resets the configuration used for navigation and generating links. * Resets the configuration used for navigation and generating links.
* *
* @usageNotes * @param config The route array for the new configuration.
* *
* ### Example * @usageNotes
* *
* ``` * ```
* router.resetConfig([ * router.resetConfig([
@ -834,7 +844,7 @@ export class Router {
/** @docsNotRequired */ /** @docsNotRequired */
ngOnDestroy(): void { this.dispose(); } ngOnDestroy(): void { this.dispose(); }
/** Disposes of the router */ /** Disposes of the router. */
dispose(): void { dispose(): void {
if (this.locationSubscription) { if (this.locationSubscription) {
this.locationSubscription.unsubscribe(); 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 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. * 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 * // 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: * @param url An absolute URL. The function does not apply any delta to the current URL.
* - resolves to 'true' when navigation succeeds, * @param extras An object containing properties that modify the navigation strategy.
* - resolves to 'false' when navigation fails, * The function ignores any properties in the `NavigationExtras` that would change the
* - is rejected when an error happens. * provided URL.
*
* @returns A Promise that resolves to 'true' when navigation succeeds,
* to 'false' when navigation fails, or is rejected on error.
* *
* @usageNotes * @usageNotes
* *
@ -933,10 +948,6 @@ export class Router {
* router.navigateByUrl("/team/33/user/11", { skipLocationChange: true }); * 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}): navigateByUrl(url: string|UrlTree, extras: NavigationExtras = {skipLocationChange: false}):
Promise<boolean> { Promise<boolean> {