honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
angular-cn/aio/content/guide/deprecation.md

27 KiB
Raw Blame History

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.

For step-by-step instructions on how to update to the latest Angular release, use the interactive update guide at 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 All @angular/common/http The entire package has been removed. See below.
@angular/http/testing All @angular/common/http/testing See below.
@angular/platform-browser DOCUMENT @angular/common

{@a http}

@angular/http

The entire @angular/http package has been removed. Use @angular/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.

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. Deprecated APIs are indicated by strikethrough in the API reference pages.

{@a common}

@angular/common

API Replacement Deprecation announced Notes
DeprecatedI18NPipesModule CommonModule 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.
DeprecatedCurrencyPipe CurrencyPipe v5 none
DeprecatedDatePipe DatePipe v5 none
DeprecatedDecimalPipe DecimalPipe v5 none
DeprecatedPercentPipe 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 v4.0.0 in v7 docs none IterableChangeRecord
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 v5 in v7 docs Slow and brings in a lot of code. Injector.create
core ReflectiveKey marked in v6, can't check v5 in v7 docs No replacement
core RenderComponentType marked in v4 docs in v7 docs none RendererType2 and Renderer2
core Renderer marked in v4 docs in v7 docs none Renderer2
core RootRenderer marked in v4 docs in v7 docs none 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 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. Now deprecated: <ngForm #myForm="ngForm">. Replacement: <ng-form #myForm="ngForm">.
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 marked deprecated as far back as v4 docs in v7 docs none Import from @angular/common
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

@angular/router

The following exports from @angular/router are deprecated:

Package API Deprecation announced Removed in Details Replacement
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 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. For more information about upgrading from AngularJS to Angular, see Upgrading from AngularJS. none
upgrade UpgradeAdapter v5 in v7 docs none Use upgrade/static instead, which also supports Ahead-of-Time compilation
upgrade UpgradeAdapterRef v5 in v7 docs none Use upgrade/static instead, which also supports Ahead-of-Time compilation
upgrade/static getAngularLib marked in v5 docs in v7 docs none Use getAngularJSGlobal instead
upgrade/static setAngularLib marked in v5 docs in v7 docs none Use 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 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 and FormControlName.

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 DeprecatedDatePipe DeprecatedDecimalPipe 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.

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 to @angular/animations. In v6.0.0, @angular/core/animations was removed. Imports from @angular/core were announced as deprecated in v4. 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 <template> tag was deprecated in Angular v4 to avoid collisions (such as when using web components). Use <ng-template> instead. (<template> removed in v6.0.0 (2018-05-03)

https://angular.io/guide/aot-compiler#enablelegacytemplate

enableLegacyTemplate: Use of the <template> element was deprecated starting in Angular 4.0 in favor of using <ng-template> to avoid colliding with the DOM's element of the same name. Setting this option to true enables the use of the deprecated <template> element. This option is false by default. This option might be required by some third-party Angular libraries.

API or feature Deprecation announced Removed in Details Replacement
animate v6.0.0 This symbol has moved Import from @angular/animations instead

Removed in v5

API Replacement Notes
NgFor NgForOf Deprecated in v4.0.0. Removed in v5.0.0

Other deprecations

The following changes and deprecations are mentioned in the update instructions at update.angular.io.

Updating from v5 to v6

  • Replace ngOutletContext with ngTemplateOutletContext.
  • Replace CollectionChangeRecord with IterableChangeRecord
  • Anywhere you use Renderer, now use Renderer2
  • If you use preserveQueryParams, instead use queryParamsHandling
  • If you use DOCUMENT from @angular/platform-browser, you should start to import this from @angular/common
  • Anywhere you use ReflectiveInjector, now use StaticInjector
  • Choose a value of off for preserveWhitespaces in your tsconfig.json to gain the benefits of this setting, which was set to off by default in v6.
  • Format of angular.json changed. Update your Angular CLI globally and locally, and migrate the configuration to the new angular.json format by following the instructions in update.angular.io.
  • Update any scripts you may have in your package.json to use the latest Angular CLI commands. All CLI commands now use two dashes for flags (eg ng build --prod --source-map) to be POSIX compliant.

Updating v4 to v5

  • Stop using DefaultIterableDiffer, KeyValueDiffers#factories, or IterableDiffers#factories
  • Rename your template tags to ng-template
  • Replace any OpaqueToken with InjectionToken.
  • If you call DifferFactory.create(...) remove the ChangeDetectorRef argument.
  • Stop passing any arguments to the constructor for ErrorHandler
  • If you use ngProbeToken, make sure you import it from @angular/core instead of @angular/platform-browser
  • If you use TrackByFn, instead use TrackByFunction
  • If you import any animations services or tools from @angular/core, you should import them from @angular/animations
  • Replace ngOutletContext with ngTemplateOutletContext.
  • Replace CollectionChangeRecord with IterableChangeRecord
  • Anywhere you use Renderer, now use Renderer2
  • If you use preserveQueryParams, instead use queryParamsHandling
  • If you rely on the date, currency, decimal, or percent pipes, in 5 you will see minor changes to the format. For applications using locales other than en-us you will need to import it and optionally locale_extended_fr from @angular/common/i18n_data/locale_fr and registerLocaleData(local).
  • Do not rely on gendir, instead look at using skipTemplateCodeGen. Read More https://github.com/angular/angular/issues/19339#issuecomment-332607471%22
  • Switch from HttpModule and the Http service to HttpClientModule and the HttpClient service. HttpClient simplifies the default ergonomics (You don't need to map to json anymore) and now supports typed return values and interceptors. Read more on angular.io
  • If you use DOCUMENT from @angular/platform-browser, you should start to import this from @angular/common
  • Anywhere you use ReflectiveInjector, now use StaticInjector
  • Choose a value of off for preserveWhitespaces in your tsconfig.json to gain the benefits of this setting, which was set to off by default in v6.

Updating v2 to v4

  • Ensure you don't use extends OnInit, or use extends with any lifecycle event. Instead use implements .
  • Stop using deep imports, these symbols are now marked with ɵ and are not part of our public API.
  • Stop using Renderer.invokeElementMethod as this method has been removed. There is not currently a replacement.
  • Stop using DefaultIterableDiffer, KeyValueDiffers#factories, or IterableDiffers#factories
  • If you use animations in your application, you should import BrowserAnimationsModule from @angular/platform-browser/animations in your App NgModule.
  • Replace RootRenderer with RendererFactoryV2 instead.
  • Rename your template tags to ng-template
  • Replace any OpaqueToken with InjectionToken.
  • If you call DifferFactory.create(...) remove the ChangeDetectorRef argument.
  • Stop passing any arguments to the constructor for ErrorHandler
  • If you use ngProbeToken, make sure you import it from @angular/core instead of @angular/platform-browser
  • If you use TrackByFn, instead use TrackByFunction
  • If you import any animations services or tools from @angular/core, you should import them from @angular/animations
  • Replace ngOutletContext with ngTemplateOutletContext.
  • Replace CollectionChangeRecord with IterableChangeRecord
  • Anywhere you use Renderer, now use Renderer2
  • If you use preserveQueryParams, instead use queryParamsHandling