mirror of
https://github.com/angular/angular.git
synced 2026-09-14 13:54:52 +08:00
docs: add new internationalization links (#43245)
Update link for subtopics of internationalization guide. Clean up markdown. PR Close #43245
This commit is contained in:
Joe Martin (Crowdstaffing)
committed by
Alex Rickabaugh
Alex Rickabaugh
parent
a5a8697e16
commit
3f3adc7ae2
@@ -4,21 +4,24 @@ When you use [AOT compilation](guide/aot-compiler), you can control how your app
|
||||
|
||||
The template options object, `angularCompilerOptions`, is a sibling to the `compilerOptions` object that supplies standard options to the TypeScript compiler.
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"experimentalDecorators": true,
|
||||
...
|
||||
},
|
||||
"angularCompilerOptions": {
|
||||
"fullTemplateTypeCheck": true,
|
||||
"preserveWhitespaces": true,
|
||||
...
|
||||
}
|
||||
<code-example language="json">
|
||||
|
||||
{
|
||||
"compilerOptions": {
|
||||
"experimentalDecorators": true,
|
||||
...
|
||||
},
|
||||
"angularCompilerOptions": {
|
||||
"fullTemplateTypeCheck": true,
|
||||
"preserveWhitespaces": true,
|
||||
...
|
||||
}
|
||||
```
|
||||
}
|
||||
|
||||
</code-example>
|
||||
|
||||
{@a tsconfig-extends}
|
||||
|
||||
## Configuration inheritance with extends
|
||||
|
||||
Like the TypeScript compiler, the Angular AOT compiler also supports `extends` in the `angularCompilerOptions` section of the TypeScript configuration file.
|
||||
@@ -29,7 +32,8 @@ The configuration options from the base file are loaded first, then overridden b
|
||||
|
||||
For example:
|
||||
|
||||
```json
|
||||
<code-example language="json">
|
||||
|
||||
{
|
||||
"extends": "../tsconfig.json",
|
||||
"compilerOptions": {
|
||||
@@ -42,7 +46,8 @@ For example:
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</code-example>
|
||||
|
||||
For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
|
||||
|
||||
@@ -58,9 +63,8 @@ When `true`, generate all possible files even if they are empty. Default is `fal
|
||||
|
||||
Modifies how Angular-specific annotations are emitted to improve tree-shaking. Non-Angular annotations are not affected. One of `static fields` (the default) or `decorators`.
|
||||
|
||||
* By default, the compiler replaces decorators with a static field in the class, which allows advanced tree-shakers like [Closure compiler](https://github.com/google/closure-compiler) to remove unused classes.
|
||||
|
||||
* The `decorators` value leaves the decorators in place, which makes compilation faster. TypeScript emits calls to the` __decorate` helper. Use `--emitDecoratorMetadata` for runtime reflection (but note that the resulting code will not properly tree-shake.
|
||||
* By default, the compiler replaces decorators with a static field in the class, which allows advanced tree-shakers like [Closure compiler](https://github.com/google/closure-compiler) to remove unused classes.
|
||||
* The `decorators` value leaves the decorators in place, which makes compilation faster. TypeScript emits calls to the `__decorate` helper. Use `--emitDecoratorMetadata` for runtime reflection (but note that the resulting code will not properly tree-shake.
|
||||
|
||||
### `annotateForClosureCompiler`
|
||||
|
||||
@@ -71,8 +75,8 @@ When `true`, use [Tsickle](https://github.com/angular/tsickle) to annotate the e
|
||||
|
||||
Specifies the compilation mode to use. The following modes are available:
|
||||
|
||||
- `'full'`: generates fully AOT-compiled code according to the version of Angular that is currently being used.
|
||||
- `'partial'`: generates code in a stable, but intermediate form suitable for a published library.
|
||||
* `'full'`: generates fully AOT-compiled code according to the version of Angular that is currently being used.
|
||||
* `'partial'`: generates code in a stable, but intermediate form suitable for a published library.
|
||||
|
||||
The default value is `'full'`.
|
||||
|
||||
@@ -88,8 +92,8 @@ When `true`, the compiler does not check the TypeScript version and does not rep
|
||||
|
||||
### `enableI18nLegacyMessageIdFormat`
|
||||
|
||||
Instructs the Angular template compiler to generate legacy IDs for messages that are tagged in templates by the `i18n` attribute.
|
||||
See [Localizing your app](guide/i18n#mark-text-for-translations) for more information about marking messages for localization.
|
||||
Instructs the Angular template compiler to generate legacy ids for messages that are tagged in templates by the `i18n` attribute.
|
||||
See [Mark text for translations][AioGuideI18nCommonPrepareMarkTextForTranslations] for more information about marking messages for localization.
|
||||
|
||||
Set this option to `false` unless your project relies upon translations that were previously generated using legacy IDs. Default is `true`.
|
||||
|
||||
@@ -113,7 +117,6 @@ When enabled, the `.js` output of `ngc` does not include any lazy-loaded templat
|
||||
|
||||
For library projects generated with the CLI, the development configuration default is `true`.
|
||||
|
||||
|
||||
{@a enablelegacytemplate}
|
||||
|
||||
### `enableLegacyTemplate`
|
||||
@@ -122,18 +125,13 @@ When `true`, enables use of the `<template>` element, which was deprecated in An
|
||||
|
||||
### `flatModuleId`
|
||||
|
||||
The module ID to use for importing a flat module (when `flatModuleOutFile` is `true`). References generated by the template compiler use this module name when importing symbols
|
||||
from the flat module. Ignored if `flatModuleOutFile` is `false`.
|
||||
The module ID to use for importing a flat module (when `flatModuleOutFile` is `true`). References generated by the template compiler use this module name when importing symbols from the flat module. Ignored if `flatModuleOutFile` is `false`.
|
||||
|
||||
### `flatModuleOutFile`
|
||||
|
||||
When `true`, generates a flat module index of the given file name and the corresponding flat module metadata. Use to create 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.
|
||||
When `true`, generates a flat module index of the given file name and the corresponding flat module metadata. Use to create 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.
|
||||
|
||||
Produces only one `.metadata.json` file, which 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 include both the public API from the library index
|
||||
as well as shrouded internal symbols.
|
||||
Produces only one `.metadata.json` file, which 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 include 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 the library index.
|
||||
If more than one `.ts` file is specified, `libraryIndex` is used to select the file to use.
|
||||
@@ -142,9 +140,8 @@ If more than one `.ts` file is supplied without a `libraryIndex`, an error is pr
|
||||
A flat module index `.d.ts` and `.js` is created with the given `flatModuleOutFile` name in the same location as the library index `.d.ts` file.
|
||||
|
||||
For example, if a library uses the `public_api.ts` file as the library index of the module, the `tsconfig.json` `files` field would be `["public_api.ts"]`.
|
||||
The `flatModuleOutFile` option could then be set to (for example) `"index.js"`, which produces `index.d.ts` and `index.metadata.json` files.
|
||||
The `module` field of the library's `package.json` would be `"index.js"` and the `typings` field
|
||||
would be `"index.d.ts"`.
|
||||
The `flatModuleOutFile` option could then be set to (for example) `"index.js"`, which produces `index.d.ts` and `index.metadata.json` files.
|
||||
The `module` field of the library's `package.json` would be `"index.js"` and the `typings` field would be `"index.d.ts"`.
|
||||
|
||||
### `fullTemplateTypeCheck`
|
||||
|
||||
@@ -154,12 +151,10 @@ Default is `false`, but when you use the CLI command `ng new --strict`, it is se
|
||||
|
||||
### `generateCodeForLibraries`
|
||||
|
||||
When `true` (the default), generates factory files (`.ngfactory.js` and `.ngstyle.js`)
|
||||
for `.d.ts` files with a corresponding `.metadata.json` file.
|
||||
When `true` (the default), generates factory files (`.ngfactory.js` and `.ngstyle.js`) for `.d.ts` files with a corresponding `.metadata.json` file.
|
||||
|
||||
When `false`, factory files are generated only for `.ts` files. Do this when using factory summaries.
|
||||
|
||||
|
||||
### `preserveWhitespaces`
|
||||
|
||||
When `false` (the default), removes blank text nodes from compiled templates, which results in smaller emitted template factory modules. Set to `true` to preserve blank text nodes.
|
||||
@@ -168,15 +163,12 @@ When `false` (the default), removes blank text nodes from compiled templates, wh
|
||||
|
||||
When `true`, does not produce `.metadata.json` files. Default is `false`.
|
||||
|
||||
The `.metadata.json` files contain information 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 includes, 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.
|
||||
The `.metadata.json` files contain information 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 includes, 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.
|
||||
|
||||
You can set to `true` when using factory summaries, because the factory summaries
|
||||
include a copy of the information that is in the `.metadata.json` file.
|
||||
You can set to `true` when using factory summaries, because the factory summaries include a copy of the information that is in the `.metadata.json` file.
|
||||
|
||||
Set to `true` if you are using TypeScript's `--outFile` option, because the metadata files
|
||||
are not valid for this style of TypeScript output. However, we do not recommend using `--outFile` with Angular. Use a bundler, such as [webpack](https://webpack.js.org/), instead.
|
||||
Set to `true` if you are using TypeScript's `--outFile` option, because the metadata files are not valid for this style of TypeScript output. However, we do not recommend using `--outFile` with Angular. Use a bundler, such as [webpack](https://webpack.js.org/), instead.
|
||||
|
||||
### `skipTemplateCodegen`
|
||||
|
||||
@@ -199,8 +191,7 @@ The metadata collector cannot predict the symbols that are designed for use in a
|
||||
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 does not normally report this until the client uses the symbol.
|
||||
This option allows detection of these errors during the build phase of
|
||||
the library and is used, for example, in producing Angular libraries themselves.
|
||||
This option allows detection of these errors during the build phase of the library and is used, for example, in producing Angular libraries themselves.
|
||||
|
||||
For library projects generated with the CLI, the development configuration default is `true`.
|
||||
|
||||
@@ -222,8 +213,8 @@ When you use the CLI command `ng new --strict`, it is set to `true` in the gener
|
||||
|
||||
When `true`, prints extra information while compiling templates. Default is `false`.
|
||||
|
||||
|
||||
{@a cli-options}
|
||||
|
||||
## Command Line Options
|
||||
|
||||
While most of the time you interact with the Angular Compiler indirectly using Angular CLI, when debugging certain issues, you might find it useful to invoke the Angular Compiler directly.
|
||||
@@ -232,3 +223,11 @@ You can use the `ngc` command provided by the `@angular/compiler-cli` npm packag
|
||||
The `ngc` command is just a wrapper around TypeScript's `tsc` compiler command and is primarily configured via the `tsconfig.json` configuration options documented in [the previous sections](#angular-compiler-options).
|
||||
|
||||
In addition to the configuration file, you can also use [`tsc` command line options](https://www.typescriptlang.org/docs/handbook/compiler-options.html) to configure `ngc`.
|
||||
|
||||
<!-- links -->
|
||||
|
||||
[AioGuideI18nCommonPrepareMarkTextForTranslations]: guide/i18n-common-prepare#mark-text-for-translations "Mark text for translations - Prepare templates for translations | Angular"
|
||||
|
||||
<!-- end links -->
|
||||
|
||||
@reviewed 2021-08-18
|
||||
|
||||
@@ -3,21 +3,16 @@
|
||||
After you understand the basic Angular building blocks, you can learn more
|
||||
about the features and tools that can help you develop and deliver Angular applications.
|
||||
|
||||
* Work through the [Tour of Heroes](tutorial) tutorial to get a feel for how to fit the basic building blocks together to create a well-designed application.
|
||||
|
||||
* Check out the [Glossary](guide/glossary) to understand Angular-specific terms and usage.
|
||||
|
||||
* Use the documentation to learn about key features in more depth, according to your stage of development and areas of interest.
|
||||
* Work through the [Tour of Heroes](tutorial) tutorial to get a feel for how to fit the basic building blocks together to create a well-designed application.
|
||||
* Check out the [Glossary](guide/glossary) to understand Angular-specific terms and usage.
|
||||
* Use the documentation to learn about key features in more depth, according to your stage of development and areas of interest.
|
||||
|
||||
## Application architecture
|
||||
|
||||
* The **Main Concepts** section located in the table of contents contains several topics that explain how to connect the application data in your [components](guide/glossary#component) to your page-display [templates](guide/glossary#template), to create a complete interactive application.
|
||||
|
||||
* The [NgModules](guide/ngmodules) guide provides in-depth information on the modular structure of an Angular application.
|
||||
|
||||
* The [Routing and navigation](guide/router) guide provides in-depth information on how to construct applications that allow a user to navigate to different [views](guide/glossary#view) within your single-page application.
|
||||
|
||||
* The [Dependency injection](guide/dependency-injection) guide provides in-depth information on how to construct an application such that each component class can acquire the services and objects it needs to perform its function.
|
||||
* The **Main Concepts** section located in the table of contents contains several topics that explain how to connect the application data in your [components](guide/glossary#component) to your page-display [templates](guide/glossary#template), to create a complete interactive application.
|
||||
* The [NgModules](guide/ngmodules) guide provides in-depth information on the modular structure of an Angular application.
|
||||
* The [Routing and navigation](guide/router) guide provides in-depth information on how to construct applications that allow a user to navigate to different [views](guide/glossary#view) within your single-page application.
|
||||
* The [Dependency injection](guide/dependency-injection) guide provides in-depth information on how to construct an application such that each component class can acquire the services and objects it needs to perform its function.
|
||||
|
||||
## Responsive programming
|
||||
|
||||
@@ -25,15 +20,11 @@ The [template syntax](guide/template-syntax) and related topics contain details
|
||||
|
||||
Additional pages and sections describe some basic programming techniques for Angular applications.
|
||||
|
||||
* [Lifecycle hooks](guide/lifecycle-hooks): Tap into key moments in the lifetime of a component, from its creation to its destruction, by implementing the lifecycle hook interfaces.
|
||||
|
||||
* [Observables and event processing](guide/observables): How to use observables with components and services to publish and subscribe to messages of any type, such as user-interaction events and asynchronous operation results.
|
||||
|
||||
* [Angular elements](guide/elements): How to package components as *custom elements* using Web Components, a web standard for defining new HTML elements in a framework-agnostic way.
|
||||
|
||||
* [Forms](guide/forms-overview): Support complex data entry scenarios with HTML-based input validation.
|
||||
|
||||
* [Animations](guide/animations): Use Angular's animation library to animate component behavior
|
||||
* [Lifecycle hooks](guide/lifecycle-hooks): Tap into key moments in the lifetime of a component, from its creation to its destruction, by implementing the lifecycle hook interfaces.
|
||||
* [Observables and event processing](guide/observables): How to use observables with components and services to publish and subscribe to messages of any type, such as user-interaction events and asynchronous operation results.
|
||||
* [Angular elements](guide/elements): How to package components as *custom elements* using Web Components, a web standard for defining new HTML elements in a framework-agnostic way.
|
||||
* [Forms](guide/forms-overview): Support complex data entry scenarios with HTML-based input validation.
|
||||
* [Animations](guide/animations): Use Angular's animation library to animate component behavior
|
||||
without deep knowledge of animation techniques or CSS.
|
||||
|
||||
## Client-server interaction
|
||||
@@ -42,46 +33,39 @@ Angular provides a framework for single-page applications, where most of the log
|
||||
Most applications still need to access a server using the `HttpClient` to access and save data.
|
||||
For some platforms and applications, you might also want to use the PWA (Progressive Web App) model to improve the user experience.
|
||||
|
||||
* [HTTP](guide/http): Communicate with a server to get data, save data, and invoke server-side actions with an HTTP client.
|
||||
|
||||
* [Server-side rendering](guide/universal): Angular Universal generates static application pages on the server through server-side rendering (SSR). This allows you to run your Angular application on the server in order to improve performance and show the first page quickly on mobile and low-powered devices, and also facilitate web crawlers.
|
||||
|
||||
* [Service workers and PWA](guide/service-worker-intro): Use a service worker to reduce dependency on the network and significantly improve the user experience.
|
||||
|
||||
* [Web workers](guide/web-worker): Learn how to run CPU-intensive computations in a background thread.
|
||||
* [HTTP](guide/http): Communicate with a server to get data, save data, and invoke server-side actions with an HTTP client.
|
||||
* [Server-side rendering](guide/universal): Angular Universal generates static application pages on the server through server-side rendering (SSR). This allows you to run your Angular application on the server in order to improve performance and show the first page quickly on mobile and low-powered devices, and also facilitate web crawlers.
|
||||
* [Service workers and PWA](guide/service-worker-intro): Use a service worker to reduce dependency on the network and significantly improve the user experience.
|
||||
* [Web workers](guide/web-worker): Learn how to run CPU-intensive computations in a background thread.
|
||||
|
||||
## Support for the development cycle
|
||||
|
||||
* [CLI Command Reference](cli): The Angular CLI is a command-line tool that you use to create projects, generate application and library code, and perform a variety of ongoing development tasks such as testing, bundling, and deployment.
|
||||
|
||||
* [Compilation](guide/aot-compiler): Angular provides just-in-time (JIT) compilation for the development environment, and ahead-of-time (AOT) compilation for the production environment.
|
||||
|
||||
* [Testing platform](guide/testing): Run unit tests on your application parts as they interact with the Angular framework.
|
||||
|
||||
* [Deployment](guide/deployment): Learn techniques for deploying your Angular application to a remote server.
|
||||
|
||||
* [Security guidelines](guide/security): Learn about Angular's built-in protections against common web-application vulnerabilities and attacks such as cross-site scripting attacks.
|
||||
|
||||
* [Internationalization](guide/i18n): Make your application available in multiple languages with Angular's internationalization (i18n) tools.
|
||||
|
||||
* [Accessibility](guide/accessibility): Make your application accessible to all users.
|
||||
* [CLI Command Reference](cli): The Angular CLI is a command-line tool that you use to create projects, generate application and library code, and perform a variety of ongoing development tasks such as testing, bundling, and deployment.
|
||||
* [Compilation](guide/aot-compiler): Angular provides just-in-time (JIT) compilation for the development environment, and ahead-of-time (AOT) compilation for the production environment.
|
||||
* [Testing platform](guide/testing): Run unit tests on your application parts as they interact with the Angular framework.
|
||||
* [Deployment](guide/deployment): Learn techniques for deploying your Angular application to a remote server.
|
||||
* [Security guidelines](guide/security): Learn about Angular's built-in protections against common web-application vulnerabilities and attacks such as cross-site scripting attacks.
|
||||
* [Internationalization][AioGuideI18nOverview]: Make your application available in multiple languages with Angular's internationalization (i18n) tools.
|
||||
* [Accessibility](guide/accessibility): Make your application accessible to all users.
|
||||
|
||||
## File structure, configuration, and dependencies
|
||||
|
||||
* [Workspace and file structure](guide/file-structure): Understand the structure of Angular workspace and project folders.
|
||||
|
||||
* [Building and serving](guide/build): Learn to define different build and proxy server configurations for your project, such as development, staging, and production.
|
||||
|
||||
* [npm packages](guide/npm-packages): The Angular Framework, Angular CLI, and components used by Angular applications are packaged as [npm](https://docs.npmjs.com/) packages and distributed using the npm registry. The Angular CLI creates a default `package.json` file, which specifies a starter set of packages that work well together and jointly support many common application scenarios.
|
||||
|
||||
* [TypeScript configuration](guide/typescript-configuration): TypeScript is the primary language for Angular application development.
|
||||
|
||||
* [Browser support](guide/browser-support): Make your applications compatible across a wide range of browsers.
|
||||
* [Workspace and file structure](guide/file-structure): Understand the structure of Angular workspace and project folders.
|
||||
* [Building and serving](guide/build): Learn to define different build and proxy server configurations for your project, such as development, staging, and production.
|
||||
* [npm packages](guide/npm-packages): The Angular Framework, Angular CLI, and components used by Angular applications are packaged as [npm](https://docs.npmjs.com) packages and distributed using the npm registry. The Angular CLI creates a default `package.json` file, which specifies a starter set of packages that work well together and jointly support many common application scenarios.
|
||||
* [TypeScript configuration](guide/typescript-configuration): TypeScript is the primary language for Angular application development.
|
||||
* [Browser support](guide/browser-support): Make your applications compatible across a wide range of browsers.
|
||||
|
||||
## Extending Angular
|
||||
|
||||
* [Angular libraries](guide/libraries): Learn about using and creating re-usable libraries.
|
||||
* [Angular libraries](guide/libraries): Learn about using and creating re-usable libraries.
|
||||
* [Schematics](guide/schematics): Learn about customizing and extending the CLI's generation capabilities.
|
||||
* [CLI builders](guide/cli-builder): Learn about customizing and extending the CLI's ability to apply tools to perform complex tasks, such as building and testing applications.
|
||||
|
||||
* [Schematics](guide/schematics): Learn about customizing and extending the CLI's generation capabilities.
|
||||
<!-- links -->
|
||||
|
||||
* [CLI builders](guide/cli-builder): Learn about customizing and extending the CLI's ability to apply tools to perform complex tasks, such as building and testing applications.
|
||||
[AioGuideI18nOverview]: guide/i18n-overview "Angular Internationalization | Angular"
|
||||
|
||||
<!-- end links -->
|
||||
|
||||
@reviewed 2021-09-02
|
||||
|
||||
+222
-172
@@ -7,17 +7,14 @@ To make these transitions as easy as possible, we deprecate APIs and features fo
|
||||
|
||||
This guide contains a summary of all Angular APIs and features that are currently deprecated.
|
||||
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
|
||||
Features and APIs that were deprecated in v6 or earlier are candidates for removal in version 9 or any later major version. For information about Angular's deprecation and removal practices, see [Angular Release Practices](guide/releases#deprecation-practices "Angular Release Practices: Deprecation practices").
|
||||
|
||||
For step-by-step instructions on how to update to the latest Angular release, use the interactive update guide at [update.angular.io](https://update.angular.io).
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
## Index
|
||||
|
||||
To help you future-proof your projects, the following table lists all deprecated APIs and features, organized by the release in which they are candidates for removal. Each item is linked to the section later in this guide that describes the deprecation reason and replacement options.
|
||||
@@ -35,32 +32,31 @@ v11 - v14
|
||||
v12 - v15
|
||||
-->
|
||||
|
||||
|
||||
| Area | API or Feature | May be removed in |
|
||||
| ----------------------------- | --------------------------------------------------------------------------- | ----------------- |
|
||||
| `@angular/common` | [`ReflectiveInjector`](#reflectiveinjector) | <!--v8--> v11 |
|
||||
| `@angular/common` | [`CurrencyPipe` - `DEFAULT_CURRENCY_CODE`](api/common/CurrencyPipe#currency-code-deprecation) | <!--v9--> v11 |
|
||||
| `@angular/common/http` | [`XhrFactory`](api/common/http/XhrFactory) | <!--v12--> v15 |
|
||||
| `@angular/core` | [`DefaultIterableDiffer`](#core) | <!--v7--> v11 |
|
||||
| `@angular/core` | [`ReflectiveKey`](#core) | <!--v8--> v11 |
|
||||
| `@angular/core` | [`RenderComponentType`](#core) | <!--v7--> v11 |
|
||||
| `@angular/core` | [`WrappedValue`](#core) | <!--v10--> v12 |
|
||||
| `@angular/forms` | [`ngModel` with reactive forms](#ngmodel-reactive) | <!--v6--> v11 |
|
||||
| `@angular/upgrade` | [`@angular/upgrade`](#upgrade) | <!--v8--> v11 |
|
||||
| `@angular/upgrade` | [`getAngularLib`](#upgrade-static) | <!--v8--> v11 |
|
||||
| `@angular/upgrade` | [`setAngularLib`](#upgrade-static) | <!--v8--> v11 |
|
||||
| template syntax | [`<template`>](#template-tag) | <!--v7--> v11 |
|
||||
| polyfills | [reflect-metadata](#reflect-metadata) | <!--v8--> v11 |
|
||||
| npm package format | [`esm5` and `fesm5` entry-points in @angular/* npm packages](guide/deprecations#esm5-fesm5) | <!-- v9 --> v11 |
|
||||
| `@angular/core` | [`defineInjectable`](#core) | <!--v8--> v11 |
|
||||
| `@angular/core` | [`entryComponents`](api/core/NgModule#entryComponents) | <!--v9--> v11 |
|
||||
| `@angular/core` | [`ANALYZE_FOR_ENTRY_COMPONENTS`](api/core/ANALYZE_FOR_ENTRY_COMPONENTS) | <!--v9--> v11 |
|
||||
| `@angular/router` | [`loadChildren` string syntax](#loadChildren) | <!--v9--> v11 |
|
||||
| `@angular/core/testing` | [`TestBed.get`](#testing) | <!--v9--> v12 |
|
||||
| `@angular/core/testing` | [`async`](#testing) | <!--v9--> v12 |
|
||||
| `@angular/forms` | [`FormBuilder.group` legacy options parameter](api/forms/FormBuilder#group) | <!--v11--> v14 |
|
||||
| `@angular/router` | [`ActivatedRoute` params and `queryParams` properties](#activatedroute-props) | unspecified |
|
||||
| template syntax | [`/deep/`, `>>>`, and `::ng-deep`](#deep-component-style-selector) | <!--v7--> unspecified |
|
||||
| Area | API or Feature | May be removed in |
|
||||
|:--- |:--- |:--- |
|
||||
| `@angular/common` | [`ReflectiveInjector`](#reflectiveinjector) | <!--v8--> v11 |
|
||||
| `@angular/common` | [`CurrencyPipe` - `DEFAULT_CURRENCY_CODE`](api/common/CurrencyPipe#currency-code-deprecation) | <!--v9--> v11 |
|
||||
| `@angular/common/http` | [`XhrFactory`](api/common/http/XhrFactory) | <!--v12--> v15 |
|
||||
| `@angular/core` | [`DefaultIterableDiffer`](#core) | <!--v7--> v11 |
|
||||
| `@angular/core` | [`ReflectiveKey`](#core) | <!--v8--> v11 |
|
||||
| `@angular/core` | [`RenderComponentType`](#core) | <!--v7--> v11 |
|
||||
| `@angular/core` | [`WrappedValue`](#core) | <!--v10--> v12 |
|
||||
| `@angular/forms` | [`ngModel` with reactive forms](#ngmodel-reactive) | <!--v6--> v11 |
|
||||
| `@angular/upgrade` | [`@angular/upgrade`](#upgrade) | <!--v8--> v11 |
|
||||
| `@angular/upgrade` | [`getAngularLib`](#upgrade-static) | <!--v8--> v11 |
|
||||
| `@angular/upgrade` | [`setAngularLib`](#upgrade-static) | <!--v8--> v11 |
|
||||
| template syntax | [`<template>`](#template-tag) | <!--v7--> v11 |
|
||||
| polyfills | [reflect-metadata](#reflect-metadata) | <!--v8--> v11 |
|
||||
| npm package format | [`esm5` and `fesm5` entry-points in @angular/* npm packages](guide/deprecations#esm5-fesm5) | <!-- v9 --> v11 |
|
||||
| `@angular/core` | [`defineInjectable`](#core) | <!--v8--> v11 |
|
||||
| `@angular/core` | [`entryComponents`](api/core/NgModule#entryComponents) | <!--v9--> v11 |
|
||||
| `@angular/core` | [`ANALYZE_FOR_ENTRY_COMPONENTS`](api/core/ANALYZE_FOR_ENTRY_COMPONENTS) | <!--v9--> v11 |
|
||||
| `@angular/router` | [`loadChildren` string syntax](#loadChildren) | <!--v9--> v11 |
|
||||
| `@angular/core/testing` | [`TestBed.get`](#testing) | <!--v9--> v12 |
|
||||
| `@angular/core/testing` | [`async`](#testing) | <!--v9--> v12 |
|
||||
| `@angular/forms` | [`FormBuilder.group` legacy options parameter](api/forms/FormBuilder#group) | <!--v11--> v14 |
|
||||
| `@angular/router` | [`ActivatedRoute` params and `queryParams` properties](#activatedroute-props) | unspecified |
|
||||
| template syntax | [`/deep/`, `>>>`, and `::ng-deep`](#deep-component-style-selector) | <!--v7--> unspecified |
|
||||
|
||||
For information about Angular CDK and Angular Material deprecations, see the [changelog](https://github.com/angular/components/blob/master/CHANGELOG.md).
|
||||
|
||||
@@ -68,233 +64,238 @@ For information about Angular CDK and Angular Material deprecations, see the [ch
|
||||
|
||||
This section contains a complete list all of the currently-deprecated APIs, with details to help you plan your migration to a replacement.
|
||||
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
Tip: In the [API reference section](api) of this site, deprecated APIs are indicated by ~~strikethrough.~~ You can filter the API list by [**Status: deprecated**](api?status=deprecated).
|
||||
**TIP**: In the [API reference section](api) of this site, deprecated APIs are indicated by ~~strikethrough.~~ You can filter the API list by [**Status: deprecated**](api?status=deprecated).
|
||||
|
||||
</div>
|
||||
|
||||
{@a common}
|
||||
|
||||
### @angular/common
|
||||
|
||||
| API | Replacement | Deprecation announced | Notes |
|
||||
| --------------------------------------------------------------------------------------------- | --------------------------------------------------- | --------------------- | ----- |
|
||||
| API | Replacement | Deprecation announced | Notes |
|
||||
| :--- |:--- |:--- |:--- |
|
||||
| [`CurrencyPipe` - `DEFAULT_CURRENCY_CODE`](api/common/CurrencyPipe#currency-code-deprecation) | `{provide: DEFAULT_CURRENCY_CODE, useValue: 'USD'}` | v9 | From v11 the default code will be extracted from the locale data given by `LOCALE_ID`, rather than `USD`. |
|
||||
|
||||
|
||||
{@a common-http}
|
||||
|
||||
### @angular/common/http
|
||||
|
||||
| API | Replacement | Deprecation announced | Notes |
|
||||
| -------------------------------------------- | ------------------------------------ | --------------------- | ----- |
|
||||
| [`XhrFactory`](api/common/http/XhrFactory) | `XhrFactory` in `@angular/common` | v12 | The `XhrFactory` has moved from `@angular/common/http` to `@angular/common`. |
|
||||
|
||||
| API | Replacement | Deprecation announced | Notes |
|
||||
|:--- |:--- |:--- |:--- |
|
||||
| [`XhrFactory`](api/common/http/XhrFactory) | `XhrFactory` in `@angular/common` | v12 | The `XhrFactory` has moved from `@angular/common/http` to `@angular/common`. |
|
||||
|
||||
{@a core}
|
||||
|
||||
### @angular/core
|
||||
|
||||
| API | Replacement | Deprecation announced | Notes |
|
||||
| --- | ----------- | --------------------- | ----- |
|
||||
| [`DefaultIterableDiffer`](api/core/DefaultIterableDiffer) | n/a | v4 | Not part of public API. |
|
||||
| [`ReflectiveInjector`](api/core/ReflectiveInjector) | `{@link Injector#create Injector.create()}` | v5 | See [`ReflectiveInjector`](#reflectiveinjector) |
|
||||
| [`ReflectiveKey`](api/core/ReflectiveKey) | none | v5 | none |
|
||||
| [`defineInjectable`](api/core/defineInjectable) | `ɵɵdefineInjectable` | v8 | Used only in generated code. No source code should depend on this API. |
|
||||
| [`entryComponents`](api/core/NgModule#entryComponents) | none | v9 | See [`entryComponents`](#entryComponents) |
|
||||
| [`ANALYZE_FOR_ENTRY_COMPONENTS`](api/core/ANALYZE_FOR_ENTRY_COMPONENTS) | none | v9 | See [`ANALYZE_FOR_ENTRY_COMPONENTS`](#entryComponents) |
|
||||
| [`WrappedValue`](api/core/WrappedValue) | none | v10 | See [removing `WrappedValue`](#wrapped-value) |
|
||||
| [`async`](api/core/testing/async) | [`waitForAsync`](api/core/testing/waitForAsync) | v11 | The `async` function from `@angular/core/testing` has been renamed to `waitForAsync` in order to avoid confusion with the native JavaScript `async` syntax. The existing function is deprecated and will be removed in a future version. |
|
||||
[ `ViewChildren.emitDistinctChangesOnly` / `ContentChildren.emitDistinctChangesOnly` | none (was part of [issue #40091](https://github.com/angular/angular/issues/40091)) ] | This is a temporary flag introduced as part of bugfix of [issue #40091](https://github.com/angular/angular/issues/40091) and will be removed. |
|
||||
| API | Replacement | Deprecation announced | Notes |
|
||||
|:--- |:--- |:--- |:--- |
|
||||
| [`DefaultIterableDiffer`](api/core/DefaultIterableDiffer) | n/a | v4 | Not part of public API. |
|
||||
| [`ReflectiveInjector`](api/core/ReflectiveInjector) | `{@link Injector#create Injector.create()}` | v5 | See [`ReflectiveInjector`](#reflectiveinjector) |
|
||||
| [`ReflectiveKey`](api/core/ReflectiveKey) | none | v5 | none |
|
||||
| [`defineInjectable`](api/core/defineInjectable) | `ɵɵdefineInjectable` | v8 | Used only in generated code. No source code should depend on this API. |
|
||||
| [`entryComponents`](api/core/NgModule#entryComponents) | none | v9 | See [`entryComponents`](#entryComponents) |
|
||||
| [`ANALYZE_FOR_ENTRY_COMPONENTS`](api/core/ANALYZE_FOR_ENTRY_COMPONENTS) | none | v9 | See [`ANALYZE_FOR_ENTRY_COMPONENTS`](#entryComponents) |
|
||||
| [`WrappedValue`](api/core/WrappedValue) | none | v10 | See [removing `WrappedValue`](#wrapped-value) |
|
||||
| [`async`](api/core/testing/async) | [`waitForAsync`](api/core/testing/waitForAsync) | v11 | The `async` function from `@angular/core/testing` has been renamed to `waitForAsync` in order to avoid confusion with the native JavaScript `async` syntax. The existing function is deprecated and will be removed in a future version. |
|
||||
| `ViewChildren.emitDistinctChangesOnly` / `ContentChildren.emitDistinctChangesOnly` | none (was part of [issue #40091](https://github.com/angular/angular/issues/40091)) | | This is a temporary flag introduced as part of bugfix of [issue #40091](https://github.com/angular/angular/issues/40091) and will be removed. |
|
||||
|
||||
{@a testing}
|
||||
|
||||
### @angular/core/testing
|
||||
|
||||
| API | Replacement | Deprecation announced | Notes |
|
||||
| --- | ----------- | --------------------- | ----- |
|
||||
| [`TestBed.get`](api/core/testing/TestBed#get) | [`TestBed.inject`](api/core/testing/TestBed#inject) | v9 | Same behavior, but type safe. |
|
||||
| [`async`](api/core/testing/async) | [`waitForAsync`](api/core/testing/waitForAsync) | v10 | Same behavior, but rename to avoid confusion. |
|
||||
|
||||
| API | Replacement | Deprecation announced | Notes |
|
||||
|:--- |:--- |:--- |:--- |
|
||||
| [`TestBed.get`](api/core/testing/TestBed#get) | [`TestBed.inject`](api/core/testing/TestBed#inject) | v9 | Same behavior, but type safe. |
|
||||
| [`async`](api/core/testing/async) | [`waitForAsync`](api/core/testing/waitForAsync) | v10 | Same behavior, but rename to avoid confusion. |
|
||||
|
||||
{@a forms}
|
||||
|
||||
### @angular/forms
|
||||
|
||||
| API | Replacement | Deprecation announced | Notes |
|
||||
| --- | ----------- | --------------------- | ----- |
|
||||
| [`ngModel` with reactive forms](#ngmodel-reactive) | [`FormControlDirective`](api/forms/FormControlDirective) | v6 | none |
|
||||
| [`FormBuilder.group` legacy options parameter](api/forms/FormBuilder#group) | [`AbstractControlOptions` parameter value](api/forms/AbstractControlOptions) | v11 | none |
|
||||
|
||||
| API | Replacement | Deprecation announced | Notes |
|
||||
|:--- |:--- |:--- |:--- |
|
||||
| [`ngModel` with reactive forms](#ngmodel-reactive) | [`FormControlDirective`](api/forms/FormControlDirective) | v6 | none |
|
||||
| [`FormBuilder.group` legacy options parameter](api/forms/FormBuilder#group) | [`AbstractControlOptions` parameter value](api/forms/AbstractControlOptions) | v11 | none |
|
||||
|
||||
{@a upgrade}
|
||||
|
||||
### @angular/upgrade
|
||||
|
||||
| API | Replacement | Deprecation announced | Notes |
|
||||
| --- | ----------- | --------------------- | ----- |
|
||||
| [All entry points](api/upgrade) | [`@angular/upgrade/static`](api/upgrade/static) | v5 | See [Upgrading from AngularJS](guide/upgrade). |
|
||||
| API | Replacement | Deprecation announced | Notes |
|
||||
|:--- |:--- |:--- |:--- |
|
||||
| [All entry points](api/upgrade) | [`@angular/upgrade/static`](api/upgrade/static) | v5 | See [Upgrading from AngularJS](guide/upgrade). |
|
||||
|
||||
{@a upgrade-static}
|
||||
|
||||
### @angular/upgrade/static
|
||||
|
||||
| API | Replacement | Deprecation announced | Notes |
|
||||
| --- | ----------- | --------------------- | ----- |
|
||||
| [`getAngularLib`](api/upgrade/static/getAngularLib) | [`getAngularJSGlobal`](api/upgrade/static/getAngularJSGlobal) | v5 | See [Upgrading from AngularJS](guide/upgrade). |
|
||||
[`setAngularLib`](api/upgrade/static/setAngularLib) | [`setAngularJSGlobal`](api/upgrade/static/setAngularJSGlobal) | v5 | See [Upgrading from AngularJS](guide/upgrade). |
|
||||
|
||||
|
||||
| API | Replacement | Deprecation announced | Notes |
|
||||
|:--- |:--- |:--- |:--- |
|
||||
| [`getAngularLib`](api/upgrade/static/getAngularLib) | [`getAngularJSGlobal`](api/upgrade/static/getAngularJSGlobal) | v5 | See [Upgrading from AngularJS](guide/upgrade). |
|
||||
| [`setAngularLib`](api/upgrade/static/setAngularLib) | [`setAngularJSGlobal`](api/upgrade/static/setAngularJSGlobal) | v5 | See [Upgrading from AngularJS](guide/upgrade). |
|
||||
|
||||
{@a deprecated-features}
|
||||
|
||||
## Deprecated features
|
||||
|
||||
This section lists all of the currently-deprecated features, which includes template syntax, configuration options, and any other deprecations not listed in the [Deprecated APIs](#deprecated-apis) section above. It also includes deprecated API usage scenarios or API combinations, to augment the information above.
|
||||
|
||||
{@a bazelbuilder}
|
||||
|
||||
### Bazel builder and schematics
|
||||
|
||||
Bazel builder and schematics were introduced in Angular Labs to let users try out Bazel without having to manage Bazel version and BUILD files.
|
||||
This feature has been deprecated. For more information, please refer to the [migration doc](https://github.com/angular/angular/blob/master/packages/bazel/docs/BAZEL_SCHEMATICS.md).
|
||||
|
||||
{@a wtf}
|
||||
|
||||
### Web Tracing Framework integration
|
||||
|
||||
Angular previously supported an integration with the [Web Tracing Framework (WTF)](https://google.github.io/tracing-framework/) for performance testing of Angular applications. This integration has not been maintained and is now defunct. As a result, the integration was deprecated in Angular version 8, and due to no evidence of any existing usage, removed in version 9.
|
||||
|
||||
Angular previously supported an integration with the [Web Tracing Framework (WTF)](https://google.github.io/tracing-framework) for performance testing of Angular applications. This integration has not been maintained and is now defunct. As a result, the integration was deprecated in Angular version 8, and due to no evidence of any existing usage, removed in version 9.
|
||||
|
||||
{@a deep-component-style-selector}
|
||||
|
||||
### `/deep/`, `>>>`, and `::ng-deep` component style selectors
|
||||
|
||||
The shadow-dom-piercing descendant combinator is deprecated and support is being [removed from major browsers and tools](https://developers.google.com/web/updates/2017/10/remove-shadow-piercing). As such, in v4 we deprecated support in Angular for all three of `/deep/`, `>>>`, and `::ng-deep`. Until removal, `::ng-deep` is preferred for broader compatibility with the tools.
|
||||
|
||||
For more information, see [/deep/, >>>, and ::ng-deep](guide/component-styles#deprecated-deep--and-ng-deep "Component Styles guide, Deprecated deep and ngdeep")
|
||||
in the Component Styles guide.
|
||||
|
||||
For more information, see [/deep/, >>>, and ::ng-deep](guide/component-styles#deprecated-deep--and-ng-deep "Component Styles guide, Deprecated deep and ngdeep") in the Component Styles guide.
|
||||
|
||||
{@a template-tag}
|
||||
### <template> tag
|
||||
|
||||
### `<template>` tag
|
||||
|
||||
The `<template>` tag was deprecated in v4 to avoid colliding with the DOM's element of the same name (such as when using web components). Use `<ng-template>` instead. For more information, see the [Ahead-of-Time Compilation](guide/aot-compiler) guide.
|
||||
|
||||
|
||||
|
||||
{@a ngmodel-reactive}
|
||||
|
||||
### ngModel with reactive forms
|
||||
|
||||
Support for using the `ngModel` input property and `ngModelChange` event with reactive
|
||||
form directives has been deprecated in Angular v6 and will be removed in a future version
|
||||
of Angular.
|
||||
Support for using the `ngModel` input property and `ngModelChange` event with reactive form directives has been deprecated in Angular v6 and will be removed in a future version of Angular.
|
||||
|
||||
Now deprecated:
|
||||
|
||||
```html
|
||||
<input [formControl]="control" [(ngModel)]="value">
|
||||
```
|
||||
<code-example language="html">
|
||||
|
||||
<input [formControl]="control" [(ngModel)]="value">
|
||||
|
||||
</code-example>
|
||||
|
||||
<code-example language="typescript">
|
||||
|
||||
```ts
|
||||
this.value = 'some value';
|
||||
```
|
||||
|
||||
This support was deprecated for several reasons. First, developers found this pattern
|
||||
confusing. It seems like the actual `ngModel` directive is being used, but in fact it's
|
||||
an input/output property named `ngModel` on the reactive form directive that
|
||||
approximates some, but not all, of the directive's behavior.
|
||||
It allows getting and setting a value and intercepting value events, but
|
||||
some of `ngModel`'s other features, such as
|
||||
delaying updates with`ngModelOptions` or exporting the directive, don't work.
|
||||
</code-example>
|
||||
|
||||
In addition, this pattern mixes template-driven and reactive forms strategies, which
|
||||
prevents taking advantage of the full benefits of either strategy.
|
||||
Setting the value in the template violates the template-agnostic
|
||||
principles behind reactive forms, whereas adding a `FormControl`/`FormGroup` layer in
|
||||
the class removes the convenience of defining forms in the template.
|
||||
This support was deprecated for several reasons. First, developers found this pattern confusing. It seems like the actual `ngModel` directive is being used, but in fact it's an input/output property named `ngModel` on the reactive form directive that approximates some, but not all, of the directive's behavior.
|
||||
It allows getting and setting a value and intercepting value events, but some of `ngModel`'s other features, such as delaying updates with`ngModelOptions` or exporting the directive, don't work.
|
||||
|
||||
To update your code before support is removed, you'll want to decide whether to stick
|
||||
with reactive form directives (and get/set values using reactive forms patterns) or
|
||||
switch to template-driven directives.
|
||||
In addition, this pattern mixes template-driven and reactive forms strategies, which prevents taking advantage of the full benefits of either strategy.
|
||||
Setting the value in the template violates the template-agnostic principles behind reactive forms, whereas adding a `FormControl`/`FormGroup` layer in the class removes the convenience of defining forms in the template.
|
||||
|
||||
After (choice 1 - use reactive forms):
|
||||
To update your code before support is removed, you'll want to decide whether to stick with reactive form directives (and get/set values using reactive forms patterns) or switch to template-driven directives.
|
||||
|
||||
```html
|
||||
<input [formControl]="control">
|
||||
```
|
||||
**After** (choice 1 - use reactive forms):
|
||||
|
||||
<code-example language="html">
|
||||
|
||||
<input [formControl]="control">
|
||||
|
||||
</code-example>
|
||||
|
||||
<code-example language="typescript">
|
||||
|
||||
```ts
|
||||
this.control.setValue('some value');
|
||||
```
|
||||
|
||||
After (choice 2 - use template-driven forms):
|
||||
</code-example>
|
||||
|
||||
```html
|
||||
<input [(ngModel)]="value">
|
||||
```
|
||||
**After** (choice 2 - use template-driven forms):
|
||||
|
||||
<code-example language="html">
|
||||
|
||||
<input [(ngModel)]="value">
|
||||
|
||||
</code-example>
|
||||
|
||||
<code-example language="typescript">
|
||||
|
||||
```ts
|
||||
this.value = 'some value';
|
||||
```
|
||||
|
||||
By default, when you use this pattern, you will see a deprecation warning once in dev
|
||||
mode. You can choose to silence this warning by configuring
|
||||
`ReactiveFormsModule` at import time:
|
||||
</code-example>
|
||||
|
||||
By default, when you use this pattern, you will see a deprecation warning once in dev mode. You can choose to silence this warning by configuring `ReactiveFormsModule` at import time:
|
||||
|
||||
<code-example language="typescript">
|
||||
|
||||
```ts
|
||||
imports: [
|
||||
ReactiveFormsModule.withConfig({warnOnNgModelWithFormControl: 'never'});
|
||||
]
|
||||
```
|
||||
|
||||
Alternatively, you can choose to surface a separate warning for each instance of this
|
||||
pattern with a configuration value of `"always"`. This may help to track down where in the code
|
||||
the pattern is being used as the code is being updated.
|
||||
</code-example>
|
||||
|
||||
Alternatively, you can choose to surface a separate warning for each instance of this pattern with a configuration value of `"always"`. This may help to track down where in the code the pattern is being used as the code is being updated.
|
||||
|
||||
{@a reflectiveinjector}
|
||||
|
||||
### ReflectiveInjector
|
||||
|
||||
In v5, Angular replaced the `ReflectiveInjector` with the `StaticInjector`. The injector no longer requires the Reflect polyfill, reducing application size for most developers.
|
||||
|
||||
Before:
|
||||
**Before**:
|
||||
|
||||
<code-example language="typescript">
|
||||
|
||||
```
|
||||
ReflectiveInjector.resolveAndCreate(providers);
|
||||
```
|
||||
|
||||
After:
|
||||
</code-example>
|
||||
|
||||
**After**:
|
||||
|
||||
<code-example language="typescript">
|
||||
|
||||
```
|
||||
Injector.create({providers});
|
||||
```
|
||||
|
||||
</code-example>
|
||||
|
||||
{@a loadChildren}
|
||||
|
||||
### loadChildren string syntax
|
||||
|
||||
When Angular first introduced lazy routes, there wasn't browser support for dynamically loading additional JavaScript. Angular created our own scheme using the syntax `loadChildren: './lazy/lazy.module#LazyModule'` and built tooling to support it. Now that ECMAScript dynamic import is supported in many browsers, Angular is moving toward this new syntax.
|
||||
|
||||
In version 8, the string syntax for the [`loadChildren`](api/router/LoadChildren) route specification was deprecated, in favor of new syntax that uses `import()` syntax.
|
||||
|
||||
Before:
|
||||
**Before**:
|
||||
|
||||
<code-example language="typescript">
|
||||
|
||||
```
|
||||
const routes: Routes = [{
|
||||
path: 'lazy',
|
||||
// The following string syntax for loadChildren is deprecated
|
||||
loadChildren: './lazy/lazy.module#LazyModule'
|
||||
}];
|
||||
```
|
||||
|
||||
After:
|
||||
</code-example>
|
||||
|
||||
**After**:
|
||||
|
||||
<code-example language="typescript">
|
||||
|
||||
```
|
||||
const routes: Routes = [{
|
||||
path: 'lazy',
|
||||
// The new import() syntax
|
||||
loadChildren: () => import('./lazy/lazy.module').then(m => m.LazyModule)
|
||||
}];
|
||||
```
|
||||
|
||||
</code-example>
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
|
||||
**Version 8 update**: When you update to version 8, the [`ng update`](cli/update) command performs the transformation automatically. Prior to version 7, the `import()` syntax only works in JIT mode (with view engine).
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
<div class="alert is-helpful">
|
||||
@@ -303,8 +304,6 @@ const routes: Routes = [{
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
{@a activatedroute-props}
|
||||
|
||||
### ActivatedRoute params and queryParams properties
|
||||
@@ -318,9 +317,10 @@ const routes: Routes = [{
|
||||
|
||||
For more information see the [Getting route information](guide/router-reference#activated-route) section of the [Router guide](guide/router).
|
||||
|
||||
|
||||
{@a reflect-metadata}
|
||||
|
||||
### Dependency on a reflect-metadata polyfill in JIT mode
|
||||
|
||||
Angular applications, and specifically applications that relied on the JIT compiler, used to require a polyfill for the [reflect-metadata](https://github.com/rbuckton/reflect-metadata) APIs.
|
||||
|
||||
The need for this polyfill was removed in Angular version 8.0 ([see #14473](https://github.com/angular/angular-cli/pull/14473)), rendering the presence of the poylfill in most Angular applications unnecessary. Because the polyfill can be depended on by 3rd-party libraries, instead of removing it from all Angular projects, we are deprecating the requirement for this polyfill as of version 8.0. This should give library authors and application developers sufficient time to evaluate if they need the polyfill, and perform any refactoring necessary to remove the dependency on it.
|
||||
@@ -328,45 +328,56 @@ The need for this polyfill was removed in Angular version 8.0 ([see #14473](http
|
||||
In a typical Angular project, the polyfill is not used in production builds, so removing it should not impact production applications. The goal behind this removal is overall simplification of the build setup and decrease in the number of external dependencies.
|
||||
|
||||
{@a static-query-resolution}
|
||||
|
||||
### `@ViewChild()` / `@ContentChild()` static resolution as the default
|
||||
|
||||
See the [dedicated migration guide for static queries](guide/static-query-migration).
|
||||
|
||||
{@a contentchild-input-together}
|
||||
|
||||
### `@ContentChild()` / `@Input()` used together
|
||||
|
||||
The following pattern is deprecated:
|
||||
|
||||
```ts
|
||||
@Input() @ContentChild(TemplateRef) tpl !: TemplateRef<any>;
|
||||
```
|
||||
<code-example language="typescript">
|
||||
|
||||
@Input() @ContentChild(TemplateRef) tpl !: TemplateRef<any>;
|
||||
|
||||
</code-example>
|
||||
|
||||
Rather than using this pattern, separate the two decorators into their own
|
||||
properties and add fallback logic as in the following example:
|
||||
|
||||
```ts
|
||||
@Input() tpl !: TemplateRef<any>;
|
||||
@ContentChild(TemplateRef) inlineTemplate !: TemplateRef<any>;
|
||||
```
|
||||
<code-example language="typescript">
|
||||
|
||||
@Input() tpl !: TemplateRef<any>;
|
||||
@ContentChild(TemplateRef) inlineTemplate !: TemplateRef<any>;
|
||||
|
||||
</code-example>
|
||||
|
||||
{@a cant-assign-template-vars}
|
||||
|
||||
### Cannot assign to template variables
|
||||
|
||||
In the following example, the two-way binding means that `optionName`
|
||||
should be written when the `valueChange` event fires.
|
||||
|
||||
```html
|
||||
<option *ngFor="let optionName of options" [(value)]="optionName"></option>
|
||||
```
|
||||
<code-example language="html">
|
||||
|
||||
<option *ngFor="let optionName of options" [(value)]="optionName"></option>
|
||||
|
||||
</code-example>
|
||||
|
||||
However, in practice, Angular ignores two-way bindings to template variables. Starting in version 8, attempting to write to template variables is deprecated. In a future version, we will throw to indicate that the write is not supported.
|
||||
|
||||
```html
|
||||
<option *ngFor="let optionName of options" [value]="optionName"></option>
|
||||
```
|
||||
<code-example language="html">
|
||||
|
||||
<option *ngFor="let optionName of options" [value]="optionName"></option>
|
||||
|
||||
</code-example>
|
||||
|
||||
{@a binding-to-innertext}
|
||||
|
||||
### Binding to `innerText` in `platform-server`
|
||||
|
||||
[Domino](https://github.com/fgnass/domino), which is used in server-side rendering, doesn't support `innerText`, so in platform-server's "domino adapter", there was special code to fall back to `textContent` if you tried to bind to `innerText`.
|
||||
@@ -374,19 +385,23 @@ However, in practice, Angular ignores two-way bindings to template variables. St
|
||||
These two properties have subtle differences, so switching to `textContent` under the hood can be surprising to users. For this reason, we are deprecating this behavior. Going forward, users should explicitly bind to `textContent` when using Domino.
|
||||
|
||||
{@a wtf-apis}
|
||||
|
||||
### `wtfStartTimeRange` and all `wtf*` APIs
|
||||
|
||||
All of the `wtf*` APIs are deprecated and will be removed in a future version.
|
||||
|
||||
{@a entryComponents}
|
||||
|
||||
### `entryComponents` and `ANALYZE_FOR_ENTRY_COMPONENTS` no longer required
|
||||
|
||||
Previously, the `entryComponents` array in the `NgModule` definition was used to tell the compiler which components would be created and inserted dynamically.
|
||||
With Ivy, this isn't a requirement anymore and the `entryComponents` array can be removed from existing module declarations.
|
||||
The same applies to the `ANALYZE_FOR_ENTRY_COMPONENTS` injection token.
|
||||
|
||||
Note: You may still need to keep these if building a library that will be consumed by a View Engine application.
|
||||
**NOTE**: You may still need to keep these if building a library that will be consumed by a View Engine application.
|
||||
|
||||
{@a moduleWithProviders}
|
||||
|
||||
### `ModuleWithProviders` type without a generic
|
||||
|
||||
Some Angular libraries, such as `@angular/router` and `@ngrx/store`, implement APIs that return a type called `ModuleWithProviders` (typically using a method named `forRoot()`).
|
||||
@@ -394,13 +409,14 @@ This type represents an `NgModule` along with additional providers.
|
||||
Angular version 9 deprecates use of `ModuleWithProviders` without an explicitly generic type, where the generic type refers to the type of the `NgModule`.
|
||||
In a future version of Angular, the generic will no longer be optional.
|
||||
|
||||
|
||||
If you're using the CLI, `ng update` should [migrate your code automatically](guide/migration-module-with-providers).
|
||||
If you're not using the CLI, you can add any missing generic types to your application manually.
|
||||
For example:
|
||||
|
||||
**Before**
|
||||
```ts
|
||||
|
||||
<code-example language="typescript">
|
||||
|
||||
@NgModule({...})
|
||||
export class MyModule {
|
||||
static forRoot(config: SomeConfig): ModuleWithProviders {
|
||||
@@ -412,11 +428,13 @@ export class MyModule {
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
</code-example>
|
||||
|
||||
**After**:
|
||||
|
||||
<code-example language="typescript">
|
||||
|
||||
```ts
|
||||
@NgModule({...})
|
||||
export class MyModule {
|
||||
static forRoot(config: SomeConfig): ModuleWithProviders<SomeModule> {
|
||||
@@ -428,10 +446,12 @@ export class MyModule {
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</code-example>
|
||||
|
||||
{@a wrapped-value}
|
||||
### `WrappedValue`
|
||||
|
||||
### `WrappedValue`
|
||||
|
||||
The purpose of `WrappedValue` is to allow the same object instance to be treated as different for the purposes of change detection.
|
||||
It is commonly used with the `async` pipe in the case where the `Observable` produces the same instance of the value.
|
||||
@@ -440,23 +460,36 @@ Given that this use case is relatively rare and special handling impacts applica
|
||||
No replacement is planned for this deprecation.
|
||||
|
||||
If you rely on the behavior that the same object instance should cause change detection, you have two options:
|
||||
- Clone the resulting value so that it has a new identity.
|
||||
- Explicitly call [`ChangeDetectorRef.detectChanges()`](api/core/ChangeDetectorRef#detectchanges) to force the update.
|
||||
|
||||
* Clone the resulting value so that it has a new identity.
|
||||
* Explicitly call [`ChangeDetectorRef.detectChanges()`](api/core/ChangeDetectorRef#detectchanges) to force the update.
|
||||
|
||||
<!--
|
||||
### Internet Explorer 11
|
||||
|
||||
Angular support for Microsoft's Internet Explorer 11 (IE11) is deprecated and will be removed in Angular v13.
|
||||
Ending IE11 support allows Angular to take advantage of web platform APIs present only in evergreen browsers, resulting in better APIs for developers and more capabilities for application users.
|
||||
An additional motivation behind this removal is the drop in global usage of IE11 to just ~1% (as of March 2021).
|
||||
For full rationale and discussion behind this deprecation, see [RFC: Internet Explorer 11 support deprecation and removal](https://github.com/angular/angular/issues/41840).
|
||||
|
||||
***Note***: *IE11 will be supported in Angular v12 LTS releases through November 2022.*
|
||||
-->
|
||||
|
||||
{@a deprecated-cli-flags}
|
||||
|
||||
## Deprecated CLI APIs and Options
|
||||
|
||||
This section contains a complete list all of the currently deprecated CLI flags.
|
||||
|
||||
### @angular-devkit/build-angular
|
||||
|
||||
| API/Option | May be removed in | Notes |
|
||||
| ------------------------------- | ----------------- |-------------------------------------------------------------------------------- |
|
||||
| `extractCss` | <!--v11--> v13 | No longer required to disable CSS extraction during development. |
|
||||
| `i18nFormat` | <!--v9--> v12 | Format is now automatically detected. |
|
||||
| `i18nLocale` | <!--v9--> v12 | New [localization option](/guide/i18n#localize-config) in version 9 and later. |
|
||||
| `hmrWarning` | <!--v11--> v13 | No longer has an effect. |
|
||||
| `servePathDefaultWarning` | <!--v11--> v13 | No longer has an effect. |
|
||||
| API/Option | May be removed in | Notes |
|
||||
| ------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
|
||||
| `extractCss` | <!--v11--> v13 | No longer required to disable CSS extraction during development. |
|
||||
| `i18nFormat` | <!--v9--> v12 | Format is now automatically detected. |
|
||||
| `i18nLocale` | <!--v9--> v12 | New [localization option][AioGuideI18nCommonMergeDefineLocalesInTheBuildConfiguration] in version 9 and later. |
|
||||
| `hmrWarning` | <!--v11--> v13 | No longer has an effect. |
|
||||
| `servePathDefaultWarning` | <!--v11--> v13 | No longer has an effect. |
|
||||
|
||||
### @schematics/angular
|
||||
|
||||
@@ -465,6 +498,7 @@ This section contains a complete list all of the currently deprecated CLI flags.
|
||||
| `lintFix` | <!--v11--> v12 | Deprecated as part of TSLint deprecation. |
|
||||
|
||||
{@a removed}
|
||||
|
||||
## Removed APIs
|
||||
|
||||
The following APIs have been removed starting with version 11.0.0*:
|
||||
@@ -473,10 +507,10 @@ The following APIs have been removed starting with version 11.0.0*:
|
||||
| ---------------- | -------------- | ----------- | ----- |
|
||||
| `@angular/router` | `preserveQueryParams` | [`queryParamsHandling`](api/router/UrlCreationOptions#queryParamsHandling) | |
|
||||
|
||||
*To see APIs removed in version 10, check out this guide on the [version 10 docs site](https://v10.angular.io/guide/deprecations#removed).
|
||||
|
||||
\* To see APIs removed in version 10, check out this guide on the [version 10 docs site](https://v10.angular.io/guide/deprecations#removed).
|
||||
|
||||
{@a esm5-fesm5}
|
||||
|
||||
### `esm5` and `fesm5` code formats in @angular/* npm packages
|
||||
|
||||
As of Angular v8, the CLI primarily consumes the `fesm2015` variant of the code distributed as part of `@angular/*` npm packages.
|
||||
@@ -493,7 +527,9 @@ However, we do recommend that libraries ship their code in ES2015 format in orde
|
||||
In practical terms, the `package.json` of all `@angular` packages has changed in the following way:
|
||||
|
||||
**Before**:
|
||||
```
|
||||
|
||||
<code-example language="json" header="package.app.json">
|
||||
|
||||
{
|
||||
"name": "@angular/core",
|
||||
"version": "9.0.0",
|
||||
@@ -506,10 +542,13 @@ In practical terms, the `package.json` of all `@angular` packages has changed in
|
||||
"fesm2015": "./fesm2015/core.js",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
</code-example>
|
||||
|
||||
**After**:
|
||||
```
|
||||
|
||||
<code-example language="json" header="package.app.json">
|
||||
|
||||
{
|
||||
"name": "@angular/core",
|
||||
"version": "10.0.0",
|
||||
@@ -520,10 +559,21 @@ In practical terms, the `package.json` of all `@angular` packages has changed in
|
||||
"fesm2015": "./fesm2015/core.js",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
</code-example>
|
||||
|
||||
For more information about the npm package format, see the [Angular Package Format spec](https://goo.gl/jB3GVv).
|
||||
|
||||
{@a style-sanitization}
|
||||
|
||||
### Style Sanitization for `[style]` and `[style.prop]` bindings
|
||||
|
||||
Angular used to sanitize `[style]` and `[style.prop]` bindings to prevent malicious code from being inserted through `javascript:` expressions in CSS `url()` entries. However, most modern browsers no longer support the usage of these expressions, so sanitization was only maintained for the sake of IE 6 and 7. Given that Angular does not support either IE 6 or 7 and sanitization has a performance cost, we will no longer sanitize style bindings as of version 10 of Angular.
|
||||
|
||||
<!-- links -->
|
||||
|
||||
[AioGuideI18nCommonMergeDefineLocalesInTheBuildConfiguration]: guide/i18n-common-merge#define-locales-in-the-build-configuration "Define locales in the build configuration - Common Internationalization task #6: Merge translations into the application | Angular"
|
||||
|
||||
<!-- end links -->
|
||||
|
||||
@reviewed 2021-09-02
|
||||
|
||||
+36
-14
@@ -7,15 +7,15 @@ With the version 9 release of Angular, the new compiler and runtime instructions
|
||||
|
||||
Learn more about the [Compiler](https://www.youtube.com/watch?v=anphffaCZrQ) and [Runtime](https://www.youtube.com/watch?v=S0o-4yc2n-8) in these videos from our team.
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
{@a aot-and-ivy}
|
||||
|
||||
## AOT and Ivy
|
||||
|
||||
AOT compilation with Ivy is faster and should be used by default.
|
||||
In the `angular.json` workspace configuration file, set the default build options for your project to always use AOT compilation.
|
||||
When using application internationalization (i18n) with Ivy, [translation merging](guide/i18n#merge) also requires the use of AOT compilation.
|
||||
When using application internationalization (i18n) with Ivy, [translation merging][AioGuideI18nCommonMerge] also requires the use of AOT compilation.
|
||||
|
||||
<code-example language="json" header="angular.json">
|
||||
|
||||
@@ -33,6 +33,7 @@ When using application internationalization (i18n) with Ivy, [translation mergin
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
</code-example>
|
||||
|
||||
## Ivy and libraries
|
||||
@@ -44,6 +45,7 @@ CLI commands run `ngcc` as needed when performing an Angular build.
|
||||
For more information on how to publish libraries see [Publishing your Library](guide/creating-libraries#publishing-your-library).
|
||||
|
||||
{@a maintaining-library-compatibility}
|
||||
|
||||
### Maintaining library compatibility
|
||||
|
||||
If you are a library author, you should keep using the View Engine compiler as of version 9.
|
||||
@@ -53,28 +55,33 @@ See the [Creating Libraries](guide/creating-libraries) guide for more on how to
|
||||
When you use the tools integrated into the Angular CLI or `ng-packagr`, your library will always be built the right way automatically.
|
||||
|
||||
{@a ivy-and-universal-app-shell}
|
||||
|
||||
## Ivy and Universal/App shell
|
||||
|
||||
In version 9, the server builder which is used for [App shell](guide/app-shell) and [Angular Universal](guide/universal) has the `bundleDependencies` option enabled by default.
|
||||
If you opt-out of bundling dependencies you will need to run the standalone Angular compatibility compiler (`ngcc`). This is needed because otherwise Node will be unable to resolve the Ivy version of the packages.
|
||||
|
||||
You can run `ngcc` after each installation of node_modules by adding a `postinstall` [npm script](https://docs.npmjs.com/misc/scripts):
|
||||
|
||||
<code-example language="json" header="package.json">
|
||||
|
||||
{
|
||||
"scripts": {
|
||||
"postinstall": "ngcc"
|
||||
}
|
||||
}
|
||||
|
||||
</code-example>
|
||||
|
||||
<div class="alert is-important">
|
||||
|
||||
* The `postinstall` script will run on every installation of `node_modules`, including those performed by `ng update` and `ng add`.
|
||||
* Don't use `--create-ivy-entry-points` as this will cause Node not to resolve the Ivy version of the packages correctly.
|
||||
|
||||
* The `postinstall` script will run on every installation of `node_modules`, including those performed by `ng update` and `ng add`.
|
||||
* Don't use `--create-ivy-entry-points` as this will cause Node not to resolve the Ivy version of the packages correctly.
|
||||
|
||||
</div>
|
||||
|
||||
{@a opting-out-of-angular-ivy}
|
||||
|
||||
## Opting out of Ivy in version 9
|
||||
|
||||
In version 9, Ivy is the default.
|
||||
@@ -93,6 +100,7 @@ The value of the `enableIvy` flag is set to `true` by default, as of version 9.
|
||||
The following example shows how to set the `enableIvy` option to `false` in order to opt out of Ivy.
|
||||
|
||||
<code-example language="json" header="tsconfig.app.json">
|
||||
|
||||
{
|
||||
"extends": "./tsconfig.json",
|
||||
"compilerOptions": {
|
||||
@@ -110,6 +118,7 @@ The following example shows how to set the `enableIvy` option to `false` in orde
|
||||
"enableIvy": false
|
||||
}
|
||||
}
|
||||
|
||||
</code-example>
|
||||
|
||||
<div class="alert is-important">
|
||||
@@ -125,23 +134,27 @@ If you disable Ivy and the project uses internationalization, you can also remov
|
||||
To remove, delete the `import '@angular/localize/init';` line from the polyfills file.
|
||||
|
||||
<code-example language="typescript" header="polyfills.ts">
|
||||
|
||||
/***************************************************************************************************
|
||||
* Load `$localize` onto the global scope - used if i18n tags appear in Angular templates.
|
||||
*/
|
||||
import '@angular/localize/init';
|
||||
|
||||
</code-example>
|
||||
|
||||
{@a using-ssr-without-angular-ivy}
|
||||
|
||||
### Using SSR without Ivy
|
||||
|
||||
If you opt out of Ivy and your application uses [Angular Universal](guide/universal) to render Angular applications on the server, you must also change the way the server performs bootstrapping.
|
||||
If you opt out of Ivy and your application uses [Angular Universal](guide/universal) to render Angular applications on the server, you must also change the way the server performs bootstrapping.
|
||||
|
||||
The following example shows how you modify the `server.ts` file to provide the `AppServerModuleNgFactory` as the bootstrap module.
|
||||
|
||||
* Import `AppServerModuleNgFactory` from the `app.server.module.ngfactory` virtual file.
|
||||
* Set `bootstrap: AppServerModuleNgFactory` in the `ngExpressEngine` call.
|
||||
* Import `AppServerModuleNgFactory` from the `app.server.module.ngfactory` virtual file.
|
||||
* Set `bootstrap: AppServerModuleNgFactory` in the `ngExpressEngine` call.
|
||||
|
||||
<code-example language="typescript" header="server.ts">
|
||||
|
||||
import 'zone.js/node';
|
||||
|
||||
import { ngExpressEngine } from '@nguniversal/express-engine';
|
||||
@@ -156,33 +169,33 @@ import { AppServerModuleNgFactory } from './src/app/app.server.module.ngfactory'
|
||||
export function app() {
|
||||
const server = express();
|
||||
const distFolder = join(process.cwd(), 'dist/ivy-test/browser');
|
||||
|
||||
|
||||
// Our Universal express-engine (found @ https://github.com/angular/universal/tree/master/modules/express-engine)
|
||||
server.engine('html', ngExpressEngine({
|
||||
bootstrap: AppServerModuleNgFactory,
|
||||
}));
|
||||
|
||||
|
||||
server.set('view engine', 'html');
|
||||
server.set('views', distFolder);
|
||||
|
||||
|
||||
// Example Express Rest API endpoints
|
||||
// app.get('/api/**', (req, res) => { });
|
||||
// Serve static files from /browser
|
||||
server.get('*.*', express.static(distFolder, {
|
||||
maxAge: '1y'
|
||||
}));
|
||||
|
||||
|
||||
// All regular routes use the Universal engine
|
||||
server.get('*', (req, res) => {
|
||||
res.render('index', { req, providers: [{ provide: APP_BASE_HREF, useValue: req.baseUrl }] });
|
||||
});
|
||||
|
||||
|
||||
return server;
|
||||
}
|
||||
|
||||
function run() {
|
||||
const port = process.env.PORT || 4000;
|
||||
|
||||
|
||||
// Start up the Node server
|
||||
const server = app();
|
||||
server.listen(port, () => {
|
||||
@@ -200,4 +213,13 @@ if (mainModule && mainModule.filename === __filename) {
|
||||
}
|
||||
|
||||
export * from './src/main.server';
|
||||
|
||||
</code-example>
|
||||
|
||||
<!-- links -->
|
||||
|
||||
[AioGuideI18nCommonMerge]: guide/i18n-common-merge "Common Internationalization task #6: Merge translations into the application | Angular"
|
||||
|
||||
<!-- end links -->
|
||||
|
||||
@reviewed 2021-09-02
|
||||
|
||||
+59
-120
@@ -6,24 +6,24 @@ For example, you would use a pipe to show a date as **April 15, 1988** rather th
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
For the sample application used in this topic, see the <live-example></live-example>.
|
||||
For the sample application used in this topic, see the <live-example></live-example>.
|
||||
|
||||
</div>
|
||||
|
||||
Angular provides built-in pipes for typical data transformations, including transformations for internationalization (i18n), which use locale information to format data.
|
||||
The following are commonly used built-in pipes for data formatting:
|
||||
|
||||
* [`DatePipe`](api/common/DatePipe): Formats a date value according to locale rules.
|
||||
* [`UpperCasePipe`](api/common/UpperCasePipe): Transforms text to all upper case.
|
||||
* [`LowerCasePipe`](api/common/LowerCasePipe): Transforms text to all lower case.
|
||||
* [`CurrencyPipe`](api/common/CurrencyPipe): Transforms a number to a currency string, formatted according to locale rules.
|
||||
* [`DecimalPipe`](/api/common/DecimalPipe): Transforms a number into a string with a decimal point, formatted according to locale rules.
|
||||
* [`PercentPipe`](api/common/PercentPipe): Transforms a number to a percentage string, formatted according to locale rules.
|
||||
* [`DatePipe`](api/common/DatePipe): Formats a date value according to locale rules.
|
||||
* [`UpperCasePipe`](api/common/UpperCasePipe): Transforms text to all upper case.
|
||||
* [`LowerCasePipe`](api/common/LowerCasePipe): Transforms text to all lower case.
|
||||
* [`CurrencyPipe`](api/common/CurrencyPipe): Transforms a number to a currency string, formatted according to locale rules.
|
||||
* [`DecimalPipe`](/api/common/DecimalPipe): Transforms a number into a string with a decimal point, formatted according to locale rules.
|
||||
* [`PercentPipe`](api/common/PercentPipe): Transforms a number to a percentage string, formatted according to locale rules.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
* For a complete list of built-in pipes, see the [pipes API documentation](/api/common#pipes "Pipes API reference summary").
|
||||
* To learn more about using pipes for internationalization (i18n) efforts, see [formatting data based on locale](/guide/i18n#i18n-pipes "Formatting data based on locale").
|
||||
* For a complete list of built-in pipes, see the [pipes API documentation](/api/common#pipes "Pipes API reference summary").
|
||||
* To learn more about using pipes for internationalization (i18n) efforts, see [formatting data based on locale][AioGuideI18nCommonFormatDataLocale].
|
||||
|
||||
</div>
|
||||
|
||||
@@ -33,28 +33,21 @@ Create pipes to encapsulate custom transformations and use your custom pipes in
|
||||
|
||||
To use pipes you should have a basic understanding of the following:
|
||||
|
||||
* [Typescript](guide/glossary#typescript "Definition of Typescript") and HTML5 programming
|
||||
* [Templates](guide/glossary#template "Definition of a template") in HTML with CSS styles
|
||||
* [Components](guide/glossary#component "Definition of a component")
|
||||
* [Typescript](guide/glossary#typescript "Definition of Typescript") and HTML5 programming
|
||||
* [Templates](guide/glossary#template "Definition of a template") in HTML with CSS styles
|
||||
* [Components](guide/glossary#component "Definition of a component")
|
||||
|
||||
## Using a pipe in a template
|
||||
|
||||
To apply a pipe, use the pipe operator (`|`) within a template expression as shown in the following code example, along with the *name* of the pipe, which is `date` for the built-in [`DatePipe`](api/common/DatePipe).
|
||||
The tabs in the example show the following:
|
||||
|
||||
* `app.component.html` uses `date` in a separate template to display a birthday.
|
||||
* `hero-birthday1.component.ts` uses the same pipe as part of an in-line template in a component that also sets the birthday value.
|
||||
* `app.component.html` uses `date` in a separate template to display a birthday.
|
||||
* `hero-birthday1.component.ts` uses the same pipe as part of an in-line template in a component that also sets the birthday value.
|
||||
|
||||
<code-tabs>
|
||||
<code-pane
|
||||
header="src/app/app.component.html"
|
||||
region="hero-birthday-template"
|
||||
path="pipes/src/app/app.component.html">
|
||||
</code-pane>
|
||||
<code-pane
|
||||
header="src/app/hero-birthday1.component.ts"
|
||||
path="pipes/src/app/hero-birthday1.component.ts">
|
||||
</code-pane>
|
||||
<code-pane header="src/app/app.component.html" region="hero-birthday-template" path="pipes/src/app/app.component.html"></code-pane>
|
||||
<code-pane header="src/app/hero-birthday1.component.ts" path="pipes/src/app/hero-birthday1.component.ts"></code-pane>
|
||||
</code-tabs>
|
||||
|
||||
The component's `birthday` value flows through the pipe operator, `|` to the [`date`](api/common/DatePipe) function.
|
||||
@@ -77,27 +70,15 @@ Some pipes require at least one parameter and allow more optional parameters, su
|
||||
|
||||
The tabs in the following example demonstrates toggling between two different formats (`'shortDate'` and `'fullDate'`):
|
||||
|
||||
* The `app.component.html` template uses a format parameter for the [`DatePipe`](api/common/DatePipe) (named `date`) to show the date as **04/15/88**.
|
||||
* The `hero-birthday2.component.ts` component binds the pipe's format parameter to the component's `format` property in the `template` section, and adds a button for a click event bound to the component's `toggleFormat()` method.
|
||||
* The `hero-birthday2.component.ts` component's `toggleFormat()` method toggles the component's `format` property between a short form
|
||||
* The `app.component.html` template uses a format parameter for the [`DatePipe`](api/common/DatePipe) (named `date`) to show the date as **04/15/88**.
|
||||
* The `hero-birthday2.component.ts` component binds the pipe's format parameter to the component's `format` property in the `template` section, and adds a button for a click event bound to the component's `toggleFormat()` method.
|
||||
* The `hero-birthday2.component.ts` component's `toggleFormat()` method toggles the component's `format` property between a short form
|
||||
(`'shortDate'`) and a longer form (`'fullDate'`).
|
||||
|
||||
<code-tabs>
|
||||
<code-pane
|
||||
header="src/app/app.component.html"
|
||||
region="format-birthday"
|
||||
path="pipes/src/app/app.component.html">
|
||||
</code-pane>
|
||||
<code-pane
|
||||
header="src/app/hero-birthday2.component.ts (template)"
|
||||
region="template"
|
||||
path="pipes/src/app/hero-birthday2.component.ts">
|
||||
</code-pane>
|
||||
<code-pane
|
||||
header="src/app/hero-birthday2.component.ts (class)"
|
||||
region="class"
|
||||
path="pipes/src/app/hero-birthday2.component.ts">
|
||||
</code-pane>
|
||||
<code-pane header="src/app/app.component.html" region="format-birthday" path="pipes/src/app/app.component.html"></code-pane>
|
||||
<code-pane header="src/app/hero-birthday2.component.ts (template)" region="template" path="pipes/src/app/hero-birthday2.component.ts"></code-pane>
|
||||
<code-pane header="src/app/hero-birthday2.component.ts (class)" region="class" path="pipes/src/app/hero-birthday2.component.ts"></code-pane>
|
||||
</code-tabs>
|
||||
|
||||
Clicking the **Toggle Format** button alternates the date format between **04/15/1988** and **Friday, April 15, 1988**.
|
||||
@@ -117,16 +98,8 @@ The first tab for the `src/app/app.component.html` template chains `DatePipe` an
|
||||
The second tab for the `src/app/app.component.html` template passes the `fullDate` parameter to `date` before chaining to `uppercase`, which produces **FRIDAY, APRIL 15, 1988**.
|
||||
|
||||
<code-tabs>
|
||||
<code-pane
|
||||
header="src/app/app.component.html (1)"
|
||||
region="chained-birthday"
|
||||
path="pipes/src/app/app.component.html">
|
||||
</code-pane>
|
||||
<code-pane
|
||||
header="src/app/app.component.html (2)"
|
||||
region="chained-parameter-birthday"
|
||||
path="pipes/src/app/app.component.html">
|
||||
</code-pane>
|
||||
<code-pane header="src/app/app.component.html (1)" region="chained-birthday" path="pipes/src/app/app.component.html"></code-pane>
|
||||
<code-pane header="src/app/app.component.html (2)" region="chained-parameter-birthday" path="pipes/src/app/app.component.html"></code-pane>
|
||||
</code-tabs>
|
||||
|
||||
{@a Custom-pipes}
|
||||
@@ -147,8 +120,8 @@ Use `name` in template expressions as you would for a built-in pipe.
|
||||
|
||||
<div class="alert is-important">
|
||||
|
||||
* Include your pipe in the `declarations` field of the `NgModule` metadata in order for it to be available to a template. See the `app.module.ts` file in the example application (<live-example></live-example>). For details, see [NgModules](guide/ngmodules "NgModules introduction").
|
||||
* Register your custom pipes. The [Angular CLI](cli "CLI Overview and Command Reference") [`ng generate pipe`](cli/generate#pipe "ng generate pipe in the CLI Command Reference") command registers the pipe automatically.
|
||||
* Include your pipe in the `declarations` field of the `NgModule` metadata in order for it to be available to a template. See the `app.module.ts` file in the example application (<live-example></live-example>). For details, see [NgModules](guide/ngmodules "NgModules introduction").
|
||||
* Register your custom pipes. The [Angular CLI](cli "CLI Overview and Command Reference") [`ng generate pipe`](cli/generate#pipe "ng generate pipe in the CLI Command Reference") command registers the pipe automatically.
|
||||
|
||||
</div>
|
||||
|
||||
@@ -166,20 +139,13 @@ Use a custom pipe for this transformation.
|
||||
|
||||
The following code example shows two component definitions:
|
||||
|
||||
* The `exponential-strength.pipe.ts` component defines a custom pipe named `exponentialStrength` with the `transform` method that performs the transformation.
|
||||
It defines an argument to the `transform` method (`exponent`) for a parameter passed to the pipe.
|
||||
|
||||
* The `power-booster.component.ts` component demonstrates how to use the pipe, specifying a value (`2`) and the exponent parameter (`10`).
|
||||
* The `exponential-strength.pipe.ts` component defines a custom pipe named `exponentialStrength` with the `transform` method that performs the transformation.
|
||||
It defines an argument to the `transform` method (`exponent`) for a parameter passed to the pipe.
|
||||
* The `power-booster.component.ts` component demonstrates how to use the pipe, specifying a value (`2`) and the exponent parameter (`10`).
|
||||
|
||||
<code-tabs>
|
||||
<code-pane
|
||||
header="src/app/exponential-strength.pipe.ts"
|
||||
path="pipes/src/app/exponential-strength.pipe.ts">
|
||||
</code-pane>
|
||||
<code-pane
|
||||
header="src/app/power-booster.component.ts"
|
||||
path="pipes/src/app/power-booster.component.ts">
|
||||
</code-pane>
|
||||
<code-pane header="src/app/exponential-strength.pipe.ts" path="pipes/src/app/exponential-strength.pipe.ts"></code-pane>
|
||||
<code-pane header="src/app/power-booster.component.ts" path="pipes/src/app/power-booster.component.ts"></code-pane>
|
||||
</code-tabs>
|
||||
|
||||
The browser displays the following:
|
||||
@@ -207,9 +173,7 @@ If the data is a primitive input value, such as `String` or `Number`, or an obje
|
||||
|
||||
For example, you could change the previous custom pipe example to use two-way data binding with `ngModel` to input the amount and boost factor, as shown in the following code example.
|
||||
|
||||
<code-example path="pipes/src/app/power-boost-calculator.component.ts" header="src/app/power-boost-calculator.component.ts">
|
||||
|
||||
</code-example>
|
||||
<code-example path="pipes/src/app/power-boost-calculator.component.ts" header="src/app/power-boost-calculator.component.ts"></code-example>
|
||||
|
||||
The `exponentialStrength` pipe executes every time the user changes the "normal power" value or the "boost factor".
|
||||
|
||||
@@ -223,20 +187,12 @@ Angular looks for changes to data-bound values in a [change detection](guide/glo
|
||||
The following example, which doesn't use a pipe, demonstrates how Angular uses its default change detection strategy to monitor and update its display of every hero in the `heroes` array.
|
||||
The example tabs show the following:
|
||||
|
||||
* In the `flying-heroes.component.html (v1)` template, the `*ngFor` repeater displays the hero names.
|
||||
* Its companion component class `flying-heroes.component.ts (v1)` provides heroes, adds heroes into the array, and resets the array.
|
||||
* In the `flying-heroes.component.html (v1)` template, the `*ngFor` repeater displays the hero names.
|
||||
* Its companion component class `flying-heroes.component.ts (v1)` provides heroes, adds heroes into the array, and resets the array.
|
||||
|
||||
<code-tabs>
|
||||
<code-pane
|
||||
header="src/app/flying-heroes.component.html (v1)"
|
||||
region="template-1"
|
||||
path="pipes/src/app/flying-heroes.component.html">
|
||||
</code-pane>
|
||||
<code-pane
|
||||
header="src/app/flying-heroes.component.ts (v1)"
|
||||
region="v1"
|
||||
path="pipes/src/app/flying-heroes.component.ts">
|
||||
</code-pane>
|
||||
<code-pane header="src/app/flying-heroes.component.html (v1)" region="template-1" path="pipes/src/app/flying-heroes.component.html"></code-pane>
|
||||
<code-pane header="src/app/flying-heroes.component.ts (v1)" region="v1" path="pipes/src/app/flying-heroes.component.ts"></code-pane>
|
||||
</code-tabs>
|
||||
|
||||
Angular updates the display every time the user adds a hero.
|
||||
@@ -266,20 +222,12 @@ To demonstrate this issue, change the previous example to filter the list of her
|
||||
Use the `FlyingHeroesPipe` in the `*ngFor` repeater as shown in the following code.
|
||||
The tabs for the example show the following:
|
||||
|
||||
* The template (`flying-heroes.component.html (flyers)`) with the new pipe.
|
||||
* The `FlyingHeroesPipe` custom pipe implementation (`flying-heroes.pipe.ts`).
|
||||
* The template (`flying-heroes.component.html (flyers)`) with the new pipe.
|
||||
* The `FlyingHeroesPipe` custom pipe implementation (`flying-heroes.pipe.ts`).
|
||||
|
||||
<code-tabs>
|
||||
<code-pane
|
||||
header="src/app/flying-heroes.component.html (flyers)"
|
||||
region="template-flying-heroes"
|
||||
path="pipes/src/app/flying-heroes.component.html">
|
||||
</code-pane>
|
||||
<code-pane
|
||||
header="src/app/flying-heroes.pipe.ts"
|
||||
region="pure"
|
||||
path="pipes/src/app/flying-heroes.pipe.ts">
|
||||
</code-pane>
|
||||
<code-pane header="src/app/flying-heroes.component.html (flyers)" region="template-flying-heroes" path="pipes/src/app/flying-heroes.component.html"></code-pane>
|
||||
<code-pane header="src/app/flying-heroes.pipe.ts" region="pure" path="pipes/src/app/flying-heroes.pipe.ts"></code-pane>
|
||||
</code-tabs>
|
||||
|
||||
The application now shows unexpected behavior: When the user adds flying heroes, none of them appear under "Heroes who fly."
|
||||
@@ -324,16 +272,8 @@ The following code shows the complete implementation of `FlyingHeroesImpurePipe`
|
||||
The example shows that you don't have to change anything else—the only difference is setting the `pure` flag as `false` in the pipe metadata.
|
||||
|
||||
<code-tabs>
|
||||
<code-pane
|
||||
header="src/app/flying-heroes.pipe.ts (FlyingHeroesImpurePipe)"
|
||||
region="impure"
|
||||
path="pipes/src/app/flying-heroes.pipe.ts">
|
||||
</code-pane>
|
||||
<code-pane
|
||||
header="src/app/flying-heroes.pipe.ts (FlyingHeroesPipe)"
|
||||
region="pure"
|
||||
path="pipes/src/app/flying-heroes.pipe.ts">
|
||||
</code-pane>
|
||||
<code-pane header="src/app/flying-heroes.pipe.ts (FlyingHeroesImpurePipe)" region="impure" path="pipes/src/app/flying-heroes.pipe.ts"></code-pane>
|
||||
<code-pane header="src/app/flying-heroes.pipe.ts (FlyingHeroesPipe)" region="pure" path="pipes/src/app/flying-heroes.pipe.ts"></code-pane>
|
||||
</code-tabs>
|
||||
|
||||
`FlyingHeroesImpurePipe` is a good candidate for an impure pipe because the `transform` function is trivial and fast:
|
||||
@@ -347,7 +287,7 @@ As shown in the following code, only the pipe in the template changes.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
To confirm that the display updates as the user adds heroes, see the <live-example></live-example>.
|
||||
To confirm that the display updates as the user adds heroes, see the <live-example></live-example>.
|
||||
|
||||
</div>
|
||||
|
||||
@@ -371,9 +311,7 @@ Without this pipe, your component code would have to subscribe to the observable
|
||||
The following code example binds an observable of message strings
|
||||
(`message$`) to a view with the `async` pipe.
|
||||
|
||||
<code-example path="pipes/src/app/hero-async-message.component.ts" header="src/app/hero-async-message.component.ts">
|
||||
|
||||
</code-example>
|
||||
<code-example path="pipes/src/app/hero-async-message.component.ts" header="src/app/hero-async-message.component.ts"></code-example>
|
||||
|
||||
{@a no-filter-pipe}
|
||||
|
||||
@@ -389,24 +327,18 @@ Impure pipes are called whenever change detection runs for a component, which co
|
||||
To avoid performance problems, call the server only when the requested URL changes, as shown in the following example, and use the pipe to cache the server response.
|
||||
The tabs show the following:
|
||||
|
||||
* The `fetch` pipe (`fetch-json.pipe.ts`).
|
||||
* A harness component (`hero-list.component.ts`) for demonstrating the request, using a template that defines two bindings to the pipe requesting the heroes from the `heroes.json` file. The second binding chains the `fetch` pipe with the built-in `JsonPipe` to display the same hero data in JSON format.
|
||||
* The `fetch` pipe (`fetch-json.pipe.ts`).
|
||||
* A harness component (`hero-list.component.ts`) for demonstrating the request, using a template that defines two bindings to the pipe requesting the heroes from the `heroes.json` file. The second binding chains the `fetch` pipe with the built-in `JsonPipe` to display the same hero data in JSON format.
|
||||
|
||||
<code-tabs>
|
||||
<code-pane
|
||||
header="src/app/fetch-json.pipe.ts"
|
||||
path="pipes/src/app/fetch-json.pipe.ts">
|
||||
</code-pane>
|
||||
<code-pane
|
||||
header="src/app/hero-list.component.ts"
|
||||
path="pipes/src/app/hero-list.component.ts">
|
||||
</code-pane>
|
||||
<code-pane header="src/app/fetch-json.pipe.ts" path="pipes/src/app/fetch-json.pipe.ts"></code-pane>
|
||||
<code-pane header="src/app/hero-list.component.ts" path="pipes/src/app/hero-list.component.ts"></code-pane>
|
||||
</code-tabs>
|
||||
|
||||
In the preceding example, a breakpoint on the pipe's request for data shows the following:
|
||||
|
||||
* Each binding gets its own pipe instance.
|
||||
* Each pipe instance caches its own URL and data and calls the server only once.
|
||||
* Each binding gets its own pipe instance.
|
||||
* Each pipe instance caches its own URL and data and calls the server only once.
|
||||
|
||||
The `fetch` and `fetch-json` pipes display the heroes in the browser as follows:
|
||||
|
||||
@@ -436,5 +368,12 @@ The pipe operator cannot be used without parentheses in the first and second ope
|
||||
|
||||
Due to precedence, if you want a pipe to apply to the result of a ternary, wrap the entire expression in parentheses; for example, `(a ? b : c) | x`.
|
||||
|
||||
<code-example path="pipes/src/app/precedence.component.html" region="precedence" header="src/app/precedence.component.html">
|
||||
</code-example>
|
||||
<code-example path="pipes/src/app/precedence.component.html" region="precedence" header="src/app/precedence.component.html"></code-example>
|
||||
|
||||
<!-- links -->
|
||||
|
||||
[AioGuideI18nCommonFormatDataLocale]: guide/i18n-common-format-data-locale "Format data based on locale | Angular"
|
||||
|
||||
<!-- end links -->
|
||||
|
||||
@reviewed 2021-09-02
|
||||
|
||||
@@ -9,11 +9,11 @@ At the top level of `angular.json`, a few properties configure the workspace, an
|
||||
|
||||
The following properties, at the top level of the file, configure the workspace.
|
||||
|
||||
* `version`: The configuration-file version.
|
||||
* `newProjectRoot`: Path where new projects are created. Absolute or relative to the workspace folder.
|
||||
* `defaultProject`: Default project name to use in commands, where not provided as an argument. When you use `ng new` to create a new application in a new workspace, that application is the default project for the workspace until you change it here.
|
||||
* `schematics` : A set of [schematics](guide/glossary#schematic) that customize the `ng generate` sub-command option defaults for this workspace. See [Generation schematics](#schematics) below.
|
||||
* `projects` : Contains a subsection for each project (library or application) in the workspace, with the per-project configuration options.
|
||||
* `version`: The configuration-file version.
|
||||
* `newProjectRoot`: Path where new projects are created. Absolute or relative to the workspace folder.
|
||||
* `defaultProject`: Default project name to use in commands, where not provided as an argument. When you use `ng new` to create a new application in a new workspace, that application is the default project for the workspace until you change it here.
|
||||
* `schematics` : A set of [schematics](guide/glossary#schematic) that customize the `ng generate` sub-command option defaults for this workspace. See [Generation schematics](#schematics) below.
|
||||
* `projects` : Contains a subsection for each project (library or application) in the workspace, with the per-project configuration options.
|
||||
|
||||
The initial application that you create with `ng new app_name` is listed under "projects":
|
||||
|
||||
@@ -32,11 +32,12 @@ When you create a library project with `ng generate library`, the library projec
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
Note that the `projects` section of the configuration file does not correspond exactly to the workspace file structure.
|
||||
* The initial application created by `ng new` is at the top level of the workspace file structure.
|
||||
* Additional applications and libraries go into a `projects` folder in the workspace.
|
||||
**NOTE**: The `projects` section of the configuration file does not correspond exactly to the workspace file structure.
|
||||
|
||||
For more information, see [Workspace and project file structure](guide/file-structure).
|
||||
* The initial application created by `ng new` is at the top level of the workspace file structure.
|
||||
* Additional applications and libraries go into a `projects` folder in the workspace.
|
||||
|
||||
For more information, see [Workspace and project file structure](guide/file-structure).
|
||||
|
||||
</div>
|
||||
|
||||
@@ -46,25 +47,25 @@ The following top-level configuration properties are available for each project,
|
||||
|
||||
<code-example language="json">
|
||||
|
||||
"my-app": {
|
||||
"root": "",
|
||||
"sourceRoot": "src",
|
||||
"projectType": "application",
|
||||
"prefix": "app",
|
||||
"schematics": {},
|
||||
"architect": {}
|
||||
}
|
||||
"my-app": {
|
||||
"root": "",
|
||||
"sourceRoot": "src",
|
||||
"projectType": "application",
|
||||
"prefix": "app",
|
||||
"schematics": {},
|
||||
"architect": {}
|
||||
}
|
||||
|
||||
</code-example>
|
||||
|
||||
| PROPERTY | DESCRIPTION |
|
||||
| :-------------- | :---------------------------- |
|
||||
| PROPERTY | DESCRIPTION |
|
||||
|:--- |:--- |
|
||||
| `root` | The root folder for this project's files, relative to the workspace folder. Empty for the initial app, which resides at the top level of the workspace. |
|
||||
| `sourceRoot` | The root folder for this project's source files. |
|
||||
| `projectType` | One of "application" or "library". An application can run independently in a browser, while a library cannot.|
|
||||
| `prefix` | A string that Angular prepends to generated selectors. Can be customized to identify an application or feature area. |
|
||||
| `schematics` | A set of schematics that customize the `ng generate` sub-command option defaults for this project. See [Generation schematics](#schematics) below. |
|
||||
| `architect` | Configuration defaults for Architect builder targets for this project. |
|
||||
| `sourceRoot` | The root folder for this project's source files. |
|
||||
| `projectType` | One of "application" or "library". An application can run independently in a browser, while a library cannot. |
|
||||
| `prefix` | A string that Angular prepends to generated selectors. Can be customized to identify an application or feature area. |
|
||||
| `schematics` | A set of schematics that customize the `ng generate` sub-command option defaults for this project. See [Generation schematics](#schematics) below. |
|
||||
| `architect` | Configuration defaults for Architect builder targets for this project. |
|
||||
|
||||
{@a schematics}
|
||||
|
||||
@@ -98,13 +99,13 @@ Angular defines default builders for use with specific CLI commands, or with the
|
||||
The JSON schemas that define the options and defaults for each of these default builders are collected in the [`@angular-devkit/build-angular`](https://github.com/angular/angular-cli/blob/master/packages/angular/cli/lib/config/schema.json) package.
|
||||
The schemas configure options for the following builders.
|
||||
|
||||
* app-shell
|
||||
* browser
|
||||
* dev-server
|
||||
* extract-i18n
|
||||
* karma
|
||||
* server
|
||||
* tslint
|
||||
* app-shell
|
||||
* browser
|
||||
* dev-server
|
||||
* extract-i18n
|
||||
* karma
|
||||
* server
|
||||
* tslint
|
||||
|
||||
### Configuring builder targets
|
||||
|
||||
@@ -118,38 +119,31 @@ See the example in [Build target](#build-target) below.
|
||||
|
||||
<code-example language="json">
|
||||
|
||||
"architect": {
|
||||
"build": { },
|
||||
"serve": { },
|
||||
"e2e" : { },
|
||||
"test": { },
|
||||
"lint": { },
|
||||
"extract-i18n": { },
|
||||
"server": { },
|
||||
"app-shell": { }
|
||||
}
|
||||
"architect": {
|
||||
"build": { },
|
||||
"serve": { },
|
||||
"e2e" : { },
|
||||
"test": { },
|
||||
"lint": { },
|
||||
"extract-i18n": { },
|
||||
"server": { },
|
||||
"app-shell": { }
|
||||
}
|
||||
|
||||
</code-example>
|
||||
|
||||
* The `architect/build` section configures defaults for options of the `ng build` command.
|
||||
See [Build target](#build-target) below for more information.
|
||||
|
||||
* The `architect/serve` section overrides build defaults and supplies additional serve defaults for the `ng serve` command. In addition to the options available for the `ng build` command, it adds options related to serving the application.
|
||||
|
||||
* The `architect/e2e` section overrides build-option defaults for building end-to-end testing applications using the `ng e2e` command.
|
||||
|
||||
* The `architect/test` section overrides build-option defaults for test builds and supplies additional test-running defaults for the `ng test` command.
|
||||
|
||||
* The `architect/lint` section configures defaults for options of the `ng lint` command, which performs code analysis on project source files.
|
||||
|
||||
* The `architect/extract-i18n` section configures defaults for options of the `ng extract-i18n` command, which extracts marked message strings from source code and outputs translation files.
|
||||
|
||||
* The `architect/server` section configures defaults for creating a Universal application with server-side rendering, using the `ng run <project>:server` command.
|
||||
|
||||
* The `architect/app-shell` section configures defaults for creating an application shell for a progressive web application (PWA), using the `ng run <project>:app-shell` command.
|
||||
* The `architect/build` section configures defaults for options of the `ng build` command.
|
||||
See [Build target](#build-target) below for more information.
|
||||
* The `architect/serve` section overrides build defaults and supplies additional serve defaults for the `ng serve` command. In addition to the options available for the `ng build` command, it adds options related to serving the application.
|
||||
* The `architect/e2e` section overrides build-option defaults for building end-to-end testing applications using the `ng e2e` command.
|
||||
* The `architect/test` section overrides build-option defaults for test builds and supplies additional test-running defaults for the `ng test` command.
|
||||
* The `architect/lint` section configures defaults for options of the `ng lint` command, which performs code analysis on project source files.
|
||||
* The `architect/extract-i18n` section configures defaults for options of the `ng extract-i18n` command, which extracts marked message strings from source code and outputs translation files.
|
||||
* The `architect/server` section configures defaults for creating a Universal application with server-side rendering, using the `ng run <project>:server` command.
|
||||
* The `architect/app-shell` section configures defaults for creating an application shell for a progressive web application (PWA), using the `ng run <project>:app-shell` command.
|
||||
|
||||
In general, the options for which you can configure defaults correspond to the command options listed in the [CLI reference page](cli) for each command.
|
||||
Note that all options in the configuration file must use [camelCase](guide/glossary#case-conventions), rather than dash-case.
|
||||
**NOTE**: All options in the configuration file must use [camelCase](guide/glossary#case-conventions), rather than dash-case.
|
||||
|
||||
{@a build-target}
|
||||
|
||||
@@ -157,28 +151,28 @@ Note that all options in the configuration file must use [camelCase](guide/gloss
|
||||
|
||||
The `architect/build` section configures defaults for options of the `ng build` command. It has the following top-level properties.
|
||||
|
||||
| PROPERTY | DESCRIPTION |
|
||||
| :-------------- | :---------------------------- |
|
||||
| `builder` | The npm package for the build tool used to create this target. The default builder for an application (`ng build myApp`) is `@angular-devkit/build-angular:browser`, which uses the [webpack](https://webpack.js.org/) package bundler. Note that a different builder is used for building a library (`ng build myLib`). |
|
||||
| `options` | This section contains default build target options, used when no named alternative configuration is specified. See [Default build targets](#default-build-targets) below. |
|
||||
| `configurations`| This section defines and names alternative configurations for different intended destinations. It contains a section for each named configuration, which sets the default options for that intended environment. See [Alternate build configurations](#build-configs) below. |
|
||||
|
||||
| PROPERTY | DESCRIPTION |
|
||||
|:--- |:--- |
|
||||
| `builder` | The npm package for the build tool used to create this target. The default builder for an application (`ng build myApp`) is `@angular-devkit/build-angular:browser`, which uses the [webpack](https://webpack.js.org) package bundler. **NOTE**: A different builder is used for building a library (`ng build myLib`). |
|
||||
| `options` | This section contains default build target options, used when no named alternative configuration is specified. See [Default build targets](#default-build-targets) below. |
|
||||
| `configurations`| This section defines and names alternative configurations for different intended destinations. It contains a section for each named configuration, which sets the default options for that intended environment. See [Alternate build configurations](#build-configs) below. |
|
||||
|
||||
{@a build-configs}
|
||||
|
||||
### Alternate build configurations
|
||||
|
||||
Angular CLI comes with two build configurations: `production` and `development`. By default, the `ng build` command uses the `production` configuration, which applies a number of build optimizations, including:
|
||||
* Bundling files
|
||||
* Minimizing excess whitespace
|
||||
* Removing comments and dead code
|
||||
* Rewriting code to use short, mangled names (minification)
|
||||
|
||||
You can define and name additional alternate configurations (such as `stage`, for instance) appropriate to your development process. Some examples of different build configurations are `stable`, `archive` and `next` used by AIO itself, and the individual locale-specific configurations required for building localized versions of an application. For details, see [Internationalization (i18n)](guide/i18n#merge-aot).
|
||||
* Bundling files
|
||||
* Minimizing excess whitespace
|
||||
* Removing comments and dead code
|
||||
* Rewriting code to use short, mangled names (minification)
|
||||
|
||||
You can define and name additional alternate configurations (such as `stage`, for instance) appropriate to your development process. Some examples of different build configurations are `stable`, `archive` and `next` used by AIO itself, and the individual locale-specific configurations required for building localized versions of an application. For details, see [Internationalization (i18n)][AioGuideI18nCommonMerge].
|
||||
|
||||
You can select an alternate configuration by passing its name to the `--configuration` command line flag.
|
||||
|
||||
You can also pass in more than one configuration name as a comma-separated list. For example, to apply both `stage` and `fr` build configurations, use the command `ng build --configuration stage,fr`. In this case, the command parses the named configurations from left to right. If multiple configurations change the same setting, the last-set value is the final one. So in this example, if both `stage` and `fr` configurations set the output path the value in `fr` would get used.
|
||||
You can also pass in more than one configuration name as a comma-separated list. For example, to apply both `stage` and `fr` build configurations, use the command `ng build --configuration stage,fr`. In this case, the command parses the named configurations from left to right. If multiple configurations change the same setting, the last-set value is the final one. So in this example, if both `stage` and `fr` configurations set the output path the value in `fr` would get used.
|
||||
|
||||
{@a build-props}
|
||||
|
||||
@@ -188,14 +182,14 @@ The configurable options for a default or targeted build generally correspond to
|
||||
|
||||
Some additional options can only be set through the configuration file, either by direct editing or with the [`ng config`](cli/config) command.
|
||||
|
||||
| OPTIONS PROPERTIES | DESCRIPTION |
|
||||
| :------------------------- | :---------------------------- |
|
||||
| `assets` | An object containing paths to static assets to add to the global context of the project. The default paths point to the project's icon file and its `assets` folder. See more in [Assets configuration](#asset-config) below. |
|
||||
| `styles` | An array of style files to add to the global context of the project. Angular CLI supports CSS imports and all major CSS preprocessors: [sass/scss](https://sass-lang.com/) and [less](http://lesscss.org/). See more in [Styles and scripts configuration](#style-script-config) below. |
|
||||
| `stylePreprocessorOptions` | An object containing option-value pairs to pass to style preprocessors. See more in [Styles and scripts configuration](#style-script-config) below. |
|
||||
| `scripts` | An object containing JavaScript script files to add to the global context of the project. The scripts are loaded exactly as if you had added them in a `<script>` tag inside `index.html`. See more in [Styles and scripts configuration](#style-script-config) below. |
|
||||
| OPTIONS PROPERTIES | DESCRIPTION |
|
||||
|:--- |:--- |
|
||||
| `assets` | An object containing paths to static assets to add to the global context of the project. The default paths point to the project's icon file and its `assets` folder. See more in [Assets configuration](#asset-config) below. |
|
||||
| `styles` | An array of style files to add to the global context of the project. Angular CLI supports CSS imports and all major CSS preprocessors: [sass/scss](https://sass-lang.com) and [less](http://lesscss.org). See more in [Styles and scripts configuration](#style-script-config) below. |
|
||||
| `stylePreprocessorOptions` | An object containing option-value pairs to pass to style preprocessors. See more in [Styles and scripts configuration](#style-script-config) below. |
|
||||
| `scripts` | An object containing JavaScript script files to add to the global context of the project. The scripts are loaded exactly as if you had added them in a `<script>` tag inside `index.html`. See more in [Styles and scripts configuration](#style-script-config) below. |
|
||||
| `budgets` | Default size-budget type and thresholds for all or parts of your application. You can configure the builder to report a warning or an error when the output reaches or exceeds a threshold size. See [Configure size budgets](guide/build#configure-size-budgets). (Not available in `test` section.) |
|
||||
| `fileReplacements` | An object containing files and their compile-time replacements. See more in [Configure target-specific file replacements](guide/build#configure-target-specific-file-replacements).|
|
||||
| `fileReplacements` | An object containing files and their compile-time replacements. See more in [Configure target-specific file replacements](guide/build#configure-target-specific-file-replacements). |
|
||||
|
||||
{@a complex-config}
|
||||
|
||||
@@ -226,11 +220,11 @@ To exclude an asset, you can remove it from the assets configuration.
|
||||
You can further configure assets to be copied by specifying assets as objects, rather than as simple paths relative to the workspace root.
|
||||
A asset specification object can have the following fields.
|
||||
|
||||
* `glob`: A [node-glob](https://github.com/isaacs/node-glob/blob/master/README.md) using `input` as base directory.
|
||||
* `input`: A path relative to the workspace root.
|
||||
* `output`: A path relative to `outDir` (default is `dist/`*project-name*). Because of the security implications, the CLI never writes files outside of the project output path.
|
||||
* `ignore`: A list of globs to exclude.
|
||||
* `followSymlinks`: Allow glob patterns to follow symlink directories. This allows subdirectories of the symlink to be searched. Defaults to `false`.
|
||||
* `glob`: A [node-glob](https://github.com/isaacs/node-glob/blob/master/README.md) using `input` as base directory.
|
||||
* `input`: A path relative to the workspace root.
|
||||
* `output`: A path relative to `outDir` (default is `dist/`*project-name*). Because of the security implications, the CLI never writes files outside of the project output path.
|
||||
* `ignore`: A list of globs to exclude.
|
||||
* `followSymlinks`: Allow glob patterns to follow symlink directories. This allows subdirectories of the symlink to be searched. Defaults to `false`.
|
||||
|
||||
For example, the default asset paths can be represented in more detail using the following objects.
|
||||
|
||||
@@ -257,11 +251,11 @@ For example, the following configuration copies assets from a node package:
|
||||
<code-example language="json">
|
||||
|
||||
"assets": [
|
||||
{
|
||||
"glob": "**/*",
|
||||
"input": "./node_modules/some-package/images",
|
||||
"output": "/some-package/"
|
||||
}
|
||||
{
|
||||
"glob": "**/*",
|
||||
"input": "./node_modules/some-package/images",
|
||||
"output": "/some-package/"
|
||||
}
|
||||
]
|
||||
|
||||
</code-example>
|
||||
@@ -273,12 +267,12 @@ The following example uses the `ignore` field to exclude certain files in the as
|
||||
<code-example language="json">
|
||||
|
||||
"assets": [
|
||||
{
|
||||
"glob": "**/*",
|
||||
"input": "src/assets/",
|
||||
"ignore": ["**/*.svg"],
|
||||
"output": "/assets/"
|
||||
}
|
||||
{
|
||||
"glob": "**/*",
|
||||
"input": "src/assets/",
|
||||
"ignore": ["**/*.svg"],
|
||||
"output": "/assets/"
|
||||
}
|
||||
]
|
||||
|
||||
</code-example>
|
||||
@@ -296,20 +290,20 @@ For example, the following object values create and name a bundle that contains
|
||||
|
||||
<code-example language="json">
|
||||
|
||||
"styles": [
|
||||
{
|
||||
"input": "src/external-module/styles.scss",
|
||||
"inject": false,
|
||||
"bundleName": "external-module"
|
||||
}
|
||||
],
|
||||
"scripts": [
|
||||
{
|
||||
"input": "src/external-module/main.js",
|
||||
"inject": false,
|
||||
"bundleName": "external-module"
|
||||
}
|
||||
]
|
||||
"styles": [
|
||||
{
|
||||
"input": "src/external-module/styles.scss",
|
||||
"inject": false,
|
||||
"bundleName": "external-module"
|
||||
}
|
||||
],
|
||||
"scripts": [
|
||||
{
|
||||
"input": "src/external-module/main.js",
|
||||
"inject": false,
|
||||
"bundleName": "external-module"
|
||||
}
|
||||
]
|
||||
|
||||
</code-example>
|
||||
|
||||
@@ -346,30 +340,38 @@ To add paths, use the `stylePreprocessorOptions` option:
|
||||
|
||||
Files in that folder, such as `src/style-paths/_variables.scss`, can be imported from anywhere in your project without the need for a relative path:
|
||||
|
||||
```ts
|
||||
<code-example language="typescript">
|
||||
|
||||
// src/app/app.component.scss
|
||||
// A relative path works
|
||||
@import '../style-paths/variables';
|
||||
// But now this works as well
|
||||
@import 'variables';
|
||||
```
|
||||
|
||||
Note that you will also need to add any styles or scripts to the `test` builder if you need them for unit tests.
|
||||
</code-example>
|
||||
|
||||
**NOTE**: You will also need to add any styles or scripts to the `test` builder if you need them for unit tests.
|
||||
See also [Using runtime-global libraries inside your app](guide/using-libraries#using-runtime-global-libraries-inside-your-app).
|
||||
|
||||
### Optimization configuration
|
||||
|
||||
The `optimization` browser builder option can be either a Boolean or an Object for more fine-tune configuration. This option enables various optimizations of the build output, including:
|
||||
|
||||
- Minification of scripts and styles
|
||||
- Tree-shaking
|
||||
- Dead-code elimination
|
||||
- Inlining of critical CSS
|
||||
- Fonts inlining
|
||||
* Minification of scripts and styles
|
||||
* Tree-shaking
|
||||
* Dead-code elimination
|
||||
* Inlining of critical CSS
|
||||
* Fonts inlining
|
||||
|
||||
There are several options that can be used to fine-tune the optimization of an application.
|
||||
|
||||
<table class="is-full-width is-fixed-layout">
|
||||
| Option | Description | Value Type | Dafault Value |
|
||||
|:--- |:--- |:--- |:--- |
|
||||
| `scripts` | Enables optimization of the scripts output. | `boolean` | `true` |
|
||||
| `styles` | Enables optimization of the styles output. | `boolean` | `true` |
|
||||
| `fonts` | Enables optimization for fonts. <br /> **NOTE**: This requires internet access. | `boolean` | `true` |
|
||||
|
||||
<!--<table class="is-full-width is-fixed-layout">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Option</th>
|
||||
@@ -398,10 +400,16 @@ There are several options that can be used to fine-tune the optimization of an a
|
||||
<td><code>true</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</table>-->
|
||||
|
||||
#### Styles optimization options
|
||||
<table class="is-full-width is-fixed-layout">
|
||||
|
||||
| Option | Description | Value Type | Dafault Value |
|
||||
|:--- |:--- |:--- |:--- |
|
||||
| `minify` | Minify CSS definitions by removing extraneous whitespace and comments, merging identifiers and minimizing values. | `boolean` | `true` |
|
||||
| `inlineCritical` | Extract and inline critical CSS definitions to improve [First Contentful Paint](https://web.dev/first-contentful-paint). | `boolean` | `true` |
|
||||
|
||||
<!--<table class="is-full-width is-fixed-layout">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Option</th>
|
||||
@@ -424,10 +432,15 @@ There are several options that can be used to fine-tune the optimization of an a
|
||||
<td><code>true</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</table>-->
|
||||
|
||||
#### Fonts optimization options
|
||||
<table class="is-full-width is-fixed-layout">
|
||||
|
||||
| Option | Description | Value Type | Dafault Value |
|
||||
|:--- |:--- |:--- |:--- |
|
||||
| `inline` | Reduce [render blocking requests](https://web.dev/render-blocking-resources) by inlining external Google Fonts and Adobe Fonts CSS definitions in the application's HTML index file. <br /> **NOTE**: This requires internet access. | `boolean` | `true` |
|
||||
|
||||
<!--<table class="is-full-width is-fixed-layout">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Option</th>
|
||||
@@ -444,28 +457,26 @@ There are several options that can be used to fine-tune the optimization of an a
|
||||
<td><code>true</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
</table>-->
|
||||
|
||||
You can supply a value such as the following to apply optimization to one or the other:
|
||||
|
||||
<code-example language="json">
|
||||
|
||||
"optimization": {
|
||||
"scripts": true,
|
||||
"styles": {
|
||||
"minify": true,
|
||||
"inlineCritical": true
|
||||
},
|
||||
"fonts": true
|
||||
}
|
||||
"optimization": {
|
||||
"scripts": true,
|
||||
"styles": {
|
||||
"minify": true,
|
||||
"inlineCritical": true
|
||||
},
|
||||
"fonts": true
|
||||
}
|
||||
|
||||
</code-example>
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
For [Universal](guide/glossary#universal), you can reduce the code rendered in the HTML page by
|
||||
setting styles optimization to `true`.
|
||||
For [Universal](guide/glossary#universal), you can reduce the code rendered in the HTML page by setting styles optimization to `true`.
|
||||
|
||||
</div>
|
||||
|
||||
@@ -473,7 +484,14 @@ You can supply a value such as the following to apply optimization to one or the
|
||||
|
||||
The `sourceMap` browser builder option can be either a Boolean or an Object for more fine-tune configuration to control the source maps of an application.
|
||||
|
||||
<table class="is-full-width is-fixed-layout">
|
||||
| Option | Description | Value Type | Dafault Value |
|
||||
|:--- |:--- |:--- |:--- |
|
||||
| `scripts` | Output source maps for all scripts. | `boolean` | `true` |
|
||||
| `styles` | Output source maps for all styles. | `boolean` | `true` |
|
||||
| `vendor` | Resolve vendor packages source maps. | `boolean` | `false` |
|
||||
| `hidden` | Output source maps used for error reporting tools. | `boolean` | `false` |
|
||||
|
||||
<!--<table class="is-full-width is-fixed-layout">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Option</th>
|
||||
@@ -508,26 +526,32 @@ The `sourceMap` browser builder option can be either a Boolean or an Object for
|
||||
<td><code>false</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
</table>-->
|
||||
|
||||
The example below shows how to toggle one or more values to configure the source map outputs:
|
||||
|
||||
<code-example language="json">
|
||||
|
||||
"sourceMap": {
|
||||
"scripts": true,
|
||||
"styles": false,
|
||||
"hidden": true,
|
||||
"vendor": true
|
||||
}
|
||||
"sourceMap": {
|
||||
"scripts": true,
|
||||
"styles": false,
|
||||
"hidden": true,
|
||||
"vendor": true
|
||||
}
|
||||
|
||||
</code-example>
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
When using hidden source maps, source maps will not be referenced in the bundle.
|
||||
These are useful if you only want source maps to map error stack traces in error reporting tools,
|
||||
but don't want to expose your source maps in the browser developer tools.
|
||||
When using hidden source maps, source maps will not be referenced in the bundle.
|
||||
These are useful if you only want source maps to map error stack traces in error reporting tools, but don't want to expose your source maps in the browser developer tools.
|
||||
|
||||
</div>
|
||||
|
||||
<!-- links -->
|
||||
|
||||
[AioGuideI18nCommonMerge]: guide/i18n-common-merge "Common Internationalization task #6: Merge translations into the application | Angular"
|
||||
|
||||
<!-- end links -->
|
||||
|
||||
@reviewed 2021-09-02
|
||||
|
||||
Reference in New Issue
Block a user