diff --git a/aio/content/guide/deprecation.md b/aio/content/guide/deprecation.md new file mode 100644 index 0000000000..b43b30c4fc --- /dev/null +++ b/aio/content/guide/deprecation.md @@ -0,0 +1,506 @@ +# Deprecation Summary + + + +Angular strives to balance innovation and stability. +Sometimes, APIs and features become obsolete and need to be removed or replaced so that Angular can stay current with new best practices, changing dependencies, or changes in the (web) platform itself. + +To make these transitions as easy as possible, we deprecate APIs and features for a period of time before removing them. This gives you time to update your apps to the latest APIs and best practices. + +This guide contains a summary of all Angular APIs and features that are currently deprecated. + + +
+ +For information about Angular's deprecation and removal practices, see [Angular versioning and releases](guide/releases#deprecation-practices "Angular versioning and releases: 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). + +
+ + +{@a removed} +## Removed in v8 + +The following APIs and features were previously announced as deprecated and have been removed starting with version 8.0.0: + +| Package | API or feature | Replacement | Notes | +| ------- | -------------- | ----------- | ----- | +| [@angular/http](https://v7.angular.io/api/http) | All | [@angular/common/http](https://v7.api/common/http) | The entire package has been removed. See [below](#http). | +[@angular/http/testing](https://v7.api/http/testing) | All | [@angular/common/http/testing](https://v7.api/common/http/testing) | See [below](#http). | +| @angular/platform-browser | [DOCUMENT](https://v7.angular.io/api/platform-browser/DOCUMENT) | [`@angular/common`](https://v7.angular.io/api/common/DOCUMENT) | | + + + +{@a http} +### @angular/http + + + + +The entire [@angular/http](http://v7.angular.io/api/http) package has been removed. Use [@angular/common/http](api/common/http) instead. + +The new API simplifies the default ergonomics (You don't need to map to `json` anymore.) and supports typed return values and interceptors. + +To update your apps: +* Replace `HttpModule` with `HttpClientModule` +* Replace the `Http` service with the `HttpClient` service +* Remove any map(`res => res.json()`) calls + +For more information about using the replacement APIs, see the [HttpClient](guide/http "HTTP Client guide") guide. + + +| Removed API | Replacement API | +| ----------- | --------------- | +| BaseRequestOptions | tbd | +| BaseResponseOptions | tbd | +| BrowserXhr | tbd | +| Connection | tbd | +| ConnectionBackend | tbd | +| CookieXSRFStrategy | tbd | +| Headers | tbd | +| HttpModule | tbd | +| Jsonp | tbd | +| JSONPBackend | tbd | +| JSONPConnection | tbd | +| JsonpModule | tbd | +| QueryEncoder | tbd | +| ReadyState | tbd | +| Request | tbd | +| RequestMethod | tbd | +| RequestOptions | tbd | +| RequestOptionsArgs | tbd | +| Response | tbd | +| ResponseContentType | tbd | +| ResponseOptions | tbd | +| ResponseOptionsArgs | tbd | +| ResponseType | tbd | +| URLSearchParams | tbd | +| XHRBackend | tbd | +| XHRConnection | tbd | +| XSRFStrategy | tbd | +| @http/testing/MockBackend | tbd | +| @http/testing/MockConnection | tbd | + + +## Deprecated APIs + +The following table lists all of the deprecated APIs, with details to help you plan your migration to a replacement. + +
+ +To see a quick summary of all APIs that are deprecated, filter the API list by [**Status: deprecated**](https://angular.io/api?status=deprecated). Deprecated APIs are indicated by ~~strikethrough~~ in the API reference pages. + +
+ +{@a common} +### @angular/common + +| API | Replacement | Deprecation announced | Notes | +| --- | ----------- | --------------------- | ----- | +| [DeprecatedI18NPipesModule](api/common/DeprecatedI18NPipesModule) | [`CommonModule`](https://angular.io/api?query=pipe) | v5 | Pipes that rely the JS Intl API use the deprecated module, while the new `CommonModule` extracts and uses data from CLDR instead. For mappings to assist your update, see [Date Formats](https://docs.google.com/spreadsheets/d/12iygt-_cakNP1VO7MV9g4lq9NsxVWG4tSfc98HpHb0k/edit#gid=0 "Date formats Google sheet"). | +| [DeprecatedCurrencyPipe](https://angular.io/api/common/DeprecatedCurrencyPipe) | [CurrencyPipe](https://angular.io/api/common/CurrencyPipe) | v5 | none | +| [DeprecatedDatePipe](https://angular.io/api/common/DeprecatedDatePipe) | [DatePipe](https://angular.io/api/common/DatePipe) | v5 | none | +| [DeprecatedDecimalPipe](https://angular.io/api/common/DeprecatedDecimalPipe) | [DecimalPipe](https://angular.io/api/common/DecimalPipe) | v5 | none | +| [DeprecatedPercentPipe](https://angular.io/api/common/DeprecatedPercentPipe) | [PercentPipe](https://angular.io/api/common/PercentPipe) v5 | | none | + + + + + + + +### @angular/core + + +The following exports from `@angular/care` are deprecated: + +Package | API | Deprecation announced | Removed in | Details | Replacement +------- | --- | --------------------- | ---------- | ------- | ----------- +core | animate | v5 or earlier | ? | none | tbd +core | AnimationAnimateMetadata | v5 or earlier | ? | none | tbd +core | AnimationEntryMetadata | v5 or earlier | ? | none | tbd +core | AnimationGroupMetadata | v5 or earlier | ? | none | tbd +core | AnimationKeyframe | v5 or earlier | ? | none | tbd +core | AnimationKeyframesSequenceMetadata | v5 or earlier | ? | none | tbd +core | AnimationMetadata | v5 or earlier | ? | none | tbd +core | AnimationPlayer | v5 or earlier | ? | none | tbd +core | AnimationSequenceMetadata | v5 or earlier | ? | none | tbd +core | AnimationStateMetadata | v5 or earlier | ? | none | tbd +core | AnimationStateTransitionMetadata | v5 or earlier | ? | none | tbd +core | AnimationStyleMetadata | v5 or earlier | ? | none | tbd +core | AnimationStyles | v5 or earlier | ? | none | tbd +core | AnimationTransitionEvent | v5 or earlier | ? | none | tbd +core | AnimationTransitionMetadata | v5 or earlier | ? | none | tbd +core | AnimationTriggerMetadata | v5 or earlier | ? | none | tbd +core | AUTO_STYLE | v5 or earlier | ? | none | tbd +core | [CollectionChangeRecord](https://angular.io/api/core/CollectionChangeRecord) | v4.0.0 | in v7 docs | none | [IterableChangeRecord](https://angular.io/api/core/IterableChangeRecord) +core | [DefaultIterableDiffer](https://angular.io/api/core/DefaultIterableDiffer) | v4.0.0 | in v7 docs | Should not be part of public API. | not applicable +core | group | v5 or earlier | ? | none | tbd +core | keyframes | v5 or earlier | ? | none | tbd +core | [ReflectiveInjector](https://angular.io/api/core/ReflectiveInjector) | v5 | in v7 docs | Slow and brings in a lot of code. | [Injector.create](https://angular.io/api/core/Injector#create) +core | [ReflectiveKey](https://angular.io/api/core/ReflectiveKey) | marked in v6, can't check v5 | in v7 docs | No replacement +core | [RenderComponentType](https://angular.io/api/core/RenderComponentType) | marked in v4 docs | in v7 docs | none | [`RendererType2`](https://angular.io/api/core/RendererType2) and [`Renderer2`](https://angular.io/api/core/Renderer2) +core | [Renderer](https://angular.io/api/core/Renderer) | marked in v4 docs | in v7 docs | none | [`Renderer2`](https://angular.io/api/core/Renderer2) +core | [RootRenderer](https://angular.io/api/core/RootRenderer) | marked in v4 docs | in v7 docs | none | [`RendererFactory2`](https://angular.io/api/core/RendererFactory2) +core | sequence | v5 or earlier | ? | none | tbd +core | state | v5 or earlier | ? | none | tbd +core | style | v5 or earlier | ? | none | tbd +core | transition | v5 or earlier | ? | none | tbd +core | trigger| v5 or earlier | ? | none | tbd + + + + +### @angular/forms + + +The following exports from `@angular/forms` are deprecated: + + +Package | API | Deprecation announced | Removed in | Details | Replacement +------- | --- | --------------------- | ---------- | ------- | ----------- +forms | [NgForm](https://angular.io/api/forms/NgForm) | v6 | will be removed in v9 | This has been deprecated to keep selectors consistent with other core Angular selectors, as element selectors are typically written in kebab-case. | See description in [NgForm](https://angular.io/api/forms/NgForm). Now deprecated: ``. Replacement: ``. +forms | [NgFormSelectorWarning](https://angular.io/api/forms/NgFormSelectorWarning) | v6 (page added to API ref in v7 docs) | will be removed in v9 | This directive is solely used to display warnings when the deprecated ngForm selector is used. | not applicable + +Support for using ngForm element selector has been deprecated in Angular v6 and will be removed in Angular v9. + +This has been deprecated to keep selectors consistent with other core Angular selectors, as element selectors are typically written in kebab-case. + +For details, see https://angular.io/api/forms/NgForm#description + + + +### @angular/platform-browser + + +The following exports from `@angular/platform-browser` are deprecated: + + +Package | API | Deprecation announced | Removed in | Details | Replacement +------- | --- | --------------------- | ---------- | ------- | ----------- +platform-browser | [platform-browser/DOCUMENT](https://angular.io/api/platform-browser/DOCUMENT) | marked deprecated as far back as v4 docs | in v7 docs | none | Import from [`@angular/common`](https://angular.io/api/common/DOCUMENT) +platform-browser | [NgProbeToken](https://v4.angular.io/api/platform-browser/NgProbeToken) | marked deprecated as far back as API Reference (v2.4.10) docs | not in docs v5+ | none | [Use the one from `@angular/core`](https://angular.io/api/core/NgProbeToken) + +### @angular/router + +The following exports from `@angular/router` are deprecated: + +Package | API | Deprecation announced | Removed in | Details | Replacement +------- | --- | --------------------- | ---------- | ------- | ----------- +router | [RouterLink](https://angular.io/api/router/RouterLink) | v4 | candidate v7 | none | `queryParamsHandling` + + +Two older properties are still available. They are less capable than their replacements, discouraged, and may be deprecated in a future Angular version. + +* params—An Observable that contains the required and optional parameters specific to the route. Use paramMap instead. + +* queryParams—An Observable that contains the query parameters available to all routes. Use queryParamMap instead. + +See https://angular.io/guide/router#activated-route + + +### @angular/upgrade + + +The following exports from `@angular/upgrade` are deprecated: + + +Package | API | Deprecation announced | Removed in | Details | Replacement +------- | --- | --------------------- | ---------- | ------- | ----------- +upgrade | entire [`@angular/upgrade`](https://angular.io/api/upgrade) package | v5? | in nv7 docs | All exports of this entry point are deprecated. Supports the upgrade path from AngularJS to Angular, allowing components from both systems to be used in the same application. All exports of this entry point are deprecated. Use [@angular/upgrade/static](https://angular.io/api/upgrade/static). For more information about upgrading from AngularJS to Angular, see [Upgrading from AngularJS](https://angular.io/guide/upgrade). | none +upgrade | [UpgradeAdapter](https://angular.io/api/upgrade/UpgradeAdapter) | v5 | in v7 docs | none | Use [`upgrade/static`](https://angular.io/api/upgrade/static) instead, which also supports [Ahead-of-Time compilation](guide/aot-compiler) +upgrade | [UpgradeAdapterRef](https://angular.io/api/upgrade/UpgradeAdapterRef) | v5 | in v7 docs | none | Use [`upgrade/static`](https://angular.io/api/upgrade/static) instead, which also supports [Ahead-of-Time compilation](guide/aot-compiler) +upgrade/static | [getAngularLib](https://angular.io/api/upgrade/static/getAngularLib) | marked in v5 docs | in v7 docs | none | Use [`getAngularJSGlobal`](https://angular.io/api/upgrade/static/getAngularJSGlobal) instead +upgrade/static | [setAngularLib](https://angular.io/api/upgrade/static/setAngularLib) | marked in v5 docs | in v7 docs | none | Use [`setAngularJSGlobal`](https://angular.io/api/upgrade/static/setAngularJSGlobal) instead + + + +{@a features} +## Deprecated features + + +### Component styles + +The shadow-piercing descendant combinator is deprecated and support is being removed from major browsers and tools. As such, we plan to drop support in Angular for all 3 of `/deep/`, `>>>` and `::ng-deep`). Until then `::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]. + + +### ngModel with reactive forms + +Support for using the `ngModel` input property and `ngModelChange` event with reactive form directives was deprecated in version 6.0.0. + +For more information, see the [usage notes of FormControlDirective](api/forms/FormControlDirective#use-with-ngmodel) and [FormControlName](api/forms/FormControlName#use-with-ngmodel). + + + + +### Service worker versionedFiles + +6.1.0 (2018-07-25) and 6.0.2 (2018-05-15) +service-worker: deprecate versionedFiles in asset-group resources (#23584) (1d378e2) +As of v6 `versionedFiles` and `files` options have the same behavior. Use `files` instead. + +https://angular.io/guide/service-worker-config + +As of v6 `versionedFiles` and `files` options have the same behavior. Use `files` instead. + +From update.angular.io 6.1 to 7.0: f you use the Angular Service worker, migrate any `versionedFiles` to the `files` array. The behavior is the same. + + + + +### ReflectiveInjector replaced with StaticInjector (From blog) +In order to remove even more polyfills, we’ve replaced the ReflectiveInjector with the StaticInjector. This injector no longer requires the Reflect polyfill, reducing application size for most developers. + +Before +ReflectiveInjector.resolveAndCreate(providers); + +After +Injector.create(providers); + +Note: This is marked v4 in the API reference docs. + + +{@a i18n-pipes} +### Pipes that use the JS Intl API + + + + +Angular used to rely on the browser to provide number, date, and currency formatting using browser i18n APIs. This practice meant that most apps needed to use a polyfill, users were seeing inconsistent results across browsers, and common formats (such as the currency pipe) didn’t match developer expectations out of the box. + +In version 4.3, Angular introduced new number, date, and currency pipes that increase standardization across browsers and eliminate the need for i18n polyfills. These pipes use the CLDR (instead of the JS Intl API) to provide extensive locale support. + +In 5.0.0, Angular updated its pipes to use the CLRD implementation. +At the same time, it introduced `DeprecatedI18NPipesModule` to provide access to the old behavior. +[DeprecatedCurrencyPipe](https://angular.io/api/common/DeprecatedCurrencyPipe) +[DeprecatedDatePipe](https://angular.io/api/common/DeprecatedDatePipe) +[DeprecatedDecimalPipe](https://angular.io/api/common/DeprecatedDecimalPipe) +[DeprecatedPercentPipe](https://angular.io/api/common/DeprecatedPercentPipe) + +All `Deprecated` pipes are deprecated and candidates for removal beginning in version 8.0.0 + + + +For more information about the mapping of pipe behavior between v4 and v5, see [Date Formats](https://docs.google.com/spreadsheets/d/12iygt-_cakNP1VO7MV9g4lq9NsxVWG4tSfc98HpHb0k/edit#gid=0 "Date Formats Google sheet"). + +Read more about the changes to our i18n pipes in the changelog. https://github.com/angular/angular/blob/master/CHANGELOG.md#i18n-pipes + +If you aren’t ready for the new pipes, you can import `DeprecatedI18NPipesModule` to get access to the old behavior. + + + +If you use the following deprecated i18n pipes: +* date, +* currency, +* decimal, +* percent + +You need the Intl API on all browsers except Chrome, Firefox, Edge, IE11 and Safari 10. + + + +## Removed in v6 + +The following APIs were removed in v6.0.0. + +* Animations APIs were moved from [`@angular/core/animations`](https://v5.angular.io/api/animations) to [`@angular/animations`](api/animations). +In v6.0.0, [`@angular/core/animations`](https://v5.angular.io/api/animations) was removed. +Imports from `@angular/core` were [announced as deprecated in v4](https://blog.angularjs.org/2017/03/angular-400-now-available.html). +Use imports from the new package import { trigger, state, style, transition, animate } from `@angular/animations`. +If you import any animations services or tools from `@angular/core`, you should import them from `@angular/animations`. + +* The `