diff --git a/packages/router/src/directives/router_link.ts b/packages/router/src/directives/router_link.ts index 4a37f6ccad64b..7b041980f38e6 100644 --- a/packages/router/src/directives/router_link.ts +++ b/packages/router/src/directives/router_link.ts @@ -20,56 +20,63 @@ import {UrlTree} from '../url_tree'; /** * @description * - * Lets you link to specific routes in your app. - * - * Consider the following route configuration: - * `[{ path: 'user/:name', component: UserCmp }]`. - * When linking to this `user/:name` route, you use the `RouterLink` directive. + * When applied to an element in a template, makes that element a link + * that initiates navigation to a route. Navigation opens one or more routed components + * in one or more `` locations on the page. * - * If the link is static, you can use the directive as follows: + * Given a route configuration `[{ path: 'user/:name', component: UserCmp }]`, + * the following creates a static link to the route: * `link to user component` * - * If you use dynamic values to generate the link, you can pass an array of path - * segments, followed by the params for each segment. + * You can use dynamic values to generate the link. + * For a dynamic link, pass an array of path segments, + * followed by the params for each segment. + * For example, `['/team', teamId, 'user', userName, {details: true}]` + * generates a link to `/team/11/user/bob;details=true`. + * + * Multiple static segments can be merged into one term and combined with dynamic segements. + * For example, `['/team/11/user', userName, {details: true}]` + * + * The input that you provide to the link is treated as a delta to the current URL. + * For instance, suppose the current URL is `/user/(box//aux:team)`. + * The link `Jim` creates the URL + * `/user/(jim//aux:team)`. + * See {@link Router#createUrlTree createUrlTree} for more information. * - * For instance `['/team', teamId, 'user', userName, {details: true}]` - * means that we want to generate a link to `/team/11/user/bob;details=true`. + * @usageNotes * - * Multiple static segments can be merged into one - * (e.g., `['/team/11/user', userName, {details: true}]`). + * You can use absolute or relative paths in a link, set query parameters, + * control how parameters are handled, and keep a history of navigation states. * - * The first segment name can be prepended with `/`, `./`, or `../`: - * * If the first segment begins with `/`, the router will look up the route from the root of the + * ### Relative link paths + * + * The first segment name can be prepended with `/`, `./`, or `../`. + * * If the first segment begins with `/`, the router looks up the route from the root of the * app. - * * If the first segment begins with `./`, or doesn't begin with a slash, the router will - * instead look in the children of the current activated route. - * * And if the first segment begins with `../`, the router will go up one level. + * * If the first segment begins with `./`, or doesn't begin with a slash, the router + * looks in the children of the current activated route. + * * If the first segment begins with `../`, the router goes up one level in the route tree. + * + * ### Setting and handling query params and fragments * - * You can set query params and fragment as follows: + * The following link adds a query parameter and a fragment to the generated URL: * * ``` * * link to user component * * ``` - * RouterLink will use these to generate this link: `/user/bob?debug=true#education`. + * By default, the directive constructs the new URL using the given query parameters. + * The example generates the link: `/user/bob?debug=true#education`. * - * (Deprecated in v4.0.0 use `queryParamsHandling` instead) You can also tell the - * directive to preserve the current query params and fragment: + * You can instruct the directive to handle query parameters differently + * by specifying the `queryParamsHandling` option in the link. + * Allowed values are: * - * ``` - * - * link to user component - * - * ``` - * - * You can tell the directive how to handle queryParams. Available options are: - * - `'merge'`: merge the queryParams into the current queryParams - * - `'preserve'`: preserve the current queryParams - * - default/`''`: use the queryParams only + * - `'merge'`: Merge the given `queryParams` into the current query params. + * - `'preserve'`: Preserve the current query params. * - * Same options for {@link NavigationExtras#queryParamsHandling - * NavigationExtras#queryParamsHandling}. + * For example: * * ``` * @@ -77,9 +84,13 @@ import {UrlTree} from '../url_tree'; * * ``` * - * You can provide a `state` value to be persisted to the browser's History.state - * property (See https://developer.mozilla.org/en-US/docs/Web/API/History#Properties). It's - * used as follows: + * See {@link NavigationExtras.queryParamsHandling NavigationExtras#queryParamsHandling}. + * + * ### Preserving navigation history + * + * You can provide a `state` value to be persisted to the browser's + * [`History.state` property](https://developer.mozilla.org/en-US/docs/Web/API/History#Properties). + * For example: * * ``` * @@ -87,8 +98,9 @@ import {UrlTree} from '../url_tree'; * * ``` * - * And later the value can be read from the router through `router.getCurrentNavigation`. - * For example, to capture the `tracingId` above during the `NavigationStart` event: + * Use {@link Router.getCurrentNavigation() Router#getCurrentNavigation} to retrieve a saved + * navigation-state value. For example, to capture the `tracingId` during the `NavigationStart` + * event: * * ``` * // Get NavigationStart events @@ -98,15 +110,6 @@ import {UrlTree} from '../url_tree'; * }); * ``` * - * The router link directive always treats the provided input as a delta to the current url. - * - * For instance, if the current url is `/user/(box//aux:team)`. - * - * Then the following link `Jim` will generate the link - * `/user/(jim//aux:team)`. - * - * See {@link Router#createUrlTree createUrlTree} for more information. - * * @ngModule RouterModule * * @publicApi