angular-cn/aio/content/guide/deprecations.md

Deprecated APIs and Features

弃用的 API 和特性

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.

Angular 力图兼顾创新与稳定。但有时，API 和特性已经过时，需要进行删除或替换，以便 Angular 可以及时跟上新的最佳实践、依赖项变更或者 Web 平台自身的变化。

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.

为了让这些转换变得尽可能简单，我们会在删除 API 和特性之前先弃用它们一段时间。让你有时间把应用更新到最新的 API 和最佳实践。

This guide contains a summary of all Angular APIs and features that are currently deprecated.

本指南包含了当前不推荐使用的所有 Angular API 和特性的汇总表。

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.

v6 或更早版本中已弃用的特性和 API 将会在版本 9 或更高级版本中删除。要了解 Angular 中关于弃用和删除的实践，参见Angular 发布实践 。

For step-by-step instructions on how to update to the latest Angular release, use the interactive update guide at update.angular.io.

有关如何更新到最新 Angular 版本的分步说明，请参阅 update.angular.io 上的交互式更新指南。

Deprecated APIs

已弃用的 API

This section contains a complete list all of the currently-deprecated APIs, with details to help you plan your migration to a replacement.

本节包含所有当前已弃用的 API 的完整列表，其中包含一些可帮助你规划如何迁移到其替代品的详细信息。

Tip: In the API reference section of this doc site, deprecated APIs are indicated by strikethrough. You can filter the API list by Status: deprecated.

提示：在本文档站的 API参考手册部分，不推荐使用的 API 会用删除线标记出来。你可以按状态: 已弃用来过滤 API 列表。

@angular/common

API	Replacement	Deprecation announced	Notes
API	替代品	已宣布弃用	备注
DeprecatedI18NPipesModule	CommonModule	v5	See Pipes
DeprecatedI18NPipesModule	CommonModule	v5	参见管道
DeprecatedCurrencyPipe	CurrencyPipe	v5	See Pipes
DeprecatedCurrencyPipe	CurrencyPipe	v5	参见管道
DeprecatedDatePipe	DatePipe	v5	See Pipes
DeprecatedDatePipe	DatePipe	v5	参见管道
DeprecatedDecimalPipe	DecimalPipe	v5	See Pipes
DeprecatedDecimalPipe	DecimalPipe	v5	参见管道
DeprecatedPercentPipe	PercentPipe	v5	See Pipes
DeprecatedPercentPipe	PercentPipe	v5	参见管道

@angular/core

API	Replacement	Deprecation announced	Notes
API	替代品	已宣布弃用	备注
CollectionChangeRecord	IterableChangeRecord	v4	none
CollectionChangeRecord	IterableChangeRecord	v4	无
DefaultIterableDiffer	n/a	v4	Not part of public API.
DefaultIterableDiffer	不适用	v4	不属于公共 API。
defineInjectable	ɵɵdefineInjectable	v8	Used only in generated code. No source code should depend on this API.
defineInjectable	ɵɵdefineInjectable	v8	仅在生成的代码中使用。没有源码会依赖这个 API。
inject	ɵɵinject	v8	Used only in generated code. No source code should depend on this API.
inject	ɵɵinject	v8	仅在生成的代码中使用。没有源码会依赖这个 API。
ReflectiveInjector	Injector.create	v5	See ReflectiveInjector
ReflectiveInjector	Injector.create	v5	参见 ReflectiveInjector
ReflectiveKey	none	v5	none
ReflectiveKey	无	v5	无
RenderComponentType	RendererType2 and Renderer2	v4	none
RenderComponentType	RendererType2和Renderer2	v4	无
Renderer	Renderer2	v4	none
Renderer	Renderer2	v4	无
RootRenderer	RendererFactory2	v4	none
RootRenderer	RendererFactory2	v4	无
ViewEncapsulation.Native	ViewEncapsulation.ShadowDom	v6	Use the native encapsulation mechanism of the renderer. See view.ts.
ViewEncapsulation.Native	ViewEncapsulation.ShadowDom	v6	使用渲染器的原生封装方式（Native）。参见 view.ts

@angular/core/testing

API	Replacement	Deprecation announced	Notes
API	替代品	已宣布弃用	备注
TestBed.deprecatedOverrideProvider()	TestBed.overrideProvider()	v7	none
TestBed.deprecatedOverrideProvider()	TestBed.overrideProvider()	v7	无
TestBedStatic.deprecatedOverrideProvider()	TestBedStatic.overrideProvider()	v5	none
TestBedStatic.deprecatedOverrideProvider()	TestBedStatic.overrideProvider()	v5	无

@angular/forms

API	Replacement	Deprecation announced	Notes
API	替代品	已宣布弃用	备注
NgFormSelectorWarning	n/a	v6	See ngForm.
NgFormSelectorWarning	不适用	v6	参见 ngForm 。

@angular/router

API	Replacement	Deprecation announced	Notes
API	替代品	已宣布弃用	备注
preserveQueryParams	queryParamsHandling	v4	none
preserveQueryParams	queryParamsHandling	v4	无

@angular/upgrade

API	Replacement	Deprecation announced	Notes
API	替代品	已宣布弃用	备注
All entry points	@angular/upgrade/static	v5	See Upgrading from AngularJS.
所有入口点	@angular/upgrade/static	v5	参见从 AngularJS 升级 。

@angular/upgrade/static

API	Replacement	Deprecation announced	Notes
API	替代品	已宣布弃用	备注
getAngularLib	getAngularJSGlobal	v5	See Upgrading from AngularJS.
getAngularLib	getAngularJSGlobal	v5	参见从 AngularJS 升级 。
setAngularLib	setAngularJSGlobal	v5	See Upgrading from AngularJS.
setAngularLib	setAngularJSGlobal	v5	参见从 AngularJS 升级 。

{@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 section above. It also includes deprecated API usage scenarios or API combinations, to augment the information above.

本节列出了所有当前已弃用的特性，包括模板语法、配置选项，以及前面已弃用的 API 部分未列出的其它弃用。它还包括已弃用的 API 用例或 API 组合，以增强上述信息。

{@a component-styles}

Component styles

组件样式

The shadow-piercing descendant combinator is deprecated and support is being removed from major browsers and tools. As such, in v4 we deprecated support in Angular for all 3 of /deep/, >>> and ::ng-deep. Until removal, ::ng-deep is preferred for broader compatibility with the tools.

刺穿 Shadow DOM 的 CSS 组合符已经弃用，并且主要的浏览器和工具都已删除它。因此，在 v4 中，Angular 也弃用了对 /deep/，>>> 和 ::ng-deep 的支持。在彻底删除它之前，我们首选::ng-deep ，以便和各种工具实现更广泛的兼容。

For more information, see /deep/, >>>, and ::ng-deep in the Component Styles guide.

欲知详情，参阅“组件样式”一章中的 /deep/，>>> 和 :: ng-deep。

{@a template-tag}

<template> tag

<template> 标签

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.

<template> 标记在 v4 中已弃用，以避免与同名的 DOM 元素冲突（例如当使用 Web Components 时）。请改用 <ng-template>。欲知详情，请参阅预先编译一章。

{@a ngform}

ngForm element selector

ngForm 元素选择器

Support for using ngForm element selector was deprecated in v6. It has been deprecated to be consistent with other core Angular selectors, which are typically written in kebab-case.

在 v6 中不再支持使用 ngForm 元素选择器了。它已被弃用，以便与其它核心 Angular 选择器保持一致，那些选择器通常写作中线形式（kebab-case）。

Deprecated:

已弃用：

<ngForm #myForm="ngForm">

Replacement:

替代品：

<ng-form #myForm="ngForm">

The NgFormSelectorWarning directive is solely used to display warnings when the deprecated ngForm selector is used.

当使用这个已弃用的 ngForm 选择器时， NgFormSelectorWarning 指令只是用来显示警告信息的。

{@a ngmodel-reactive}

ngModel with reactive forms

和响应式表单一起使用 ngModel

Support for using the ngModel input property and ngModelChange event with reactive form directives was deprecated in version 6.

版本 6 中已弃用：和响应式表单指令一起使用 ngModel 和 ngModelChange。

For more information, see the usage notes for FormControlDirective and FormControlName.

欲知详情，请参阅 FormControlDirective 和 FormControlName 的用法说明部分。

{@a sw-versionedfiles}

Service worker versionedFiles

Service Worker 的 versionedFiles

In the service worker configuration file ngsw-config.json, versionedFiles and files have the same behavior. As of v6, versionedFiles is deprecated; use files instead.

在 Service Worker 的配置文件 ngsw-config.json 中，versionedFiles 和 files 的行为是完全一样的。从 v6 开始，弃用 versionedFiles，请改用files。

For more information, see Service Worker Configuration.

欲知详情，请参阅Service Worker 配置 。

{@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.

在 v5 中，Angular 用 StaticInjector 代替了 ReflectiveInjector。该注入器不再需要 Reflect 的腻子脚本，对大部分开发人员来说都显著减小了应用的体积。

Before:

之前：

ReflectiveInjector.resolveAndCreate(providers);

After:

之后：

Injector.create({providers});

{@a i18n-pipes}

Pipes using Intl API

使用 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.

Angular 曾依赖浏览器的 i18n API，来提供数字、日期和货币的格式化功能。这种做法意味着大多数应用都需要使用腻子脚本，用户还会看到不同浏览器上的结果不一致，并且常见的格式（例如货币管道）不能满足开发者的期望。

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 Unicode Common Locale Data Repository (CLDR) instead of the JS Intl API to provide extensive locale support.

在 4.3 版本中，Angular 引入了新的数字，日期和货币管道，可以提高浏览器的标准化水平，并且无需 i18n 的腻子脚本。这些管道使用通用语言环境数据仓库（CLDR）而不是 JS Intl API，以便提供更广泛的本地化支持。

In version 5.0.0, Angular updated its standard pipes to use the CLRD implementation. At that time, Angular also added DeprecatedI18NPipesModule and related APIs to provide limited-time access to the old behavior. If you need to use these Deprecated* pipes, see Angular change log and the Date Formats mappings.

在 5.0.0 版本中，Angular 修改了它的标准管道，以便使用 CLRD 来实现。那时，Angular 还添加了DeprecatedI18NPipesModule 和相关的 API 来提供对原有行为的限时访问。如果你要使用这些 Deprecated* 管道，可参见 Angular 的变更日志和日期格式的映射表 。

Reminder: If you use these Deprecated* pipes, you should migrate to the current APIs listed above as soon as possible. These deprecated APIs are candidates for removal in the next major release.

提醒：如果你用到了这些 Deprecated* 管道，那么你应该尽快迁移到上面列出的新 API。这些已弃用的 API 都是下一个主版本中准备删除的 API。

{@a loadChildren}

loadChildren string syntax

loadChildren 字符串语法

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.

当 Angular 第一次引入惰性路由时，还没有浏览器能支持动态加载额外的 JavaScript。因此 Angular 创建了自己的方案，所用的语法是 loadChildren: './lazy/lazy.module#LazyModule' 并且还构建了一些工具来支持它。现在，很多浏览器都已支持 ECMAScript 的动态导入，Angular 也正朝着这个新语法前进。

In v8, the string syntax for the loadChildren route specification was deprecated, in favor of new syntax that uses import() syntax.

在 v8 中，不推荐使用 loadChildren 路由规范的字符串语法，loadChildren 支持使用基于 import() 的新语法。

Before:

之前：

const routes: Routes = [{
  path: 'lazy',
  // The following string syntax for loadChildren is deprecated
  loadChildren: './lazy/lazy.module#LazyModule'
}];

After:

之后：

const routes: Routes = [{
  path: 'lazy',
  // The new import() syntax 
  loadChildren: () => import('./lazy/lazy.module').then(m => m.LazyModule)
}];

v8 update: When you update to version 8, the ng update command performs the transformation automatically. Prior to version 7, the import() syntax only works in JIT mode (with view engine).

v8 更新：当你升级到版本 8 时，ng update 命令会自动执行转换。在版本 7 之前，import() 语法只能在 JIT 模式下运行（和视图引擎一起）。

{@a activatedroute-props}

ActivatedRoute params and queryParams properties

ActivatedRoute 的 params 和 queryParams 属性

ActivatedRoute contains two properties that are less capable than their replacements and may be deprecated in a future Angular version.

ActivatedRoute 包含两个属性 ，它们的能力低于它们的替代品，在将来的 Angular 版本中可能会弃用。

Property	Replacement
属性	替代品
params	paramMap
queryParams	queryParamMap

For more information see the Router guide.

欲知详情，参见路由器指南 。

{@a removed}

Removed APIs

已删除的 API

The following APIs have been removed starting with version 8.0.0:

从 8.0.0 开始，已删除下列 API：

Package	API	Replacement	Notes
包	API	替代品	备注
@angular/http	All exports	@angular/common/http	See below.
@angular/http	全部导出	@angular/common/http	参见下文 。
@angular/http/testing	All exports	@angular/common/http/testing	See below.
@angular/http/testing	全部导出	@angular/common/http/testing	参见下文 。
@angular/platform-browser	DOCUMENT	DOCUMENT in @angular/common	Updating to version 8 with ng update changes this automatically.
@angular/platform-browser	DOCUMENT	@angular/common DOCUMENT	使用 ng update 更新到版本 8 时会自动更改。

{@a http}

@angular/http

The entire @angular/http package has been removed. Use @angular/common/http instead.

已删除了整个 @angular/http 包。请改用 @angular/common/http。

The new API is a smaller, easier, and more powerful way to make HTTP requests in Angular. The new API simplifies the default ergonomics: There is no need to map by invoking the .json() method. It also supports typed return values and interceptors.

新的 API 用一种更小、更简单、更强大的方式来在 Angular 中发起 HTTP 请求。新的 API 简化成了更人性化的默认设计：不用再通过调用 .json() 方法进行映射。它还支持带类型的返回值，以及拦截器。

To update your apps:

要更新你的应用：

• Replace HttpModule with HttpClientModule (from @angular/common/http) in each of your modules.

  在每个模块中用 HttpClientModule （来自 @angular/common/http ）代替 HttpModule。

• Replace the Http service with the HttpClient service.

  用 HttpClient 服务代替 Http 服务。

• Remove any map(res => res.json()) calls. They are no longer needed.

  删除所有 map(res => res.json()) 调用，它们没用了。

For more information about using @angular/common/http, see the HttpClient guide.

有关使用 @angular/common/http 的更多信息，请参见 HttpClient 指南 。

@angular/http	Closest replacement in @angular/common/http
@angular/http	@angular/common/http 中最接近的替代品
BaseRequestOptions	HttpRequest
BaseResponseOptions	HttpResponse
BrowserXhr
Connection	HttpBackend
ConnectionBackend	HttpBackend
CookieXSRFStrategy	HttpClientXsrfModule
Headers	HttpHeaders
Http	HttpClient
HttpModule	HttpClientModule
Jsonp	HttpClient
JSONPBackend	JsonpClientBackend
JSONPConnection	JsonpClientBackend
JsonpModule	HttpClientJsonpModule
QueryEncoder	HttpUrlEncodingCodec
ReadyState	HttpBackend
Request	HttpRequest
RequestMethod	HttpClient
RequestOptions	HttpRequest
RequestOptionsArgs	HttpRequest
Response	HttpResponse
ResponseContentType	HttpClient
ResponseOptions	HttpResponse
ResponseOptionsArgs	HttpResponse
ResponseType	HttpClient
URLSearchParams	HttpParams
XHRBackend	HttpXhrBackend
XHRConnection	HttpXhrBackend
XSRFStrategy	HttpClientXsrfModule

@angular/http/testing	Closest replacement in @angular/common/http/testing
@angular/http/testing	@angular/common/http/testing 中最接近的替代品
MockBackend	HttpTestingController
MockConnection	HttpTestingController