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

docs: edit location doc (#32042)

Browse Source 
PR Close #32042
This commit is contained in:
Judy Bogart 2019-08-07 08:59:20 -07:00 committed by Kara Erickson
parent 7d4c9e4b67
commit b25f925311
1 changed files with 36 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
packages/common/src/location/location.ts
View File

@ -25,12 +25,12 @@ export interface PopStateEvent {
* *
* A service that applications can use to interact with a browser's URL. * A service that applications can use to interact with a browser's URL.
* *
* Depending on the `LocationStrategy` used, `Location` will either persist * Depending on the `LocationStrategy` used, `Location` persists
* to the URL's path or the URL's hash segment. * to the URL's path or the URL's hash segment.
* *
* @usageNotes * @usageNotes
* *
* It's better to use the {@link Router#navigate} service to trigger route changes. Use * It's better to use the `Router#navigate` service to trigger route changes. Use
* `Location` only if you need to interact with or create normalized URLs outside of * `Location` only if you need to interact with or create normalized URLs outside of
* routing. * routing.
* *
@ -77,9 +77,9 @@ export class Location {
} }
/** /**
* Returns the normalized URL path. * Normalizes the URL path for this location.
* *
* @param includeHash Whether path has an anchor fragment. * @param includeHash True to include an anchor fragment in the path.
* *
* @returns The normalized URL path. * @returns The normalized URL path.
*/ */
@ -90,17 +90,18 @@ export class Location {
} }
/** /**
* Returns the current value of the history.state object. * Reports the current state of the location history.
* @returns The current value of the `history.state` object.
*/ */
getState(): unknown { return this._platformLocation.getState(); } getState(): unknown { return this._platformLocation.getState(); }
/** /**
* Normalizes the given path and compares to the current normalized path. * Normalizes the given path and compares to the current normalized path.
* *
* @param path The given URL path * @param path The given URL path.
* @param query Query parameters * @param query Query parameters.
* *
* @returns `true` if the given URL path is equal to the current normalized path, `false` * @returns True if the given URL path is equal to the current normalized path, false
* otherwise. * otherwise.
*/ */
isCurrentPathEqualTo(path: string, query: string = ''): boolean { isCurrentPathEqualTo(path: string, query: string = ''): boolean {
@ -108,23 +109,21 @@ export class Location {
} }
/** /**
* Given a string representing a URL, returns the URL path after stripping the * Normalizes a URL path by stripping any trailing slashes.
* trailing slashes.
* *
* @param url String representing a URL. * @param url String representing a URL.
* *
* @returns Normalized URL string. * @returns The normalized URL string.
*/ */
normalize(url: string): string { normalize(url: string): string {
return Location.stripTrailingSlash(_stripBaseHref(this._baseHref, _stripIndexHtml(url))); return Location.stripTrailingSlash(_stripBaseHref(this._baseHref, _stripIndexHtml(url)));
} }
/** /**
* Given a string representing a URL, returns the platform-specific external URL path. * Normalizes an external URL path.
* If the given URL doesn't begin with a leading slash (`'/'`), this method adds one * If the given URL doesn't begin with a leading slash (`'/'`), adds one
* before normalizing. This method also adds a hash if `HashLocationStrategy` is * before normalizing. Adds a hash if `HashLocationStrategy` is
* used, or the `APP_BASE_HREF` if the `PathLocationStrategy` is in use. * in use, or the `APP_BASE_HREF` if the `PathLocationStrategy` is in use.
*
* *
* @param url String representing a URL. * @param url String representing a URL.
* *
@ -139,12 +138,12 @@ export class Location {
// TODO: rename this method to pushState // TODO: rename this method to pushState
/** /**
* Changes the browsers URL to a normalized version of the given URL, and pushes a * Changes the browser's URL to a normalized version of a given URL, and pushes a
* new item onto the platform's history. * new item onto the platform's history.
* *
* @param path URL path to normalizze * @param path URL path to normalize.
* @param query Query parameters * @param query Query parameters.
* @param state Location history state * @param state Location history state.
* *
*/ */
go(path: string, query: string = '', state: any = null): void { go(path: string, query: string = '', state: any = null): void {
@ -157,9 +156,9 @@ export class Location {
* Changes the browser's URL to a normalized version of the given URL, and replaces * Changes the browser's URL to a normalized version of the given URL, and replaces
* the top item on the platform's history stack. * the top item on the platform's history stack.
* *
* @param path URL path to normalizze * @param path URL path to normalize.
* @param query Query parameters * @param query Query parameters.
* @param state Location history state * @param state Location history state.
*/ */
replaceState(path: string, query: string = '', state: any = null): void { replaceState(path: string, query: string = '', state: any = null): void {
this._platformStrategy.replaceState(state, '', path, query); this._platformStrategy.replaceState(state, '', path, query);
@ -178,8 +177,10 @@ export class Location {
back(): void { this._platformStrategy.back(); } back(): void { this._platformStrategy.back(); }
/** /**
* Register URL change listeners. This API can be used to catch updates performed by the Angular * Registers a URL change listener. Use to catch updates performed by the Angular
* framework. These are not detectible through "popstate" or "hashchange" events. * framework that are not detectible through "popstate" or "hashchange" events.
*
* @param fn The change handler function, which take a URL and a location history state.
*/ */
onUrlChange(fn: (url: string, state: unknown) => void) { onUrlChange(fn: (url: string, state: unknown) => void) {
this._urlChangeListeners.push(fn); this._urlChangeListeners.push(fn);
@ -192,7 +193,7 @@ export class Location {
} }
/** /**
* Subscribe to the platform's `popState` events. * Subscribes to the platform's `popState` events.
* *
* @param value Event that is triggered when the state history changes. * @param value Event that is triggered when the state history changes.
* @param exception The exception to throw. * @param exception The exception to throw.
@ -206,25 +207,24 @@ export class Location {
} }
/** /**
* Given a string of url parameters, prepend with `?` if needed, otherwise return the * Normalizes URL parameters by prepending with `?` if needed.
* parameters as is.
* *
* @param params String of URL parameters * @param params String of URL parameters.
* *
* @returns URL parameters prepended with `?` or the parameters as is. * @returns The normalized URL parameters string.
*/ */
public static normalizeQueryParams(params: string): string { public static normalizeQueryParams(params: string): string {
return params && params[0] !== '?' ? '?' + params : params; return params && params[0] !== '?' ? '?' + params : params;
} }
/** /**
* Given 2 parts of a URL, join them with a slash if needed. * Joins two parts of a URL with a slash if needed.
* *
* @param start URL string * @param start URL string
* @param end URL string * @param end URL string
* *
* *
* @returns Given URL strings joined with a slash, if needed. * @returns The joined URL string.
*/ */
public static joinWithSlash(start: string, end: string): string { public static joinWithSlash(start: string, end: string): string {
if (start.length == 0) { if (start.length == 0) {
@ -250,14 +250,13 @@ export class Location {
} }
/** /**
* If URL has a trailing slash, remove it, otherwise return the URL as is. The * Removes a trailing slash from a URL string if needed.
* method looks for the first occurrence of either `#`, `?`, or the end of the * Looks for the first occurrence of either `#`, `?`, or the end of the
* line as `/` characters and removes the trailing slash if one exists. * line as `/` characters and removes the trailing slash if one exists.
* *
* @param url URL string * @param url URL string.
* *
* @returns Returns a URL string after removing the trailing slash if one exists, otherwise * @returns The URL string, modified if needed.
* returns the string as is.
*/ */
public static stripTrailingSlash(url: string): string { public static stripTrailingSlash(url: string): string {
const match = url.match(/#|\?|$/); const match = url.match(/#|\?|$/);