Router
Provides the navigation and url manipulation capabilities.
Example
Imperative navigation:
export class AppComponent {
constructor(private router: Router) {
}
navigateToHome() {
this.router.navigate('/home');
}
}
Interface
- config
- createUrlTree
- dispose
- errorHandler
- events
- getCurrentNavigation
- initialNavigation
- isActive
- malformedUriErrorHandler
- navigate
- navigateByUrl
- navigated
- onSameUrlNavigation
- paramsInheritanceStrategy
- parseUrl
- relativeLinkResolution
- resetConfig
- routeReuseStrategy
- routerState
- serializeUrl
- setUpLocationChangeListener
- url
- urlHandlingStrategy
- urlUpdateStrategy
config
#
config: Routes
createUrlTree
#
createUrlTree(commands: any[], navigationExtras: UrlCreationOptions = {}): UrlTree
Appends URL segments to the current URL tree to create a new URL tree.
Returns The new URL tree.
// create /team/33/user/11
router.createUrlTree(['/team', 33, 'user', 11]);
// create /team/33;expand=true/user/11
router.createUrlTree(['/team', 33, {expand: true}, 'user', 11]);
// you can collapse static segments like this (this works only with the first passed-in value):
router.createUrlTree(['/team/33/user', userId]);
// If the first segment can contain slashes, and you do not want the router to split it,
// you can do the following:
router.createUrlTree([{segmentPath: '/one/two'}]);
// create /team/33/(user/11//right:chat)
router.createUrlTree(['/team', 33, {outlets: {primary: 'user/11', right: 'chat'}}]);
// remove the right secondary node
router.createUrlTree(['/team', 33, {outlets: {primary: 'user/11', right: null}}]);
// assuming the current url is `/team/33/user/11` and the route points to `user/11`
// navigate to /team/33/user/11/details
router.createUrlTree(['details'], {relativeTo: route});
// navigate to /team/33/user/22
router.createUrlTree(['../22'], {relativeTo: route});
// navigate to /team/44/user/22
router.createUrlTree(['../../team/44/user/22'], {relativeTo: route});
Note that a value of `null` or `undefined` for `relativeTo` indicates that the
tree should be created relative to the root.
dispose
#
dispose(): void
Disposes of the router.
errorHandler
#
errorHandler: ErrorHandler
A handler for navigation errors in this NgModule.
events
#
events: Observable<Event>
An event stream for routing events in this NgModule.
getCurrentNavigation
#
getCurrentNavigation(): Navigation|null
Returns the current Navigation
object when the router is navigating,
and null
when idle.
initialNavigation
#
initialNavigation(): void
Sets up the location change listener and performs the initial navigation.
isActive
#
isActive(url: string|UrlTree, matchOptions: boolean|IsActiveMatchOptions): boolean
malformedUriErrorHandler
#
malformedUriErrorHandler: (error: URIError, urlSerializer: UrlSerializer,
url: string) => UrlTree
A handler for errors thrown by Router.parseUrl(url)
when url
contains an invalid character.
The most common case is a %
sign
that's not encoded and is not part of a percent encoded sequence.
navigate
#
navigate(commands: any[], extras: NavigationExtras = {skipLocationChange: false}): Promise<boolean>
Navigate based on the provided array of commands and a starting point. If no starting route is provided, the navigation is absolute.
Returns A Promise that resolves to true
when navigation succeeds, to false
when navigation
fails,
or is rejected on error.
The following calls request navigation to a dynamic route path relative to the current URL.
router.navigate(['team', 33, 'user', 11], {relativeTo: route});
// Navigate without updating the URL, overriding the default behavior
router.navigate(['team', 33, 'user', 11], {relativeTo: route, skipLocationChange: true});
Returns a Promise
that:
- resolves to
true
when navigation succeeds, - resolves to
false
when navigation fails, - is rejected when an error happens.
Example
router.navigate(['team', 33, 'user', 11], {relativeTo: route});
// Navigate without updating the URL
router.navigate(['team', 33, 'user', 11], {relativeTo: route, skipLocationChange: true});
The first parameter of navigate()
is a delta to be applied to the current URL or the one provided in the relativeTo
property of the second parameter (the NavigationExtras).
navigateByUrl
#
navigateByUrl(url: string|UrlTree, extras: NavigationBehaviorOptions = {
skipLocationChange: false
}): Promise<boolean>
Navigates to a view using an absolute route path.
Returns A Promise that resolves to 'true' when navigation succeeds, to 'false' when navigation fails, or is rejected on error.
The following calls request navigation to an absolute path.
router.navigateByUrl("/team/33/user/11");
// Navigate without updating the URL
router.navigateByUrl("/team/33/user/11", { skipLocationChange: true });
Returns a Promise
that:
- resolves to
true
when navigation succeeds, - resolves to
false
when navigation fails, - is rejected when an error happens.
Example
router.navigateByUrl("/team/33/user/11");
// Navigate without updating the URL
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.
navigated
#
navigated: boolean
True if at least one navigation event has occurred, false otherwise.
onSameUrlNavigation
#
onSameUrlNavigation: 'reload'|'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.
Note that this only configures whether the Route reprocesses the URL and triggers related
action and events like redirects, guards, and resolvers. By default, the router re-uses a
component instance when it re-navigates to the same component type without visiting a different
component first. This behavior is configured by the RouteReuseStrategy
. In order to reload
routed components on same url navigation, you need to set onSameUrlNavigation
to 'reload'
and provide a RouteReuseStrategy
which returns false
for shouldReuseRoute
.
paramsInheritanceStrategy
#
paramsInheritanceStrategy: 'emptyOnly'|'always'
How to merge parameters, data, and resolved data from parent to child routes. One of:
'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.
parseUrl
#
parseUrl(url: string): UrlTree
Parses a string into a UrlTree
relativeLinkResolution
#
relativeLinkResolution: 'legacy'|'corrected'
Enables a bug fix that corrects relative link resolution in components with empty paths.
resetConfig
#
resetConfig(config: Routes): void
Resets the route configuration used for navigation and generating links.
router.resetConfig([
{ path: 'team/:id', component: TeamCmp, children: [
{ path: 'simple', component: SimpleCmp },
{ path: 'user/:name', component: UserCmp }
]}
]);
routeReuseStrategy
#
routeReuseStrategy: RouteReuseStrategy
A strategy for re-using routes.
routerState
#
routerState: RouterState
The current state of routing in this NgModule.
serializeUrl
#
serializeUrl(url: UrlTree): string
Serializes a UrlTree
into a string
setUpLocationChangeListener
#
setUpLocationChangeListener(): void
Sets up the location change listener. This listener detects navigations triggered from outside the Router (the browser back/forward buttons, for example) and schedules a corresponding Router navigation so that the correct events, guards, etc. are triggered.
url
#
get url(): string
The current URL.
urlHandlingStrategy
#
urlHandlingStrategy: UrlHandlingStrategy
A strategy for extracting and merging URLs. Used for AngularJS to Angular migrations.
urlUpdateStrategy
#
urlUpdateStrategy: 'deferred'|'eager'
Determines when the router updates the browser URL.
By default ("deferred"
), updates the browser URL after navigation has finished.
Set to 'eager'
to update the browser URL at the beginning of navigation.
You can choose to update early so that, if navigation fails,
you can show an error message with the URL that failed.