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

docs: http api doc edit (#31613) 

PR Close #31613
This commit is contained in:
Judy Bogart 2019-07-16 17:25:53 -07:00 committed by Misko Hevery
parent 59c3700c8c
commit 27997a16c0
6 changed files with 105 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
packages/common/http/src/client.ts
View File

@ -47,14 +47,10 @@ export type HttpObserve = 'body' | 'events' | 'response';
/**
* Performs HTTP requests.
*
* `HttpClient` is available as an injectable class, with methods to perform HTTP requests.
* This service is available as an injectable class, with methods to perform HTTP requests.
* Each request method has multiple signatures, and the return type varies based on
* the signature that is called (mainly the values of `observe` and `responseType`).
*
*
* @see [HTTP Guide](guide/http)
*
*
* @usageNotes
* Sample HTTP requests for the [Tour of Heroes](/tutorial/toh-pt0) application.
*
@ -75,7 +71,6 @@ export type HttpObserve = 'body' | 'events' | 'response';
* }
* ```
*
*
* ### PATCH Example
* ```
* // PATCH one of the heroes' name
@ -86,6 +81,8 @@ export type HttpObserve = 'body' | 'events' | 'response';
* }
* ```
*
* @see [HTTP Guide](guide/http)
*
* @publicApi
*/
@Injectable()

12
packages/common/http/src/headers.ts
View File

@ -13,7 +13,8 @@ interface Update {
}
/**
* `HttpHeaders` class represents the header configuration options for an HTTP request.
* Represents the header configuration options for an HTTP request.
*
* Instances should be assumed immutable with lazy parsing.
*
* @publicApi
@ -35,7 +36,6 @@ export class HttpHeaders {
/**
* Complete the lazy initialization of this object (needed before reading).
*/
// TODO(issue/24571): remove '!'.
private lazyInit !: HttpHeaders | Function | null;
/**
@ -98,7 +98,7 @@ export class HttpHeaders {
}
/**
* Returns the first header value that matches a given name.
* Retrieves the first header value that matches a given name.
*
* @param name The header name to retrieve.
*
@ -112,7 +112,7 @@ export class HttpHeaders {
}
/**
* Returns the names of the headers.
* Retrieves the names of the headers.
*
* @returns A list of header names.
*/
@ -123,7 +123,7 @@ export class HttpHeaders {
}
/**
* Returns a list of header values for a given header name.
* Retrieves a list of header values for a given header name.
*
* @param name The header name from which to retrieve the values.
*
@ -152,7 +152,7 @@ export class HttpHeaders {
* its value is replaced with the given value.
*
* @param name The header name.
* @param value Provides the value to set or overide for a given name.
* @param value The value to set or overide for a given name.
*
* @returns A clone of the HTTP header object with the newly set header value.
*/

14
packages/common/http/src/interceptor.ts
View File

@ -14,7 +14,7 @@ import {HttpRequest} from './request';
import {HttpEvent} from './response';
/**
* Intercepts `HttpRequest` or `HttpResponse` and handles them.
* Intercepts and handles an `HttpRequest` or `HttpResponse`.
*
* Most interceptors transform the outgoing request before passing it to the
* next interceptor in the chain, by calling `next.handle(transformedReq)`.
@ -44,9 +44,11 @@ import {HttpEvent} from './response';
*/
export interface HttpInterceptor {
/**
* * **req**: The outgoing request to handle
* * **next**: The next interceptor in the chain, or the backend if no interceptors in the chain.
*
* Identifies and handles a given HTTP request.
* @param req The outgoing request object to handle.
* @param next The next interceptor in the chain, or the backend
* if no interceptors remain in the chain.
* @returns An observable of the event stream.
*/
intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>>;
}
@ -65,8 +67,8 @@ export class HttpInterceptorHandler implements HttpHandler {
}
/**
* A multi-provider token which represents the array of `HttpInterceptor`s that
* are registered.
* A multi-provider token that represents the array of registered
* `HttpInterceptor` objects.
*
* @publicApi
*/

20
packages/common/http/src/jsonp.ts
View File

@ -39,8 +39,10 @@ export const JSONP_ERR_WRONG_RESPONSE_TYPE = 'JSONP requests must use Json respo
export abstract class JsonpCallbackContext { [key: string]: (data: any) => void; }
/**
* `HttpBackend` that only processes `HttpRequest` with the JSONP method,
* Processes an `HttpRequest` with the JSONP method,
* by performing JSONP style requests.
* @see `HttpHandler`
* @see `HttpXhrBackend`
*
* @publicApi
*/
@ -54,7 +56,10 @@ export class JsonpClientBackend implements HttpBackend {
private nextCallback(): string { return `ng_jsonp_callback_${nextRequestId++}`; }
/**
* Process a JSONP request and return an event stream of the results.
* Processes a JSONP request and returns an event stream of the results.
* @param req The request object.
* @returns An observable of the response events.
*
*/
handle(req: HttpRequest<never>): Observable<HttpEvent<any>> {
// Firstly, check both the method and response type. If either doesn't match
@ -203,15 +208,24 @@ export class JsonpClientBackend implements HttpBackend {
}
/**
* An `HttpInterceptor` which identifies requests with the method JSONP and
* Identifies requests with the method JSONP and
* shifts them to the `JsonpClientBackend`.
*
* @see `HttpInterceptor`
*
* @publicApi
*/
@Injectable()
export class JsonpInterceptor {
constructor(private jsonp: JsonpClientBackend) {}
/**
* Identifies and handles a given JSONP request.
* @param req The outgoing request object to handle.
* @param next The next interceptor in the chain, or the backend
* if no interceptors remain in the chain.
* @returns An observable of the event stream.
*/
intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
if (req.method === 'JSONP') {
return this.jsonp.handle(req as HttpRequest<never>);

83
packages/common/http/src/params.ts
View File

@ -22,20 +22,42 @@ export interface HttpParameterCodec {
}
/**
* A class that uses `encodeURIComponent` and `decodeURIComponent` to
* serialize and parse URL parameter keys and values. If you pass URL query parameters
* without encoding, the query parameters can get misinterpreted at the receiving end.
* Use the `HttpParameterCodec` class to encode and decode the query-string values.
* Provides encoding and decoding of URL parameter and query-string values.
*
* Serializes and parses URL parameter keys and values to encode and decode them.
* If you pass URL query parameters without encoding,
* the query parameters can be misinterpreted at the receiving end.
*
*
* @publicApi
*/
export class HttpUrlEncodingCodec implements HttpParameterCodec {
/**
* Encodes a key name for a URL parameter or query-string.
* @param key The key name.
* @returns The encoded key name.
*/
encodeKey(key: string): string { return standardEncoding(key); }
/**
* Encodes the value of a URL parameter or query-string.
* @param value The value.
* @returns The encoded value.
*/
encodeValue(value: string): string { return standardEncoding(value); }
/**
* Decodes an encoded URL parameter or query-string key.
* @param key The encoded key name.
* @returns The decoded key name.
*/
decodeKey(key: string): string { return decodeURIComponent(key); }
/**
* Decodes an encoded URL parameter or query-string value.
* @param value The encoded value.
* @returns The decoded value.
*/
decodeValue(value: string) { return decodeURIComponent(value); }
}
@ -75,18 +97,21 @@ interface Update {
op: 'a'|'d'|'s';
}
/** Options used to construct an `HttpParams` instance. */
/** Options used to construct an `HttpParams` instance.
*
* @publicApi
*/
export interface HttpParamsOptions {
/**
* String representation of the HTTP params in URL-query-string format. Mutually exclusive with
* `fromObject`.
* String representation of the HTTP parameters in URL-query-string format.
* Mutually exclusive with `fromObject`.
*/
fromString?: string;
/** Object map of the HTTP params. Mutually exclusive with `fromString`. */
/** Object map of the HTTP parameters. Mutually exclusive with `fromString`. */
fromObject?: {[param: string]: string | string[]};
/** Encoding codec used to parse and serialize the params. */
/** Encoding codec used to parse and serialize the parameters. */
encoder?: HttpParameterCodec;
}
@ -94,7 +119,7 @@ export interface HttpParamsOptions {
* An HTTP request/response body that represents serialized parameters,
* per the MIME type `application/x-www-form-urlencoded`.
*
* This class is immutable - all mutation operations return a new instance.
* This class is immutable; all mutation operations return a new instance.
*
* @publicApi
*/
@ -123,7 +148,10 @@ export class HttpParams {
}
/**
* Check whether the body has one or more values for the given parameter name.
* Reports whether the body includes one or more values for a given parameter.
* @param param The parameter name.
* @returns True if the parameter has one or more values,
* false if it has no value or is not present.
*/
has(param: string): boolean {
this.init();
@ -131,7 +159,10 @@ export class HttpParams {
}
/**
* Get the first value for the given parameter name, or `null` if it's not present.
* Retrieves the first value for a parameter.
* @param param The parameter name.
* @returns The first value of the given parameter,
* or `null` if the parameter is not present.
*/
get(param: string): string|null {
this.init();
@ -140,7 +171,10 @@ export class HttpParams {
}
/**
* Get all values for the given parameter name, or `null` if it's not present.
* Retrieves all values for a parameter.
* @param param The parameter name.
* @returns All values in a string array,
* or `null` if the parameter not present.
*/
getAll(param: string): string[]|null {
this.init();
@ -148,7 +182,8 @@ export class HttpParams {
}
/**
* Get all the parameter names for this body.
* Retrieves all the parameters for this body.
* @returns The parameter names in a string array.
*/
keys(): string[] {
this.init();
@ -156,24 +191,32 @@ export class HttpParams {
}
/**
* Construct a new body with an appended value for the given parameter name.
* Appends a new value to existing values for a parameter.
* @param param The parameter name.
* @param value The new value to add.
* @return A new body with the appended value.
*/
append(param: string, value: string): HttpParams { return this.clone({param, value, op: 'a'}); }
/**
* Construct a new body with a new value for the given parameter name.
* Replaces the value for a parameter.
* @param param The parameter name.
* @param value The new value.
* @return A new body with the new value.
*/
set(param: string, value: string): HttpParams { return this.clone({param, value, op: 's'}); }
/**
* Construct a new body with either the given value for the given parameter
* removed, if a value is given, or all values for the given parameter removed
* if not.
* Removes a given value or all values from a parameter.
* @param param The parameter name.
* @param value The value to remove, if provided.
* @return A new body with the given value removed, or with all values
* removed if no value is specified.
*/
delete (param: string, value?: string): HttpParams { return this.clone({param, value, op: 'd'}); }
/**
* Serialize the body to an encoded string, where key-value pairs (separated by `=`) are
* Serializes the body to an encoded string, where key-value pairs (separated by `=`) are
* separated by `&`s.
*/
toString(): string {

12
packages/common/http/src/xhr.ts
View File

@ -38,8 +38,7 @@ function getResponseUrl(xhr: any): string|null {
export abstract class XhrFactory { abstract build(): XMLHttpRequest; }
/**
* A factory for @{link HttpXhrBackend} that uses the `XMLHttpRequest` browser API.
*
* A factory for `HttpXhrBackend` that uses the `XMLHttpRequest` browser API.
*
*/
@Injectable()
@ -59,8 +58,9 @@ interface PartialResponse {
}
/**
* An `HttpBackend` which uses the XMLHttpRequest API to send
* requests to a backend server.
* Uses `XMLHttpRequest` to send requests to a backend server.
* @see `HttpHandler`
* @see `JsonpClientBackend`
*
* @publicApi
*/
@ -69,7 +69,9 @@ export class HttpXhrBackend implements HttpBackend {
constructor(private xhrFactory: XhrFactory) {}
/**
* Process a request and return a stream of response events.
* Processes a request and returns a stream of response events.
* @param req The request object.
* @returns An observable of the response events.
*/
handle(req: HttpRequest<any>): Observable<HttpEvent<any>> {
// Quick check to give a better error message when a user attempts to use