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

docs: clean up router api doc (#31476) 

PR Close #31476
This commit is contained in:
Judy Bogart 2019-07-03 16:15:15 -07:00 committed by Miško Hevery
parent 9ef9bfe76b
commit 1e9eeafa9e
12 changed files with 273 additions and 316 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -143,7 +143,8 @@ export type DeprecatedLoadChildren = string;
* - `merge` : Merge new with current parameters. * - `merge` : Merge new with current parameters.
* - `preserve` : Preserve current parameters. * - `preserve` : Preserve current parameters.
* *
* @see `RouterLink#queryParamsHandling`. * @see `NavigationExtras#queryParamsHandling`
* @see `RouterLink`
* @publicApi * @publicApi
*/ */
export type QueryParamsHandling = 'merge' | 'preserve' | ''; export type QueryParamsHandling = 'merge' | 'preserve' | '';

147
packages/router/src/events.ts
View File

@ -10,27 +10,23 @@ import {Route} from './config';
import {ActivatedRouteSnapshot, RouterStateSnapshot} from './router_state'; import {ActivatedRouteSnapshot, RouterStateSnapshot} from './router_state';
/** /**
* @description * Identifies the call or event that triggered a navigation.
* *
* Identifies the trigger of the navigation. * * 'imperative': Triggered by `router.navigateByUrl()` or `router.navigate()`.
* * * 'popstate' : Triggered by a `popstate` event.
* * 'imperative'--triggered by `router.navigateByUrl` or `router.navigate`. * * 'hashchange'-: Triggered by a `hashchange` event.
* * 'popstate'--triggered by a popstate event
* * 'hashchange'--triggered by a hashchange event
* *
* @publicApi * @publicApi
*/ */
export type NavigationTrigger = 'imperative' | 'popstate' | 'hashchange'; export type NavigationTrigger = 'imperative' | 'popstate' | 'hashchange';
/** /**
* @description * Base for events the router goes through, as opposed to events tied to a specific
* route. Fired one time for any given navigation.
* *
* Base for events the Router goes through, as opposed to events tied to a specific * @usageNotes
* Route. `RouterEvent`s will only be fired one time for any given navigation.
* *
* Example: * ```ts
*
* ```
* class MyService { * class MyService {
* constructor(public router: Router, logger: Logger) { * constructor(public router: Router, logger: Logger) {
* router.events.pipe( * router.events.pipe(
@ -42,46 +38,46 @@ export type NavigationTrigger = 'imperative' | 'popstate' | 'hashchange';
* } * }
* ``` * ```
* *
* @see `Event`
* @publicApi * @publicApi
*/ */
export class RouterEvent { export class RouterEvent {
constructor( constructor(
/** @docsNotRequired */ /** A unique ID that the router assigns to every router navigation. */
public id: number, public id: number,
/** @docsNotRequired */ /** The URL that is the destination for this navigation. */
public url: string) {} public url: string) {}
} }
/** /**
* @description * An event triggered when a navigation starts.
*
* Represents an event triggered when a navigation starts.
* *
* @publicApi * @publicApi
*/ */
export class NavigationStart extends RouterEvent { export class NavigationStart extends RouterEvent {
/** /**
* Identifies the trigger of the navigation. * Identifies the call or event that triggered the navigation.
* An `imperative` trigger is a call to `router.navigateByUrl()` or `router.navigate()`.
* *
* * 'imperative'--triggered by `router.navigateByUrl` or `router.navigate`.
* * 'popstate'--triggered by a popstate event
* * 'hashchange'--triggered by a hashchange event
*/ */
navigationTrigger?: 'imperative'|'popstate'|'hashchange'; navigationTrigger?: 'imperative'|'popstate'|'hashchange';
/** /**
* This reflects the state object that was previously supplied to the pushState call. This is * The navigation state that was previously supplied to the `pushState` call,
* not null only when the navigation is triggered by a popstate event. * when the navigation is triggered by a `popstate` event. Otherwise null.
* *
* The router assigns a navigationId to every router transition/navigation. Even when the user * The state object is defined by `NavigationExtras`, and contains any
* clicks on the back button in the browser, a new navigation id will be created. So from * developer-defined state value, as well as a unique ID that
* the perspective of the router, the router never "goes back". By using the `restoredState` * the router assigns to every router transition/navigation.
* and its navigationId, you can implement behavior that differentiates between creating new *
* states * From the perspective of the router, the router never "goes back".
* and popstate events. In the latter case you can restore some remembered state (e.g., scroll * When the user clicks on the back button in the browser,
* position). * a new navigation ID is created.
*
* Use the ID in this previous-state object to differentiate between a newly created
* state and one returned to by a `popstate` event, so that you can restore some
* remembered state, such as scroll position.
* *
* See {@link NavigationExtras} for more information.
*/ */
restoredState?: {[k: string]: any, navigationId: number}|null; restoredState?: {[k: string]: any, navigationId: number}|null;
@ -104,9 +100,7 @@ export class NavigationStart extends RouterEvent {
} }
/** /**
* @description * An event triggered when a navigation ends successfully.
*
* Represents an event triggered when a navigation ends successfully.
* *
* @publicApi * @publicApi
*/ */
@ -128,9 +122,7 @@ export class NavigationEnd extends RouterEvent {
} }
/** /**
* @description * An event triggered when a navigation is canceled.
*
* Represents an event triggered when a navigation is canceled.
* *
* @publicApi * @publicApi
*/ */
@ -150,9 +142,7 @@ export class NavigationCancel extends RouterEvent {
} }
/** /**
* @description * An event triggered when a navigation fails due to an unexpected error.
*
* Represents an event triggered when a navigation fails due to an unexpected error.
* *
* @publicApi * @publicApi
*/ */
@ -174,9 +164,7 @@ export class NavigationError extends RouterEvent {
} }
/** /**
* @description *An event triggered when routes are recognized.
*
* Represents an event triggered when routes are recognized.
* *
* @publicApi * @publicApi
*/ */
@ -200,9 +188,7 @@ export class RoutesRecognized extends RouterEvent {
} }
/** /**
* @description * An event triggered at the start of the Guard phase of routing.
*
* Represents the start of the Guard phase of routing.
* *
* @publicApi * @publicApi
*/ */
@ -225,9 +211,7 @@ export class GuardsCheckStart extends RouterEvent {
} }
/** /**
* @description * An event triggered at the end of the Guard phase of routing.
*
* Represents the end of the Guard phase of routing.
* *
* @publicApi * @publicApi
*/ */
@ -252,12 +236,10 @@ export class GuardsCheckEnd extends RouterEvent {
} }
/** /**
* @description * An event triggered at the the start of the Resolve phase of routing.
* *
* Represents the start of the Resolve phase of routing. The timing of this * Runs in the "resolve" phase whether or not there is anything to resolve.
* event may change, thus it's experimental. In the current iteration it will run * In future, may change to only run when there are things to be resolved.
* in the "resolve" phase whether there's things to resolve or not. In the future this
* behavior may change to only run when there are things to be resolved.
* *
* @publicApi * @publicApi
*/ */
@ -280,10 +262,8 @@ export class ResolveStart extends RouterEvent {
} }
/** /**
* @description * An event triggered at the end of the Resolve phase of routing.
* * @see `ResolveStart`.
* Represents the end of the Resolve phase of routing. See note on
* `ResolveStart` for use of this experimental API.
* *
* @publicApi * @publicApi
*/ */
@ -306,9 +286,7 @@ export class ResolveEnd extends RouterEvent {
} }
/** /**
* @description * An event triggered before lazy loading a route configuration.
*
* Represents an event triggered before lazy loading a route config.
* *
* @publicApi * @publicApi
*/ */
@ -320,9 +298,7 @@ export class RouteConfigLoadStart {
} }
/** /**
* @description * An event triggered when a route has been lazy loaded.
*
* Represents an event triggered when a route has been lazy loaded.
* *
* @publicApi * @publicApi
*/ */
@ -334,10 +310,10 @@ export class RouteConfigLoadEnd {
} }
/** /**
* @description * An event triggered at the start of the child-activation
* * part of the Resolve phase of routing.
* Represents the start of end of the Resolve phase of routing. See note on * @see `ChildActivationEnd`
* `ChildActivationEnd` for use of this experimental API. * @see `ResolveStart`
* *
* @publicApi * @publicApi
*/ */
@ -352,11 +328,10 @@ export class ChildActivationStart {
} }
/** /**
* @description * An event triggered at the end of the child-activation part
* * of the Resolve phase of routing.
* Represents the start of end of the Resolve phase of routing. See note on * @see `ChildActivationStart`
* `ChildActivationStart` for use of this experimental API. * @see `ResolveStart` *
*
* @publicApi * @publicApi
*/ */
export class ChildActivationEnd { export class ChildActivationEnd {
@ -370,10 +345,10 @@ export class ChildActivationEnd {
} }
/** /**
* @description * An event triggered at the start of the activation part
* * of the Resolve phase of routing.
* Represents the start of end of the Resolve phase of routing. See note on * @see ActivationEnd`
* `ActivationEnd` for use of this experimental API. * @see `ResolveStart`
* *
* @publicApi * @publicApi
*/ */
@ -388,10 +363,10 @@ export class ActivationStart {
} }
/** /**
* @description * An event triggered at the end of the activation part
* * of the Resolve phase of routing.
* Represents the start of end of the Resolve phase of routing. See note on * @see `ActivationStart`
* `ActivationStart` for use of this experimental API. * @see `ResolveStart`
* *
* @publicApi * @publicApi
*/ */
@ -406,9 +381,7 @@ export class ActivationEnd {
} }
/** /**
* @description * An event triggered by scrolling.
*
* Represents a scrolling event.
* *
* @publicApi * @publicApi
*/ */
@ -430,11 +403,9 @@ export class Scroll {
} }
/** /**
* @description * Router events that allow you to track the lifecycle of the router.
* *
* Represents a router event, allowing you to track the lifecycle of the router. * The sequence of router events is as follows:
*
* The sequence of router events is:
* *
* - `NavigationStart`, * - `NavigationStart`,
* - `RouteConfigLoadStart`, * - `RouteConfigLoadStart`,

2
packages/router/src/index.ts
View File

@ -7,7 +7,7 @@
*/ */
export {Data, DeprecatedLoadChildren, LoadChildren, LoadChildrenCallback, ResolveData, Route, Routes, RunGuardsAndResolvers, UrlMatchResult, UrlMatcher} from './config'; export {Data, DeprecatedLoadChildren, LoadChildren, LoadChildrenCallback, QueryParamsHandling, ResolveData, Route, Routes, RunGuardsAndResolvers, UrlMatchResult, UrlMatcher} from './config';
export {RouterLink, RouterLinkWithHref} from './directives/router_link'; export {RouterLink, RouterLinkWithHref} from './directives/router_link';
export {RouterLinkActive} from './directives/router_link_active'; export {RouterLinkActive} from './directives/router_link_active';
export {RouterOutlet} from './directives/router_outlet'; export {RouterOutlet} from './directives/router_outlet';

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

@ -42,9 +42,10 @@ import {isUrlTree} from './utils/type_guards';
*/ */
export interface NavigationExtras { export interface NavigationExtras {
/** /**
* Enables relative navigation from the current ActivatedRoute. * Specifies a root URI to use for relative navigation.
* *
* Configuration: * For example, consider the following route configuration where the parent route
* has two children.
* *
* ``` * ```
* [{ * [{
@ -60,7 +61,8 @@ export interface NavigationExtras {
* }] * }]
* ``` * ```
* *
* Navigate to list route from child route: * The following `go()` function navigates to the `list` route by
* interpreting the destination URI as relative to the activated `child` route
* *
* ``` * ```
* @Component({...}) * @Component({...})
@ -96,20 +98,18 @@ export interface NavigationExtras {
fragment?: string; fragment?: string;
/** /**
* DEPRECATED: Use `queryParamsHandling` instead to preserve * **DEPRECATED**: Use `queryParamsHandling: "preserve"` instead to preserve
* query parameters for the next navigation. * query parameters for the next navigation.
* *
* ```
* // Preserve query params from /results?page=1 to /view?page=1
* this.router.navigate(['/view'], { preserveQueryParams: true });
* ```
*
* @deprecated since v4 * @deprecated since v4
*/ */
preserveQueryParams?: boolean; preserveQueryParams?: boolean;
/** /**
* Configuration strategy for how to handle query parameters for the next navigation. * How to handle query parameters in the router link for the next navigation.
* One of:
* * `merge` : Merge new with current parameters.
* * `preserve` : Preserve current parameters.
* *
* ``` * ```
* // from /results?page=1 to /view?page=1&page=2 * // from /results?page=1 to /view?page=1&page=2
@ -118,7 +118,7 @@ export interface NavigationExtras {
*/ */
queryParamsHandling?: QueryParamsHandling|null; queryParamsHandling?: QueryParamsHandling|null;
/** /**
* Preserves the fragment for the next navigation * When true, preserves the URL fragment for the next navigation
* *
* ``` * ```
* // Preserve fragment from /results#top to /view#top * // Preserve fragment from /results#top to /view#top
@ -127,7 +127,7 @@ export interface NavigationExtras {
*/ */
preserveFragment?: boolean; preserveFragment?: boolean;
/** /**
* Navigates without pushing a new state into history. * When true, navigates without pushing a new state into history.
* *
* ``` * ```
* // Navigate silently to /view * // Navigate silently to /view
@ -136,7 +136,7 @@ export interface NavigationExtras {
*/ */
skipLocationChange?: boolean; skipLocationChange?: boolean;
/** /**
* Navigates while replacing the current state in history. * When true, navigates while replacing the current state in history.
* *
* ``` * ```
* // Navigate to /view * // Navigate to /view
@ -145,26 +145,26 @@ export interface NavigationExtras {
*/ */
replaceUrl?: boolean; replaceUrl?: boolean;
/** /**
* State passed to any navigation. This value will be accessible through the `extras` object * Developer-defined state that can be passed to any navigation.
* returned from `router.getCurrentNavigation()` while a navigation is executing. Once a * Access this value through the `Navigation.extras` object
* navigation completes, this value will be written to `history.state` when the `location.go` * returned from `router.getCurrentNavigation()` while a navigation is executing.
* or `location.replaceState` method is called before activating of this route. Note that
* `history.state` will not pass an object equality test because the `navigationId` will be
* added to the state before being written.
* *
* While `history.state` can accept any type of value, because the router adds the `navigationId` * After a navigation completes, the router writes an object containing this
* on each navigation, the `state` must always be an object. * value together with a `navigationId` to `history.state`.
* The value is written when `location.go()` or `location.replaceState()`
* is called before activating this route.
*
* Note that `history.state` does not pass an object equality test because
* the router adds the `navigationId` on each navigation.
*/ */
state?: {[k: string]: any}; state?: {[k: string]: any};
} }
/** /**
* @description * Error handler that is invoked when a navigation error occurs.
* *
* Error handler that is invoked when a navigation errors. * If the handler returns a value, the navigation promise is resolved with this value.
* * If the handler throws an exception, the navigation promise is rejected with
* If the handler returns a value, the navigation promise will be resolved with this value.
* If the handler throws an exception, the navigation promise will be rejected with
* the exception. * the exception.
* *
* @publicApi * @publicApi
@ -185,10 +185,8 @@ export type RestoredState = {
}; };
/** /**
* @description * Information about a navigation operation. Retrieve the most recent
* * navigation object with the `router.getCurrentNavigation()` method.
* Information about any given navigation. This information can be gotten from the router at
* any time using the `router.getCurrentNavigation()` method.
* *
* @publicApi * @publicApi
*/ */
@ -198,35 +196,37 @@ export type Navigation = {
*/ */
id: number; id: number;
/** /**
* Target URL passed into the {@link Router#navigateByUrl} call before navigation. This is * The target URL passed into the `Router#navigateByUrl()` call before navigation. This is
* the value before the router has parsed or applied redirects to it. * the value before the router has parsed or applied redirects to it.
*/ */
initialUrl: string | UrlTree; initialUrl: string | UrlTree;
/** /**
* The initial target URL after being parsed with {@link UrlSerializer.extract()}. * The initial target URL after being parsed with `UrlSerializer.extract()`.
*/ */
extractedUrl: UrlTree; extractedUrl: UrlTree;
/** /**
* Extracted URL after redirects have been applied. This URL may not be available immediately, * The extracted URL after redirects have been applied.
* therefore this property can be `undefined`. It is guaranteed to be set after the * This URL may not be available immediately, therefore this property can be `undefined`.
* {@link RoutesRecognized} event fires. * It is guaranteed to be set after the `RoutesRecognized` event fires.
*/ */
finalUrl?: UrlTree; finalUrl?: UrlTree;
/** /**
* Identifies the trigger of the navigation. * Identifies how this navigation was triggered.
* *
* * 'imperative'--triggered by `router.navigateByUrl` or `router.navigate`. * * 'imperative'--Triggered by `router.navigateByUrl` or `router.navigate`.
* * 'popstate'--triggered by a popstate event * * 'popstate'--Triggered by a popstate event.
* * 'hashchange'--triggered by a hashchange event * * 'hashchange'--Triggered by a hashchange event.
*/ */
trigger: 'imperative' | 'popstate' | 'hashchange'; trigger: 'imperative' | 'popstate' | 'hashchange';
/** /**
* The NavigationExtras used in this navigation. See {@link NavigationExtras} for more info. * Options that controlled the strategy used for this navigation.
* See `NavigationExtras`.
*/ */
extras: NavigationExtras; extras: NavigationExtras;
/** /**
* Previously successful Navigation object. Only a single previous Navigation is available, * The previously successful `Navigation` object. Only one previous navigation
* therefore this previous Navigation will always have a `null` value for `previousNavigation`. * is available, therefore this previous `Navigation` object has a `null` value
* for its own `previousNavigation`.
*/ */
previousNavigation: Navigation | null; previousNavigation: Navigation | null;
}; };
@ -320,8 +320,9 @@ export class Router {
errorHandler: ErrorHandler = defaultErrorHandler; errorHandler: ErrorHandler = defaultErrorHandler;
/** /**
* Malformed uri error handler is invoked when `Router.parseUrl(url)` throws an * A handler for errors thrown by `Router.parseUrl(url)`
* error due to containing an invalid character. The most common case would be a `%` sign * 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. * that's not encoded and is not part of a percent encoded sequence.
*/ */
malformedUriErrorHandler: malformedUriErrorHandler:
@ -348,12 +349,13 @@ export class Router {
}; };
/** /**
* Extracts and merges URLs. Used for AngularJS to Angular migrations. * A strategy for extracting and merging URLs.
* Used for AngularJS to Angular migrations.
*/ */
urlHandlingStrategy: UrlHandlingStrategy = new DefaultUrlHandlingStrategy(); urlHandlingStrategy: UrlHandlingStrategy = new DefaultUrlHandlingStrategy();
/** /**
* The strategy for re-using routes. * A strategy for re-using routes.
*/ */
routeReuseStrategy: RouteReuseStrategy = new DefaultRouteReuseStrategy(); routeReuseStrategy: RouteReuseStrategy = new DefaultRouteReuseStrategy();
@ -376,19 +378,17 @@ export class Router {
paramsInheritanceStrategy: 'emptyOnly'|'always' = 'emptyOnly'; paramsInheritanceStrategy: 'emptyOnly'|'always' = 'emptyOnly';
/** /**
* Defines when the router updates the browser URL. The default behavior is to update after * Determines when the router updates the browser URL.
* successful navigation. However, some applications may prefer a mode where the URL gets * By default (`"deferred"`), udates the browser URL after navigation has finished.
* updated at the beginning of navigation. The most common use case would be updating the * Set to `'eager'` to update the browser URL at the beginning of navigation.
* URL early so if navigation fails, you can show an error message with the URL that failed. * You can choose to update early so that, if navigation fails,
* Available options are: * you can show an error message with the URL that failed.
*
* - `'deferred'`, the default, updates the browser URL after navigation has finished.
* - `'eager'`, updates browser URL at the beginning of navigation.
*/ */
urlUpdateStrategy: 'deferred'|'eager' = 'deferred'; urlUpdateStrategy: 'deferred'|'eager' = 'deferred';
/** /**
* See {@link RouterModule} for more information. * Enables a bug fix that corrects relative link resolution in components with empty paths.
* @see `RouterModule`
*/ */
relativeLinkResolution: 'legacy'|'corrected' = 'legacy'; relativeLinkResolution: 'legacy'|'corrected' = 'legacy';
@ -864,10 +864,10 @@ 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. * Otherwise, applies the given command starting from the root.
* *
* @param commands An array of commands to apply. * @param commands An array of commands to apply.
* @param navigationExtras * @param navigationExtras Options that control the navigation strategy.
* @returns The new URL tree. * @returns The new URL tree.
* *
* @usageNotes * @usageNotes
@ -882,9 +882,8 @@ export class Router {
* // you can collapse static segments like this (this works only with the first passed-in value): * // you can collapse static segments like this (this works only with the first passed-in value):
* router.createUrlTree(['/team/33/user', userId]); * router.createUrlTree(['/team/33/user', userId]);
* *
* // If the first segment can contain slashes, and you do not want the router to split it, you * // If the first segment can contain slashes, and you do not want the router to split it,
* // can do the following: * // you can do the following:
*
* router.createUrlTree([{segmentPath: '/one/two'}]); * router.createUrlTree([{segmentPath: '/one/two'}]);
* *
* // create /team/33/(user/11//right:chat) * // create /team/33/(user/11//right:chat)
@ -947,8 +946,6 @@ export class Router {
* *
* @usageNotes * @usageNotes
* *
* ### Example
*
* ``` * ```
* router.navigateByUrl("/team/33/user/11"); * router.navigateByUrl("/team/33/user/11");
* *
@ -981,8 +978,6 @@ export class Router {
* *
* @usageNotes * @usageNotes
* *
* ### Example
*
* ``` * ```
* router.navigate(['team', 33, 'user', 11], {relativeTo: route}); * router.navigate(['team', 33, 'user', 11], {relativeTo: route});
* *

3
packages/router/src/router_config_loader.ts
View File

@ -13,7 +13,8 @@ import {LoadChildren, LoadedRouterConfig, Route, standardizeConfig} from './conf
import {flatten, wrapIntoObservable} from './utils/collection'; import {flatten, wrapIntoObservable} from './utils/collection';
/** /**
* @docsNotRequired * The [DI token](guide/glossary/#di-token) for a router configuration.
* @see `ROUTES`
* @publicApi * @publicApi
*/ */
export const ROUTES = new InjectionToken<Route[][]>('ROUTES'); export const ROUTES = new InjectionToken<Route[][]>('ROUTES');

174
packages/router/src/router_module.ts
View File

@ -31,19 +31,13 @@ import {flatten} from './utils/collection';
/** /**
* @description * The directives defined in the `RouterModule`.
*
* Contains a list of directives
*
*
*/ */
const ROUTER_DIRECTIVES = const ROUTER_DIRECTIVES =
[RouterOutlet, RouterLink, RouterLinkWithHref, RouterLinkActive, EmptyOutletComponent]; [RouterOutlet, RouterLink, RouterLinkWithHref, RouterLinkActive, EmptyOutletComponent];
/** /**
* @description * A [DI token](guide/glossary/#di-token) for the router service.
*
* Is used in DI to configure the router.
* *
* @publicApi * @publicApi
*/ */
@ -121,12 +115,12 @@ export function routerNgProbeToken() {
* In addition, we often want to split applications into multiple bundles and load them on demand. * In addition, we often want to split applications into multiple bundles and load them on demand.
* Doing this transparently is not trivial. * Doing this transparently is not trivial.
* *
* The Angular router solves these problems. Using the router, you can declaratively specify * The Angular router service solves these problems. Using the router, you can declaratively specify
* application states, manage state transitions while taking care of the URL, and load bundles on * application states, manage state transitions while taking care of the URL, and load bundles on
* demand. * demand.
* *
* [Read this developer guide](https://angular.io/docs/ts/latest/guide/router.html) to get an * @see [Routing and Navigation](guide/router.html) for an
* overview of how the router should be used. * overview of how the router service should be used.
* *
* @publicApi * @publicApi
*/ */
@ -140,34 +134,12 @@ export class RouterModule {
constructor(@Optional() @Inject(ROUTER_FORROOT_GUARD) guard: any, @Optional() router: Router) {} constructor(@Optional() @Inject(ROUTER_FORROOT_GUARD) guard: any, @Optional() router: Router) {}
/** /**
* Creates a module with all the router providers and directives. It also optionally sets up an * Creates and configures a module with all the router providers and directives.
* application listener to perform an initial navigation. * Optionally sets up an application listener to perform an initial navigation.
* *
* Configuration Options: * @param routes An array of `Route` objects that define the navigation paths for the application.
* * @param config An `ExtraOptions` configuration object that controls how navigation is performed.
* * `enableTracing` Toggles whether the router should log all navigation events to the console. * @return The new router module.
* * `useHash` Enables the location strategy that uses the URL fragment instead of the history
* API.
* * `initialNavigation` Disables the initial navigation.
* * `errorHandler` Defines a custom error handler for failed navigations.
* * `preloadingStrategy` Configures a preloading strategy. See `PreloadAllModules`.
* * `onSameUrlNavigation` Define what the router should do if it receives a navigation request to
* the current URL.
* * `scrollPositionRestoration` Configures if the scroll position needs to be restored when
* navigating back.
* * `anchorScrolling` Configures if the router should scroll to the element when the url has a
* fragment.
* * `scrollOffset` Configures the scroll offset the router will use when scrolling to an element.
* * `paramsInheritanceStrategy` Defines how the router merges params, data and resolved data from
* parent to child routes.
* * `malformedUriErrorHandler` Defines a custom malformed uri error handler function. This
* handler is invoked when encodedURI contains invalid character sequences.
* * `urlUpdateStrategy` Defines when the router updates the browser URL. The default behavior is
* to update after successful navigation.
* * `relativeLinkResolution` Enables the correct relative link resolution in components with
* empty paths.
*
* See `ExtraOptions` for more details about the above options.
*/ */
static forRoot(routes: Routes, config?: ExtraOptions): ModuleWithProviders<RouterModule> { static forRoot(routes: Routes, config?: ExtraOptions): ModuleWithProviders<RouterModule> {
return { return {
@ -235,12 +207,10 @@ export function provideForRootGuard(router: Router): any {
} }
/** /**
* @description * Registers a [DI provider](guide/glossary#provider) for a set of routes.
* * @param routes The route configuration to provide.
* Registers routes.
* *
* @usageNotes * @usageNotes
* ### Example
* *
* ``` * ```
* @NgModule({ * @NgModule({
@ -260,70 +230,75 @@ export function provideRoutes(routes: Routes): any {
} }
/** /**
* @description * Allowed values in an `ExtraOptions` object that configure
* when the router performs the initial navigation operation.
* *
* Represents an option to configure when the initial navigation is performed. * * 'enabled' (Default) The initial navigation starts before the root component is created.
*
* * 'enabled' - the initial navigation starts before the root component is created.
* The bootstrap is blocked until the initial navigation is complete. * The bootstrap is blocked until the initial navigation is complete.
* * 'disabled' - the initial navigation is not performed. The location listener is set up before * * 'disabled' - The initial navigation is not performed. The location listener is set up before
* the root component gets created. * the root component gets created. Use if there is a reason to have
* * 'legacy_enabled'- the initial navigation starts after the root component has been created. * more control over when the router starts its initial navigation due to some complex
* initialization logic.
* * 'legacy_enabled'- The initial navigation starts after the root component has been created.
* The bootstrap is not blocked until the initial navigation is complete. @deprecated * The bootstrap is not blocked until the initial navigation is complete. @deprecated
* * 'legacy_disabled'- the initial navigation is not performed. The location listener is set up * * 'legacy_disabled'- The initial navigation is not performed. The location listener is set up
* after @deprecated * after the root component gets created. @deprecated
* the root component gets created.
* * `true` - same as 'legacy_enabled'. @deprecated since v4 * * `true` - same as 'legacy_enabled'. @deprecated since v4
* * `false` - same as 'legacy_disabled'. @deprecated since v4 * * `false` - same as 'legacy_disabled'. @deprecated since v4
* *
* The 'enabled' option should be used for applications unless there is a reason to have
* more control over when the router starts its initial navigation due to some complex
* initialization logic. In this case, 'disabled' should be used.
*
* The 'legacy_enabled' and 'legacy_disabled' should not be used for new applications. * The 'legacy_enabled' and 'legacy_disabled' should not be used for new applications.
* *
* @see `forRoot()`
*
* @publicApi * @publicApi
*/ */
export type InitialNavigation = export type InitialNavigation =
true | false | 'enabled' | 'disabled' | 'legacy_enabled' | 'legacy_disabled'; true | false | 'enabled' | 'disabled' | 'legacy_enabled' | 'legacy_disabled';
/** /**
* @description * A set of configuration options for a router module, provided in the
* * `forRoot()` method.
* Represents options to configure the router.
* *
* @publicApi * @publicApi
*/ */
export interface ExtraOptions { export interface ExtraOptions {
/** /**
* Makes the router log all its internal events to the console. * When true, log all internal navigation events to the console.
* Use for debugging.
*/ */
enableTracing?: boolean; enableTracing?: boolean;
/** /**
* Enables the location strategy that uses the URL fragment instead of the history API. * When true, enable the location strategy that uses the URL fragment
* instead of the history API.
*/ */
useHash?: boolean; useHash?: boolean;
/** /**
* Disables the initial navigation. * One of `enabled` (the default) or `disabled`.
* By default, the initial navigation starts before the root component is created.
* The bootstrap is blocked until the initial navigation is complete.
* When set to `disabled`, the initial navigation is not performed.
* The location listener is set up before the root component gets created.
*/ */
initialNavigation?: InitialNavigation; initialNavigation?: InitialNavigation;
/** /**
* A custom error handler. * A custom error handler for failed navigations.
*/ */
errorHandler?: ErrorHandler; errorHandler?: ErrorHandler;
/** /**
* Configures a preloading strategy. See `PreloadAllModules`. * Configures a preloading strategy.
* One of `PreloadAllModules` or `NoPreloading` (the default).
*/ */
preloadingStrategy?: any; preloadingStrategy?: any;
/** /**
* Define what the router should do if it receives a navigation request to the current URL. * 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 * Default is `ignore`, which causes the router ignores the navigation.
* as a "refresh" button. Use this option to configure the behavior when navigating to the * This can disable features such as a "refresh" button.
* Use this option to configure the behavior when navigating to the
* current URL. Default is 'ignore'. * current URL. Default is 'ignore'.
*/ */
onSameUrlNavigation?: 'reload'|'ignore'; onSameUrlNavigation?: 'reload'|'ignore';
@ -331,14 +306,15 @@ export interface ExtraOptions {
/** /**
* Configures if the scroll position needs to be restored when navigating back. * Configures if the scroll position needs to be restored when navigating back.
* *
* * 'disabled'--does nothing (default). Scroll position will be maintained on navigation. * * 'disabled'- (Default) Does nothing. Scroll position is maintained on navigation.
* * 'top'--set the scroll position to x = 0, y = 0 on all navigation. * * 'top'- Sets the scroll position to x = 0, y = 0 on all navigation.
* * 'enabled'--restores the previous scroll position on backward navigation, else sets the * * 'enabled'- Restores the previous scroll position on backward navigation, else sets the
* position to the anchor if one is provided, or sets the scroll position to [0, 0] (forward * position to the anchor if one is provided, or sets the scroll position to [0, 0] (forward
* navigation). This option will be the default in the future. * navigation). This option will be the default in the future.
* *
* You can implement custom scroll restoration behavior by adapting the enabled behavior as * You can implement custom scroll restoration behavior by adapting the enabled behavior as
* follows: * in the following example.
*
* ```typescript * ```typescript
* class AppModule { * class AppModule {
* constructor(router: Router, viewportScroller: ViewportScroller) { * constructor(router: Router, viewportScroller: ViewportScroller) {
@ -363,10 +339,8 @@ export interface ExtraOptions {
scrollPositionRestoration?: 'disabled'|'enabled'|'top'; scrollPositionRestoration?: 'disabled'|'enabled'|'top';
/** /**
* Configures if the router should scroll to the element when the url has a fragment. * When set to 'enabled', scrolls to the anchor element when the URL has a fragment.
* * Anchor scrolling is disabled by default.
* * 'disabled'--does nothing (default).
* * 'enabled'--scrolls to the element. This option will be the default in the future.
* *
* Anchor scrolling does not happen on 'popstate'. Instead, we restore the position * Anchor scrolling does not happen on 'popstate'. Instead, we restore the position
* that we stored or scroll to the top. * that we stored or scroll to the top.
@ -376,28 +350,28 @@ export interface ExtraOptions {
/** /**
* Configures the scroll offset the router will use when scrolling to an element. * Configures the scroll offset the router will use when scrolling to an element.
* *
* When given a tuple with two numbers, the router will always use the numbers. * When given a tuple with x and y position value,
* When given a function, the router will invoke the function every time it restores scroll * the router uses that offset each time it scrolls.
* position. * When given a function, the router invokes the function every time
* it restores scroll position.
*/ */
scrollOffset?: [number, number]|(() => [number, number]); scrollOffset?: [number, number]|(() => [number, number]);
/** /**
* Defines how the router merges params, data and resolved data from parent to child * Defines how the router merges parameters, data, and resolved data from parent to child
* routes. Available options are: * routes. By default ('emptyOnly'), inherits parent parameters only for
* * path-less or component-less routes.
* - `'emptyOnly'`, the default, only inherits parent params for path-less or component-less * Set to 'always' to enable unconditional inheritance of parent parameters.
* routes.
* - `'always'`, enables unconditional inheritance of parent params.
*/ */
paramsInheritanceStrategy?: 'emptyOnly'|'always'; paramsInheritanceStrategy?: 'emptyOnly'|'always';
/** /**
* A custom malformed uri error handler function. This handler is invoked when encodedURI contains * A custom handler for malformed URI errors. The handler is invoked when `encodedURI` contains
* invalid character sequences. The default implementation is to redirect to the root url dropping * invalid character sequences.
* any path or param info. This function passes three parameters: * The default implementation is to redirect to the root URL, dropping
* any path or parameter information. The function takes three parameters:
* *
* - `'URIError'` - Error thrown when parsing a bad URL * - `'URIError'` - Error thrown when parsing a bad URL.
* - `'UrlSerializer'` - UrlSerializer that’s configured with the router. * - `'UrlSerializer'` - UrlSerializer that’s configured with the router.
* - `'url'` - The malformed URL that caused the URIError * - `'url'` - The malformed URL that caused the URIError
* */ * */
@ -405,14 +379,11 @@ export interface ExtraOptions {
(error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree; (error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree;
/** /**
* Defines when the router updates the browser URL. The default behavior is to update after * Defines when the router updates the browser URL. By default ('deferred'),
* successful navigation. However, some applications may prefer a mode where the URL gets * update after successful navigation.
* updated at the beginning of navigation. The most common use case would be updating the * Set to 'eager' if prefer to update the URL at the beginning of navigation.
* URL early so if navigation fails, you can show an error message with the URL that failed. * Updating the URL early allows you to handle a failure of navigation by
* Available options are: * showing an error message with the URL that failed.
*
* - `'deferred'`, the default, updates the browser URL after navigation has finished.
* - `'eager'`, updates browser URL at the beginning of navigation.
*/ */
urlUpdateStrategy?: 'deferred'|'eager'; urlUpdateStrategy?: 'deferred'|'eager';
@ -505,13 +476,13 @@ export function rootRoute(router: Router): ActivatedRoute {
} }
/** /**
* To initialize the router properly we need to do in two steps: * Router initialization requires two steps:
* *
* We need to start the navigation in a APP_INITIALIZER to block the bootstrap if * First, we start the navigation in a `APP_INITIALIZER` to block the bootstrap if
* a resolver or a guards executes asynchronously. Second, we need to actually run * a resolver or a guard executes asynchronously.
* activation in a BOOTSTRAP_LISTENER. We utilize the afterPreactivation
* hook provided by the router to do that.
* *
* Next, we actually run activation in a `BOOTSTRAP_LISTENER`, using the
* `afterPreactivation` hook provided by the router.
* The router navigation starts, reaches the point when preactivation is done, and then * The router navigation starts, reaches the point when preactivation is done, and then
* pauses. It waits for the hook to be resolved. We then resolve it only in a bootstrap listener. * pauses. It waits for the hook to be resolved. We then resolve it only in a bootstrap listener.
*/ */
@ -603,7 +574,8 @@ export function getBootstrapListener(r: RouterInitializer) {
} }
/** /**
* A token for the router initializer that will be called after the app is bootstrapped. * A [DI token](guide/glossary/#di-token) for the router initializer that
* is called after the app is bootstrapped.
* *
* @publicApi * @publicApi
*/ */

57
packages/router/src/router_state.ts
View File

@ -19,14 +19,15 @@ import {Tree, TreeNode} from './utils/tree';
/** /**
* @description * Represents the state of the router as a tree of activated routes.
*
* Represents the state of the router.
*
* RouterState is a tree of activated routes. Every node in this tree knows about the "consumed" URL
* segments, the extracted parameters, and the resolved data.
* *
* @usageNotes * @usageNotes
*
* Every node in the route tree is an `ActivatedRoute` instance
* that knows about the "consumed" URL segments, the extracted parameters,
* and the resolved data.
* Use the `ActivatedRoute` properties to traverse the tree from any node.
*
* ### Example * ### Example
* *
* ``` * ```
@ -42,7 +43,7 @@ import {Tree, TreeNode} from './utils/tree';
* } * }
* ``` * ```
* *
* See `ActivatedRoute` for more information. * @see `ActivatedRoute`
* *
* @publicApi * @publicApi
*/ */
@ -86,10 +87,9 @@ export function createEmptyStateSnapshot(
} }
/** /**
* @description * Provides access to information about a route associated with a component
* * that is loaded in an outlet.
* Contains the information about a route associated with a component loaded in an * Use to traverse the `RouterState` tree and extract information from nodes.
* outlet. An `ActivatedRoute` can also be used to traverse the router state tree.
* *
* {@example router/activated-route/module.ts region="activated-route" * {@example router/activated-route/module.ts region="activated-route"
* header="activated-route.component.ts" linenums="false"} * header="activated-route.component.ts" linenums="false"}
@ -98,58 +98,57 @@ export function createEmptyStateSnapshot(
*/ */
export class ActivatedRoute { export class ActivatedRoute {
/** The current snapshot of this route */ /** The current snapshot of this route */
// TODO(issue/24571): remove '!'.
snapshot !: ActivatedRouteSnapshot; snapshot !: ActivatedRouteSnapshot;
/** @internal */ /** @internal */
_futureSnapshot: ActivatedRouteSnapshot; _futureSnapshot: ActivatedRouteSnapshot;
/** @internal */ /** @internal */
// TODO(issue/24571): remove '!'.
_routerState !: RouterState; _routerState !: RouterState;
/** @internal */ /** @internal */
// TODO(issue/24571): remove '!'.
_paramMap !: Observable<ParamMap>; _paramMap !: Observable<ParamMap>;
/** @internal */ /** @internal */
// TODO(issue/24571): remove '!'.
_queryParamMap !: Observable<ParamMap>; _queryParamMap !: Observable<ParamMap>;
/** @internal */ /** @internal */
constructor( constructor(
/** An observable of the URL segments matched by this route */ /** An observable of the URL segments matched by this route. */
public url: Observable<UrlSegment[]>, public url: Observable<UrlSegment[]>,
/** An observable of the matrix parameters scoped to this route */ /** An observable of the matrix parameters scoped to this route. */
public params: Observable<Params>, public params: Observable<Params>,
/** An observable of the query parameters shared by all the routes */ /** An observable of the query parameters shared by all the routes. */
public queryParams: Observable<Params>, public queryParams: Observable<Params>,
/** An observable of the URL fragment shared by all the routes */ /** An observable of the URL fragment shared by all the routes. */
public fragment: Observable<string>, public fragment: Observable<string>,
/** An observable of the static and resolved data of this route. */ /** An observable of the static and resolved data of this route. */
public data: Observable<Data>, public data: Observable<Data>,
/** The outlet name of the route. It's a constant */ /** The outlet name of the route, a constant. */
public outlet: string, public outlet: string,
/** The component of the route. It's a constant */ /** The component of the route, a constant. */
// TODO(vsavkin): remove |string // TODO(vsavkin): remove |string
public component: Type<any>|string|null, futureSnapshot: ActivatedRouteSnapshot) { public component: Type<any>|string|null, futureSnapshot: ActivatedRouteSnapshot) {
this._futureSnapshot = futureSnapshot; this._futureSnapshot = futureSnapshot;
} }
/** The configuration used to match this route */ /** The configuration used to match this route. */
get routeConfig(): Route|null { return this._futureSnapshot.routeConfig; } get routeConfig(): Route|null { return this._futureSnapshot.routeConfig; }
/** The root of the router state */ /** The root of the router state. */
get root(): ActivatedRoute { return this._routerState.root; } get root(): ActivatedRoute { return this._routerState.root; }
/** The parent of this route in the router state tree */ /** The parent of this route in the router state tree. */
get parent(): ActivatedRoute|null { return this._routerState.parent(this); } get parent(): ActivatedRoute|null { return this._routerState.parent(this); }
/** The first child of this route in the router state tree */ /** The first child of this route in the router state tree. */
get firstChild(): ActivatedRoute|null { return this._routerState.firstChild(this); } get firstChild(): ActivatedRoute|null { return this._routerState.firstChild(this); }
/** The children of this route in the router state tree */ /** The children of this route in the router state tree. */
get children(): ActivatedRoute[] { return this._routerState.children(this); } get children(): ActivatedRoute[] { return this._routerState.children(this); }
/** The path from the root of the router state tree to this route */ /** The path from the root of the router state tree to this route. */
get pathFromRoot(): ActivatedRoute[] { return this._routerState.pathFromRoot(this); } get pathFromRoot(): ActivatedRoute[] { return this._routerState.pathFromRoot(this); }
/** An Observable that contains a map of the required and optional parameters
* specific to the route.
* The map supports retrieving single and multiple values from the same parameter. */
get paramMap(): Observable<ParamMap> { get paramMap(): Observable<ParamMap> {
if (!this._paramMap) { if (!this._paramMap) {
this._paramMap = this.params.pipe(map((p: Params): ParamMap => convertToParamMap(p))); this._paramMap = this.params.pipe(map((p: Params): ParamMap => convertToParamMap(p)));
@ -157,6 +156,10 @@ export class ActivatedRoute {
return this._paramMap; return this._paramMap;
} }
/**
* An Observable that contains a map of the query parameters available to all routes.
* The map supports retrieving single and multiple values from the query parameter.
*/
get queryParamMap(): Observable<ParamMap> { get queryParamMap(): Observable<ParamMap> {
if (!this._queryParamMap) { if (!this._queryParamMap) {
this._queryParamMap = this._queryParamMap =

46
packages/router/src/shared.ts
View File

@ -11,16 +11,16 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree';
/** /**
* @description * The primary routing outlet.
*
* Name of the primary outlet.
* *
* @publicApi * @publicApi
*/ */
export const PRIMARY_OUTLET = 'primary'; export const PRIMARY_OUTLET = 'primary';
/** /**
* A collection of parameters. * A collection of matrix and query URL parameters.
* @see `convertToParamMap()`
* @see `ParamMap`
* *
* @publicApi * @publicApi
*/ */
@ -29,34 +29,40 @@ export type Params = {
}; };
/** /**
* Matrix and Query parameters. * A map that provides access to the required and optional parameters
* specific to a route.
* The map supports retrieving a single value with `get()`
* or multiple values with `getAll()`.
* *
* `ParamMap` makes it easier to work with parameters as they could have either a single value or * @see [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
* multiple value. Because this should be known by the user, calling `get` or `getAll` returns the
* correct type (either `string` or `string[]`).
*
* The API is inspired by the URLSearchParams interface.
* see https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
* *
* @publicApi * @publicApi
*/ */
export interface ParamMap { export interface ParamMap {
/**
* Reports whether the map contains a given parameter.
* @param name The parameter name.
* @returns True if the map contains the given parameter, false otherwise.
*/
has(name: string): boolean; has(name: string): boolean;
/** /**
* Return a single value for the given parameter name: * Retrieves a single value for a parameter.
* - the value when the parameter has a single value, * @param name The parameter name.
* - the first value if the parameter has multiple values, * @return The parameter's single value,
* - `null` when there is no such parameter. * or the first value if the parameter has multiple values,
* or `null` when there is no such parameter.
*/ */
get(name: string): string|null; get(name: string): string|null;
/** /**
* Return an array of values for the given parameter name. * Retrieves multiple values for a parameter.
* @param name The parameter name.
* @return An array containing one or more values,
* or an empty array if there is no such parameter.
* *
* If there is no such parameter, an empty array is returned.
*/ */
getAll(name: string): string[]; getAll(name: string): string[];
/** Name of the parameters */ /** Names of the parameters in the map. */
readonly keys: string[]; readonly keys: string[];
} }
@ -89,7 +95,9 @@ class ParamsAsMap implements ParamMap {
} }
/** /**
* Convert a `Params` instance to a `ParamMap`. * Converts a `Params` instance to a `ParamMap`.
* @param params The instance to convert.
* @returns The new map instance.
* *
* @publicApi * @publicApi
*/ */

1
packages/router/testing/PACKAGE.md Normal file
View File

@ -0,0 +1 @@
Supplies a testing module for the Angular `Router` subsystem.

1
packages/router/upgrade/PACKAGE.md Normal file
View File

@ -0,0 +1 @@
Provides support for upgrading routing applications from Angular JS to Angular.

24
packages/router/upgrade/src/upgrade.ts
View File

@ -12,12 +12,12 @@ import {Router} from '@angular/router';
import {UpgradeModule} from '@angular/upgrade/static'; import {UpgradeModule} from '@angular/upgrade/static';
/** /**
* @description * Creates an initializer that sets up `ngRoute` integration
* along with setting up the Angular router.
* *
* Creates an initializer that in addition to setting up the Angular * @usageNotes
* router sets up the ngRoute integration.
* *
* ``` * <code-example language="typescript" linenums="false">
* @NgModule({ * @NgModule({
* imports: [ * imports: [
* RouterModule.forRoot(SOME_ROUTES), * RouterModule.forRoot(SOME_ROUTES),
@ -30,7 +30,7 @@ import {UpgradeModule} from '@angular/upgrade/static';
* export class AppModule { * export class AppModule {
* ngDoBootstrap() {} * ngDoBootstrap() {}
* } * }
* ``` * </code-example>
* *
* @publicApi * @publicApi
*/ */
@ -49,12 +49,14 @@ export function locationSyncBootstrapListener(ngUpgrade: UpgradeModule) {
} }
/** /**
* @description * Sets up a location change listener to trigger `history.pushState`.
* Works around the problem that `onPopState` does not trigger `history.pushState`.
* Must be called *after* calling `UpgradeModule.bootstrap`.
* *
* Sets up a location synchronization. * @param ngUpgrade The upgrade NgModule.
* * @param urlType The location strategy.
* History.pushState does not fire onPopState, so the Angular location * @see `HashLocationStrategy`
* doesn't detect it. The workaround is to attach a location change listener * @see `PathLocationStrategy`
* *
* @publicApi * @publicApi
*/ */
@ -87,7 +89,7 @@ export function setUpLocationSync(ngUpgrade: UpgradeModule, urlType: 'path' | 'h
} }
/** /**
* Normalize and parse a URL. * Normalizes and parses a URL.
* *
* - Normalizing means that a relative URL will be resolved into an absolute URL in the context of * - Normalizing means that a relative URL will be resolved into an absolute URL in the context of
* the application document. * the application document.

2
tools/public_api_guard/router/router.d.ts vendored
View File

@ -255,6 +255,8 @@ export declare const PRIMARY_OUTLET = "primary";
export declare function provideRoutes(routes: Routes): any; export declare function provideRoutes(routes: Routes): any;
export declare type QueryParamsHandling = 'merge' | 'preserve' | '';
export interface Resolve<T> { export interface Resolve<T> {
resolve(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Observable<T> | Promise<T> | T; resolve(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Observable<T> | Promise<T> | T;
} }