docs: minor fixes (anchor tags, redundant whitespace, consistent code-snippets lang) (#21589)
PR Close #21589
This commit is contained in:
George Kalpakas
Miško Hevery
parent
1ce46b56f8
commit
bf248792eb
|
|
@ -78,172 +78,172 @@ With no templates to read and no risky client-side HTML or JavaScript evaluation
|
|||
there are fewer opportunities for injection attacks.
|
||||
|
||||
{@a compiler-options}
|
||||
|
||||
## Angular Compiler Options
|
||||
|
||||
You can control your app compilation by providing template compiler options in the `tsconfig.json` file along with the options supplied to the TypeScript compiler. The template compiler options are specified as members of
|
||||
`"angularCompilerOptions"` object as shown below:
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"experimentalDecorators": true,
|
||||
...
|
||||
},
|
||||
"angularCompilerOptions": {
|
||||
"fullTemplateTypeCheck": true,
|
||||
"preserveWhiteSpace": false,
|
||||
...
|
||||
}
|
||||
|
||||
## Angular Compiler Options
|
||||
|
||||
You can control your app compilation by providing template compiler options in the `tsconfig.json` file along with the options supplied to the TypeScript compiler. The template compiler options are specified as members of
|
||||
`"angularCompilerOptions"` object as shown below:
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"experimentalDecorators": true,
|
||||
...
|
||||
},
|
||||
"angularCompilerOptions": {
|
||||
"fullTemplateTypeCheck": true,
|
||||
"preserveWhiteSpace": false,
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
### *skipMetadataEmit*
|
||||
}
|
||||
```
|
||||
|
||||
This option tells the compiler not to produce `.metadata.json` files.
|
||||
The option is `false` by default.
|
||||
|
||||
`.metadata.json` files contain infomration needed by the template compiler from a `.ts`
|
||||
file that is not included in the `.d.ts` file produced by the TypeScript compiler. This information contains,
|
||||
for example, the content of annotations (such as a component's template) which TypeScript
|
||||
emits to the `.js` file but not to the `.d.ts` file.
|
||||
|
||||
This option should be set to `true` if using TypeScript's `--outFile` option, as the metadata files
|
||||
are not valid for this style of TypeScript output. It is not recommeded to use `--outFile` with
|
||||
Angular. Use a bundler, such as [webpack](https://webpack.js.org/), instead.
|
||||
|
||||
This option can also be set to `true` when using factory summaries as the factory summaries
|
||||
include a copy of the information that is in the `.metadata.json` file.
|
||||
|
||||
### *strictMetadataEmit*
|
||||
|
||||
This option tells the template compiler to report an error to the `.metadata.json`
|
||||
file if `"skipMetadataEmit"` is `false` . This option is `false` by default. This should only be used when `"skipMetadataEmit"` is `false` and `"skipTemplateCodeGen"` is `true`.
|
||||
|
||||
It is intended to validate the `.metadata.json` files emitted for bundling with an `npm` package. The validation is overly strict and can emit errors for metadata that would never produce an error when used by the template compiler. You can choose to suppress the error emitted by this option for an exported symbol by including `@dynamic` in the comment documenting the symbol.
|
||||
|
||||
It is valid for `.metadata.json` files to contain errors. The template compiler reports these errors
|
||||
if the metadata is used to determine the contents of an annotation. The metadata
|
||||
collector cannot predict the symbols that are designed to use in an annotation, so it will preemptively
|
||||
include error nodes in the metadata for the exported symbols. The template compiler can then use the error
|
||||
nodes to report an error if these symbols are used. If the client of a library intends to use a symbol in an annotation, the template compiler will not normally report
|
||||
this until the client uses the symbol. This option allows detecting these errors during the build phase of
|
||||
the library and is used, for example, in producing Angular libraries themselves.
|
||||
|
||||
### *skipTemplateCodegen*
|
||||
|
||||
This option tells the compiler to suppress emitting `.ngfactory.js` and `.ngstyle.js` files. When set,
|
||||
this turns off most of the template compiler and disables reporting template diagnostics.
|
||||
This option can be used to instruct the
|
||||
template compiler to produce `.metadata.json` files for distribution with an `npm` package while
|
||||
avoiding the production of `.ngfactory.js` and `.ngstyle.js` files that cannot be distributed to
|
||||
`npm`.
|
||||
|
||||
### *strictInjectionParameters*
|
||||
|
||||
When set to `true`, this options tells the compiler to report an error for a parameter supplied
|
||||
whose injection type cannot be determined. When this value option is not provided or is `false`, constructor parameters of classes marked with `@Injectable` whose type cannot be resolved will
|
||||
produce a warning.
|
||||
### *skipMetadataEmit*
|
||||
|
||||
*Note*: It is recommended to change this option explicitly to `true` as this option will default to `true` in the future.
|
||||
|
||||
### *flatModuleOutFile*
|
||||
|
||||
When set to `true`, this option tells the template compiler to generate a flat module
|
||||
index of the given file name and the corresponding flat module metadata. Use this option when creating
|
||||
flat modules that are packaged similarly to `@angular/core` and `@angular/common`. When this option
|
||||
is used, the `package.json` for the library should refer
|
||||
to the generated flat module index instead of the library index file. With this
|
||||
option only one `.metadata.json` file is produced that contains all the metadata necessary
|
||||
for symbols exported from the library index. In the generated `.ngfactory.js` files, the flat
|
||||
module index is used to import symbols that includes both the public API from the library index
|
||||
as well as shrowded internal symbols.
|
||||
|
||||
By default the `.ts` file supplied in the `files` field is assumed to be library index.
|
||||
If more than one `.ts` file is specified, `libraryIndex` is used to select the file to use.
|
||||
If more than one `.ts` file is supplied without a `libraryIndex`, an error is produced. A flat module
|
||||
index `.d.ts` and `.js` will be created with the given `flatModuleOutFile` name in the same
|
||||
location as the library index `.d.ts` file. For example, if a library uses
|
||||
`public_api.ts` file as the library index of the module, the `tsconfig.json` `files` field
|
||||
would be `["public_api.ts"]`. The `flatModuleOutFile` options could then be set to, for
|
||||
example `"index.js"`, which produces `index.d.ts` and `index.metadata.json` files. The
|
||||
library's `package.json`'s `module` field would be `"index.js"` and the `typings` field
|
||||
would be `"index.d.ts"`.
|
||||
|
||||
### *flatModuleId*
|
||||
|
||||
This option specifies the preferred module id to use for importing a flat module.
|
||||
References generated by the template compiler will use this module name when importing symbols
|
||||
from the flat module.
|
||||
This is only meaningful when `flatModuleOutFile` is also supplied. Otherwise the compiler ignores
|
||||
this option.
|
||||
|
||||
### *generateCodeForLibraries*
|
||||
|
||||
This option tells the template compiler to generate factory files (`.ngfactory.js` and `.ngstyle.js`)
|
||||
for `.d.ts` files with a corresponding `.metadata.json` file. This option defaults to
|
||||
`true`. When this option is `false`, factory files are generated only for `.ts` files.
|
||||
|
||||
This option should be set to `false` when using factory summaries.
|
||||
|
||||
### *fullTemplateTypeCheck*
|
||||
|
||||
This option tells the compiler to enable the [binding expression validation](#binding-expresion-validation)
|
||||
phase of the template compiler which uses TypeScript to validate binding expressions.
|
||||
|
||||
This option is `false` by default.
|
||||
|
||||
*Note*: It is recommended to set this to `true` as this option will default to `true` in the future.
|
||||
|
||||
### *annotateForClosureCompiler*
|
||||
|
||||
This option tells the compiler to use [Tsickle](https://github.com/angular/tsickle) to annotate the emitted
|
||||
JavaScript with [JsDoc](http://usejsdoc.org/) comments needed by the
|
||||
[Closure Compiler](https://github.com/google/closure-compiler). This option defaults to `false`.
|
||||
|
||||
### *annotationsAs*
|
||||
|
||||
Use this option to modify how the Angular specific annotations are emitted to improve tree-shaking. Non-Angular
|
||||
annotations and decorators are unnaffected. Default is `static fields`.
|
||||
|
||||
value | description
|
||||
----------------|-------------------------------------------------------------
|
||||
`decorators` | Leave the Decorators in-place. This makes compilation faster. TypeScript will emit calls to the __decorate helper. Use `--emitDecoratorMetadata` for runtime reflection. However, the resulting code will not properly tree-shake.
|
||||
`static fields` | Replace decorators with a static field in the class. Allows advanced tree-shakers like [Closure Compiler](https://github.com/google/closure-compiler) to remove unused classes.
|
||||
|
||||
### *trace*
|
||||
|
||||
This tells the compiler to print extra information while compiling templates.
|
||||
|
||||
### *enableLegacyTemplate*
|
||||
|
||||
The use of `<template>` element was deprecated starting in Angular 4.0 in favor of using
|
||||
`<ng-template>` to avoid colliding with the DOM's element of the same name. Setting this option to
|
||||
`true` enables the use of the deprecated `<template>` element . This option
|
||||
is `false` by default. This option might be required by some third-party Angular libraries.
|
||||
|
||||
### *disableExpressionLowering*
|
||||
|
||||
The Angular template compiler transforms code that is used, or could be used, in an annotation
|
||||
to allow it to be imported from template factory modules. See
|
||||
[metadata rewriting](#metadata-rewriting) for more information.
|
||||
|
||||
Setting this option to `false` disables this rewriting, requiring the rewriting to be
|
||||
done manually.
|
||||
|
||||
### *preserveWhitespaces*
|
||||
|
||||
This option tells the compiler whether to remove blank text nodes from compiled templates.
|
||||
This option is `true` by default.
|
||||
|
||||
*Note*: It is recommended to set this explicitly to `false` as it emits smaller template factory modules and might be set to `false` by default in the future.
|
||||
|
||||
### *allowEmptyCodegenFiles*
|
||||
|
||||
Tells the compiler to generate all the possible generated files even if they are empty. This option is
|
||||
`false` by default. This is an option used by `bazel` build rules and is needed to simplify
|
||||
how `bazel` rules track file dependencies. It is not recommended to use this option outside of the `bazel`
|
||||
rules.
|
||||
This option tells the compiler not to produce `.metadata.json` files.
|
||||
The option is `false` by default.
|
||||
|
||||
`.metadata.json` files contain infomration needed by the template compiler from a `.ts`
|
||||
file that is not included in the `.d.ts` file produced by the TypeScript compiler. This information contains,
|
||||
for example, the content of annotations (such as a component's template) which TypeScript
|
||||
emits to the `.js` file but not to the `.d.ts` file.
|
||||
|
||||
This option should be set to `true` if using TypeScript's `--outFile` option, as the metadata files
|
||||
are not valid for this style of TypeScript output. It is not recommeded to use `--outFile` with
|
||||
Angular. Use a bundler, such as [webpack](https://webpack.js.org/), instead.
|
||||
|
||||
This option can also be set to `true` when using factory summaries as the factory summaries
|
||||
include a copy of the information that is in the `.metadata.json` file.
|
||||
|
||||
### *strictMetadataEmit*
|
||||
|
||||
This option tells the template compiler to report an error to the `.metadata.json`
|
||||
file if `"skipMetadataEmit"` is `false` . This option is `false` by default. This should only be used when `"skipMetadataEmit"` is `false` and `"skipTemplateCodeGen"` is `true`.
|
||||
|
||||
It is intended to validate the `.metadata.json` files emitted for bundling with an `npm` package. The validation is overly strict and can emit errors for metadata that would never produce an error when used by the template compiler. You can choose to suppress the error emitted by this option for an exported symbol by including `@dynamic` in the comment documenting the symbol.
|
||||
|
||||
It is valid for `.metadata.json` files to contain errors. The template compiler reports these errors
|
||||
if the metadata is used to determine the contents of an annotation. The metadata
|
||||
collector cannot predict the symbols that are designed to use in an annotation, so it will preemptively
|
||||
include error nodes in the metadata for the exported symbols. The template compiler can then use the error
|
||||
nodes to report an error if these symbols are used. If the client of a library intends to use a symbol in an annotation, the template compiler will not normally report
|
||||
this until the client uses the symbol. This option allows detecting these errors during the build phase of
|
||||
the library and is used, for example, in producing Angular libraries themselves.
|
||||
|
||||
### *skipTemplateCodegen*
|
||||
|
||||
This option tells the compiler to suppress emitting `.ngfactory.js` and `.ngstyle.js` files. When set,
|
||||
this turns off most of the template compiler and disables reporting template diagnostics.
|
||||
This option can be used to instruct the
|
||||
template compiler to produce `.metadata.json` files for distribution with an `npm` package while
|
||||
avoiding the production of `.ngfactory.js` and `.ngstyle.js` files that cannot be distributed to
|
||||
`npm`.
|
||||
|
||||
### *strictInjectionParameters*
|
||||
|
||||
When set to `true`, this options tells the compiler to report an error for a parameter supplied
|
||||
whose injection type cannot be determined. When this value option is not provided or is `false`, constructor parameters of classes marked with `@Injectable` whose type cannot be resolved will
|
||||
produce a warning.
|
||||
|
||||
*Note*: It is recommended to change this option explicitly to `true` as this option will default to `true` in the future.
|
||||
|
||||
### *flatModuleOutFile*
|
||||
|
||||
When set to `true`, this option tells the template compiler to generate a flat module
|
||||
index of the given file name and the corresponding flat module metadata. Use this option when creating
|
||||
flat modules that are packaged similarly to `@angular/core` and `@angular/common`. When this option
|
||||
is used, the `package.json` for the library should refer
|
||||
to the generated flat module index instead of the library index file. With this
|
||||
option only one `.metadata.json` file is produced that contains all the metadata necessary
|
||||
for symbols exported from the library index. In the generated `.ngfactory.js` files, the flat
|
||||
module index is used to import symbols that includes both the public API from the library index
|
||||
as well as shrowded internal symbols.
|
||||
|
||||
By default the `.ts` file supplied in the `files` field is assumed to be library index.
|
||||
If more than one `.ts` file is specified, `libraryIndex` is used to select the file to use.
|
||||
If more than one `.ts` file is supplied without a `libraryIndex`, an error is produced. A flat module
|
||||
index `.d.ts` and `.js` will be created with the given `flatModuleOutFile` name in the same
|
||||
location as the library index `.d.ts` file. For example, if a library uses
|
||||
`public_api.ts` file as the library index of the module, the `tsconfig.json` `files` field
|
||||
would be `["public_api.ts"]`. The `flatModuleOutFile` options could then be set to, for
|
||||
example `"index.js"`, which produces `index.d.ts` and `index.metadata.json` files. The
|
||||
library's `package.json`'s `module` field would be `"index.js"` and the `typings` field
|
||||
would be `"index.d.ts"`.
|
||||
|
||||
### *flatModuleId*
|
||||
|
||||
This option specifies the preferred module id to use for importing a flat module.
|
||||
References generated by the template compiler will use this module name when importing symbols
|
||||
from the flat module.
|
||||
This is only meaningful when `flatModuleOutFile` is also supplied. Otherwise the compiler ignores
|
||||
this option.
|
||||
|
||||
### *generateCodeForLibraries*
|
||||
|
||||
This option tells the template compiler to generate factory files (`.ngfactory.js` and `.ngstyle.js`)
|
||||
for `.d.ts` files with a corresponding `.metadata.json` file. This option defaults to
|
||||
`true`. When this option is `false`, factory files are generated only for `.ts` files.
|
||||
|
||||
This option should be set to `false` when using factory summaries.
|
||||
|
||||
### *fullTemplateTypeCheck*
|
||||
|
||||
This option tells the compiler to enable the [binding expression validation](#binding-expresion-validation)
|
||||
phase of the template compiler which uses TypeScript to validate binding expressions.
|
||||
|
||||
This option is `false` by default.
|
||||
|
||||
*Note*: It is recommended to set this to `true` as this option will default to `true` in the future.
|
||||
|
||||
### *annotateForClosureCompiler*
|
||||
|
||||
This option tells the compiler to use [Tsickle](https://github.com/angular/tsickle) to annotate the emitted
|
||||
JavaScript with [JsDoc](http://usejsdoc.org/) comments needed by the
|
||||
[Closure Compiler](https://github.com/google/closure-compiler). This option defaults to `false`.
|
||||
|
||||
### *annotationsAs*
|
||||
|
||||
Use this option to modify how the Angular specific annotations are emitted to improve tree-shaking. Non-Angular
|
||||
annotations and decorators are unnaffected. Default is `static fields`.
|
||||
|
||||
value | description
|
||||
----------------|-------------------------------------------------------------
|
||||
`decorators` | Leave the Decorators in-place. This makes compilation faster. TypeScript will emit calls to the __decorate helper. Use `--emitDecoratorMetadata` for runtime reflection. However, the resulting code will not properly tree-shake.
|
||||
`static fields` | Replace decorators with a static field in the class. Allows advanced tree-shakers like [Closure Compiler](https://github.com/google/closure-compiler) to remove unused classes.
|
||||
|
||||
### *trace*
|
||||
|
||||
This tells the compiler to print extra information while compiling templates.
|
||||
|
||||
### *enableLegacyTemplate*
|
||||
|
||||
The use of `<template>` element was deprecated starting in Angular 4.0 in favor of using
|
||||
`<ng-template>` to avoid colliding with the DOM's element of the same name. Setting this option to
|
||||
`true` enables the use of the deprecated `<template>` element . This option
|
||||
is `false` by default. This option might be required by some third-party Angular libraries.
|
||||
|
||||
### *disableExpressionLowering*
|
||||
|
||||
The Angular template compiler transforms code that is used, or could be used, in an annotation
|
||||
to allow it to be imported from template factory modules. See
|
||||
[metadata rewriting](#metadata-rewriting) for more information.
|
||||
|
||||
Setting this option to `false` disables this rewriting, requiring the rewriting to be
|
||||
done manually.
|
||||
|
||||
### *preserveWhitespaces*
|
||||
|
||||
This option tells the compiler whether to remove blank text nodes from compiled templates.
|
||||
This option is `true` by default.
|
||||
|
||||
*Note*: It is recommended to set this explicitly to `false` as it emits smaller template factory modules and might be set to `false` by default in the future.
|
||||
|
||||
### *allowEmptyCodegenFiles*
|
||||
|
||||
Tells the compiler to generate all the possible generated files even if they are empty. This option is
|
||||
`false` by default. This is an option used by `bazel` build rules and is needed to simplify
|
||||
how `bazel` rules track file dependencies. It is not recommended to use this option outside of the `bazel`
|
||||
rules.
|
||||
|
||||
## Angular Metadata and AOT
|
||||
|
||||
|
|
@ -353,7 +353,7 @@ and [arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Re
|
|||
|
||||
Consider the following component decorator:
|
||||
|
||||
```ts
|
||||
```typescript
|
||||
@Component({
|
||||
...
|
||||
providers: [{provide: server, useFactory: () => new Server()}]
|
||||
|
|
@ -367,7 +367,7 @@ When the compiler later interprets this node, it reports an error that invites y
|
|||
|
||||
You can fix the error by converting to this:
|
||||
|
||||
```ts
|
||||
```typescript
|
||||
export function serverFactory() {
|
||||
return new Server();
|
||||
}
|
||||
|
|
@ -406,7 +406,7 @@ module-local `const` declarations and initialized `var` and `let` declarations,
|
|||
|
||||
Consider the following component definition:
|
||||
|
||||
```ts
|
||||
```typescript
|
||||
const template = '<div>{{hero.name}}</div>';
|
||||
|
||||
@Component({
|
||||
|
|
@ -423,7 +423,7 @@ The compiler could not refer to the `template` constant because it isn't exporte
|
|||
But the _collector_ can _fold_ the `template` constant into the metadata definition by inlining its contents.
|
||||
The effect is the same as if you had written:
|
||||
|
||||
```TypeScript
|
||||
```typescript
|
||||
@Component({
|
||||
selector: 'app-hero',
|
||||
template: '<div>{{hero.name}}</div>'
|
||||
|
|
@ -437,7 +437,7 @@ There is no longer a reference to `template` and, therefore, nothing to trouble
|
|||
|
||||
You can take this example a step further by including the `template` constant in another expression:
|
||||
|
||||
```TypeScript
|
||||
```typescript
|
||||
const template = '<div>{{hero.name}}</div>';
|
||||
|
||||
@Component({
|
||||
|
|
@ -495,7 +495,7 @@ Decorated component class members must be public. You cannot make an `@Input()`
|
|||
|
||||
Data bound properties must also be public.
|
||||
|
||||
```TypeScript
|
||||
```typescript
|
||||
// BAD CODE - title is private
|
||||
@Component({
|
||||
selector: 'app-root',
|
||||
|
|
@ -547,7 +547,7 @@ methods that return an expression.
|
|||
|
||||
For example, consider the following function:
|
||||
|
||||
```TypeScript
|
||||
```typescript
|
||||
export function wrapInArray<T>(value: T): T[] {
|
||||
return [value];
|
||||
}
|
||||
|
|
@ -557,7 +557,7 @@ You can call the `wrapInArray` in a metadata definition because it returns the v
|
|||
|
||||
You might use `wrapInArray()` like this:
|
||||
|
||||
```TypeScript
|
||||
```typescript
|
||||
@NgModule({
|
||||
declarations: wrapInArray(TypicalComponent)
|
||||
})
|
||||
|
|
@ -566,7 +566,7 @@ export class TypicalModule {}
|
|||
|
||||
The compiler treats this usage as if you had written:
|
||||
|
||||
```TypeScript
|
||||
```typescript
|
||||
@NgModule({
|
||||
declarations: [TypicalComponent]
|
||||
})
|
||||
|
|
@ -580,7 +580,8 @@ The Angular [`RouterModule`](api/router/RouterModule) exports two macro static m
|
|||
Review the [source code](https://github.com/angular/angular/blob/master/packages/router/src/router_module.ts#L139 "RouterModule.forRoot source code")
|
||||
for these methods to see how macros can simplify configuration of complex [NgModules](guide/ngmodules).
|
||||
|
||||
{@ metadata-rewriting}
|
||||
{@a metadata-rewriting}
|
||||
|
||||
### Metadata rewriting
|
||||
|
||||
The compiler treats object literals containing the fields `useClass`, `useValue`, `useFactory`, and `data` specially. The compiler converts the expression initializing one of these fields into an exported variable, which replaces the expression. This process of rewriting these expressions removes all the restrictions on what can be in them because
|
||||
|
|
@ -590,7 +591,7 @@ the compiler doesn't need to know the expression's value—it just needs to
|
|||
|
||||
You might write something like:
|
||||
|
||||
```ts
|
||||
```typescript
|
||||
class TypicalServer {
|
||||
|
||||
}
|
||||
|
|
@ -605,7 +606,7 @@ Without rewriting, this would be invalid because lambdas are not supported and `
|
|||
|
||||
To allow this, the compiler automatically rewrites this to something like:
|
||||
|
||||
```ts
|
||||
```typescript
|
||||
class TypicalServer {
|
||||
|
||||
}
|
||||
|
|
@ -1132,21 +1133,21 @@ Chuck: After reviewing your PR comment I'm still at a loss. See [comment there](
|
|||
|
||||
-->
|
||||
{@a binding-expresion-validation}
|
||||
|
||||
|
||||
## Phase 3: binding expression validation
|
||||
|
||||
|
||||
In the validation phase, the Angular template compiler uses the TypeScript compiler to validate the
|
||||
binding expressions in templates. Enable this phase explicity by adding the compiler
|
||||
option `"fullTemplateTypeCheck"` in the `"angularCompilerOptions"` of the project's `tsconfig.json` (see
|
||||
[Angular Compiler Options](#compiler-options)).
|
||||
|
||||
|
||||
Template validation produces error messages when a type error is detected in a template binding
|
||||
expression, similar to how type errors are reported by the TypeScript compiler against code in a `.ts`
|
||||
file.
|
||||
|
||||
|
||||
For example, consider the following component:
|
||||
|
||||
```ts
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: 'my-component',
|
||||
template: '{{person.addresss.street}}'
|
||||
|
|
@ -1155,35 +1156,35 @@ Chuck: After reviewing your PR comment I'm still at a loss. See [comment there](
|
|||
person?: Person;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
This will produce the following error:
|
||||
|
||||
|
||||
```
|
||||
my.component.ts.MyComponent.html(1,1): : Property 'addresss' does not exist on type 'Person'. Did you mean 'address'?
|
||||
```
|
||||
|
||||
|
||||
The file name reported in the error message, `my.component.ts.MyComponent.html`, is a synthetic file
|
||||
generated by the template compiler that holds contents of the `MyComponent` class template.
|
||||
Compiler never writes this file to disk. The line and column numbers are relative to the template string
|
||||
in the `@Component` annotation of the class, `MyComponent` in this case. If a component uses
|
||||
`templateUrl` instead of `template`, the errors are reported in the HTML file refereneced by the
|
||||
`templateUrl` instead of a synthetic file.
|
||||
|
||||
|
||||
The error location is the beginning of the text node that contains the interpolation expression with
|
||||
the error. If the error is in an attribute binding such as `[value]="person.address.street"`, the error
|
||||
location is the location of the attribute that contains the error.
|
||||
|
||||
|
||||
The validation uses the TypeScript type checker and the options supplied to the TypeScript compiler to control
|
||||
how detailed the type validation is. For example, if the `strictTypeChecks` is specified, the error ```my.component.ts.MyComponent.html(1,1): : Object is possibly 'undefined'``` is reported as well as the above error message.
|
||||
|
||||
|
||||
### Type narrowing
|
||||
|
||||
|
||||
The expression used in an `ngIf` directive is used to narrow type unions in the Angular
|
||||
template compiler, the same way the `if` expression does in TypeScript. For example, to avoid
|
||||
`Object is possibly 'undefined'` error in the template above, modify it to only emit the
|
||||
interpolation if the value of `person` is initialized as shown below:
|
||||
|
||||
```ts
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: 'my-component',
|
||||
template: '<span *ngIf="person"> {{person.addresss.street}} </span>'
|
||||
|
|
@ -1192,38 +1193,38 @@ Chuck: After reviewing your PR comment I'm still at a loss. See [comment there](
|
|||
person?: Person;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Using `*ngIf` allows the TypeScript compiler to infer that the `person` used in the
|
||||
binding expression will never be `undefined`.
|
||||
|
||||
|
||||
#### Custom `ngIf` like directives
|
||||
|
||||
|
||||
Directives that behave like `*ngIf` can declare that they want the same treatment by including
|
||||
a static member marker that is a signal to the template compiler to treat them
|
||||
a static member marker that is a signal to the template compiler to treat them
|
||||
like `*ngIf`. This static member for `*ngIf` is:
|
||||
|
||||
```ts
|
||||
|
||||
```typescript
|
||||
public static ngIfUseIfTypeGuard: void;
|
||||
```
|
||||
|
||||
|
||||
This declares that the input property `ngIf` of the `NgIf` directive should be treated as a
|
||||
guard to the use of its template, implying that the template will only be instantiated if
|
||||
the `ngIf` input property is true.
|
||||
|
||||
|
||||
|
||||
|
||||
### Non-null type assertion operator
|
||||
|
||||
|
||||
Use the [non-null type assertion operator](guide/template-syntax#non-null-assertion-operator)
|
||||
to suppress the `Object is possibly 'undefined'` error when it is incovienent to use
|
||||
`*ngIf` or when some constraint in the component ensures that the expression is always
|
||||
non-null when the binding expression is interpolated.
|
||||
|
||||
|
||||
In the following example, the `person` and `address` properties are always set together,
|
||||
implying that `address` is always non-null if `person` is non-null. There is no convenient
|
||||
way to describe this constraint to TypeScript and the template compiler, but the error
|
||||
is suppressed in the example by using `address!.street`.
|
||||
|
||||
```ts
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: 'my-component',
|
||||
template: '<span *ngIf="person"> {{person.name}} lives on {{address!.street}} </span>'
|
||||
|
|
@ -1231,21 +1232,21 @@ Chuck: After reviewing your PR comment I'm still at a loss. See [comment there](
|
|||
class MyComponent {
|
||||
person?: Person;
|
||||
address?: Address;
|
||||
|
||||
|
||||
setData(person: Person, address: Address) {
|
||||
this.person = person;
|
||||
this.address = address;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The non-null assertion operator should be used sparingly as refactoring of the component
|
||||
|
||||
The non-null assertion operator should be used sparingly as refactoring of the component
|
||||
might break this constraint.
|
||||
|
||||
In this example it is recommended to include the checking of `address`
|
||||
in the `*ngIf`as shown below:
|
||||
|
||||
```ts
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: 'my-component',
|
||||
template: '<span *ngIf="person && address"> {{person.name}} lives on {{address.street}} </span>'
|
||||
|
|
@ -1253,25 +1254,25 @@ Chuck: After reviewing your PR comment I'm still at a loss. See [comment there](
|
|||
class MyComponent {
|
||||
person?: Person;
|
||||
address?: Address;
|
||||
|
||||
|
||||
setData(person: Person, address: Address) {
|
||||
this.person = person;
|
||||
this.address = address;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### Disabling type checking using `$any()`
|
||||
|
||||
|
||||
Disable checking of a binding expression by surrounding the expression
|
||||
in a call to the [`$any()` cast pseudo-function](guide/template-syntax).
|
||||
The compiler treats it as a cast to the `any` type just like in TypeScript when a `<any>`
|
||||
or `as any` cast is used.
|
||||
|
||||
|
||||
In the following example, the error `Property addresss does not exist` is suppressed
|
||||
by casting `person` to the `any` type.
|
||||
|
||||
```ts
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: 'my-component',
|
||||
template: '{{$any(person).addresss.street}}'
|
||||
|
|
@ -1289,4 +1290,3 @@ Chuck: After reviewing your PR comment I'm still at a loss. See [comment there](
|
|||
* Macro-functions and macro-static methods.
|
||||
* Compiler errors related to metadata.
|
||||
* Validation of binding expressions
|
||||
|
||||
|
|
|
|||
|
|
@ -8,13 +8,13 @@ A basic understanding of the following:
|
|||
<hr />
|
||||
|
||||
An NgModule describes how the application parts fit together.
|
||||
Every application has at least one Angular module, the _root_ module
|
||||
Every application has at least one Angular module, the _root_ module
|
||||
that you bootstrap to launch the application.
|
||||
By convention, it is usually called `AppModule`.
|
||||
|
||||
If you use the CLI to generate an app, the default `AppModule` is as follows:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
/* JavaScript imports */
|
||||
import { BrowserModule } from '@angular/platform-browser';
|
||||
import { NgModule } from '@angular/core';
|
||||
|
|
@ -49,10 +49,10 @@ The `@NgModule` decorator identifies `AppModule` as an `NgModule` class.
|
|||
* **_declarations_**—this application's lone component.
|
||||
* **_imports_**—import `BrowserModule` to have browser specific services such as DOM rendering, sanitization, and location.
|
||||
* **_providers_**—the service providers.
|
||||
* **_bootstrap_**—the _root_ component that Angular creates and inserts
|
||||
into the `index.html` host web page.
|
||||
* **_bootstrap_**—the _root_ component that Angular creates and inserts
|
||||
into the `index.html` host web page.
|
||||
|
||||
The default CLI application only has one component, `AppComponent`, so it
|
||||
The default CLI application only has one component, `AppComponent`, so it
|
||||
is in both the `declarations` and the `bootstrap` arrays.
|
||||
|
||||
{@a declarations}
|
||||
|
|
@ -62,23 +62,23 @@ is in both the `declarations` and the `bootstrap` arrays.
|
|||
The module's `declarations` array tells Angular which components belong to that module.
|
||||
As you create more components, add them to `declarations`.
|
||||
|
||||
You must declare every component in exactly one `NgModule` class.
|
||||
If you use a component without declaring it, Angular returns an
|
||||
You must declare every component in exactly one `NgModule` class.
|
||||
If you use a component without declaring it, Angular returns an
|
||||
error message.
|
||||
|
||||
The `declarations` array only takes declarables. Declarables
|
||||
The `declarations` array only takes declarables. Declarables
|
||||
are components, [directives](guide/attribute-directives) and [pipes](guide/pipes).
|
||||
All of a module's declarables must be in the `declarations` array.
|
||||
Declarables must belong to exactly one module. The compiler emits
|
||||
All of a module's declarables must be in the `declarations` array.
|
||||
Declarables must belong to exactly one module. The compiler emits
|
||||
an error if you try to declare the same class in more than one module.
|
||||
|
||||
These declared classes are visible within the module but invisible
|
||||
to components in a different module unless they are exported from
|
||||
These declared classes are visible within the module but invisible
|
||||
to components in a different module unless they are exported from
|
||||
this module and the other module imports this one.
|
||||
|
||||
An example of what goes into a declarations array follows:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
declarations: [
|
||||
YourComponent,
|
||||
YourPipe,
|
||||
|
|
@ -86,8 +86,8 @@ An example of what goes into a declarations array follows:
|
|||
],
|
||||
```
|
||||
|
||||
A declarable can only belong to one module, so only declare it in
|
||||
one `@NgModule`. When you need it elsewhere,
|
||||
A declarable can only belong to one module, so only declare it in
|
||||
one `@NgModule`. When you need it elsewhere,
|
||||
import the module that has the declarable you need in it.
|
||||
|
||||
**Only `@NgModule` references** go in the `imports` array.
|
||||
|
|
@ -103,13 +103,13 @@ To use a directive, component, or pipe in a module, you must do a few things:
|
|||
3. Declare it in the `@NgModule` `declarations` array.
|
||||
|
||||
|
||||
Those three steps look like the following. In the file where you create your directive, export it.
|
||||
Those three steps look like the following. In the file where you create your directive, export it.
|
||||
The following example, named `ItemDirective` is the default directive structure that the CLI generates in its own file, `item.directive.ts`:
|
||||
|
||||
<code-example path="bootstrapping/src/app/item.directive.ts" region="directive" title="src/app/item.directive.ts" linenums="false">
|
||||
</code-example>
|
||||
|
||||
The key point here is that you have to export it so you can import it elsewhere. Next, import it
|
||||
The key point here is that you have to export it so you can import it elsewhere. Next, import it
|
||||
into the NgModule, in this example `app.module.ts`, with a JavaScript import statement:
|
||||
|
||||
<code-example path="bootstrapping/src/app/app.module.ts" region="directive-import" title="src/app/app.module.ts" linenums="false">
|
||||
|
|
@ -136,11 +136,11 @@ The module's `imports` array appears exclusively in the `@NgModule` metadata obj
|
|||
It tells Angular about other NgModules that this particular module needs to function properly.
|
||||
|
||||
This list of modules are those that export components, directives, or pipes
|
||||
that the component templates in this module reference. In this case, the component is
|
||||
`AppComponent`, which references components, directives, or pipes in `BrowserModule`,
|
||||
that the component templates in this module reference. In this case, the component is
|
||||
`AppComponent`, which references components, directives, or pipes in `BrowserModule`,
|
||||
`FormsModule`, or `HttpModule`.
|
||||
A component template can reference another component, directive,
|
||||
or pipe when the referenced class is declared in this module or
|
||||
A component template can reference another component, directive,
|
||||
or pipe when the referenced class is declared in this module or
|
||||
the class was imported from another module.
|
||||
|
||||
You don't have any services to provide yet.
|
||||
|
|
@ -150,32 +150,31 @@ But you will create some before long and you may chose to provide many of them h
|
|||
|
||||
## The `providers` array
|
||||
|
||||
The providers array is where you list the services the app needs. When
|
||||
you list services here, they are available app-wide. You can scope
|
||||
them when using feature modules and lazy loading. For more information, see
|
||||
The providers array is where you list the services the app needs. When
|
||||
you list services here, they are available app-wide. You can scope
|
||||
them when using feature modules and lazy loading. For more information, see
|
||||
[Providers](guide/providers).
|
||||
|
||||
## The `bootstrap` array
|
||||
|
||||
The application launches by bootstrapping the root `AppModule`, which is
|
||||
also referred to as an `entryComponent`.
|
||||
The application launches by bootstrapping the root `AppModule`, which is
|
||||
also referred to as an `entryComponent`.
|
||||
Among other things, the bootstrapping process creates the component(s) listed in the `bootstrap` array
|
||||
and inserts each one into the browser DOM.
|
||||
|
||||
Each bootstrapped component is the base of its own tree of components.
|
||||
Inserting a bootstrapped component usually triggers a cascade of
|
||||
Inserting a bootstrapped component usually triggers a cascade of
|
||||
component creations that fill out that tree.
|
||||
|
||||
While you can put more than one component tree on a host web page,
|
||||
While you can put more than one component tree on a host web page,
|
||||
most applications have only one component tree and bootstrap a single root component.
|
||||
|
||||
This one root component is usually called `AppComponent` and is in the
|
||||
This one root component is usually called `AppComponent` and is in the
|
||||
root module's `bootstrap` array.
|
||||
|
||||
|
||||
|
||||
## More about Angular Modules
|
||||
|
||||
For more on NgModules you're likely to see frequently in apps,
|
||||
For more on NgModules you're likely to see frequently in apps,
|
||||
see [Frequently Used Modules](#).
|
||||
|
||||
|
|
|
|||
|
|
@ -821,7 +821,7 @@ Here's an embedded live example for this guide. It has a custom image created fr
|
|||
|
||||
<live-example embedded img="guide/docs-style-guide/docs-style-guide-plunker.png"></live-example>
|
||||
|
||||
<a id="anchors"></a>
|
||||
{@a anchors}
|
||||
|
||||
## Anchors
|
||||
|
||||
|
|
@ -861,12 +861,13 @@ Sometimes the section header text makes for an unattractive anchor. [This one](#
|
|||
|
||||
The greater danger is that **a future rewording of the header text would break** a link to this section.
|
||||
|
||||
For these reasons, it is often wise to add a custom anchor explicitly, just above the heading or text to which it applies, using the special`{@ name}` syntax like this.
|
||||
For these reasons, it is often wise to add a custom anchor explicitly, just above the heading or
|
||||
text to which it applies, using the special `{@a name}` syntax like this.
|
||||
|
||||
<code-example language="html">
|
||||
{@a ugly-anchors}
|
||||
|
||||
#### Ugly, long section header anchors
|
||||
#### Ugly, long section header anchors
|
||||
</code-example>
|
||||
|
||||
Now [link to that custom anchor name](#ugly-anchors) as you did before.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ Additional benefits of `HttpClient` include testability support, strong typing o
|
|||
|
||||
Before you can use the `HttpClient`, you need to install the `HttpClientModule` which provides it. This can be done in your application module, and is only necessary once.
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
// app.module.ts:
|
||||
|
||||
import {NgModule} from '@angular/core';
|
||||
|
|
@ -48,7 +48,7 @@ The most common type of request applications make to a backend is to request JSO
|
|||
The `get()` method on `HttpClient` makes accessing this data straightforward.
|
||||
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
@Component(...)
|
||||
export class MyComponent implements OnInit {
|
||||
|
||||
|
|
@ -75,7 +75,7 @@ In the above example, the `data['results']` field access stands out because you
|
|||
You can, however, tell `HttpClient` what type the response will be, which is recommended.
|
||||
To do so, first you define an interface with the correct shape:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
interface ItemsResponse {
|
||||
results: string[];
|
||||
}
|
||||
|
|
@ -83,7 +83,7 @@ interface ItemsResponse {
|
|||
|
||||
Then, when you make the `HttpClient.get` call, pass a type parameter:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
http.get<ItemsResponse>('/api/items').subscribe(data => {
|
||||
// data is now an instance of type ItemsResponse, so you can do this:
|
||||
this.results = data.results;
|
||||
|
|
@ -94,7 +94,7 @@ http.get<ItemsResponse>('/api/items').subscribe(data => {
|
|||
|
||||
The response body doesn't return all the data you may need. Sometimes servers return special headers or status codes to indicate certain conditions, and inspecting those can be necessary. To do this, you can tell `HttpClient` you want the full response instead of just the body with the `observe` option:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
http
|
||||
.get<MyJsonData>('/data.json', {observe: 'response'})
|
||||
.subscribe(resp => {
|
||||
|
|
@ -116,7 +116,7 @@ What happens if the request fails on the server, or if a poor network connection
|
|||
|
||||
To handle it, add an error handler to your `.subscribe()` call:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
http
|
||||
.get<ItemsResponse>('/api/items')
|
||||
.subscribe(
|
||||
|
|
@ -137,7 +137,7 @@ There are two types of errors that can occur. If the backend returns an unsucces
|
|||
|
||||
In both cases, you can look at the `HttpErrorResponse` to figure out what happened.
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
http
|
||||
.get<ItemsResponse>('/api/items')
|
||||
.subscribe(
|
||||
|
|
@ -169,7 +169,7 @@ import 'rxjs/add/operator/retry';
|
|||
|
||||
Then, you can use it with HTTP Observables like this:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
http
|
||||
.get<ItemsResponse>('/api/items')
|
||||
// Retry this request up to 3 times.
|
||||
|
|
@ -182,7 +182,7 @@ http
|
|||
|
||||
Not all APIs return JSON data. Suppose you want to read a text file on the server. You have to tell `HttpClient` that you expect a textual response:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
http
|
||||
.get('/textfile.txt', {responseType: 'text'})
|
||||
// The Observable returned by get() is of type Observable<string>
|
||||
|
|
@ -200,7 +200,7 @@ In addition to fetching data from the server, `HttpClient` supports mutating req
|
|||
One common operation is to POST data to a server; for example when submitting a form. The code for
|
||||
sending a POST request is very similar to the code for GET:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
const body = {name: 'Brad'};
|
||||
|
||||
http
|
||||
|
|
@ -212,7 +212,7 @@ http
|
|||
|
||||
*Note the `subscribe()` method.* All Observables returned from `HttpClient` are _cold_, which is to say that they are _blueprints_ for making requests. Nothing will happen until you call `subscribe()`, and every such call will make a separate request. For example, this code sends a POST request with the same data twice:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
const req = http.post('/api/items/add', body);
|
||||
// 0 requests made - .subscribe() not called.
|
||||
req.subscribe();
|
||||
|
|
@ -230,7 +230,7 @@ Besides the URL and a possible request body, there are other aspects of an outgo
|
|||
|
||||
One common task is adding an `Authorization` header to outgoing requests. Here's how you do that:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
http
|
||||
.post('/api/items/add', body, {
|
||||
headers: new HttpHeaders().set('Authorization', 'my-auth-token'),
|
||||
|
|
@ -244,7 +244,7 @@ The `HttpHeaders` class is immutable, so every `set()` returns a new instance an
|
|||
|
||||
Adding URL parameters works in the same way. To send a request with the `id` parameter set to `3`, you would do:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
http
|
||||
.post('/api/items/add', body, {
|
||||
params: new HttpParams().set('id', '3'),
|
||||
|
|
@ -269,7 +269,7 @@ before sending it to the server, and the interceptors can transform the response
|
|||
To implement an interceptor, you declare a class that implements `HttpInterceptor`, which
|
||||
has a single `intercept()` method. Here is a simple interceptor which does nothing but forward the request through without altering it:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
import {Injectable} from '@angular/core';
|
||||
import {HttpEvent, HttpInterceptor, HttpHandler, HttpRequest} from '@angular/common/http';
|
||||
|
||||
|
|
@ -295,7 +295,7 @@ This pattern is similar to those in middleware frameworks such as Express.js.
|
|||
|
||||
Simply declaring the `NoopInterceptor` above doesn't cause your app to use it. You need to wire it up in your app module by providing it as an interceptor, as follows:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
import {NgModule} from '@angular/core';
|
||||
import {HTTP_INTERCEPTORS} from '@angular/common/http';
|
||||
|
||||
|
|
@ -338,7 +338,7 @@ If you have a need to mutate the request body, you need to copy the request body
|
|||
|
||||
Since requests are immutable, they cannot be modified directly. To mutate them, use `clone()`:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
|
||||
// This is a duplicate. It is exactly the same as the original.
|
||||
const dupReq = req.clone();
|
||||
|
|
@ -354,7 +354,7 @@ As you can see, the hash accepted by `clone()` allows you to mutate specific pro
|
|||
|
||||
A common use of interceptors is to set default headers on outgoing responses. For example, assuming you have an injectable `AuthService` which can provide an authentication token, here is how you would write an interceptor which adds it to all outgoing requests:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
import {Injectable} from '@angular/core';
|
||||
import {HttpEvent, HttpInterceptor, HttpHandler, HttpRequest} from '@angular/common/http';
|
||||
|
||||
|
|
@ -375,7 +375,7 @@ export class AuthInterceptor implements HttpInterceptor {
|
|||
|
||||
The practice of cloning a request to set new headers is so common that there's actually a shortcut for it:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
const authReq = req.clone({setHeaders: {Authorization: authHeader}});
|
||||
```
|
||||
|
||||
|
|
@ -389,7 +389,7 @@ An interceptor that alters headers can be used for a number of different operati
|
|||
|
||||
Because interceptors can process the request and response _together_, they can do things like log or time requests. Consider this interceptor which uses `console.log` to show how long each request takes:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
import 'rxjs/add/operator/do';
|
||||
|
||||
export class TimingInterceptor implements HttpInterceptor {
|
||||
|
|
@ -414,7 +414,7 @@ Notice the RxJS `do()` operator—it adds a side effect to an Observable wit
|
|||
|
||||
You can also use interceptors to implement caching. For this example, assume that you've written an HTTP cache with a simple interface:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
abstract class HttpCache {
|
||||
/**
|
||||
* Returns a cached response, if any, or null if not present.
|
||||
|
|
@ -430,7 +430,7 @@ abstract class HttpCache {
|
|||
|
||||
An interceptor can apply this cache to outgoing requests.
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
@Injectable()
|
||||
export class CachingInterceptor implements HttpInterceptor {
|
||||
constructor(private cache: HttpCache) {}
|
||||
|
|
@ -467,7 +467,7 @@ Obviously this example glosses over request matching, cache invalidation, etc.,
|
|||
|
||||
To really demonstrate their flexibility, you can change the above example to return _two_ response events if the request exists in cache—the cached response first, and an updated network response later.
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
|
||||
// Still skip non-GET requests.
|
||||
if (req.method !== 'GET') {
|
||||
|
|
@ -507,7 +507,7 @@ Sometimes applications need to transfer large amounts of data, and those transfe
|
|||
|
||||
To make a request with progress events enabled, first create an instance of `HttpRequest` with the special `reportProgress` option set:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
const req = new HttpRequest('POST', '/upload/file', file, {
|
||||
reportProgress: true,
|
||||
});
|
||||
|
|
@ -518,7 +518,7 @@ change detection, so only turn them on if you intend to actually update the UI o
|
|||
|
||||
Next, make the request through the `request()` method of `HttpClient`. The result will be an Observable of events, just like with interceptors:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
http.request(req).subscribe(event => {
|
||||
// Via this API, you get access to the raw event stream.
|
||||
// Look for upload progress events.
|
||||
|
|
@ -553,7 +553,7 @@ In order to prevent collisions in environments where multiple Angular apps share
|
|||
|
||||
If your backend service uses different names for the XSRF token cookie or header, use `HttpClientXsrfModule.withOptions()` to override the defaults.
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
imports: [
|
||||
HttpClientModule,
|
||||
HttpClientXsrfModule.withOptions({
|
||||
|
|
@ -575,7 +575,7 @@ Angular's HTTP testing library is designed for a pattern of testing where the ap
|
|||
|
||||
To begin testing requests made through `HttpClient`, import `HttpClientTestingModule` and add it to your `TestBed` setup, like so:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
|
||||
import {HttpClientTestingModule} from '@angular/common/http/testing';
|
||||
|
||||
|
|
@ -595,7 +595,7 @@ That's it. Now requests made in the course of your tests will hit the testing ba
|
|||
|
||||
With the mock installed via the module, you can write a test that expects a GET Request to occur and provides a mock response. The following example does this by injecting both the `HttpClient` into the test and a class called `HttpTestingController`
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
it('expects a GET request', inject([HttpClient, HttpTestingController], (http: HttpClient, httpMock: HttpTestingController) => {
|
||||
// Make an HTTP GET request, and expect that it return an object
|
||||
// of the form {name: 'Test Data'}.
|
||||
|
|
@ -624,7 +624,7 @@ it('expects a GET request', inject([HttpClient, HttpTestingController], (http: H
|
|||
|
||||
The last step, verifying that no requests remain outstanding, is common enough for you to move it into an `afterEach()` step:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
afterEach(inject([HttpTestingController], (httpMock: HttpTestingController) => {
|
||||
httpMock.verify();
|
||||
}));
|
||||
|
|
@ -634,7 +634,7 @@ afterEach(inject([HttpTestingController], (httpMock: HttpTestingController) => {
|
|||
|
||||
If matching by URL isn't sufficient, it's possible to implement your own matching function. For example, you could look for an outgoing request that has an Authorization header:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
const req = httpMock.expectOne((req) => req.headers.has('Authorization'));
|
||||
```
|
||||
|
||||
|
|
@ -644,7 +644,7 @@ Just as with the `expectOne()` by URL in the test above, if 0 or 2+ requests mat
|
|||
|
||||
If you need to respond to duplicate requests in your test, use the `match()` API instead of `expectOne()`, which takes the same arguments but returns an array of matching requests. Once returned, these requests are removed from future matching and are your responsibility to verify and flush.
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
// Expect that 5 pings have been made and flush them.
|
||||
const reqs = httpMock.match('/ping');
|
||||
expect(reqs.length).toBe(5);
|
||||
|
|
|
|||
Loading…
Reference in New Issue