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; declare var Zone: any;
/** /**
* @whatItDoes Represents the extra options used during navigation.
*
* @stable * @stable
*/ */
export interface NavigationExtras { 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({...}) * @Component({...})
@ -75,8 +77,9 @@ export interface NavigationExtras {
* ``` * ```
*/ */
relativeTo?: ActivatedRoute; relativeTo?: ActivatedRoute;
/** /**
* Sets query parameters to the URL * Sets query parameters to the URL.
* *
* ``` * ```
* // Navigate to /results?page=1 * // Navigate to /results?page=1
@ -84,8 +87,9 @@ export interface NavigationExtras {
* ``` * ```
*/ */
queryParams?: Params; queryParams?: Params;
/** /**
* Sets the hash fragment for the URL * Sets the hash fragment for the URL.
* *
* ``` * ```
* // Navigate to /results#top * // Navigate to /results#top
@ -93,8 +97,9 @@ export interface NavigationExtras {
* ``` * ```
*/ */
fragment?: string; 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 * // Preserve query params from /results?page=1 to /view?page=1
@ -112,7 +117,7 @@ export interface NavigationExtras {
*/ */
preserveFragment?: boolean; preserveFragment?: boolean;
/** /**
* Navigates without pushing a new state into history * Navigates without pushing a new state into history.
* *
* ``` * ```
* // Navigate silently to /view * // Navigate silently to /view
@ -121,7 +126,7 @@ export interface NavigationExtras {
*/ */
skipLocationChange?: boolean; skipLocationChange?: boolean;
/** /**
* Navigates while replacing the current state in history * Navigates while replacing the current state in history.
* *
* ``` * ```
* // Navigate to /view * // 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 * @stable
*/ */
export class NavigationStart { 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}')`; } 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 * @stable
*/ */
export class NavigationEnd { 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 { toString(): string {
return `NavigationEnd(id: ${this.id}, url: '${this.url}', urlAfterRedirects: '${this.urlAfterRedirects}')`; 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 * @stable
*/ */
export class NavigationCancel { 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}')`; } 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 * @stable
*/ */
export class NavigationError { 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 { toString(): string {
return `NavigationError(id: ${this.id}, url: '${this.url}', error: ${this.error})`; 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 * @stable
*/ */
export class RoutesRecognized { export class RoutesRecognized {
// TODO: vsavkin: make internal
constructor( 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) {} public state: RouterStateSnapshot) {}
/** @docsNotRequired */
toString(): string { toString(): string {
return `RoutesRecognized(id: ${this.id}, url: '${this.url}', urlAfterRedirects: '${this.urlAfterRedirects}', state: ${this.state})`; 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 * @stable
*/ */
export type Event = export type Event =
NavigationStart | NavigationEnd | NavigationCancel | NavigationError | RoutesRecognized; 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 * If the handler throws an exception, the navigation promise will be rejected with
* the exception. * 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. * See {@link Routes} for more details and examples.
* *
* @ngModule RouterModule
*
* @stable * @stable
*/ */
export class Router { export class Router {
@ -230,18 +290,22 @@ export class Router {
private navigationId: number = 0; private navigationId: number = 0;
private configLoader: RouterConfigLoader; private configLoader: RouterConfigLoader;
/**
* Error handler that is invoked when a navigation errors.
*
* See {@link ErrorHandler} for more information.
*/
errorHandler: ErrorHandler = defaultErrorHandler; errorHandler: ErrorHandler = defaultErrorHandler;
/** /**
* Indicates if at least one navigation happened. * Indicates if at least one navigation happened.
*
* @stable
*/ */
navigated: boolean = false; navigated: boolean = false;
/** /**
* Creates the router service. * Creates the router service.
*/ */
// TODO: vsavkin make internal after the final is out.
constructor( constructor(
private rootComponentType: Type<any>, private urlSerializer: UrlSerializer, private rootComponentType: Type<any>, private urlSerializer: UrlSerializer,
private outletMap: RouterOutletMap, private location: Location, private injector: Injector, 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 { initialNavigation(): void {
this.setUpLocationChangeListener(); this.setUpLocationChangeListener();
@ -262,7 +326,7 @@ export class Router {
} }
/** /**
* Sets up the location change listener * Sets up the location change listener.
*/ */
setUpLocationChangeListener(): void { setUpLocationChangeListener(): void {
// Zone.current.wrap is needed because of the issue with RxJS scheduler, // Zone.current.wrap is needed because of the issue with RxJS scheduler,
@ -311,6 +375,9 @@ export class Router {
this.config = config; this.config = config;
} }
/**
* @docsNotRequired
*/
ngOnDestroy() { this.dispose(); } ngOnDestroy() { this.dispose(); }
/** /**
@ -319,8 +386,7 @@ export class Router {
dispose(): void { this.locationSubscription.unsubscribe(); } dispose(): void { this.locationSubscription.unsubscribe(); }
/** /**
* Applies an array of commands to the current url tree and creates * Applies an array of commands to the current url tree and creates a new url tree.
* 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. * 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); } 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); } 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'; import {RouterOutlet} from './directives/router_outlet';
/** /**
* @whatItDoes Contains all the router outlets created in a component.
*
* @stable * @stable
*/ */
export class RouterOutletMap { export class RouterOutletMap {
/** @internal */ /** @internal */
_outlets: {[name: string]: RouterOutlet} = {}; _outlets: {[name: string]: RouterOutlet} = {};
/**
* Adds an outlet to this map.
*/
registerOutlet(name: string, outlet: RouterOutlet): void { this._outlets[name] = outlet; } registerOutlet(name: string, outlet: RouterOutlet): void { this._outlets[name] = outlet; }
/**
* Removes an outlet from this map.
*/
removeOutlet(name: string): void { this._outlets[name] = undefined; } removeOutlet(name: string): void { this._outlets[name] = undefined; }
} }