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

docs(common): update API docs for unified location service for upgrading (#30567) 

PR Close #30567
This commit is contained in:
Brandon 2019-05-20 12:54:26 -05:00 committed by Jason Aden
parent 697046c2b2
commit 0d52a27f41
3 changed files with 130 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
packages/common/upgrade/src/location_shim.ts
View File

@ -22,7 +22,10 @@ const DEFAULT_PORTS: {[key: string]: number} = {
};
/**
* Docs TBD.
* Location service that provides a drop-in replacement for the $location service
* provided in AngularJS.
*
* @see [Using the Angular Unified Location Service](guide/upgrade#using-the-unified-angular-location-service)
*
* @publicApi
*/
@ -321,12 +324,17 @@ export class $locationShim {
}
/**
* Register URL change listeners. This API can be used to catch updates performed by the
* AngularJS framework. These changes are a subset of the `$locationChangeStart/Success` events
* as those events fire when AngularJS updates it's internally referenced version of the browser
* URL. It's possible for `$locationChange` events to happen, but for the browser URL
* Registers listeners for URL changes. This API is used to catch updates performed by the
* AngularJS framework. These changes are a subset of the `$locationChangeStart` and
* `$locationChangeSuccess` events which fire when AngularJS updates its internally-referenced
* version of the browser URL.
*
* It's possible for `$locationChange` events to happen, but for the browser URL
* (window.location) to remain unchanged. This `onChange` callback will fire only when AngularJS
* actually updates the browser URL (window.location).
*
* @param fn The callback function that is triggered for the listener when the URL changes.
* @param err The callback function that is triggered when an error occurs.
*/
onChange(
fn: (url: string, state: unknown, oldUrl: string, oldState: unknown) => void,
@ -346,6 +354,11 @@ export class $locationShim {
});
}
/**
* Parses the provided URL, and sets the current URL to the parsed result.
*
* @param url The URL string.
*/
$$parse(url: string) {
let pathUrl: string|undefined;
if (url.startsWith('/')) {
@ -366,6 +379,12 @@ export class $locationShim {
this.composeUrls();
}
/**
* Parses the provided URL and its relative URL.
*
* @param url The full URL string.
* @param relHref A URL string relative to the full URL string.
*/
$$parseLinkUrl(url: string, relHref?: string|null): boolean {
// When relHref is passed, it should be a hash and is handled separately
if (relHref && relHref[0] === '#') {
@ -413,9 +432,8 @@ export class $locationShim {
}
/**
* This method is getter only.
*
* Return full URL representation with all segments encoded according to rules specified in
* Retrieves the full URL representation with all segments encoded according to
* rules specified in
* [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt).
*
*
@ -428,12 +446,8 @@ export class $locationShim {
absUrl(): string { return this.$$absUrl; }
/**
* This method is getter / setter.
*
* Return URL (e.g. `/path?a=b#hash`) when called without any parameter.
*
* Change path, search and hash, when called with parameter and return `$location`.
*
* Retrieves the current URL, or sets a new URL. When setting a URL,
* changes the path, search, and hash, and returns a reference to its own instance.
*
* ```js
* // given URL http://example.com/#/some/path?foo=bar&baz=xoxo
@ -463,10 +477,7 @@ export class $locationShim {
}
/**
* This method is getter only.
*
* Return protocol of current URL.
*
* Retrieves the protocol of the current URL.
*
* ```js
* // given URL http://example.com/#/some/path?foo=bar&baz=xoxo
@ -477,11 +488,9 @@ export class $locationShim {
protocol(): string { return this.$$protocol; }
/**
* This method is getter only.
* Retrieves the protocol of the current URL.
*
* Return host of current URL.
*
* Note: compared to the non-AngularJS version `location.host` which returns `hostname:port`, this
* In contrast to the non-AngularJS version `location.host` which returns `hostname:port`, this
* returns the `hostname` portion only.
*
*
@ -500,10 +509,7 @@ export class $locationShim {
host(): string { return this.$$host; }
/**
* This method is getter only.
*
* Return port of current URL.
*
* Retrieves the port of the current URL.
*
* ```js
* // given URL http://example.com/#/some/path?foo=bar&baz=xoxo
@ -514,16 +520,12 @@ export class $locationShim {
port(): number|null { return this.$$port; }
/**
* This method is getter / setter.
* Retrieves the path of the current URL, or changes the path and returns a reference to its own
* instance.
*
* Return path of current URL when called without any parameter.
*
* Change path when called with parameter and return `$location`.
*
* Note: Path should always begin with forward slash (/), this method will add the forward slash
* Paths should always begin with forward slash (/). This method adds the forward slash
* if it is missing.
*
*
* ```js
* // given URL http://example.com/#/some/path?foo=bar&baz=xoxo
* let path = $location.path();
@ -548,11 +550,8 @@ export class $locationShim {
}
/**
* This method is getter / setter.
*
* Return search part (as object) of current URL when called without any parameter.
*
* Change search part when called with parameter and return `$location`.
* Retrieves a map of the search parameters of the current URL, or changes a search
* part and returns a reference to its own instance.
*
*
* ```js
@ -585,8 +584,7 @@ export class $locationShim {
* If `paramValue` is `true`, the property specified via the first argument will be added with no
* value nor trailing equal sign.
*
* @return {Object} If called with no arguments returns the parsed `search` object. If called with
* one or more arguments returns `$location` object itself.
* @return {Object} The parsed `search` object of the current URL, or the changed `search` object.
*/
search(): {[key: string]: unknown};
search(search: string|number|{[key: string]: unknown}): this;
@ -633,12 +631,8 @@ export class $locationShim {
}
/**
* This method is getter / setter.
*
* Returns the hash fragment when called without any parameters.
*
* Changes the hash fragment when called with a parameter and returns `$location`.
*
* Retrieves the current hash fragment, or changes the hash fragment and returns a reference to
* its own instance.
*
* ```js
* // given URL http://example.com/#/some/path?foo=bar&baz=xoxo#hashValue
@ -660,7 +654,7 @@ export class $locationShim {
}
/**
* If called, all changes to $location during the current `$digest` will replace the current
* Changes to `$location` during the current `$digest` will replace the current
* history record, instead of adding a new one.
*/
replace(): this {
@ -669,15 +663,13 @@ export class $locationShim {
}
/**
* This method is getter / setter.
*
* Return the history state object when called without any parameter.
* Retrieves the history state object when called without any parameter.
*
* Change the history state object when called with one parameter and return `$location`.
* The state object is later passed to `pushState` or `replaceState`.
*
* NOTE: This method is supported only in HTML5 mode and only in browsers supporting
* the HTML5 History API (i.e. methods `pushState` and `replaceState`). If you need to support
* This method is supported only in HTML5 mode and only in browsers supporting
* the HTML5 History API methods such as `pushState` and `replaceState`. If you need to support
* older browsers (like IE9 or Android < 4.0), don't use this method.
*
*/
@ -694,7 +686,8 @@ export class $locationShim {
}
/**
* Docs TBD.
* The factory function used to create an instance of the `$locationShim` in Angular,
* and provides an API-compatiable `$locationProvider` for AngularJS.
*
* @publicApi
*/
@ -704,6 +697,9 @@ export class $locationShimProvider {
private platformLocation: PlatformLocation, private urlCodec: UrlCodec,
private locationStrategy: LocationStrategy) {}
/**
* Factory method that returns an instance of the $locationShim
*/
$get() {
return new $locationShim(
this.ngUpgrade.$injector, this.location, this.platformLocation, this.urlCodec,

22
packages/common/upgrade/src/location_upgrade_module.ts
View File

@ -20,15 +20,31 @@ import {AngularJSUrlCodec, UrlCodec} from './params';
* @publicApi
*/
export interface LocationUpgradeConfig {
/**
* Configures whether the location upgrade module should use the `HashLocationStrategy`
* or the `PathLocationStrategy`
*/
useHash?: boolean;
/**
* Configures the hash prefix used in the URL when using the `HashLocationStrategy`
*/
hashPrefix?: string;
/**
* Configures the URL codec for encoding and decoding URLs. Default is the `AngularJSCodec`
*/
urlCodec?: typeof UrlCodec;
/**
* Configures the base href when used in server-side rendered applications
*/
serverBaseHref?: string;
/**
* Configures the base href when used in client-side rendered applications
*/
appBaseHref?: string;
}
/**
* Is used in DI to configure the location upgrade package.
* A provider token used to configure the location upgrade module.
*
* @publicApi
*/
@ -38,7 +54,9 @@ export const LOCATION_UPGRADE_CONFIGURATION =
const APP_BASE_HREF_RESOLVED = new InjectionToken<string>('APP_BASE_HREF_RESOLVED');
/**
* Module used for configuring Angular's LocationUpgradeService.
* `NgModule` used for providing and configuring Angular's Unified Location Service for upgrading.
*
* @see [Using the Unified Angular Location Service](guide/upgrade#using-the-unified-angular-location-service)
*
* @publicApi
*/

63
packages/common/upgrade/src/params.ts
View File

@ -12,21 +12,80 @@
* @publicApi
**/
export abstract class UrlCodec {
/**
* Encodes the path from the provided string
*
* @param path The path string
*/
abstract encodePath(path: string): string;
/**
* Decodes the path from the provided string
*
* @param path The path string
*/
abstract decodePath(path: string): string;
/**
* Encodes the search string from the provided string or object
*
* @param path The path string or object
*/
abstract encodeSearch(search: string|{[k: string]: unknown}): string;
/**
* Decodes the search objects from the provided string
*
* @param path The path string
*/
abstract decodeSearch(search: string): {[k: string]: unknown};
/**
* Encodes the hash from the provided string
*
* @param path The hash string
*/
abstract encodeHash(hash: string): string;
/**
* Decodes the hash from the provided string
*
* @param path The hash string
*/
abstract decodeHash(hash: string): string;
/**
* Normalizes the URL from the provided string
*
* @param path The URL string
*/
abstract normalize(href: string): string;
/**
* Normalizes the URL from the provided string, search, hash, and base URL parameters
*
* @param path The URL path
* @param search The search object
* @param hash The has string
* @param baseUrl The base URL for the URL
*/
abstract normalize(path: string, search: {[k: string]: unknown}, hash: string, baseUrl?: string):
string;
/**
* Checks whether the two strings are equal
* @param valA First string for comparison
* @param valB Second string for comparison
*/
abstract areEqual(valA: string, valB: string): boolean;
/**
* Parses the URL string based on the base URL
*
* @param url The full URL string
* @param base The base for the URL
*/
abstract parse(url: string, base?: string): {
href: string,
protocol: string,
@ -40,8 +99,8 @@ export abstract class UrlCodec {
}
/**
* A `AngularJSUrlCodec` that uses logic from AngularJS to serialize and parse URLs
* and URL parameters
* A `UrlCodec` that uses logic from AngularJS to serialize and parse URLs
* and URL parameters.
*
* @publicApi
*/