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

docs(router): update docs of the Router service

This commit is contained in:
vsavkin 2016-09-10 16:51:27 -07:00
parent 0822066175
commit 617475005f
2 changed files with 103 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
modules/@angular/router/src/router.ts
View File

@ -36,13 +36,15 @@ import {TreeNode} from './utils/tree';
declare var Zone: any;
/**
* @whatItDoes Represents the extra options used during navigation.
*
* @stable
*/
export interface NavigationExtras {
/**
* Enables relative navigation from the current ActivatedRoute
* Enables relative navigation from the current ActivatedRoute.
*
* Configuration
* Configuration:
*
* ```
* [{
@ -61,7 +63,7 @@ export interface NavigationExtras {
* }]
* ```
*
* Navigate to list route from child route
* Navigate to list route from child route:
*
* ```
* @Component({...})
@ -75,8 +77,9 @@ export interface NavigationExtras {
* ```
*/
relativeTo?: ActivatedRoute;
/**
* Sets query parameters to the URL
* Sets query parameters to the URL.
*
* ```
* // Navigate to /results?page=1
@ -84,8 +87,9 @@ export interface NavigationExtras {
* ```
*/
queryParams?: Params;
/**
* Sets the hash fragment for the URL
* Sets the hash fragment for the URL.
*
* ```
* // Navigate to /results#top
@ -93,8 +97,9 @@ export interface NavigationExtras {
* ```
*/
fragment?: string;
/**
* Preserves the query parameters for the next navigation
* Preserves the query parameters for the next navigation.
*
* ```
* // Preserve query params from /results?page=1 to /view?page=1
@ -112,7 +117,7 @@ export interface NavigationExtras {
*/
preserveFragment?: boolean;
/**
* Navigates without pushing a new state into history
* Navigates without pushing a new state into history.
*
* ```
* // Navigate silently to /view
@ -121,7 +126,7 @@ export interface NavigationExtras {
*/
skipLocationChange?: boolean;
/**
* Navigates while replacing the current state in history
* Navigates while replacing the current state in history.
*
* ```
* // Navigate to /view
@ -132,78 +137,131 @@ export interface NavigationExtras {
}
/**
* An event triggered when a navigation starts
* @whatItDoes Represents an event triggered when a navigation starts.
*
* @stable
*/
export class NavigationStart {
constructor(public id: number, public url: string) {}
// TODO: vsavkin: make internal
constructor(
/** @docsNotRequired */
public id: number,
/** @docsNotRequired */
public url: string) {}
/** @docsNotRequired */
toString(): string { return `NavigationStart(id: ${this.id}, url: '${this.url}')`; }
}
/**
* An event triggered when a navigation ends successfully
* @whatItDoes Represents an event triggered when a navigation ends successfully.
*
* @stable
*/
export class NavigationEnd {
constructor(public id: number, public url: string, public urlAfterRedirects: string) {}
// TODO: vsavkin: make internal
constructor(
/** @docsNotRequired */
public id: number,
/** @docsNotRequired */
public url: string,
/** @docsNotRequired */
public urlAfterRedirects: string) {}
/** @docsNotRequired */
toString(): string {
return `NavigationEnd(id: ${this.id}, url: '${this.url}', urlAfterRedirects: '${this.urlAfterRedirects}')`;
}
}
/**
* An event triggered when a navigation is canceled
* @whatItDoes Represents an event triggered when a navigation is canceled.
*
* @stable
*/
export class NavigationCancel {
constructor(public id: number, public url: string, public reason: string) {}
// TODO: vsavkin: make internal
constructor(
/** @docsNotRequired */
public id: number,
/** @docsNotRequired */
public url: string,
/** @docsNotRequired */
public reason: string) {}
/** @docsNotRequired */
toString(): string { return `NavigationCancel(id: ${this.id}, url: '${this.url}')`; }
}
/**
* An event triggered when a navigation fails due to unexpected error
* @whatItDoes Represents an event triggered when a navigation fails due to an unexpected error.
*
* @stable
*/
export class NavigationError {
constructor(public id: number, public url: string, public error: any) {}
// TODO: vsavkin: make internal
constructor(
/** @docsNotRequired */
public id: number,
/** @docsNotRequired */
public url: string,
/** @docsNotRequired */
public error: any) {}
/** @docsNotRequired */
toString(): string {
return `NavigationError(id: ${this.id}, url: '${this.url}', error: ${this.error})`;
}
}
/**
* An event triggered when routes are recognized
* @whatItDoes Represents an event triggered when routes are recognized.
*
* @stable
*/
export class RoutesRecognized {
// TODO: vsavkin: make internal
constructor(
public id: number, public url: string, public urlAfterRedirects: string,
/** @docsNotRequired */
public id: number,
/** @docsNotRequired */
public url: string,
/** @docsNotRequired */
public urlAfterRedirects: string,
/** @docsNotRequired */
public state: RouterStateSnapshot) {}
/** @docsNotRequired */
toString(): string {
return `RoutesRecognized(id: ${this.id}, url: '${this.url}', urlAfterRedirects: '${this.urlAfterRedirects}', state: ${this.state})`;
}
}
/**
* @whatItDoes Represents a router event.
*
* Please see {@link NavigationStart}, {@link NavigationEnd}, {@link NavigationCancel}, {@link
* NavigationError},
* {@link RoutesRecognized} for more information.
*
* @stable
*/
export type Event =
NavigationStart | NavigationEnd | NavigationCancel | NavigationError | RoutesRecognized;
/**
* Error handler that is invoked when a navigation errors.
* @whatItDoes Error handler that is invoked when a navigation errors.
*
* If the handler retuns a value, the navigation promise will be resolved with this value.
* @description
* 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.
*
@ -216,10 +274,12 @@ function defaultErrorHandler(error: any): any {
}
/**
* The `Router` is responsible for mapping URLs to components.
* @whatItDoes Provides the navigation and url manipulation capabilities.
*
* See {@link Routes} for more details and examples.
*
* @ngModule RouterModule
*
* @stable
*/
export class Router {
@ -230,18 +290,22 @@ export class Router {
private navigationId: number = 0;
private configLoader: RouterConfigLoader;
/**
* Error handler that is invoked when a navigation errors.
*
* See {@link ErrorHandler} for more information.
*/
errorHandler: ErrorHandler = defaultErrorHandler;
/**
* Indicates if at least one navigation happened.
*
* @stable
*/
navigated: boolean = false;
/**
* Creates the router service.
*/
// TODO: vsavkin make internal after the final is out.
constructor(
private rootComponentType: Type<any>, private urlSerializer: UrlSerializer,
private outletMap: RouterOutletMap, private location: Location, private injector: Injector,
@ -254,7 +318,7 @@ export class Router {
}
/**
* Sets up the location change listener and performs the inital navigation
* Sets up the location change listener and performs the initial navigation.
*/
initialNavigation(): void {
this.setUpLocationChangeListener();
@ -262,7 +326,7 @@ export class Router {
}
/**
* Sets up the location change listener
* Sets up the location change listener.
*/
setUpLocationChangeListener(): void {
// Zone.current.wrap is needed because of the issue with RxJS scheduler,
@ -311,6 +375,9 @@ export class Router {
this.config = config;
}
/**
* @docsNotRequired
*/
ngOnDestroy() { this.dispose(); }
/**
@ -319,8 +386,7 @@ export class Router {
dispose(): void { this.locationSubscription.unsubscribe(); }
/**
* 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 not given a route, applies the given command starting from the root.
@ -431,7 +497,7 @@ export class Router {
serializeUrl(url: UrlTree): string { return this.urlSerializer.serialize(url); }
/**
* Parse a string into a {@link UrlTree}.
* Parses a string into a {@link UrlTree}.
*/
parseUrl(url: string): UrlTree { return this.urlSerializer.parse(url); }

9
modules/@angular/router/src/router_outlet_map.ts
View File

@ -9,12 +9,21 @@
import {RouterOutlet} from './directives/router_outlet';
/**
* @whatItDoes Contains all the router outlets created in a component.
*
* @stable
*/
export class RouterOutletMap {
/** @internal */
_outlets: {[name: string]: RouterOutlet} = {};
/**
* Adds an outlet to this map.
*/
registerOutlet(name: string, outlet: RouterOutlet): void { this._outlets[name] = outlet; }
/**
* Removes an outlet from this map.
*/
removeOutlet(name: string): void { this._outlets[name] = undefined; }
}