docs: update api reference doc for router link directive (#38181)
Edits and organizes the usage information for the directive. PR Close #38181
This commit is contained in:
Judy Bogart
Misko Hevery
parent
174aac68f7
commit
03a6252123
|
|
@ -20,56 +20,63 @@ import {UrlTree} from '../url_tree';
|
|||
/**
|
||||
* @description
|
||||
*
|
||||
* Lets you link to specific routes in your app.
|
||||
* 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 `<router-outlet>` locations on the page.
|
||||
*
|
||||
* Consider the following route configuration:
|
||||
* `[{ path: 'user/:name', component: UserCmp }]`.
|
||||
* When linking to this `user/:name` route, you use the `RouterLink` directive.
|
||||
*
|
||||
* 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:
|
||||
* `<a routerLink="/user/bob">link to user component</a>`
|
||||
*
|
||||
* 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`.
|
||||
*
|
||||
* For instance `['/team', teamId, 'user', userName, {details: true}]`
|
||||
* means that we want to generate 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}]`
|
||||
*
|
||||
* Multiple static segments can be merged into one
|
||||
* (e.g., `['/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 `<a [routerLink]="['/user/jim']">Jim</a>` creates the URL
|
||||
* `/user/(jim//aux:team)`.
|
||||
* See {@link Router#createUrlTree createUrlTree} for more information.
|
||||
*
|
||||
* 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
|
||||
* @usageNotes
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* ### 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.
|
||||
*
|
||||
* You can set query params and fragment as follows:
|
||||
* ### Setting and handling query params and fragments
|
||||
*
|
||||
* The following link adds a query parameter and a fragment to the generated URL:
|
||||
*
|
||||
* ```
|
||||
* <a [routerLink]="['/user/bob']" [queryParams]="{debug: true}" fragment="education">
|
||||
* link to user component
|
||||
* </a>
|
||||
* ```
|
||||
* 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:
|
||||
*
|
||||
* ```
|
||||
* <a [routerLink]="['/user/bob']" preserveQueryParams preserveFragment>
|
||||
* link to user component
|
||||
* </a>
|
||||
* ```
|
||||
* - `'merge'`: Merge the given `queryParams` into the current query params.
|
||||
* - `'preserve'`: Preserve the current query params.
|
||||
*
|
||||
* 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
|
||||
*
|
||||
* Same options for {@link NavigationExtras#queryParamsHandling
|
||||
* NavigationExtras#queryParamsHandling}.
|
||||
* For example:
|
||||
*
|
||||
* ```
|
||||
* <a [routerLink]="['/user/bob']" [queryParams]="{debug: true}" queryParamsHandling="merge">
|
||||
|
|
@ -77,9 +84,13 @@ import {UrlTree} from '../url_tree';
|
|||
* </a>
|
||||
* ```
|
||||
*
|
||||
* 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:
|
||||
*
|
||||
* ```
|
||||
* <a [routerLink]="['/user/bob']" [state]="{tracingId: 123}">
|
||||
|
|
@ -87,8 +98,9 @@ import {UrlTree} from '../url_tree';
|
|||
* </a>
|
||||
* ```
|
||||
*
|
||||
* 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 `<a [routerLink]="['/user/jim']">Jim</a>` will generate the link
|
||||
* `/user/(jim//aux:team)`.
|
||||
*
|
||||
* See {@link Router#createUrlTree createUrlTree} for more information.
|
||||
*
|
||||
* @ngModule RouterModule
|
||||
*
|
||||
* @publicApi
|
||||
|
|
|
|||
Loading…
Reference in New Issue