iSharkFly-Docs
/
angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: 翻译 API 文档

This commit is contained in:
Zhicheng WANG 2021-02-04 19:45:54 +08:00
parent ade723a83d
commit 3b428a1118
194 changed files with 7503 additions and 204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
aio/content/marketing/docs.md
View File

@ -65,7 +65,7 @@ Most Angular code can be written with just the latest JavaScript, using [types](
有些企业内部的防火墙比较严格，如果无法打开 <https://angular.cn>，你可以在企业内部进行私有化部署。步骤如下：
本文档的预编译版本位于 [Github](https://github.com/ng-docs/ng-docs.github.io) 上，如果你想进行私有化部署，请把它 Clone 下来，在 nginx 等服务器上按照静态网站的形式做部署即可，除此之外不需要任何服务端环境。
本文档的预编译版本位于 [Github](https://github.com/ng-docs/latest.angular.live) 上，如果你想进行私有化部署，请把它 Clone 下来，在 nginx 等服务器上按照静态网站的形式做部署即可，除此之外不需要任何服务端环境。
以 Nginx 为例，你需要在 nginx 上做如下改动：

34
packages/animations/src/animation_builder.ts
View File

@ -13,23 +13,37 @@ import {AnimationPlayer} from './players/animation_player';
* Angular component or directive.
* Provided by the `BrowserAnimationsModule` or `NoopAnimationsModule`.
*
* 一种可注入服务，可在 Angular 组件或指令中以编程的方式生成动画序列。由 `BrowserAnimationsModule` 或 `NoopAnimationsModule` 提供。
*
* @usageNotes
*
* To use this service, add it to your component or directive as a dependency.
* The service is instantiated along with your component.
*
* 要使用此服务，请将其作为依赖项添加到你的组件或指令中。该服务与你的组件一起实例化。
*
* Apps do not typically need to create their own animation players, but if you
* do need to, follow these steps:
*
* 应用通常不需要创建自己的动画播放器，但是如果需要，请按照以下步骤操作：
*
* 1. Use the `build()` method to create a programmatic animation using the
* `animate()` function. The method returns an `AnimationFactory` instance.
*
* 使用 `build()` 方法创建一个用 `animate()` 函数创建的程序性动画。该方法返回一个 `AnimationFactory` 实例。
*
* 2. Use the factory object to create an `AnimationPlayer` and attach it to a DOM element.
*
* 使用工厂对象创建 `AnimationPlayer` 并将其附加到 DOM 元素。
*
* 3. Use the player object to control the animation programmatically.
*
* 使用播放器对象以编程方式控制动画。
*
* For example:
*
* 例如：
*
* ```ts
* // import the service from BrowserAnimationsModule
* import {AnimationBuilder} from '@angular/animations';
@ -57,8 +71,17 @@ import {AnimationPlayer} from './players/animation_player';
export abstract class AnimationBuilder {
/**
* Builds a factory for producing a defined animation.
*
* 建立一个工厂来产生所定义的动画。
*
* @param animation A reusable animation definition.
*
* 可复用的动画定义。
*
* @returns A factory object that can create a player for the defined animation.
*
* 可以为所定义的动画创建播放器的工厂对象。
*
* @see `animate()`
*/
abstract build(animation: AnimationMetadata|AnimationMetadata[]): AnimationFactory;
@ -67,6 +90,8 @@ export abstract class AnimationBuilder {
/**
* A factory object returned from the `AnimationBuilder`.`build()` method.
*
* 从 `AnimationBuilder`.`build()` 方法返回的工厂对象。。
*
* @publicApi
*/
export abstract class AnimationFactory {
@ -74,9 +99,18 @@ export abstract class AnimationFactory {
* Creates an `AnimationPlayer` instance for the reusable animation defined by
* the `AnimationBuilder`.`build()` method that created this factory.
* Attaches the new player a DOM element.
*
* 创建一个 `AnimationPlayer` 实例，是由 `AnimationBuilder`.`build()` 方法定义的可复用动画。把这个新的播放器实例附加到一个 DOM 元素上。
*
* @param element The DOM element to which to attach the animation.
*
* 要将动画附加到的 DOM 元素。
*
* @param options A set of options that can include a time delay and
* additional developer-defined parameters.
*
* 一组选项，可以包括延迟时间和其他由开发人员定义的参数。
*
*/
abstract create(element: any, options?: AnimationOptions): AnimationPlayer;
}

23
packages/animations/src/animation_event.ts
View File

@ -10,6 +10,8 @@
* An instance of this class is returned as an event parameter when an animation
* callback is captured for an animation either during the start or done phase.
*
* 在开始或完成阶段调用已捕获动画的回调时，将此类的实例作为事件参数返回。
*
* ```typescript
* @Component({
* host: {
@ -40,31 +42,52 @@
export interface AnimationEvent {
/**
* The name of the state from which the animation is triggered.
*
* 触发动画的状态的名称。
*
*/
fromState: string;
/**
* The name of the state in which the animation completes.
*
* 动画完成状态的名称。
*
*/
toState: string;
/**
* The time it takes the animation to complete, in milliseconds.
*
* 动画完成所花费的时间（以毫秒为单位）。
*
*/
totalTime: number;
/**
* The animation phase in which the callback was invoked, one of
* "start" or "done".
*
* 调用此回调的动画阶段，是 "start" 或 "done" 之一。
*
*/
phaseName: string;
/**
* The element to which the animation is attached.
*
* 动画附加到的元素。
*
*/
element: any;
/**
* Internal.
*
* 内部。
*
*/
triggerName: string;
/**
* Internal.
*
* 内部。
*
*/
disabled: boolean;
}

14
packages/animations/src/animation_metadata.ts
View File

@ -653,6 +653,7 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
* 用于包装该触发器数据的对象。
*
* @usageNotes
*
* Define an animation trigger in the `animations` section of `@Component` metadata.
* In the template, reference the trigger by name and bind it to a trigger expression that
* evaluates to a defined animation state, using the following format:
@ -888,6 +889,7 @@ export function trigger(name: string, definitions: AnimationMetadata[]): Animati
* 一个用于封装动画步骤的对象。
*
* @usageNotes
*
* Call within an animation `sequence()`, `{@link animations/group group()}`, or
* `transition()` call to specify an animation step
* that applies given style data to the parent animation for a given amount of time.
@ -1002,6 +1004,7 @@ export function animate(
* 一个封装了该组数据的对象。
*
* @usageNotes
*
* Grouped animations are useful when a series of styles must be
* animated at different starting times and closed off at different ending times.
*
@ -1056,6 +1059,7 @@ export function group(
* 一个封装了该动画序列数据的对象。
*
* @usageNotes
*
* When you pass an array of steps to a
* `transition()` call, the steps run sequentially by default.
* Compare this to the `{@link animations/group group()}` call, which runs animation steps in
@ -1070,6 +1074,7 @@ export function group(
*
* 当在 `{@link animations/group group()}` 或 `transition()` 调用中应用动画序列时，
* 只有当每个内部动画步骤都完成之后，才会继续执行下一个指令。
*
* @publicApi
**/
export function sequence(
@ -1113,6 +1118,7 @@ export function sequence(
* 一个封装了样式数据的对象。
*
* @usageNotes
*
* The following examples create animation styles that collect a set of
* CSS property values:
*
@ -1185,6 +1191,7 @@ export function style(tokens: '*'|{[key: string]: string | number}|
* 一个封装了新状态数据的对象。
*
* @usageNotes
*
* Use the `trigger()` function to register states to an animation trigger.
* Use the `transition()` function to animate between states.
* When a state is active within a component, its associated styles persist on the element,
@ -1220,6 +1227,7 @@ export function state(
* 一个封装关键帧数据的对象。
*
* @usageNotes
*
* Use with the `animate()` call. Instead of applying animations
* from the current state
* to the destination state, keyframes describe how each style entry is applied and at what point
@ -1335,6 +1343,7 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe
* 一个封装了转场数据的对象。
*
* @usageNotes
*
* The template associated with a component binds an animation trigger to an element.
*
* 与组件关联的模板会把动画触发器绑定到某个元素上。
@ -1542,6 +1551,7 @@ export function transition(
* 一个封装了动画数据的对象。
*
* @usageNotes
*
* The following example defines a reusable animation, providing some default parameter
* values.
*
@ -1602,6 +1612,7 @@ export function animation(
* 一个对象，封装了子动画数据。
*
* @usageNotes
*
* Each time an animation is triggered in Angular, the parent animation
* has priority and any child animations are blocked. In order
* for a child animation to run, the parent animation must query each of the elements
@ -1698,6 +1709,7 @@ export function useAnimation(
* 一个封装了查询数据的对象。
*
* @usageNotes
*
* Tokens can be merged into a combined query selector string. For example:
*
* 多个令牌可以合并成复合查询选择器。比如：
@ -1774,7 +1786,6 @@ export function useAnimation(
* }
* }
* ```
*
* @publicApi
*/
export function query(
@ -1802,6 +1813,7 @@ export function query(
* 一个封装了交错数据的对象。
*
* @usageNotes
*
* In the following example, a container element wraps a list of items stamped out
* by an `ngFor`. The container element contains an animation trigger that will later be set
* to query for each of the inner items.

70
packages/animations/src/players/animation_player.ts
View File

@ -12,6 +12,8 @@ import {scheduleMicroTask} from '../util';
* built using the `build()` method of `AnimationBuilder`. The `build()` method
* returns a factory, whose `create()` method instantiates and initializes this interface.
*
* 提供对可复用动画序列的编程控制，该动画序列是使用 `AnimationBuilder` 的 `build()` 方法构建的。 `build()` 方法返回一个工厂，其 `create()` 方法将实例化并初始化此接口。
*
* @see `AnimationBuilder`
* @see `AnimationFactory`
* @see `animate()`
@ -21,77 +23,143 @@ import {scheduleMicroTask} from '../util';
export interface AnimationPlayer {
/**
* Provides a callback to invoke when the animation finishes.
*
* 提供当动画结束时要调用的回调。
*
* @param fn The callback function.
*
* 回调函数。
*
* @see `finish()`
*/
onDone(fn: () => void): void;
/**
* Provides a callback to invoke when the animation starts.
*
* 提供当动画启动时要调用的回调。
*
* @param fn The callback function.
*
* 回调函数。
*
* @see `run()`
*/
onStart(fn: () => void): void;
/**
* Provides a callback to invoke after the animation is destroyed.
*
* 提供当动画销毁后要调用的回调。
*
* @param fn The callback function.
*
* 回调函数。
*
* @see `destroy()`
* @see `beforeDestroy()`
*/
onDestroy(fn: () => void): void;
/**
* Initializes the animation.
*
* 初始化本动画。
*
*/
init(): void;
/**
* Reports whether the animation has started.
*
* 报告动画是否已开始。
*
* @returns True if the animation has started, false otherwise.
*
* 如果动画已开始，则为 true，否则为 false。
*
*/
hasStarted(): boolean;
/**
* Runs the animation, invoking the `onStart()` callback.
*
* 运行动画，并调用 `onStart()` 回调。
*
*/
play(): void;
/**
* Pauses the animation.
*
* 暂停动画。
*
*/
pause(): void;
/**
* Restarts the paused animation.
*
* 重新开始已暂停的动画。
*
*/
restart(): void;
/**
* Ends the animation, invoking the `onDone()` callback.
*
* 结束动画，并调用 `onDone()` 回调。
*
*/
finish(): void;
/**
* Destroys the animation, after invoking the `beforeDestroy()` callback.
* Calls the `onDestroy()` callback when destruction is completed.
*
* 在调用 `beforeDestroy()` 回调后销毁动画。销毁完成时调用 `onDestroy()`。
*
*/
destroy(): void;
/**
* Resets the animation to its initial state.
*
* 将动画重置为其初始状态。
*
*/
reset(): void;
/**
* Sets the position of the animation.
*
* 设置动画的位置。
*
* @param position A 0-based offset into the duration, in milliseconds.
*
* 持续时间中从 0 开始的偏移量，以毫秒为单位。
*
*/
setPosition(position: any /** TODO #9100 */): void;
/**
* Reports the current position of the animation.
*
* 报告动画的当前位置。
*
* @returns A 0-based offset into the duration, in milliseconds.
*
* 持续时间中从 0 开始的偏移量，以毫秒为单位。
*
*/
getPosition(): number;
/**
* The parent of this player, if any.
*
* 此播放器的父项（如果有）。
*
*/
parentPlayer: AnimationPlayer|null;
/**
* The total run time of the animation, in milliseconds.
*
* 动画的总运行时间（以毫秒为单位）。
*
*/
readonly totalTime: number;
/**
* Provides a callback to invoke before the animation is destroyed.
*
* 提供在动画销毁之前要调用的回调。
*
*/
beforeDestroy?: () => any;
/**
@ -111,6 +179,8 @@ export interface AnimationPlayer {
* Used internally when animations are disabled, to avoid
* checking for the null case when an animation player is expected.
*
* 用于可复用动画的空白程序控制器。当禁用动画时在内部使用，以免在要用动画播放器时检查其是否为 null。
*
* @see `animate()`
* @see `AnimationPlayer`
* @see `GroupPlayer`

1487
packages/common/http/src/client.ts
View File

File diff suppressed because it is too large Load Diff

39
packages/common/http/src/headers.ts
View File

@ -53,7 +53,12 @@ export class HttpHeaders {
*/
private lazyUpdate: Update[]|null = null;
/** Constructs a new HTTP header object with the given values.*/
/**
* Constructs a new HTTP header object with the given values.
*
* 使用给定的值构造一个新的 HTTP 标头对象。
*
*/
constructor(headers?: string|{[name: string]: string | string[]}) {
if (!headers) {
@ -161,7 +166,7 @@ export class HttpHeaders {
*
* @returns A string of values if the header exists, null otherwise.
*
* 如果头存在则返回一个字符串数组，否则返回 null。
* 如果标头存在则返回一个字符串数组，否则返回 null。
*
*/
getAll(name: string): string[]|null {
@ -174,10 +179,20 @@ export class HttpHeaders {
* Appends a new value to the existing set of values for a header
* and returns them in a clone of the original instance.
*
* 将新值附加到标头的现有值集中，并在原始实例的克隆中返回它们。
*
* @param name The header name for which to append the values.
*
* 要附加值的标头名称。
*
* @param value The value to append.
*
* 要附加的值。
*
* @returns A clone of the HTTP headers object with the value appended to the given header.
*
* HTTP 标头对象的克隆，带有由给定标头追加的值。
*
*/
append(name: string, value: string|string[]): HttpHeaders {
@ -188,10 +203,20 @@ export class HttpHeaders {
* If the header already exists, its value is replaced with the given value
* in the returned object.
*
* 设置或修改原始实例的克隆中给定标头的值。如果标题已经存在，则其值将在返回对象中被给定值替换。
*
* @param name The header name.
*
* 标头名称。
*
* @param value The value or values to set or overide for the given header.
*
* 要设置或覆盖给定标头的一个或多个值。
*
* @returns A clone of the HTTP headers object with the newly set header value.
*
* HTTP 标头对象的克隆，其中包含新设置的标头值。
*
*/
set(name: string, value: string|string[]): HttpHeaders {
return this.clone({name, value, op: 's'});
@ -199,10 +224,20 @@ export class HttpHeaders {
/**
* Deletes values for a given header in a clone of the original instance.
*
* 在原始实例的克隆中删除给定标头的值。
*
* @param name The header name.
*
* 标头名称。
*
* @param value The value or values to delete for the given header.
*
* 要删除的给定标头的一个或多个值。
*
* @returns A clone of the HTTP headers object with the given value deleted.
*
* HTTP 标头对象的克隆，其中删除了给定值。
*
*/
delete(name: string, value?: string|string[]): HttpHeaders {
return this.clone({name, value, op: 'd'});

13
packages/common/http/src/interceptor.ts
View File

@ -60,10 +60,21 @@ import {HttpEvent} from './response';
export interface HttpInterceptor {
/**
* Identifies and handles a given HTTP request.
*
* 标识并处理给定的 HTTP 请求。
*
* @param req The outgoing request object to handle.
*
* 要处理的传出请求对象。
*
* @param next The next interceptor in the chain, or the backend
* if no interceptors remain in the chain.
*
* 链中的下一个拦截器，如果链中没有拦截器，则为其后端接口。
*
* @returns An observable of the event stream.
*
* 事件流的可观察值。
*/
intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>>;
}
@ -86,7 +97,7 @@ export class HttpInterceptorHandler implements HttpHandler {
* `HttpInterceptor` objects.
*
*
* 一个多重提供商（multi-provider）令牌，它代表所有已注册的 `HttpInterceptor` 构成的数组。
* 一个多重提供者（multi-provider）令牌，它代表所有已注册的 `HttpInterceptor` 构成的数组。
*
* @publicApi
*/

30
packages/common/http/src/jsonp.ts
View File

@ -43,6 +43,9 @@ export abstract class JsonpCallbackContext {
/**
* Processes an `HttpRequest` with the JSONP method,
* by performing JSONP style requests.
*
* 通过执行 JSONP 风格的请求，使用 JSONP 方法处理 `HttpRequest`
*
* @see `HttpHandler`
* @see `HttpXhrBackend`
*
@ -52,6 +55,9 @@ export abstract class JsonpCallbackContext {
export class JsonpClientBackend implements HttpBackend {
/**
* A resolved promise that can be used to schedule microtasks in the event handlers.
*
* 已解决的 Promise 可用于安排事件处理器中的微任务。
*
*/
private readonly resolvedPromise = Promise.resolve();
@ -59,6 +65,9 @@ export class JsonpClientBackend implements HttpBackend {
/**
* Get the name of the next callback method, by incrementing the global `nextRequestId`.
*
* 通过递增 `nextRequestId`，来获取下一个回调方法的名称。
*
*/
private nextCallback(): string {
return `ng_jsonp_callback_${nextRequestId++}`;
@ -66,9 +75,17 @@ export class JsonpClientBackend implements HttpBackend {
/**
* Processes a JSONP request and returns an event stream of the results.
*
* 处理 JSONP 请求并返回结果的事件流。
*
* @param req The request object.
*
* 请求对象。
*
* @returns An observable of the response events.
*
* 响应事件的可观察对象。
*
*/
handle(req: HttpRequest<never>): Observable<HttpEvent<any>> {
// Firstly, check both the method and response type. If either doesn't match
@ -227,6 +244,8 @@ export class JsonpClientBackend implements HttpBackend {
* Identifies requests with the method JSONP and
* shifts them to the `JsonpClientBackend`.
*
* 使用 JSONP 方法标识这些请求，并将其转移到 `JsonpClientBackend` 。
*
* @see `HttpInterceptor`
*
* @publicApi
@ -237,10 +256,21 @@ export class JsonpInterceptor {
/**
* Identifies and handles a given JSONP request.
*
* 识别并处理给定的 JSONP 请求。
*
* @param req The outgoing request object to handle.
*
* 要处理的传出请求对象。
*
* @param next The next interceptor in the chain, or the backend
* if no interceptors remain in the chain.
*
* 链中的下一个拦截器，如果链中没有拦截器，则为其后端接口。
*
* @returns An observable of the event stream.
*
* 事件流的可观察对象。
*/
intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
if (req.method === 'JSONP') {

94
packages/common/http/src/params.ts
View File

@ -28,6 +28,8 @@ export interface HttpParameterCodec {
/**
* Provides encoding and decoding of URL parameter and query-string values.
*
* 提供 URL 参数和查询字符串值的编码和解码。
*
* Serializes and parses URL parameter keys and values to encode and decode them.
* If you pass URL query parameters without encoding,
* the query parameters can be misinterpreted at the receiving end.
@ -41,8 +43,17 @@ export interface HttpParameterCodec {
export class HttpUrlEncodingCodec implements HttpParameterCodec {
/**
* Encodes a key name for a URL parameter or query-string.
*
* 编码 URL 参数或查询字符串的键名。
*
* @param key The key name.
*
* 键名。
*
* @returns The encoded key name.
*
* 编码过的键名。
*
*/
encodeKey(key: string): string {
return standardEncoding(key);
@ -50,8 +61,17 @@ export class HttpUrlEncodingCodec implements HttpParameterCodec {
/**
* Encodes the value of a URL parameter or query-string.
*
* 对 URL 参数或查询字符串的值进行编码。
*
* @param value The value.
*
* 值。
*
* @returns The encoded value.
*
* 编码过的值。
*
*/
encodeValue(value: string): string {
return standardEncoding(value);
@ -59,8 +79,17 @@ export class HttpUrlEncodingCodec implements HttpParameterCodec {
/**
* Decodes an encoded URL parameter or query-string key.
*
* 解码编码的 URL 参数或查询字符串键。
*
* @param key The encoded key name.
*
* 编码过的键名。
*
* @returns The decoded key name.
*
* 解码过的键名。
*
*/
decodeKey(key: string): string {
return decodeURIComponent(key);
@ -68,8 +97,17 @@ export class HttpUrlEncodingCodec implements HttpParameterCodec {
/**
* Decodes an encoded URL parameter or query-string value.
*
* 解码编码的 URL 参数或查询字符串值。
*
* @param value The encoded value.
*
* 编码过的值。
*
* @returns The decoded value.
*
* 解码过的值。
*
*/
decodeValue(value: string) {
return decodeURIComponent(value);
@ -145,7 +183,7 @@ export interface HttpParamsOptions {
* An HTTP request/response body that represents serialized parameters,
* per the MIME type `application/x-www-form-urlencoded`.
*
* HTTP 请求/响应体，用来表示序列化参数，它们的 MIME 类型都是 `application/x-www-form-urlencoded`。
* HTTP 请求体/响应体，用来表示序列化参数，它们的 MIME 类型都是 `application/x-www-form-urlencoded`。
*
* This class is immutable; all mutation operations return a new instance.
*
@ -179,9 +217,18 @@ export class HttpParams {
/**
* Reports whether the body includes one or more values for a given parameter.
*
* 报告主体中是否包含给定参数的一个或多个值。
*
* @param param The parameter name.
*
* 参数名称。
*
* @returns True if the parameter has one or more values,
* false if it has no value or is not present.
*
* 如果参数具有一个或多个值，则为 true；如果参数没有值或不存在，则为 false。
*
*/
has(param: string): boolean {
this.init();
@ -190,7 +237,13 @@ export class HttpParams {
/**
* Retrieves the first value for a parameter.
*
* 检索参数的第一个值。
*
* @param param The parameter name.
*
* 参数名称。
*
* @returns The first value of the given parameter,
* or `null` if the parameter is not present.
*
@ -204,7 +257,13 @@ export class HttpParams {
/**
* Retrieves all values for a parameter.
*
* 检索某个参数的所有值。
*
* @param param The parameter name.
*
* 参数名称。
*
* @returns All values in a string array,
* or `null` if the parameter not present.
*
@ -217,7 +276,13 @@ export class HttpParams {
/**
* Retrieves all the parameters for this body.
*
* 检索此 `body` 的所有参数。
*
* @returns The parameter names in a string array.
*
* 字符串数组中的参数名称。
*
*/
keys(): string[] {
this.init();
@ -226,8 +291,17 @@ export class HttpParams {
/**
* Appends a new value to existing values for a parameter.
*
* 将新值附加到参数的现有值。
*
* @param param The parameter name.
*
* 参数名称。
*
* @param value The new value to add.
*
* 要添加的新值。
*
* @return A new body with the appended value.
*
* 构造一个新的 `body`，添加一个具有给定参数名的值。
@ -238,8 +312,17 @@ export class HttpParams {
/**
* Replaces the value for a parameter.
*
* 替换参数的值。
*
* @param param The parameter name.
*
* 参数名称。
*
* @param value The new value.
*
* 新值。
*
* @return A new body with the new value.
*
* 构造一个新的 `body`，具有一个给定参数名的新值。
@ -250,8 +333,17 @@ export class HttpParams {
/**
* Removes a given value or all values from a parameter.
*
* 从参数中删除给定值或所有值。
*
* @param param The parameter name.
*
* 参数名称。
*
* @param value The value to remove, if provided.
*
* 要删除的值（如果提供）。
*
* @return A new body with the given value removed, or with all values
* removed if no value is specified.
*

5
packages/common/http/src/response.ts
View File

@ -19,7 +19,7 @@ export enum HttpEventType {
/**
* The request was sent out over the wire.
*
* 该请求已经在线路上发出了。
* 该请求已经在路由上发出了。
*/
Sent,
@ -62,8 +62,8 @@ export enum HttpEventType {
/**
* Base interface for progress events.
*
*
* 进度事件的基础接口。
*
* @publicApi
*/
export interface HttpProgressEvent {
@ -396,7 +396,6 @@ export class HttpResponse<T> extends HttpResponseBase {
* will contain either a wrapped Error object or the error response returned
* from the server.
*
*
* 任何从 `Observable` 响应流中返回的错误都会被包装成 `HttpErrorResponse` 对象，以便在发生错误时，提供关于 HTTP 层状态的额外上下文信息。
* 该错误或者包含一个包装好的错误对象，或者包含一个从服务端返回的错误响应体。
*

14
packages/common/http/src/xhr.ts
View File

@ -33,6 +33,8 @@ function getResponseUrl(xhr: any): string|null {
/**
* A wrapper around the `XMLHttpRequest` constructor.
*
* `XMLHttpRequest` 构造函数的包装器。
*
* @publicApi
*/
export abstract class XhrFactory {
@ -63,6 +65,9 @@ interface PartialResponse {
/**
* Uses `XMLHttpRequest` to send requests to a backend server.
*
* 使用 `XMLHttpRequest` 将请求发送到后端服务器。
*
* @see `HttpHandler`
* @see `JsonpClientBackend`
*
@ -74,8 +79,17 @@ export class HttpXhrBackend implements HttpBackend {
/**
* Processes a request and returns a stream of response events.
*
* 处理请求并返回响应事件流。
*
* @param req The request object.
*
* 请求对象。
*
* @returns An observable of the response events.
*
* 响应事件的可观察对象。
*
*/
handle(req: HttpRequest<any>): Observable<HttpEvent<any>> {
// Quick check to give a better error message when a user attempts to use

7
packages/common/http/src/xsrf.ts
View File

@ -21,13 +21,20 @@ export const XSRF_HEADER_NAME = new InjectionToken<string>('XSRF_HEADER_NAME');
/**
* Retrieves the current XSRF token to use with the next outgoing request.
*
* 检索当前的 XSRF 令牌以用于下一个传出请求。
*
* @publicApi
*/
export abstract class HttpXsrfTokenExtractor {
/**
* Get the XSRF token to use with an outgoing request.
*
* 获取 XSRF 令牌以用于传出请求。
*
* Will be called for every request, so the token may change between requests.
*
* 在每个请求中都会被调用，因此该令牌可能会在请求之间更改。
*
*/
abstract getToken(): string|null;
}

54
packages/common/http/testing/src/api.ts
View File

@ -13,6 +13,8 @@ import {TestRequest} from './request';
/**
* Defines a matcher for requests based on URL, method, or both.
*
* 为基于 URL 和/或 method 的请求定义匹配器。
*
* @publicApi
*/
export interface RequestMatch {
@ -24,11 +26,16 @@ export interface RequestMatch {
* Controller to be injected into tests, that allows for mocking and flushing
* of requests.
*
* 控制器将被注入到测试中，从而可以模拟和刷新请求。
*
* @publicApi
*/
export abstract class HttpTestingController {
/**
* Search for requests that match the given parameter, without any expectations.
*
* 搜索与给定参数匹配且不带任何期望语句的请求。
*
*/
abstract match(match: string|RequestMatch|((req: HttpRequest<any>) => boolean)): TestRequest[];
@ -36,8 +43,13 @@ export abstract class HttpTestingController {
* Expect that a single request has been made which matches the given URL, and return its
* mock.
*
* 期望发出一个与给定 URL 匹配的单个请求，然后返回其模拟对象。
*
* If no such request has been made, or more than one such request has been made, fail with an
* error message including the given request description, if any.
*
* 如果没有发出这样的请求，或者发出过多个这样的请求，则失败，并显示一条错误消息，其中包括给定请求的描述（如果有）。
*
*/
abstract expectOne(url: string, description?: string): TestRequest;
@ -45,8 +57,13 @@ export abstract class HttpTestingController {
* Expect that a single request has been made which matches the given parameters, and return
* its mock.
*
* 期望发出一个与给定参数匹配的单个请求，然后返回其模拟对象。
*
* If no such request has been made, or more than one such request has been made, fail with an
* error message including the given request description, if any.
*
* 如果没有发出这样的请求，或者发出过多个这样的请求，则失败，并显示一条错误消息，其中包括给定请求的描述（如果有）。
*
*/
abstract expectOne(params: RequestMatch, description?: string): TestRequest;
@ -54,8 +71,13 @@ export abstract class HttpTestingController {
* Expect that a single request has been made which matches the given predicate function, and
* return its mock.
*
* 期望发出一个与给定谓词函数匹配的单个请求，然后返回其模拟对象。
*
* If no such request has been made, or more than one such request has been made, fail with an
* error message including the given request description, if any.
*
* 如果没有发出这样的请求，或者发出过多个这样的请求，则失败，并显示一条错误消息，其中包括给定请求的描述（如果有）。
*
*/
abstract expectOne(matchFn: ((req: HttpRequest<any>) => boolean), description?: string):
TestRequest;
@ -64,8 +86,13 @@ export abstract class HttpTestingController {
* Expect that a single request has been made which matches the given condition, and return
* its mock.
*
* 期望发出一个与给定条件匹配的单个请求，然后返回其模拟对象。
*
* If no such request has been made, or more than one such request has been made, fail with an
* error message including the given request description, if any.
*
* 如果没有发出这样的请求，或者发出过多个这样的请求，则失败，并显示一条错误消息，其中包括给定请求的描述（如果有）。
*
*/
abstract expectOne(
match: string|RequestMatch|((req: HttpRequest<any>) => boolean),
@ -74,32 +101,52 @@ export abstract class HttpTestingController {
/**
* Expect that no requests have been made which match the given URL.
*
* 期望没有发出过与给定 URL 匹配的请求。
*
* If a matching request has been made, fail with an error message including the given request
* description, if any.
*
* 如果发出了匹配的请求，则失败并显示一条错误消息，其中包括给定请求的描述（如果有）。
*
*/
abstract expectNone(url: string, description?: string): void;
/**
* Expect that no requests have been made which match the given parameters.
*
* 期望没有发出过与给定参数匹配的请求。
*
* If a matching request has been made, fail with an error message including the given request
* description, if any.
*
* 如果发出了匹配的请求，则失败并显示一条错误消息，其中包括给定请求的描述（如果有）。
*
*/
abstract expectNone(params: RequestMatch, description?: string): void;
/**
* Expect that no requests have been made which match the given predicate function.
*
* 期望没有发出过与给定谓词函数匹配的请求。
*
* If a matching request has been made, fail with an error message including the given request
* description, if any.
*
* 如果发出了匹配的请求，则失败并显示一条错误消息，其中包括给定请求的描述（如果有）。
*
*/
abstract expectNone(matchFn: ((req: HttpRequest<any>) => boolean), description?: string): void;
/**
* Expect that no requests have been made which match the given condition.
*
* 期望没有发出过与给定条件匹配的请求。
*
* If a matching request has been made, fail with an error message including the given request
* description, if any.
*
* 如果发出了匹配的请求，则失败并显示一条错误消息，其中包括给定请求的描述（如果有）。
*
*/
abstract expectNone(
match: string|RequestMatch|((req: HttpRequest<any>) => boolean), description?: string): void;
@ -107,11 +154,18 @@ export abstract class HttpTestingController {
/**
* Verify that no unmatched requests are outstanding.
*
* 验证没有任何未匹配的请求正在等待。
*
* If any requests are outstanding, fail with an error message indicating which requests were not
* handled.
*
* 如果有任何未完成的请求，则失败并显示一条错误消息，指出未处理哪些请求。
*
* If `ignoreCancelled` is not set (the default), `verify()` will also fail if cancelled requests
* were not explicitly matched.
*
* 如果未设置过 `ignoreCancelled`（默认），且未明确匹配已取消的请求，则 `verify()` 就会失败。
*
*/
abstract verify(opts?: {ignoreCancelled?: boolean}): void;
}

4
packages/common/http/testing/src/module.ts
View File

@ -16,8 +16,12 @@ import {HttpClientTestingBackend} from './backend';
/**
* Configures `HttpClientTestingBackend` as the `HttpBackend` used by `HttpClient`.
*
* 提供配置 `HttpClientTestingBackend` 作为 `HttpBackend` 所使用 `HttpClient` 。
*
* Inject `HttpTestingController` to expect and flush requests in your tests.
*
* 注入 `HttpTestingController` 以期望并刷新测试中的请求。
*
* @publicApi
*/
@NgModule({

17
packages/common/http/testing/src/request.ts
View File

@ -12,14 +12,21 @@ import {Observer} from 'rxjs';
/**
* A mock requests that was received and is ready to be answered.
*
* 已收到并准备好进行应答的模拟请求。
*
* This interface allows access to the underlying `HttpRequest`, and allows
* responding with `HttpEvent`s or `HttpErrorResponse`s.
*
* 此接口允许访问底层 `HttpRequest`，并允许使用 `HttpEvent` 或 `HttpErrorResponse` 进行响应。
*
* @publicApi
*/
export class TestRequest {
/**
* Whether the request was cancelled after it was sent.
*
* 请求在发送后是否已被取消。
*
*/
get cancelled(): boolean {
return this._cancelled;
@ -38,7 +45,11 @@ export class TestRequest {
* If the request specifies an expected body type, the body is converted into the requested type.
* Otherwise, the body is converted to `JSON` by default.
*
* 通过返回 body 以及其他 HTTP 信息（例如响应标头）（如果提供过）来解析请求。如果请求指定了预期的 body 类型，则将 body 转换为所请求的类型。否则，body 在默认情况下转换成 `JSON`。
*
* Both successful and unsuccessful responses can be delivered via `flush()`.
*
* 成功和失败的响应都可以通过 `flush()` 传递。
*/
flush(
body: ArrayBuffer|Blob|boolean|string|number|Object|(boolean|string|number|Object|null)[]|
@ -78,6 +89,9 @@ export class TestRequest {
/**
* Resolve the request by returning an `ErrorEvent` (e.g. simulating a network failure).
*
* 通过返回 `ErrorEvent` （例如，模拟网络故障）来解决请求。
*
*/
error(error: ErrorEvent, opts: {
headers?: HttpHeaders|{[name: string]: string | string[]},
@ -104,6 +118,9 @@ export class TestRequest {
/**
* Deliver an arbitrary `HttpEvent` (such as a progress event) on the response stream for this
* request.
*
* 在响应流上为此请求传递一个任意的 `HttpEvent`
*
*/
event(event: HttpEvent<any>): void {
if (this.cancelled) {

9
packages/common/src/directives/ng_class.ts
View File

@ -13,6 +13,7 @@ type NgClassSupportedTypes = string[]|Set<string>|{[klass: string]: any}|null|un
* @ngModule CommonModule
*
* @usageNotes
*
* ```
* <some-element [ngClass]="'first second'">...</some-element>
*
@ -129,10 +130,15 @@ export class NgClass implements DoCheck {
/**
* Applies a collection of CSS classes to the DOM element.
*
* 将 CSS 类的集合应用于 DOM 元素。
*
* For argument of type Set and Array CSS class names contained in those collections are always
* added.
* For argument of type Map CSS class name in the map's key is toggled based on the value (added
* for truthy and removed for falsy).
*
* 对于 Set 和 Array 类型的参数，总是添加那些集合中包含的 CSS 类名称。对于 Map 类型的参数，与映射表中的键名对应的 CSS 类名称会根据该值进行切换（为 true 添加，为 falsy 删除）。
*
*/
private _applyClasses(rawClassVal: NgClassSupportedTypes) {
if (rawClassVal) {
@ -147,6 +153,9 @@ export class NgClass implements DoCheck {
/**
* Removes a collection of CSS classes from the DOM element. This is mostly useful for cleanup
* purposes.
*
* 从 DOM 元素中删除 CSS 类的集合。这主要用于清理目的。
*
*/
private _removeClasses(rawClassVal: NgClassSupportedTypes) {
if (rawClassVal) {

27
packages/common/src/directives/ng_component_outlet.ts
View File

@ -13,32 +13,54 @@ import {ComponentFactoryResolver, ComponentRef, Directive, Injector, Input, NgMo
* Instantiates a single {@link Component} type and inserts its Host View into current View.
* `NgComponentOutlet` provides a declarative approach for dynamic component creation.
*
* 实例化单个 {@link Component} 类型，并将其宿主视图插入当前视图。`NgComponentOutlet` 为动态组件创建提供了一种声明式方法。
*
* `NgComponentOutlet` requires a component type, if a falsy value is set the view will clear and
* any existing component will get destroyed.
*
* `NgComponentOutlet` 所需的组件类型，如果设置为假值，则视图将被清除并且任何现有组件将被销毁。
*
* @usageNotes
*
* ### Fine tune control
*
* ### 微调控制
*
* You can control the component creation process by using the following optional attributes:
*
* 你可以使用以下可选属性来控制组件的创建过程：
*
* * `ngComponentOutletInjector`: Optional custom {@link Injector} that will be used as parent for
* the Component. Defaults to the injector of the current view container.
*
* `ngComponentOutletInjector`：可选的自定义 {@link Injector}，将用作此组件的父级。默认为当前视图容器的注入器。
*
* * `ngComponentOutletContent`: Optional list of projectable nodes to insert into the content
* section of the component, if exists.
*
* `ngComponentOutletContent`：要插入到组件内容部分的可投影节点的可选列表（如果存在）。
*
* * `ngComponentOutletNgModuleFactory`: Optional module factory to allow dynamically loading other
* module, then load a component from that module.
*
* `ngComponentOutletNgModuleFactory`：可选模块工厂，允许动态加载其他模块，然后从该模块加载组件。
*
* ### Syntax
*
* ### 语法
*
* Simple
*
* 简单
*
* ```
* <ng-container *ngComponentOutlet="componentTypeExpression"></ng-container>
* ```
*
* Customized injector/content
*
* 定制的注入器/内容
*
* ```
* <ng-container *ngComponentOutlet="componentTypeExpression;
* injector: injectorExpression;
@ -47,6 +69,9 @@ import {ComponentFactoryResolver, ComponentRef, Directive, Injector, Input, NgMo
* ```
*
* Customized ngModuleFactory
*
* 定制的 ngModuleFactory
*
* ```
* <ng-container *ngComponentOutlet="componentTypeExpression;
* ngModuleFactory: moduleFactory;">
@ -55,6 +80,8 @@ import {ComponentFactoryResolver, ComponentRef, Directive, Injector, Input, NgMo
*
* ### A simple example
*
* ### 一个简单的例子
*
* {@example common/ngComponentOutlet/ts/module.ts region='SimpleExample'}
*
* A more complete example with additional options:

49
packages/common/src/directives/ng_for_of.ts
View File

@ -37,14 +37,20 @@ export class NgForOfContext<T, U extends NgIterable<T> = NgIterable<T>> {
* The directive is placed on an element, which becomes the parent
* of the cloned templates.
*
* 一种[结构型指令](guide/structural-directives)，为集合中的每个条目渲染一个模板。如果指令放置在一个元素上，该元素就会成为克隆后的模板的父级。
*
* The `ngForOf` directive is generally used in the
* [shorthand form](guide/structural-directives#the-asterisk--prefix) `*ngFor`.
* In this form, the template to be rendered for each iteration is the content
* of an anchor element containing the directive.
*
* `ngForOf` 指令通常在 `*ngFor` 的[简写形式](guide/structural-directives#the-asterisk--prefix)内部使用。在这种形式下，每次迭代要渲染的模板是包含指令的锚点元素的内容。
*
* The following example shows the shorthand syntax with some options,
* contained in an `<li>` element.
*
* `<li>` 元素中包含一些选项的简写语法。
*
* ```
* <li *ngFor="let item of items; index as i; trackBy: trackByFn">...</li>
* ```
@ -54,8 +60,12 @@ export class NgForOfContext<T, U extends NgIterable<T> = NgIterable<T>> {
* The content of the `<ng-template>` element is the `<li>` element that held the
* short-form directive.
*
* 简写形式会扩展为使用 `<ng-template>` 元素 `ngForOf` 选择器的长形式。`<ng-template>` 元素的内容是包裹此简写格式指令的 `<li>` 元素。
*
* Here is the expanded version of the short-form example.
*
* 这是简写形式示例的扩展版本。
*
* ```
* <ng-template ngFor let-item [ngForOf]="items" let-i="index" [ngForTrackBy]="trackByFn">
* <li>...</li>
@ -66,6 +76,8 @@ export class NgForOfContext<T, U extends NgIterable<T> = NgIterable<T>> {
* The context for each embedded view is logically merged to the current component
* context according to its lexical position.
*
* Angular 在编译模板时会自动扩展简写语法。每个嵌入式视图的上下文都会根据其词法位置在逻辑上合并到当前组件上下文。
*
* When using the shorthand syntax, Angular allows only [one structural directive
* on an element](guide/structural-directives#one-structural-directive-per-host-element).
* If you want to iterate conditionally, for example,
@ -73,16 +85,18 @@ export class NgForOfContext<T, U extends NgIterable<T> = NgIterable<T>> {
* For futher discussion, see
* [Structural Directives](guide/structural-directives#one-per-element).
*
* `NgForOf` 指令会为可迭代对象中的每一个条目实例化一个模板。实例化时的上下文环境来自其外部环境，它以当前正在迭代的条目作为循环变量。
* 使用简写语法时，Angular 在[一个元素上只允许有一个结构型指令](guide/structural-directives#one-structural-directive-per-host-element)。例如，如果要根据条件进行迭代，请将 `*ngIf` 放在 `*ngFor` 元素的容器元素上。欲知详情，请参见[《结构型指令》](guide/structural-directives#one-per-element) 。
*
* @usageNotes
*
* ### Local variables
*
* ### 局部变量
*
* `NgForOf` provides exported values that can be aliased to local variables.
* For example:
*
* ### 局部变量
* `NgForOf` 可以为所提供的导出值指定一个局部变量别名。例如：
*
* ```
* <li *ngFor="let user of users; index as i; first as isFirst">
@ -96,7 +110,7 @@ export class NgForOfContext<T, U extends NgIterable<T> = NgIterable<T>> {
*
* - `$implicit: T`: The value of the individual items in the iterable (`ngForOf`).
*
* `$implicit: T`：迭代目标（绑定到`ngForOf`）中每个条目的值。
* `$implicit: T`：迭代目标（绑定到 `ngForOf`）中每个条目的值。
*
* - `ngForOf: NgIterable<T>`: The value of the iterable expression. Useful when the expression is
* more complex then a property access, for example when using the async pipe (`userStreams |
@ -180,6 +194,9 @@ export class NgForOfContext<T, U extends NgIterable<T> = NgIterable<T>> {
* 如果给出了 `trackBy`，Angular 就会使用该函数的返回值来跟踪变化。
*
* @see [Structural Directives](guide/structural-directives)
*
* [结构型指令](guide/structural-directives)
*
* @ngModule CommonModule
* @publicApi
*/
@ -188,6 +205,9 @@ export class NgForOf<T, U extends NgIterable<T> = NgIterable<T>> implements DoCh
/**
* The value of the iterable expression, which can be used as a
* [template input variable](guide/structural-directives#template-input-variable).
*
* 可迭代表达式的值，可以将其用作[模板输入变量](guide/structural-directives#template-input-variable)。
*
*/
@Input()
set ngForOf(ngForOf: U&NgIterable<T>|undefined|null) {
@ -197,19 +217,28 @@ export class NgForOf<T, U extends NgIterable<T> = NgIterable<T>> implements DoCh
/**
* A function that defines how to track changes for items in the iterable.
*
* 定义如何跟踪可迭代项的更改的函数。
*
* When items are added, moved, or removed in the iterable,
* the directive must re-render the appropriate DOM nodes.
* To minimize churn in the DOM, only nodes that have changed
* are re-rendered.
*
* 在迭代器中添加、移动或删除条目时，指令必须重新渲染适当的 DOM 节点。为了最大程度地减少 DOM 中的搅动，仅重新渲染已更改的节点。
*
* By default, the change detector assumes that
* the object instance identifies the node in the iterable.
* When this function is supplied, the directive uses
* the result of calling this function to identify the item node,
* rather than the identity of the object itself.
*
* 默认情况下，变更检测器假定对象实例标识可迭代对象。提供此函数后，指令将使用调用此函数的结果来标识项节点，而不是对象本身的标识。
*
* The function receives two inputs,
* the iteration index and the associated node data.
*
* 该函数接收两个输入，即迭代索引和关联的节点数据。
*
*/
@Input()
set ngForTrackBy(fn: TrackByFunction<T>) {
@ -240,7 +269,13 @@ export class NgForOf<T, U extends NgIterable<T> = NgIterable<T>> implements DoCh
/**
* A reference to the template that is stamped out for each item in the iterable.
*
* 此模板引用用来为 iterable 中的生成每个条目。
*
* @see [template reference variable](guide/template-reference-variables)
*
* [模板引用变量](guide/template-reference-variables)
*
*/
@Input()
set ngForTemplate(value: TemplateRef<NgForOfContext<T, U>>) {
@ -254,6 +289,9 @@ export class NgForOf<T, U extends NgIterable<T> = NgIterable<T>> implements DoCh
/**
* Applies the changes when needed.
*
* 要按需应用的更改。
*
*/
ngDoCheck(): void {
if (this._ngForOfDirty) {
@ -326,8 +364,13 @@ export class NgForOf<T, U extends NgIterable<T> = NgIterable<T>> implements DoCh
/**
* Asserts the correct type of the context for the template that `NgForOf` will render.
*
* 为 `NgForOf` 将要渲染的模板确保正确的上下文类型。
*
* The presence of this method is a signal to the Ivy template type-check compiler that the
* `NgForOf` structural directive renders its template with a specific context type.
*
* 此方法的存在向 Ivy 模板类型检查编译器发出信号，即 `NgForOf` 结构型指令使用特定的上下文类型渲染其模板。
*
*/
static ngTemplateContextGuard<T, U extends NgIterable<T>>(dir: NgForOf<T, U>, ctx: any):
ctx is NgForOfContext<T, U> {

60
packages/common/src/directives/ng_if.ts
View File

@ -17,20 +17,28 @@ import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef, ɵstri
* Angular renders the template provided in an optional `else` clause. The default
* template for the `else` clause is blank.
*
* 本结构型指令用于根据表达式的值（强转为 boolean）是否为真值，来有条件的包含某个模板。当表达式计算为 true 时，Angular 会渲染 `then` 子句中提供的模板，当为 false 或 null 时则渲染可选的 `else` 子句中的模板。`else` 子句的默认模板是空白模板。
*
* A [shorthand form](guide/structural-directives#the-asterisk--prefix) of the directive,
* `*ngIf="condition"`, is generally used, provided
* as an attribute of the anchor element for the inserted template.
* Angular expands this into a more explicit version, in which the anchor element
* is contained in an `<ng-template>` element.
*
* 通常使用指令的[简写形式](guide/structural-directives#the-asterisk--prefix) `*ngIf="condition"`，作为插入模板的锚点元素的属性提供。Angular 将其扩展为更明确的版本，其中锚点元素包含在 `<ng-template>` 元素中。
*
* Simple form with shorthand syntax:
*
* 具有简写语法的简单形式：
*
* ```
* <div *ngIf="condition">Content to render when condition is true.</div>
* ```
*
* Simple form with expanded syntax:
*
* 具有扩展语法的简单形式：
*
* ```
* <ng-template [ngIf]="condition"><div>Content to render when condition is
* true.</div></ng-template>
@ -38,6 +46,8 @@ import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef, ɵstri
*
* Form with an "else" block:
*
* 带有 “else” 块的格式：
*
* ```
* <div *ngIf="condition; else elseBlock">Content to render when condition is true.</div>
* <ng-template #elseBlock>Content to render when condition is false.</ng-template>
@ -45,6 +55,8 @@ import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef, ɵstri
*
* Shorthand form with "then" and "else" blocks:
*
* 带 “then” 和 “else” 块的简写形式：
*
* ```
* <div *ngIf="condition; then thenBlock else elseBlock"></div>
* <ng-template #thenBlock>Content to render when condition is true.</ng-template>
@ -53,6 +65,8 @@ import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef, ɵstri
*
* Form with storing the value locally:
*
* 本地存储值的形式：
*
* ```
* <div *ngIf="condition as value; else elseBlock">{{value}}</div>
* <ng-template #elseBlock>Content to render when value is null.</ng-template>
@ -64,52 +78,74 @@ import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef, ɵstri
* as seen in the following example.
* The default `else` template is blank.
*
* `*ngIf` 指令通常用于根据条件显示内联模板，就像下面的例子展示的一样。默认的 `else` 模板是空白的。
*
* {@example common/ngIf/ts/module.ts region='NgIfSimple'}
*
* ### Showing an alternative template using `else`
*
* ### 使用 `else` 显示替代模板
*
* To display a template when `expression` evaluates to false, use an `else` template
* binding as shown in the following example.
* The `else` binding points to an `<ng-template>` element labeled `#elseBlock`.
* The template can be defined anywhere in the component view, but is typically placed right after
* `ngIf` for readability.
*
* 要在 `expression` 计算为 false 时显示一个模板，请使用如下所示的 `else` 模板绑定。`else` 绑定指向一个带有 `#elseBlock` 标签的 `<ng-template>`。该模板可以定义在组件视图中的任何地方，但通常放在 `ngIf` 的紧后方，以提高可读性。
*
* {@example common/ngIf/ts/module.ts region='NgIfElse'}
*
* ### Using an external `then` template
*
* ### 使用内部 `then` 模板
*
* In the previous example, the then-clause template is specified inline, as the content of the
* tag that contains the `ngIf` directive. You can also specify a template that is defined
* externally, by referencing a labeled `<ng-template>` element. When you do this, you can
* change which template to use at runtime, as shown in the following example.
*
* 在前面的例子中，then 子句的模板是内联的，也就是作为 `ngIf` 指令所在标签的内容。你还可以通过引用一个带标签的 `<ng-template>` 元素来指定一个在外部定义的模板。这样就可以让你在运行时更改模板，就像下面的例子所演示的。
*
* {@example common/ngIf/ts/module.ts region='NgIfThenElse'}
*
* ### Storing a conditional result in a variable
*
* ### 把条件结果保存在变量中
*
* You might want to show a set of properties from the same object. If you are waiting
* for asynchronous data, the object can be undefined.
* In this case, you can use `ngIf` and store the result of the condition in a local
* variable as shown in the the following example.
*
* 比如你想显示同一个对象中的一组属性。如果你在等待异步数据，此对象可能是未定义的。这时候，你可以使用 `ngIf`，并且把此条件结果保存在一个局部变量中，如下例所示。
*
* {@example common/ngIf/ts/module.ts region='NgIfAs'}
*
* This code uses only one `AsyncPipe`, so only one subscription is created.
* The conditional statement stores the result of `userStream|async` in the local variable `user`.
* You can then bind the local `user` repeatedly.
*
* 这段代码只使用了一个 `AsyncPipe`，所以只会创建一个订阅。此条件表达式把 `userStream|async` 的结果保存在局部变量 `user` 中。然后你就可以反复绑定这个局部变量 `user` 了。
*
* The conditional displays the data only if `userStream` returns a value,
* so you don't need to use the
* safe-navigation-operator (`?.`)
* to guard against null values when accessing properties.
* You can display an alternative template while waiting for the data.
*
* 只有当 `userStream` 返回了值的时候，才会有条件的显示此数据。所以你不用使用安全导航操作符 (`?.`) 来在访问属性时避免空值。你可以在等待数据时显示一个备用模板。
*
* ### Shorthand syntax
*
* ### 简写语法
*
* The shorthand syntax `*ngIf` expands into two separate template specifications
* for the "then" and "else" clauses. For example, consider the following shorthand statement,
* that is meant to show a loading page while waiting for data to be loaded.
*
* `*ngIf` 的简写语法会把 "then" 和 "else" 子句分别扩展成两个独立的模板。比如，考虑下列简写语句，它要在等待数据加载期间显示一个加载中页面。
*
* ```
* <div class="hero-list" *ngIf="heroes else loading">
* ...
@ -124,11 +160,15 @@ import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef, ɵstri
* with the `#loading` label, and the template for the "then" clause
* is provided as the content of the anchor element.
*
* 你可以看到，"else" 子句引用了带有 `#loading` 标签的 `<ng-template>`，而 "then" 子句的模板是作为宿主元素的内容提供的。
*
* However, when Angular expands the shorthand syntax, it creates
* another `<ng-template>` tag, with `ngIf` and `ngIfElse` directives.
* The anchor element containing the template for the "then" clause becomes
* the content of this unlabeled `<ng-template>` tag.
*
* 不过，当 Angular 扩展此简写语法的时候，它创建了另一个带有 `ngIf` 和 `ngIfElse` 指令的 `<ng-template>`。此宿主元素包含的 "then" 子句的模板变成了无标签的 `<ng-template>` 的内容。
*
* ```
* <ng-template [ngIf]="heroes" [ngIfElse]="loading">
* <div class="hero-list">
@ -145,6 +185,7 @@ import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef, ɵstri
* structural directives. For more on this subject, see
* [Structural Directives](https://angular.io/guide/structural-directives#one-per-element).
*
* 隐式模板对象的存在，影响了结构型指令的嵌套规则。欲知详情，参见[结构型指令](https://angular.io/guide/structural-directives#one-per-element)。
* @ngModule CommonModule
* @publicApi
*/
@ -162,6 +203,9 @@ export class NgIf<T = unknown> {
/**
* The Boolean expression to evaluate as the condition for showing a template.
*
* 布尔表达式，将其作为显示模板的条件进行计算。
*
*/
@Input()
set ngIf(condition: T) {
@ -171,6 +215,9 @@ export class NgIf<T = unknown> {
/**
* A template to show if the condition expression evaluates to true.
*
* 当此条件表达式计算为 true 时要显示的模板。
*
*/
@Input()
set ngIfThen(templateRef: TemplateRef<NgIfContext<T>>|null) {
@ -182,6 +229,9 @@ export class NgIf<T = unknown> {
/**
* A template to show if the condition expression evaluates to false.
*
* 当此条件表达式计算为 false 时要显示的模板。
*
*/
@Input()
set ngIfElse(templateRef: TemplateRef<NgIfContext<T>>|null) {
@ -219,18 +269,28 @@ export class NgIf<T = unknown> {
/**
* Assert the correct type of the expression bound to the `ngIf` input within the template.
*
* 为绑定到 `ngIf` 输入属性上的模板确保正确的类型。
*
* The presence of this static field is a signal to the Ivy template type check compiler that
* when the `NgIf` structural directive renders its template, the type of the expression bound
* to `ngIf` should be narrowed in some way. For `NgIf`, the binding expression itself is used to
* narrow its type, which allows the strictNullChecks feature of TypeScript to work with `NgIf`.
*
* 该静态字段的存在向 Ivy 模板类型检查编译器发出信号，即当 `NgIf` 结构化指令渲染其模板时，应以某种方式窄化 `ngIf`。对于 `NgIf`，绑定表达式本身用于窄化其类型，这允许 TypeScript 的 strictNullChecks 功能与 `NgIf` 一起使用。
*
*/
static ngTemplateGuard_ngIf: 'binding';
/**
* Asserts the correct type of the context for the template that `NgIf` will render.
*
* 为 `NgIf` 将要渲染的模板确保正确的上下文类型。
*
* The presence of this method is a signal to the Ivy template type-check compiler that the
* `NgIf` structural directive renders its template with a specific context type.
*
* 该方法用于向 Ivy 模板类型检查编译器发出信号，即 `NgIf` 结构化指令会使用特定的上下文类型渲染其模板。
*
*/
static ngTemplateContextGuard<T>(dir: NgIf<T>, ctx: any):
ctx is NgIfContext<Exclude<T, false|0|''|null|undefined>> {

20
packages/common/src/directives/ng_plural.ts
View File

@ -17,6 +17,7 @@ import {SwitchView} from './ng_switch';
* @ngModule CommonModule
*
* @usageNotes
*
* ```
* <some-element [ngPlural]="value">
* <ng-template ngPluralCase="=0">there is nothing</ng-template>
@ -29,19 +30,33 @@ import {SwitchView} from './ng_switch';
*
* Adds / removes DOM sub-trees based on a numeric value. Tailored for pluralization.
*
* 根据数字值添加/删除 DOM 子树。为支持复数词量身定制。
*
* Displays DOM sub-trees that match the switch expression value, or failing that, DOM sub-trees
* that match the switch expression's pluralization category.
*
* 显示与开关表达式值匹配的 DOM 子树，否则显示与开关表达式的复数类别匹配的 DOM 子树。
*
* To use this directive you must provide a container element that sets the `[ngPlural]` attribute
* to a switch expression. Inner elements with a `[ngPluralCase]` will display based on their
* expression:
*
* 要使用此指令，必须提供一个容器元素，该元素将 `[ngPlural]` 属性设置为 switch 表达式。 `[ngPluralCase]` 内部元素将根据其表达式显示：
*
* - if `[ngPluralCase]` is set to a value starting with `=`, it will only display if the value
* matches the switch expression exactly,
*
* 如果 `[ngPluralCase]` 设置为以 `=` 开头的值，则仅在该值与 switch 表达式完全匹配时才会显示，
*
* - otherwise, the view will be treated as a "category match", and will only display if exact
* value matches aren't found and the value maps to its category for the defined locale.
*
* 否则，该视图将被视为“类别匹配”，并且仅在未找到精确值匹配且该值映射到已定义语言环境的类别时才会显示。
*
* See http://cldr.unicode.org/index/cldr-spec/plural-rules
*
* 参见 <http://cldr.unicode.org/index/cldr-spec/plural-rules>
*
* @publicApi
*/
@Directive({selector: '[ngPlural]'})
@ -92,7 +107,10 @@ export class NgPlural {
* Creates a view that will be added/removed from the parent {@link NgPlural} when the
* given expression matches the plural expression according to CLDR rules.
*
* 创建一个视图，当给定表达式根据 CLDR 规则与复数表达式匹配时，将在父视图 {@link NgPlural} 中添加/删除该视图。
*
* @usageNotes
*
* ```
* <some-element [ngPlural]="value">
* <ng-template ngPluralCase="=0">...</ng-template>
@ -102,6 +120,8 @@ export class NgPlural {
*
* See {@link NgPlural} for more details and example.
*
* 参见 {@link NgPlural} 以了解详情和范例。
*
* @publicApi
*/
@Directive({selector: '[ngPluralCase]'})

6
packages/common/src/directives/ng_style.ts
View File

@ -15,18 +15,24 @@ import {Directive, DoCheck, ElementRef, Input, KeyValueChanges, KeyValueDiffer,
*
* Set the font of the containing element to the result of an expression.
*
* 将容器元素的字体设置为表达式的结果。
*
* ```
* <some-element [ngStyle]="{'font-style': styleExp}">...</some-element>
* ```
*
* Set the width of the containing element to a pixel value returned by an expression.
*
* 将容器元素的宽度设置为表达式返回的像素值。
*
* ```
* <some-element [ngStyle]="{'max-width.px': widthExp}">...</some-element>
* ```
*
* Set a collection of style values using an expression that returns key-value pairs.
*
* 使用返回键值对的表达式来设置样式值的集合。
*
* ```
* <some-element [ngStyle]="objExp">...</some-element>
* ```

40
packages/common/src/directives/ng_switch.ts
View File

@ -39,15 +39,29 @@ export class SwitchView {
* @description
* The `[ngSwitch]` directive on a container specifies an expression to match against.
* The expressions to match are provided by `ngSwitchCase` directives on views within the container.
*
* 容器上的 `[ngSwitch]` 指令指定要匹配的表达式。匹配的表达式由容器内视图上的 `ngSwitchCase` 指令提供。
*
* - Every view that matches is rendered.
*
* 如果有匹配项，则渲染匹配的视图。
*
* - If there are no matches, a view with the `ngSwitchDefault` directive is rendered.
*
* 如果没有匹配项，则渲染 `ngSwitchDefault`
*
* - Elements within the `[NgSwitch]` statement but outside of any `NgSwitchCase`
* or `ngSwitchDefault` directive are preserved at the location.
*
* `[NgSwitch]` 语句内任何除 `NgSwitchCase` 或 `ngSwitchDefault` 指令之外的元素都保留在原位。
*
* @usageNotes
*
* Define a container element for the directive, and specify the switch expression
* to match against as an attribute:
*
* 为指令定义一个容器元素，并指定要匹配的 switch 表达式作为属性：
*
* ```
* <container-element [ngSwitch]="switch_expression">
* ```
@ -55,6 +69,8 @@ export class SwitchView {
* Within the container, `*ngSwitchCase` statements specify the match expressions
* as attributes. Include `*ngSwitchDefault` as the final case.
*
* 在容器内， `*ngSwitchCase` 语句将匹配表达式指定为属性。包括用 `*ngSwitchDefault` 作为最后一种情况。
*
* ```
* <container-element [ngSwitch]="switch_expression">
* <some-element *ngSwitchCase="match_expression_1">...</some-element>
@ -65,8 +81,12 @@ export class SwitchView {
*
* ### Usage Examples
*
* ### 使用范例
*
* The following example shows how to use more than one case to display the same view:
*
* 下面的示例演示如何使用多个分支来显示同一视图：
*
* ```
* <container-element [ngSwitch]="switch_expression">
* <!-- the same view can be shown in more than one case -->
@ -79,6 +99,9 @@ export class SwitchView {
* ```
*
* The following example shows how cases can be nested:
*
* 以下示例演示如何嵌套案例：
*
* ```
* <container-element [ngSwitch]="switch_expression">
* <some-element *ngSwitchCase="match_expression_1">...</some-element>
@ -98,6 +121,7 @@ export class SwitchView {
* @see `NgSwitchDefault`
* @see [Structural Directives](guide/structural-directives)
*
* [结构型指令](guide/structural-directives)
*/
@Directive({selector: '[ngSwitch]'})
export class NgSwitch {
@ -162,11 +186,15 @@ export class NgSwitch {
* When the expressions match, the given `NgSwitchCase` template is rendered.
* If multiple match expressions match the switch expression value, all of them are displayed.
*
* 提供一个 switch case 表达式来匹配一个封闭的 `ngSwitch` 表达式。当表达式匹配时，将渲染给定的 `NgSwitchCase` 模板。如果多个匹配表达式与开关表达式值相匹配，则会全部显示。
*
* @usageNotes
*
* Within a switch container, `*ngSwitchCase` statements specify the match expressions
* as attributes. Include `*ngSwitchDefault` as the final case.
*
* 在开关容器中， `*ngSwitchCase` 语句将匹配表达式指定为属性。包括用 `*ngSwitchDefault` 作为最后一种情况。
*
* ```
* <container-element [ngSwitch]="switch_expression">
* <some-element *ngSwitchCase="match_expression_1">...</some-element>
@ -179,9 +207,13 @@ export class NgSwitch {
* that defines the subtree to be selected if the value of the match expression
* matches the value of the switch expression.
*
* 每个 switch-case 语句包含一个内联 HTML 模板或模板引用，该模板或模板引用定义了 match 表达式的值与 switch 表达式的值匹配时要选择的子树。
*
* Unlike JavaScript, which uses strict equality, Angular uses loose equality.
* This means that the empty string, `""` matches 0.
*
* 与 JavaScript 使用严格相等性的方式不同，Angular 使用宽松相等性。这意味着空字符串 `""` 能匹配 0。
*
* @publicApi
* @see `NgSwitch`
* @see `NgSwitchDefault`
@ -192,6 +224,9 @@ export class NgSwitchCase implements DoCheck {
private _view: SwitchView;
/**
* Stores the HTML template to be selected on match.
*
* 存储要在匹配时选择的 HTML 模板。
*
*/
@Input() ngSwitchCase: any;
@ -204,6 +239,9 @@ export class NgSwitchCase implements DoCheck {
/**
* Performs case matching. For internal use only.
*
* 执行大小写匹配。仅限内部使用。
*
*/
ngDoCheck() {
this._view.enforceState(this.ngSwitch._matchCase(this.ngSwitchCase));
@ -219,6 +257,8 @@ export class NgSwitchCase implements DoCheck {
* match the `NgSwitch` expression.
* This statement should be the final case in an `NgSwitch`.
*
* 创建一个当没有任何 `NgSwitchCase` 表达式能匹配 `NgSwitch` 表达时要渲染的视图。该语句应该是 `NgSwitch` 的最后一种情况。
*
* @publicApi
* @see `NgSwitch`
* @see `NgSwitchCase`

6
packages/common/src/directives/ng_template_outlet.ts
View File

@ -51,11 +51,17 @@ export class NgTemplateOutlet implements OnChanges {
* object, the object's keys will be available for binding by the local template `let`
* declarations.
* Using the key `$implicit` in the context object will set its value as default.
*
* 附加到 {@link EmbeddedViewRef} 的上下文对象。这应该是一个对象，该对象的键名将可以在局部模板中使用 `let` 声明中进行绑定。在上下文对象中使用 `$implicit` 为键名时，将把它作为默认值。
*
*/
@Input() public ngTemplateOutletContext: Object|null = null;
/**
* A string defining the template reference and optionally the context object for the template.
*
* 一个字符串，用于定义模板引用以及模板的上下文对象。
*
*/
@Input() public ngTemplateOutlet: TemplateRef<any>|null = null;

4
packages/common/src/dom_tokens.ts
View File

@ -11,9 +11,13 @@ import {InjectionToken} from '@angular/core';
/**
* A DI Token representing the main rendering context. In a browser this is the DOM Document.
*
* 表示主要渲染上下文的 DI 令牌。在浏览器中，这是 DOM 文档。
*
* Note: Document might not be available in the Application Context when Application and Rendering
* Contexts are not the same (e.g. when running the application in a Web Worker).
*
* 注意：当应用程序上下文和渲染上下文不同时（例如，在 Web Worker 中运行应用程序时），document 可能在应用程序上下文中不可用。
*
* @publicApi
*/
export const DOCUMENT = new InjectionToken<Document>('DocumentToken');

50
packages/common/src/i18n/format_number.ts
View File

@ -128,23 +128,43 @@ function formatNumberToLocaleString(
*
* Formats a number as currency using locale rules.
*
* 使用区域设置规则将数字格式化为货币。
*
* @param value The number to format.
*
* 要格式化的数字。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @param currency A string containing the currency symbol or its name,
* such as "$" or "Canadian Dollar". Used in output string, but does not affect the operation
* of the function.
*
* 包含货币符号或其名称的字符串，例如 “$” 或 “加元”。在输出字符串中使用，但不影响该函数的操作。
*
* @param currencyCode The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
* currency code, such as `USD` for the US dollar and `EUR` for the euro.
* Used to determine the number of digits in the decimal part.
*
* [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 货币代码，例如 `USD` 表示美元，`EUR` 表示欧元。用于确定小数部分的位数。
*
* @param digitInfo Decimal representation options, specified by a string in the following format:
* `{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`. See `DecimalPipe` for more details.
*
* 十进制表示形式的选项，通过字符串以如下格式指定：`{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}` 。欲知详情，请参见 `DecimalPipe`。
*
* @returns The formatted currency value.
*
* 要格式化的货币值。
*
* @see `formatNumber()`
* @see `DecimalPipe`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化（i18n）指南](guide/i18n)
*
* @publicApi
*/
export function formatCurrency(
@ -175,16 +195,31 @@ export function formatCurrency(
*
* Formats a number as a percentage according to locale rules.
*
* 根据语言环境规则将数字格式化为百分比。
*
* @param value The number to format.
*
* 要格式化的数字。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @param digitInfo Decimal representation options, specified by a string in the following format:
* `{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`. See `DecimalPipe` for more details.
*
* 十进制表示形式的选项，通过字符串以如下格式指定：`{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`。欲知详情，请参见 `DecimalPipe`。
*
* @returns The formatted percentage value.
*
* 已格式化的百分比值。
*
* @see `formatNumber()`
* @see `DecimalPipe`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化（i18n）指南](guide/i18n)
*
* @publicApi
*
*/
@ -204,14 +239,29 @@ export function formatPercent(value: number, locale: string, digitsInfo?: string
* Formats a number as text, with group sizing, separator, and other
* parameters based on the locale.
*
* 将数字格式化为文本格式，并根据区域来设置组大小、分隔符和其他参数。
*
* @param value The number to format.
*
* 要格式化的数字。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @param digitInfo Decimal representation options, specified by a string in the following format:
* `{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`. See `DecimalPipe` for more details.
*
* 十进制表示形式的选项，通过字符串以如下格式指定：`{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}` 。欲知详情，请参见 `DecimalPipe`。
*
* @returns The formatted text string.
*
* 已格式化的文本字符串。
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化（i18n）指南](guide/i18n)
*
* @publicApi
*/
export function formatNumber(value: number, locale: string, digitsInfo?: string): string {

4
packages/common/src/i18n/locale_data.ts
View File

@ -12,8 +12,12 @@ import {ɵregisterLocaleData} from '@angular/core';
* Register global data to be used internally by Angular. See the
* ["I18n guide"](guide/i18n#i18n-pipes) to know how to import additional locale data.
*
* 注册全局数据以供 Angular 内部使用。请参阅 [“I18n 指南”](guide/i18n#i18n-pipes)以了解如何导入其他语言环境的数据。
*
* The signature registerLocaleData(data: any, extraData?: any) is deprecated since v5.1
*
* 从 v5.1 开始不推荐使用 registerLocaleData（data：any，extraData ?: any）签名
*
* @publicApi
*/
export function registerLocaleData(data: any, localeId?: string|any, extraData?: any): void {

431
packages/common/src/i18n/locale_data_api.ts
View File

@ -13,9 +13,15 @@ import {CURRENCIES_EN, CurrenciesSymbols} from './currencies';
/**
* Format styles that can be used to represent numbers.
*
* 可用来表示数字的格式化样式。
*
* @see `getLocaleNumberFormat()`.
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化（i18n）指南](guide/i18n)
*
* @publicApi
*/
export enum NumberFormatStyle {
@ -28,10 +34,15 @@ export enum NumberFormatStyle {
/**
* Plurality cases used for translating plurals to different languages.
*
* 用于将复数形式转换为不同语言的复数形式。
*
* @see `NgPlural`
*
* @see `NgPluralCase`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化（i18n）指南](guide/i18n)
*
* @publicApi
*/
export enum Plural {
@ -47,9 +58,17 @@ export enum Plural {
* Context-dependant translation forms for strings.
* Typically the standalone version is for the nominative form of the word,
* and the format version is used for the genitive case.
*
* 字符串的上下文相关翻译形式。通常，独立版本用于单词的主格形式，格式化的版本则用于所有格。
*
* @see [CLDR website](http://cldr.unicode.org/translation/date-time-1/date-time#TOC-Standalone-vs.-Format-Styles)
*
* [CLDR 网站](http://cldr.unicode.org/translation/date-time-1/date-time#TOC-Standalone-vs.-Format-Styles)
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化（i18n）指南](guide/i18n)
*
* @publicApi
*/
export enum FormStyle {
@ -62,16 +81,38 @@ export enum FormStyle {
* The specific character widths are locale-specific.
* Examples are given for the word "Sunday" in English.
*
* 字符串宽度可用于翻译。特定的字符宽度是特定于语言环境的。这里给出了英语中 “Sunday” 一词的示例。
*
* @publicApi
*/
export enum TranslationWidth {
/** 1 character for `en-US`. For example: 'S' */
/**
* 1 character for `en-US`. For example: 'S'
*
* 对 `en-US` 是 1 字符。比如：'S'
*
*/
Narrow,
/** 3 characters for `en-US`. For example: 'Sun' */
/**
* 3 characters for `en-US`. For example: 'Sun'
*
* 对 `en-US` 是 3 字符。比如：'Sun'
*
*/
Abbreviated,
/** Full length for `en-US`. For example: "Sunday" */
/**
* Full length for `en-US`. For example: "Sunday"
*
* 对 `en-US` 是全长。例如：“星期日”
*
*/
Wide,
/** 2 characters for `en-US`, For example: "Su" */
/**
* 2 characters for `en-US`, For example: "Su"
*
* 对 `en-US` 是 2 个字符，例如：“Su”
*
*/
Short
}
@ -80,31 +121,48 @@ export enum TranslationWidth {
* The specific character widths are locale-specific.
* Examples are given for `en-US`.
*
* 可用于日期时间格式的字符串宽度。特定的字符宽度是特定于语言环境的。示例中是给 `en-US` 的示例。
*
* @see `getLocaleDateFormat()`
* @see `getLocaleTimeFormat()``
* @see `getLocaleDateTimeFormat()`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化（i18n）指南](guide/i18n)
*
* @publicApi
*/
export enum FormatWidth {
/**
* For `en-US`, 'M/d/yy, h:mm a'`
* (Example: `6/15/15, 9:03 AM`)
*
* 对于 `en-US`，是 'M/d/yy, h:mm a'`(例如:`6/15/15, 9:03 AM`)
*
*/
Short,
/**
* For `en-US`, `'MMM d, y, h:mm:ss a'`
* (Example: `Jun 15, 2015, 9:03:01 AM`)
*
* 对于 `en-US`，是 `'MMM d, y, h:mm:ss a'`（例如： `Jun 15, 2015, 9:03:01 AM` ）
*
*/
Medium,
/**
* For `en-US`, `'MMMM d, y, h:mm:ss a z'`
* (Example: `June 15, 2015 at 9:03:01 AM GMT+1`)
*
* 对于 `en-US`，是 `'MMMM d, y, h:mm:ss a z'`，（例如： `June 15, 2015 at 9:03:01 AM GMT+1` ）
*
*/
Long,
/**
* For `en-US`, `'EEEE, MMMM d, y, h:mm:ss a zzzz'`
* (Example: `Monday, June 15, 2015 at 9:03:01 AM GMT+01:00`)
*
* 对于 `en-US`，是 `'EEEE, MMMM d, y, h:mm:ss a zzzz'`（例如：`Monday, June 15, 2015 at 9:03:01 AM GMT+01:00` ）
*
*/
Full
}
@ -113,9 +171,14 @@ export enum FormatWidth {
* Symbols that can be used to replace placeholders in number patterns.
* Examples are based on `en-US` values.
*
* 可用于替换数字模式中占位符的符号。例如基于 `en-US` 的值。
*
* @see `getLocaleNumberSymbol()`
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化（i18n）指南](guide/i18n)
*
* @publicApi
*/
export enum NumberSymbol {
@ -123,72 +186,114 @@ export enum NumberSymbol {
* Decimal separator.
* For `en-US`, the dot character.
* Example : 2,345`.`67
*
* 小数点分隔符。对于 `en-US`，是点字符。例如：2,345`.`67
*
*/
Decimal,
/**
* Grouping separator, typically for thousands.
* For `en-US`, the comma character.
* Example: 2`,`345.67
*
* 分组分隔符，通常为千位。对于 `en-US`，是逗号字符。例如：2`,`345.67
*
*/
Group,
/**
* List-item separator.
* Example: "one, two, and three"
*
* 列表项分隔符。例如："one, two, and three"
*
*/
List,
/**
* Sign for percentage (out of 100).
* Example: 23.4%
*
* 百分号（最大为 100）。例如：23.4％
*
*/
PercentSign,
/**
* Sign for positive numbers.
* Example: +23
*
* 正数的符号。例如：+23
*
*/
PlusSign,
/**
* Sign for negative numbers.
* Example: -23
*
* 负数的符号。例如：-23
*
*/
MinusSign,
/**
* Computer notation for exponential value (n times a power of 10).
* Example: 1.2E3
*
* 指数值的计算机表示法（10 的 n 次幂）。例如：1.2E3
*
*/
Exponential,
/**
* Human-readable format of exponential.
* Example: 1.2x103
*
* 可读的指数格式。例如：1.2x103
*
*/
SuperscriptingExponent,
/**
* Sign for permille (out of 1000).
* Example: 23.4‰
*
* 千分号（最大为 1000）。例如：23.4‰
*
*/
PerMille,
/**
* Infinity, can be used with plus and minus.
* Example: ∞, +∞, -∞
*
* 无穷大，可与正负一起使用。例如：∞，+∞，-∞
*
*/
Infinity,
/**
* Not a number.
* Example: NaN
*
* 非数字。例如：NaN
*
*/
NaN,
/**
* Symbol used between time units.
* Example: 10:52
*
* 时间单位之间使用的符号。例如：10:52
*
*/
TimeSeparator,
/**
* Decimal separator for currency values (fallback to `Decimal`).
* Example: $2,345.67
*
* 货币值的小数分隔符（回退为 `Decimal` ）。例如：$2,345.67
*
*/
CurrencyDecimal,
/**
* Group separator for currency values (fallback to `Group`).
* Example: $2,345.67
*
* 货币值的组分隔符（回退为 `Group` ）。例如：$2,345.67
*
*/
CurrencyGroup
}
@ -196,6 +301,8 @@ export enum NumberSymbol {
/**
* The value for each day of the week, based on the `en-US` locale
*
* 一周中每一天的值（基于 `en-US` 语言环境）
*
* @publicApi
*/
export enum WeekDay {
@ -211,10 +318,21 @@ export enum WeekDay {
/**
* Retrieves the locale ID from the currently loaded locale.
* The loaded locale could be, for example, a global one rather than a regional one.
*
* 从当前已加载的语言环境中检索语言环境 ID。加载的语言环境也可能是全球语言环境，而不是区域性语言环境。
*
* @param locale A locale code, such as `fr-FR`.
*
* 语言环境代码，例如 `fr-FR` 。
*
* @returns The locale code. For example, `fr`.
*
* 语言环境代码。例如， `fr` 。
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化（i18n）指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleId(locale: string): string {
@ -224,12 +342,28 @@ export function getLocaleId(locale: string): string {
/**
* Retrieves day period strings for the given locale.
*
* 检索给定语言环境的一天时段字符串。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @param formStyle The required grammatical form.
*
* 所需的语法形式。
*
* @param width The required character width.
*
* 所需的字符宽度。
*
* @returns An array of localized period strings. For example, `[AM, PM]` for `en-US`.
*
* 本地化的区间字符串数组。例如，`en-US` `[AM, PM]` 。
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleDayPeriods(
@ -245,13 +379,29 @@ export function getLocaleDayPeriods(
/**
* Retrieves days of the week for the given locale, using the Gregorian calendar.
*
* 使用公历来检索给定语言环境下的星期几。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @param formStyle The required grammatical form.
*
* 所需的语法形式。
*
* @param width The required character width.
*
* 所需的字符宽度。
*
* @returns An array of localized name strings.
* For example,`[Sunday, Monday, ... Saturday]` for `en-US`.
*
* 本地化名称字符串的数组。例如，`en-US` `[Sunday, Monday, ... Saturday]` 。
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleDayNames(
@ -266,13 +416,29 @@ export function getLocaleDayNames(
/**
* Retrieves months of the year for the given locale, using the Gregorian calendar.
*
* 使用公历来检索给定语言环境下一年中的月份。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @param formStyle The required grammatical form.
*
* 所需的语法形式。
*
* @param width The required character width.
*
* 所需的字符宽度。
*
* @returns An array of localized name strings.
* For example, `[January, February, ...]` for `en-US`.
*
* 本地化名称字符串的数组，例如，对于 `en-US` 是 `[January, February, ...]`。
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleMonthNames(
@ -286,13 +452,27 @@ export function getLocaleMonthNames(
/**
* Retrieves Gregorian-calendar eras for the given locale.
*
* 检索给定语言环境的格里高利历日历。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @param width The required character width.
*
* 所需的字符宽度。
*
* @returns An array of localized era strings.
* For example, `[AD, BC]` for `en-US`.
*
* 本地化年代字符串的数组。例如，对于 `en-US`，是 `[AD, BC]`。
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleEraNames(
@ -305,12 +485,22 @@ export function getLocaleEraNames(
/**
* Retrieves the first day of the week for the given locale.
*
* 检索给定语言环境中一周的第一天。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @returns A day index number, using the 0-based week-day index for `en-US`
* (Sunday = 0, Monday = 1, ...).
* For example, for `fr-FR`, returns 1 to indicate that the first day is Monday.
*
* 工作日索引号，使用基于 0 的 `en-US` 的工作日索引（星期日= 0，星期一= 1，...）。例如，对于 `fr-FR` ，返回 1 表示第一天是星期一。
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleFirstDayOfWeek(locale: string): WeekDay {
@ -321,10 +511,20 @@ export function getLocaleFirstDayOfWeek(locale: string): WeekDay {
/**
* Range of week days that are considered the week-end for the given locale.
*
* 在给定语言环境中被视为周末的工作日范围。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @returns The range of day values, `[startDay, endDay]`.
*
* 日期值的范围 `[startDay, endDay]` 。
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleWeekEndRange(locale: string): [WeekDay, WeekDay] {
@ -335,12 +535,26 @@ export function getLocaleWeekEndRange(locale: string): [WeekDay, WeekDay] {
/**
* Retrieves a localized date-value formating string.
*
* 检索本地化的日期-值格式字符串。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @param width The format type.
*
* 格式类型。
*
* @returns The localized formating string.
*
* 本地化的格式字符串。
*
* @see `FormatWidth`
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleDateFormat(locale: string, width: FormatWidth): string {
@ -351,11 +565,26 @@ export function getLocaleDateFormat(locale: string, width: FormatWidth): string
/**
* Retrieves a localized time-value formatting string.
*
* 检索本地化的时间值格式字符串。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @param width The format type.
*
* 格式类型。
*
* @returns The localized formatting string.
*
* 本地化的格式字符串。
*
* @see `FormatWidth`
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
@ -367,12 +596,26 @@ export function getLocaleTimeFormat(locale: string, width: FormatWidth): string
/**
* Retrieves a localized date-time formatting string.
*
* 检索本地化的日期时间格式字符串。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @param width The format type.
*
* 格式类型。
*
* @returns The localized formatting string.
*
* 本地化的格式字符串。
*
* @see `FormatWidth`
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleDateTimeFormat(locale: string, width: FormatWidth): string {
@ -383,12 +626,27 @@ export function getLocaleDateTimeFormat(locale: string, width: FormatWidth): str
/**
* Retrieves a localized number symbol that can be used to replace placeholders in number formats.
*
* 检索本地化的数字符号，该符号可用于替换数字格式的占位符。
*
* @param locale The locale code.
*
* 语言环境代码。
*
* @param symbol The symbol to localize.
*
* 要本地化的符号。
*
* @returns The character for the localized symbol.
*
* 本地化符号的字符。
*
* @see `NumberSymbol`
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleNumberSymbol(locale: string, symbol: NumberSymbol): string {
@ -407,36 +665,67 @@ export function getLocaleNumberSymbol(locale: string, symbol: NumberSymbol): str
/**
* Retrieves a number format for a given locale.
*
* 检索给定语言环境下的数字格式。
*
* Numbers are formatted using patterns, like `#,###.00`. For example, the pattern `#,###.00`
* when used to format the number 12345.678 could result in "12'345,678". That would happen if the
* grouping separator for your language is an apostrophe, and the decimal separator is a comma.
*
* 数字会以类似 `#,###.00` 的模式进行格式化。例如，模式 `#,###.00` 用于格式化数字 12345.678 时可能的结果是 “12'345,678”。如果你的语言的分组分隔符是撇号，而十进制分隔符是逗号，就会是这样的。
*
* <b>Important:</b> The characters `.` `,` `0` `#` (and others below) are special placeholders
* that stand for the decimal separator, and so on, and are NOT real characters.
* You must NOT "translate" the placeholders. For example, don't change `.` to `,` even though in
* your language the decimal point is written with a comma. The symbols should be replaced by the
* local equivalents, using the appropriate `NumberSymbol` for your language.
*
* *重要：*`.` `,` `0` `#`（以及以下的）字符是特殊的占位符，它们代表数字分隔符等，而不是真实的字符。你绝不能“翻译”这些占位符。例如，不要把 `.` 修改成 `,`，虽然在你的语言中小数点分隔符是写成逗号的。该符号会被其本地化等价物替换，也就是适合你的语言的 `NumberSymbol`。
*
* Here are the special characters used in number patterns:
*
* 以下是数字模式中使用的特殊字符：
*
* | Symbol | Meaning |
* |--------|---------|
* | 符号 | 含义 |
* | . | Replaced automatically by the character used for the decimal point. |
* | . | 自动替换为用作小数点的字符。 |
* | , | Replaced by the "grouping" (thousands) separator. |
* | . | 替换为（千）“分组”分隔符。 |
* | 0 | Replaced by a digit (or zero if there aren't enough digits). |
* | 0 | 替换为一个数字（如果没有足够的数字，则为零）。 |
* | # | Replaced by a digit (or nothing if there aren't enough). |
* | # | 用数字代替（如果数字不足，则不进行任何替换）。 |
* | ¤ | Replaced by a currency symbol, such as $ or USD. |
* | ¤ | 替换为货币符号，例如 $ 或 USD。 |
* | % | Marks a percent format. The % symbol may change position, but must be retained. |
* | % | 标记百分比格式。％符号可能会更改位置，但必须保留。 |
* | E | Marks a scientific format. The E symbol may change position, but must be retained. |
* | E | 标记科学计数法格式。 E 符号可能会改变位置，但必须保留。 |
* | ' | Special characters used as literal characters are quoted with ASCII single quotes. |
* | ' | 表示文本字面量的特殊字符，用 ASCII 单引号引起来。 |
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @param type The type of numeric value to be formatted (such as `Decimal` or `Currency`.)
*
* 要格式化的数值类型（例如 `Decimal` 或 `Currency`）。
*
* @returns The localized format string.
*
* 本地化的格式字符串。
*
* @see `NumberFormatStyle`
* @see [CLDR website](http://cldr.unicode.org/translation/number-patterns)
*
* [CLDR 官网](http://cldr.unicode.org/translation/number-patterns)
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleNumberFormat(locale: string, type: NumberFormatStyle): string {
@ -448,11 +737,21 @@ export function getLocaleNumberFormat(locale: string, type: NumberFormatStyle):
* Retrieves the symbol used to represent the currency for the main country
* corresponding to a given locale. For example, '$' for `en-US`.
*
* 检索用于表示与给定语言环境对应的主要国家/地区的货币的符号。对于 `en-US` 为 `$`。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @returns The localized symbol character,
* or `null` if the main country cannot be determined.
*
* 本地化的符号字符；如果无法确定主要国家则为 `null`。
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleCurrencySymbol(locale: string): string|null {
@ -463,11 +762,22 @@ export function getLocaleCurrencySymbol(locale: string): string|null {
/**
* Retrieves the name of the currency for the main country corresponding
* to a given locale. For example, 'US Dollar' for `en-US`.
*
* 检索与给定语言环境相对应的主要国家/地区的货币名称。对于 `en-US` 是 “US Dollar”。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @returns The currency name,
* or `null` if the main country cannot be determined.
*
* 货币名称；如果无法确定主要国家/地区，则为 `null`。
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化（i18n）指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleCurrencyName(locale: string): string|null {
@ -478,11 +788,20 @@ export function getLocaleCurrencyName(locale: string): string|null {
/**
* Retrieves the default currency code for the given locale.
*
* 检索给定语言环境的默认货币代码。
*
* The default is defined as the first currency which is still in use.
*
* 默认值定义为仍在使用的第一种货币。
*
* @param locale The code of the locale whose currency code we want.
*
* 我们想要获取货币代码的语言环境的代码。
*
* @returns The code of the default currency for the given locale.
*
* 给定语言环境的默认货币代码。
*
* @publicApi
*/
export function getLocaleCurrencyCode(locale: string): string|null {
@ -491,9 +810,21 @@ export function getLocaleCurrencyCode(locale: string): string|null {
/**
* Retrieves the currency values for a given locale.
*
* 获取给定语言环境的货币值。
*
* @param locale A locale code for the locale format rules to use.
*
* 语言格式规则使用的语言环境代码。
*
* @returns The currency values.
*
* 货币值。
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
*/
function getLocaleCurrencies(locale: string): {[code: string]: CurrenciesSymbols} {
const data = ɵfindLocaleData(locale);
@ -502,6 +833,7 @@ function getLocaleCurrencies(locale: string): {[code: string]: CurrenciesSymbols
/**
* @alias core/ɵgetLocalePluralCase
*
* @publicApi
*/
export const getLocalePluralCase: (locale: string) => ((value: number) => Plural) =
@ -519,22 +851,38 @@ function checkFullData(data: any) {
* Retrieves locale-specific rules used to determine which day period to use
* when more than one period is defined for a locale.
*
* 检索特定于语言环境的规则，该规则用于确定在为一个语言环境中定义了多个时段时要使用的一天时段。
*
* There is a rule for each defined day period. The
* first rule is applied to the first day period and so on.
* Fall back to AM/PM when no rules are available.
*
* 每个预定义的一天时段都有一个规则。第一条规则适用于第一个一天时段，依此类推。如果没有可用的规则，请回退为 AM / PM。
*
* A rule can specify a period as time range, or as a single time value.
*
* 本规则可以将时间段指定为时间范围或单个时间值。
*
* This functionality is only available when you have loaded the full locale data.
* See the ["I18n guide"](guide/i18n#i18n-pipes).
*
* 仅当你加载了完整的语言环境数据时，此功能才可用。请参阅 [“I18n 指南”](guide/i18n#i18n-pipes) 。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @returns The rules for the locale, a single time value or array of *from-time, to-time*,
* or null if no periods are available.
*
* 语言环境的规则，单个时间值或 *from-time，to-time* 或 null 的数组（如果没有可用时段）。
*
* @see `getLocaleExtraDayPeriods()`
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleExtraDayPeriodRules(locale: string): (Time|[Time, Time])[] {
@ -554,16 +902,34 @@ export function getLocaleExtraDayPeriodRules(locale: string): (Time|[Time, Time]
* in different languages.
* For example, for `en-US`, periods are morning, noon, afternoon, evening, and midnight.
*
* 检索特定于语言环境的一天时段，该时段大致指示如何用不同的语言分解一天。例如，对于 `en-US`，这些时段为 morning、noon、afternoon、evening 和 midnight。
*
* This functionality is only available when you have loaded the full locale data.
* See the ["I18n guide"](guide/i18n#i18n-pipes).
*
* 仅当你加载了完整的语言环境数据时，此功能才可用。请参阅 [“I18n 指南”](guide/i18n#i18n-pipes) 。
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @param formStyle The required grammatical form.
*
* 所需的语法形式。
*
* @param width The required character width.
*
* 所需的字符宽度。
*
* @returns The translated day-period strings.
*
* 翻译后的一天时段字符串。
*
* @see `getLocaleExtraDayPeriodRules()`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getLocaleExtraDayPeriods(
@ -580,10 +946,23 @@ export function getLocaleExtraDayPeriods(
/**
* Retrieves the writing direction of a specified locale
*
* 检索指定语言环境的书写方向
*
* @param locale A locale code for the locale format rules to use.
*
* 用于要使用的语言环境格式规则的语言环境代码。
*
* @publicApi
*
* @returns 'rtl' or 'ltr'
*
* 'rtl' 或 'ltr'
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
*/
export function getLocaleDirection(locale: string): 'ltr'|'rtl' {
const data = ɵfindLocaleData(locale);
@ -593,14 +972,29 @@ export function getLocaleDirection(locale: string): 'ltr'|'rtl' {
/**
* Retrieves the first value that is defined in an array, going backwards from an index position.
*
* 检索数组中定义的第一个值，从索引位置开始向后找。
*
* To avoid repeating the same data (as when the "format" and "standalone" forms are the same)
* add the first value to the locale data arrays, and add other values only if they are different.
*
* 为避免重复相同的数据（比如当 "format" 和 "standalone" 的格式相同时），将第一个值添加到语言环境数据数组，并仅在它们不同时添加其他值。
*
* @param data The data array to retrieve from.
*
* 要检索的数据数组。
*
* @param index A 0-based index into the array to start from.
*
* 从 0 开始的数组索引。
*
* @returns The value immediately before the given index position.
*
* 给定索引位置之前的值。
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
function getLastDefinedValue<T>(data: T[], index: number): T {
@ -615,6 +1009,8 @@ function getLastDefinedValue<T>(data: T[], index: number): T {
/**
* Represents a time value with hours and minutes.
*
* 用小时和分钟表示的时间值。
*
* @publicApi
*/
export type Time = {
@ -635,16 +1031,33 @@ function extractTime(time: string): Time {
/**
* Retrieves the currency symbol for a given currency code.
*
* 检索给定货币代码的货币符号。
*
* For example, for the default `en-US` locale, the code `USD` can
* be represented by the narrow symbol `$` or the wide symbol `US$`.
*
* 例如，对于默认 `en-US` 语言环境，代码 `USD` 可以由窄符号 `$` 或宽符号 `US$` 表示。
*
* @param code The currency code.
*
* 货币代码。
*
* @param format The format, `wide` or `narrow`.
*
* 格式，如 `wide` 或 `narrow` 。
*
* @param locale A locale code for the locale format rules to use.
*
* 要用作语言环境格式规则的语言环境代码。
*
* @returns The symbol, or the currency code if no symbol is available.
*
* 符号，或货币代码（如果没有可用的符号）。
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getCurrencySymbol(code: string, format: 'wide'|'narrow', locale = 'en'): string {
@ -665,10 +1078,20 @@ const DEFAULT_NB_OF_CURRENCY_DIGITS = 2;
* Reports the number of decimal digits for a given currency.
* The value depends upon the presence of cents in that particular currency.
*
* 报告给定货币的小数位数。其值取决于该特定货币中分币是否存在。
*
* @param code The currency code.
*
* 货币代码。
*
* @returns The number of decimal digits, typically 0 or 2.
*
* 小数位数，通常为 0 或 2。
*
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* [国际化(i18n)指南](guide/i18n)
*
* @publicApi
*/
export function getNumberOfCurrencyDigits(code: string): number {

2
packages/common/src/i18n/localization.ts
View File

@ -48,6 +48,8 @@ export function getPluralCategory(
/**
* Returns the plural case based on the locale
*
* 根据语言环境返回复数形式
*
* @publicApi
*/
@Injectable()

6
packages/common/src/location/hash_location_strategy.ts
View File

@ -20,13 +20,19 @@ import {joinWithSlash, normalizeQueryParams} from './util';
* [hash fragment](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax)
* of the browser's URL.
*
* 此 {@link LocationStrategy} 用来配置 {@link Location} 服务，以便在浏览器 URL 的 [hash 片段](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax)中表示其状态。
*
* For instance, if you call `location.go('/foo')`, the browser's URL will become
* `example.com#/foo`.
*
* 例如，如果你调用 `location.go('/foo')` ，则浏览器的 URL 将变为 `example.com#/foo` 。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* {@example common/location/ts/hash_location_component.ts region='LocationComponent'}
*
* @publicApi

21
packages/common/src/location/location.ts
View File

@ -61,6 +61,8 @@ export interface PopStateEvent {
*
* ### Example
*
* ### 例子
*
* <code-example path='common/location/ts/path_location_component.ts'
* region='LocationComponent'></code-example>
*
@ -122,7 +124,13 @@ export class Location {
/**
* Reports the current state of the location history.
*
* 报告位置历史记录的当前状态。
*
* @returns The current value of the `history.state` object.
*
* `history.state` 对象的当前值。
*
*/
getState(): unknown {
return this._platformLocation.getState();
@ -175,6 +183,8 @@ export class Location {
* before normalizing. Adds a hash if `HashLocationStrategy` is
* in use, or the `APP_BASE_HREF` if the `PathLocationStrategy` is in use.
*
* 标准化外部 URL 路径。如果给定的 URL 并非以斜杠（ `'/'` ）开头，就会在规范化之前添加一个。如果使用 `HashLocationStrategy` 则添加哈希；如果使用 `PathLocationStrategy` 则添加 `APP_BASE_HREF`。
*
* @param url String representing a URL.
*
* 表示一个 URL。
@ -264,7 +274,12 @@ export class Location {
* Registers a URL change listener. Use to catch updates performed by the Angular
* framework that are not detectible through "popstate" or "hashchange" events.
*
* 注册 URL 更改监听器。被 Angular 框架用于捕获那些无法通过 “popstate” 或 “hashchange” 事件检测到的更新。
*
* @param fn The change handler function, which take a URL and a location history state.
*
* 更改处理器函数，接受 URL 和位置历史记录的状态。
*
*/
onUrlChange(fn: (url: string, state: unknown) => void) {
this._urlChangeListeners.push(fn);
@ -327,8 +342,12 @@ export class Location {
* 给定 url 的两个部分，把它们连接（join）在一起，如有必要则添加一个斜杠。
*
* @param start URL string
*
* URL 字符串
*
* @param end URL string
*
* URL 字符串
*
* @returns The joined URL string.
*
@ -347,6 +366,8 @@ export class Location {
*
* @param url URL string.
*
* URL 字符串。
*
* @returns The URL string, modified if needed.
*
* 返回一个 URL 字符串，如果有结尾斜杠，则移除，否则原样返回。

24
packages/common/src/location/location_strategy.ts
View File

@ -16,16 +16,24 @@ import {joinWithSlash, normalizeQueryParams} from './util';
* Angular provides two strategies:
* `HashLocationStrategy` and `PathLocationStrategy`.
*
* 使 `Location` 服务能够从浏览器的 URL 读取路由状态。 Angular 提供了两种策略： `HashLocationStrategy` 和 `PathLocationStrategy` 。
*
* Applications should use the `Router` or `Location` services to
* interact with application route state.
*
* 应用程序应使用 `Router` 或 `Location` 服务与应用程序的路由状态进行交互。
*
* For instance, `HashLocationStrategy` produces URLs like
* <code class="no-auto-link">http://example.com#/foo</code>,
* and `PathLocationStrategy` produces
* <code class="no-auto-link">http://example.com/foo</code> as an equivalent URL.
*
* 例如，`HashLocationStrategy` 会处理像 <code class="no-auto-link">http://example.com#/foo</code> 这样的 URL，而 `PathLocationStrategy` 会处理像 <code class="no-auto-link">http://example.com/foo</code> 这样的等价 URL。
*
* See these two classes for more.
*
* 有关更多信息，请参见这两个类。
*
* @publicApi
*/
@Injectable({providedIn: 'root', useFactory: provideLocationStrategy})
@ -54,11 +62,15 @@ export function provideLocationStrategy(platformLocation: PlatformLocation) {
* The base href is the URL prefix that should be preserved when generating
* and recognizing URLs.
*
* 预定义的 [DI 令牌](guide/glossary#di-token)，用于和 `PathLocationStrategy` 一起使用的 base href。base href 是在生成和识别 URL 时应保留的 URL 前缀。
*
* @usageNotes
*
* The following example shows how to use this token to configure the root app injector
* with a base href value, so that the DI framework can supply the dependency anywhere in the app.
*
* 以下示例演示了如何使用此令牌为基本应用注入器配置 base href 值，以便 DI 框架可以在应用中的任何位置提供依赖项。
*
* ```typescript
* import {Component, NgModule} from '@angular/core';
* import {APP_BASE_HREF} from '@angular/common';
@ -80,26 +92,38 @@ export const APP_BASE_HREF = new InjectionToken<string>('appBaseHref');
* [path](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax) of the
* browser's URL.
*
* 此 {@link LocationStrategy} 用来配置 {@link Location} 服务，以便在浏览器 URL 的 [path](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax) 中表示其状态。
*
* If you're using `PathLocationStrategy`, you must provide a {@link APP_BASE_HREF}
* or add a `<base href>` element to the document.
*
* 如果你使用 `PathLocationStrategy` ，则必须提供一个 {@link APP_BASE_HREF} 或在文档中添加 `<base href>`。
*
* For instance, if you provide an `APP_BASE_HREF` of `'/my/app/'` and call
* `location.go('/foo')`, the browser's URL will become
* `example.com/my/app/foo`. To ensure all relative URIs resolve correctly,
* the `<base href>` and/or `APP_BASE_HREF` should end with a `/`.
*
* 例如，如果你提供的 `APP_BASE_HREF` 是 `'/my/app/'`，并调用 `location.go('/foo')`，则浏览器的 URL 将变为 `example.com/my/app/foo`。为了确保所有相对 URI 都能正确解析，`<base href>` 和/或 `APP_BASE_HREF` 都应该以 `/` 结尾。
*
* Similarly, if you add `<base href='/my/app/'/>` to the document and call
* `location.go('/foo')`, the browser's URL will become
* `example.com/my/app/foo`.
*
* 同样，如果将 `<base href='/my/app/'/>` 添加到文档中并调用 `location.go('/foo')` ，则浏览器的 URL 将变为 `example.com/my/app/foo` 。
*
* Note that when using `PathLocationStrategy`, neither the query nor
* the fragment in the `<base href>` will be preserved, as outlined
* by the [RFC](https://tools.ietf.org/html/rfc3986#section-5.2.2).
*
* 请注意，使用 `PathLocationStrategy` 时，如 [RFC](https://tools.ietf.org/html/rfc3986#section-5.2.2) 所述，查询和 `<base href>` 的片段部分都不会保留。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* {@example common/location/ts/path_location_component.ts region='LocationComponent'}
*
* @publicApi

12
packages/common/src/location/platform_location.ts
View File

@ -14,6 +14,8 @@ import {DOCUMENT} from '../dom_tokens';
* This class should not be used directly by an application developer. Instead, use
* {@link Location}.
*
* 此类不应由应用程序开发人员直接使用。而应使用 {@link Location}。
*
* `PlatformLocation` encapsulates all calls to DOM APIs, which allows the Router to be
* platform-agnostic.
* This means that we can have different implementation of `PlatformLocation` for the different
@ -21,15 +23,21 @@ import {DOCUMENT} from '../dom_tokens';
* implementation specific to the browser environment, while `@angular/platform-server` provides
* one suitable for use with server-side rendering.
*
* `PlatformLocation` 封装了对 DOM API 的所有调用，这可以让路由器与平台无关。这意味着我们可以为 Angular 支持的不同平台提供 `PlatformLocation` 的不同实现。例如， `@angular/platform-browser` 提供了特定于浏览器环境的实现，而 `@angular/platform-server` 提供了适合与服务器端渲染一起使用的实现。
*
* The `PlatformLocation` class is used directly by all implementations of {@link LocationStrategy}
* when they need to interact with the DOM APIs like pushState, popState, etc.
*
* {@link LocationStrategy} 的所有实现在需要与 DOM API（例如 pushState，popState 等）进行交互时，都直接使用 `PlatformLocation`
*
* {@link LocationStrategy} in turn is used by the {@link Location} service which is used directly
* by the {@link Router} in order to navigate between routes. Since all interactions between {@link
* Router} /
* {@link Location} / {@link LocationStrategy} and DOM APIs flow through the `PlatformLocation`
* class, they are all platform-agnostic.
*
* {@link LocationStrategy} 由 {@link Router} 直接使用的 {@link Location} 服务使用，以便在路由之间导航。由于 {@link Router} / {@link Location} / {@link LocationStrategy}与 DOM API 之间的所有交互都是通过 `PlatformLocation` 类进行的，因此它们都是与平台无关的。
*
* @publicApi
*/
@Injectable({
@ -68,6 +76,8 @@ export function useBrowserPlatformLocation() {
* @description
* Indicates when a location is initialized.
*
* 指示何时初始化 location。
*
* @publicApi
*/
export const LOCATION_INITIALIZED = new InjectionToken<Promise<any>>('Location Initialized');
@ -76,6 +86,8 @@ export const LOCATION_INITIALIZED = new InjectionToken<Promise<any>>('Location I
* @description
* A serializable version of the event from `onPopState` or `onHashChange`
*
* 来自 `onPopState` 或 `onHashChange` 的事件的可序列化版本
*
* @publicApi
*/
export interface LocationChangeEvent {

1
packages/common/src/pipes/case_conversion_pipes.ts
View File

@ -73,6 +73,7 @@ const unicodeWordMatch =
* @see `UpperCasePipe`
*
* @usageNotes
*
* The following example shows the result of transforming various strings into title case.
*
* 下面的例子示范了如何把多种字符串转成标题形式。

140
packages/common/src/pipes/date_pipe.ts
View File

@ -55,15 +55,17 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
* `'medium'`: 等价于 `'MMM d, y, h:mm:ss a'` (`Jun 15, 2015, 9:03:01 AM`).
*
* - `'long'`: equivalent to `'MMMM d, y, h:mm:ss a z'` (`June 15, 2015 at 9:03:01 AM
* GMT+1`).
*
* `'long'`: 等价于 `'MMMM d, y, h:mm:ss a z'` (`June 15, 2015 at 9:03:01 AM
* `'long'`: 等价于 `'MMMM d, y, h:mm:ss a z'` (`June 15, 2015 at 9:03:01 AM
* GMT+1`)。
*
* GMT+1`).
* - `'full'`: equivalent to `'EEEE, MMMM d, y, h:mm:ss a zzzz'` (`Monday, June 15, 2015 at
* 9:03:01 AM GMT+01:00`).
*
* `'full'`: 等价于 `'EEEE, MMMM d, y, h:mm:ss a zzzz'` (`Monday, June 15, 2015 at
* `'full'`: 等价于 `'EEEE, MMMM d, y, h:mm:ss a zzzz'` (`Monday, June 15, 2015 at
* 9:03:01 AM GMT+01:00`)。
*
* 9:03:01 AM GMT+01:00`).
* - `'shortDate'`: equivalent to `'M/d/yy'` (`6/15/15`).
*
* `'shortDate'`: 等价于 `'M/d/yy'` (`6/15/15`).
@ -110,73 +112,73 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
* 具体格式取决于区域设置。
* 标 `*` 的字段表示仅在特定区域的数据中才有效。
*
* | <t>Field type</t><t>字段类型</t> | <t>Format</t><t>格式</t> | <t>Description</t><t>说明</t> | <t>Example Value</t><t>范例值</t> |
* |--------------------|-------------|---------------------------------------------------------------|------------------------------------------------------------|
* | <t>Era</t><t>纪元</t> | G, GG & GGG | <t>Abbreviated</t><t>缩略</t>| AD |
* | | GGGG | <t>Wide</t><t>全称</t>| Anno Domini |
* | | GGGGG | <t>Narrow</t><t>最简</t>| A |
* | <t>Year</t><t>年</t> | y | <t>Numeric</t><t>数字</t>: <t>minimum digits</t><t>最小位数</t> | 2, 20, 201, 2017, 20173 |
* | | yy | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 02, 20, 01, 17, 73 |
* | | yyy | <t>Numeric</t><t>数字</t>: 3 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 002, 020, 201, 2017, 20173 |
* | | yyyy | <t>Numeric</t><t>数字</t>: 4 <t>digits or more + zero padded</t><t>或更多数字 + 0 补位</t> | 0002, 0020, 0201, 2017, 20173 |
* | Week-numbering year| Y | Numeric: minimum digits | 2, 20, 201, 2017, 20173 |
* | 周日历年| Y | 数字: 最少化数字 | 2, 20, 201, 2017, 20173 |
* | | YY | Numeric: 2 digits + zero padded | 02, 20, 01, 17, 73 |
* | | YY | 数字：2字符+补零 | 02, 20, 01, 17, 73 |
* | | YYY | Numeric: 3 digits + zero padded | 002, 020, 201, 2017, 20173 |
* | | YYY | 数字：3字符+补零 | 002, 020, 201, 2017, 20173 |
* | | YYYY | Numeric: 4 digits or more + zero padded | 0002, 0020, 0201, 2017, 20173 |
* | | YYYY | 数字：4字符+补零 | 0002, 0020, 0201, 2017, 20173 |
* | <t>Month</t><t>月</t> | M | <t>Numeric</t><t>数字</t>: <t>1 digit</t><t>1 数字</t> | 9, 12 |
* | | MM | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 09, 12 |
* | | MMM | <t>Abbreviated</t><t>缩略</t>| Sep |
* | | MMMM | <t>Wide</t><t>全称</t>| September |
* | | MMMMM | <t>Narrow</t><t>最简</t>| S |
* | <t>Month standalone</t><t>独立月份</t> | L | <t>Numeric</t><t>数字</t>: <t>1 digit</t><t>1 数字</t> | 9, 12 |
* | | LL | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 09, 12 |
* | | LLL | <t>Abbreviated</t><t>缩略</t>| Sep |
* | | LLLL | <t>Wide</t><t>全称</t>| September |
* | | LLLLL | <t>Narrow</t><t>最简</t>| S |
* | <t>Week of year</t><t>年内周次</t> | w | <t>Numeric</t><t>数字</t>: <t>minimum digits</t><t>最小位数</t> | 1... 53 |
* | | ww | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 01... 53 |
* | <t>Week of month</t><t>月内周次</t> | W | <t>Numeric</t><t>数字</t>: <t>1 digit</t><t>1 数字</t> | 1... 5 |
* | <t>Day of month</t><t>月内日</t> | d | <t>Numeric</t><t>数字</t>: <t>minimum digits</t><t>最小位数</t> | 1 |
* | | dd | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 01 |
* | <t>Week day</t><t>周内日</t> | E, EE & EEE | <t>Abbreviated</t><t>缩略</t>| Tue |
* | | EEEE | <t>Wide</t><t>全称</t>| Tuesday |
* | | EEEEE | <t>Narrow</t><t>最简</t>| T |
* | | EEEEEE | <t>Short</t><t>短</t> | Tu |
* | <t>Period</t><t>日内时段</t> | a, aa & aaa | <t>Abbreviated</t><t>缩略</t>| am/pm or AM/PM |
* | | aaaa | <t>Wide</t><t>全称</t><t>(fallback to `a` when missing)</t><t>(缺少时等同于 `a`)</t>| ante meridiem/post meridiem |
* | | aaaaa | <t>Narrow</t><t>最简</t>| a/p |
* | <t>Period*</t><t>日内时段</t> | B, BB & BBB | <t>Abbreviated</t><t>缩略</t>| mid. |
* | | BBBB | <t>Wide</t><t>全称</t>| am, pm, midnight, noon, morning, afternoon, evening, night |
* | | BBBBB | <t>Narrow</t><t>最简</t>| md |
* | <t>Period standalone*</t><t>独立时段</t> | b, bb & bbb | <t>Abbreviated</t><t>缩略</t>| mid. |
* | | bbbb | <t>Wide</t><t>全称</t>| am, pm, midnight, noon, morning, afternoon, evening, night |
* | | bbbbb | <t>Narrow</t><t>最简</t>| md |
* | <t>Hour 1-12</t><t>小时(1-12)</t> | h | <t>Numeric</t><t>数字</t>: <t>minimum digits</t><t>最小位数</t> | 1, 12 |
* | | hh | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 01, 12 |
* | <t>Hour 0-23</t><t>小时(0-23)</t> | H | <t>Numeric</t><t>数字</t>: <t>minimum digits</t><t>最小位数</t> | 0, 23 |
* | | HH | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 00, 23 |
* | <t>Minute</t><t>分</t> | m | <t>Numeric</t><t>数字</t>: <t>minimum digits</t><t>最小位数</t> | 8, 59 |
* | | mm | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 08, 59 |
* | <t>Second</t><t>秒</t> | s | <t>Numeric</t><t>数字</t>: <t>minimum digits</t><t>最小位数</t> | 0... 59 |
* | | ss | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 00... 59 |
* | <t>Fractional seconds</t><t>分数秒</t> | S | <t>Numeric</t><t>数字</t>: <t>1 digit</t><t>1 数字</t> | 0... 9 |
* | | SS | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 00... 99 |
* | | SSS | <t>Numeric</t><t>数字</t>: 3 <t>digits + zero padded</t><t>数字 + 0 补位</t> (= <t>milliseconds</t><t>毫秒</t>) | 000... 999 |
* | <t>Zone</t><t>时区</t> | z, zz & zzz | <t>Short specific non location format (fallback to O)</t><t>位置无关短格式（默认为0）</t> | GMT-8 |
* | | zzzz | <t>Long specific non location format (fallback to OOOO)</t><t>位置无关长格式（默认为0000）</t> | GMT-08:00 |
* | | Z, ZZ & ZZZ | ISO8601 <t>basic format</t><t>基本格式</t> | -0800 |
* | | ZZZZ | <t>Long localized GMT format</t><t>本地化 GMT 长格式</t> | GMT-8:00 |
* | | ZZZZZ | ISO8601 <t>extended format + Z indicator for offset 0</t><t>扩展格式 + 偏移为 0 时用 Z 表示</t> (= XXXXX) | -08:00 |
* | | O, OO & OOO | <t>Short localized GMT format</t><t>本地化 GMT 短格式</t> | GMT-8 |
* | | OOOO | <t>Long localized GMT format</t><t>本地化 GMT 长格式</t> | GMT-08:00 |
* | <t>Field type</t><t>字段类型</t> | <t>Format</t><t>格式</t> | <t>Description</t><t>说明</t> | <t>Example Value</t><t>范例值</t> |
* | -------------------------------- | ------------------------ | ----------------------------- | --------------------------------- |
* | <t>Era</t><t>纪元</t> | G, GG & GGG | <t>Abbreviated</t><t>缩略</t> | AD |
* | | GGGG | <t>Wide</t><t>全称</t> | Anno Domini |
* | | GGGGG | <t>Narrow</t><t>最简</t> | A |
* | <t>Year</t><t>年</t> | y | <t>Numeric</t><t>数字</t>: <t>minimum digits</t><t>最小位数</t> | 2, 20, 201, 2017, 20173 |
* | | yy | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 02, 20, 01, 17, 73 |
* | | yyy | <t>Numeric</t><t>数字</t>: 3 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 002, 020, 201, 2017, 20173 |
* | | yyyy | <t>Numeric</t><t>数字</t>: 4 <t>digits or more + zero padded</t><t>或更多数字 + 0 补位</t> | 0002, 0020, 0201, 2017, 20173 |
* | Week-numbering year | Y | Numeric: minimum digits | 2, 20, 201, 2017, 20173 |
* | 周日历年 | Y | 数字: 最少化数字 | 2, 20, 201, 2017, 20173 |
* | | YY | Numeric: 2 digits + zero padded | 02, 20, 01, 17, 73 |
* | | YY | 数字：2 字符+补零 | 02, 20, 01, 17, 73 |
* | | YYY | Numeric: 3 digits + zero padded | 002, 020, 201, 2017, 20173 |
* | | YYY | 数字：3 字符+补零 | 002, 020, 201, 2017, 20173 |
* | | YYYY | Numeric: 4 digits or more + zero padded | 0002, 0020, 0201, 2017, 20173 |
* | | YYYY | 数字：4 字符+补零 | 0002, 0020, 0201, 2017, 20173 |
* | <t>Month</t><t>月</t> | M | <t>Numeric</t><t>数字</t>: <t>1 digit</t><t>1 数字</t> | 9, 12 |
* | | MM | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 09, 12 |
* | | MMM | <t>Abbreviated</t><t>缩略</t> | Sep |
* | | MMMM | <t>Wide</t><t>全称</t> | September |
* | | MMMMM | <t>Narrow</t><t>最简</t> | S |
* | <t>Month standalone</t><t>独立月份</t> | L | <t>Numeric</t><t>数字</t>: <t>1 digit</t><t>1 数字</t> | 9, 12 |
* | | LL | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 09, 12 |
* | | LLL | <t>Abbreviated</t><t>缩略</t> | Sep |
* | | LLLL | <t>Wide</t><t>全称</t> | September |
* | | LLLLL | <t>Narrow</t><t>最简</t> | S |
* | <t>Week of year</t><t>年内周次</t> | w | <t>Numeric</t><t>数字</t>: <t>minimum digits</t><t>最小位数</t> | 1... 53 |
* | | ww | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 01... 53 |
* | <t>Week of month</t><t>月内周次</t> | W | <t>Numeric</t><t>数字</t>: <t>1 digit</t><t>1 数字</t> | 1... 5 |
* | <t>Day of month</t><t>月内日</t> | d | <t>Numeric</t><t>数字</t>: <t>minimum digits</t><t>最小位数</t> | 1 |
* | | dd | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 01 |
* | <t>Week day</t><t>周内日</t> | E, EE & EEE | <t>Abbreviated</t><t>缩略</t> | Tue |
* | | EEEE | <t>Wide</t><t>全称</t> | Tuesday |
* | | EEEEE | <t>Narrow</t><t>最简</t> | T |
* | | EEEEEE | <t>Short</t><t>短</t> | Tu |
* | <t>Period</t><t>日内时段</t> | a, aa & aaa | <t>Abbreviated</t><t>缩略</t> | am/pm or AM/PM |
* | | aaaa | <t>Wide</t><t>全称</t><t>(fallback to `a` when missing)</t><t>(缺少时等同于 `a`)</t> | ante meridiem/post meridiem |
* | | aaaaa | <t>Narrow</t><t>最简</t> | a/p |
* | <t>Period\*</t><t>日内时段</t> | B, BB & BBB | <t>Abbreviated</t><t>缩略</t> | mid. |
* | | BBBB | <t>Wide</t><t>全称</t> | am, pm, midnight, noon, morning, afternoon, evening, night |
* | | BBBBB | <t>Narrow</t><t>最简</t> | md |
* | <t>Period standalone\*</t><t>独立时段</t> | b, bb & bbb | <t>Abbreviated</t><t>缩略</t> | mid. |
* | | bbbb | <t>Wide</t><t>全称</t> | am, pm, midnight, noon, morning, afternoon, evening, night |
* | | bbbbb | <t>Narrow</t><t>最简</t> | md |
* | <t>Hour 1-12</t><t>小时(1-12)</t> | h | <t>Numeric</t><t>数字</t>: <t>minimum digits</t><t>最小位数</t> | 1, 12 |
* | | hh | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 01, 12 |
* | <t>Hour 0-23</t><t>小时(0-23)</t> | H | <t>Numeric</t><t>数字</t>: <t>minimum digits</t><t>最小位数</t> | 0, 23 |
* | | HH | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 00, 23 |
* | <t>Minute</t><t>分</t> | m | <t>Numeric</t><t>数字</t>: <t>minimum digits</t><t>最小位数</t> | 8, 59 |
* | | mm | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 08, 59 |
* | <t>Second</t><t>秒</t> | s | <t>Numeric</t><t>数字</t>: <t>minimum digits</t><t>最小位数</t> | 0... 59 |
* | | ss | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 00... 59 |
* | <t>Fractional seconds</t><t>分数秒</t> | S | <t>Numeric</t><t>数字</t>: <t>1 digit</t><t>1 数字</t> | 0... 9 |
* | | SS | <t>Numeric</t><t>数字</t>: 2 <t>digits + zero padded</t><t>数字 + 0 补位</t> | 00... 99 |
* | | SSS | <t>Numeric</t><t>数字</t>: 3 <t>digits + zero padded</t><t>数字 + 0 补位</t> (= <t>milliseconds</t><t>毫秒</t>) | 000... 999 |
* | <t>Zone</t><t>时区</t> | z, zz & zzz | <t>Short specific non location format (fallback to O)</t><t>位置无关短格式（默认为 0）</t> | GMT-8 |
* | | zzzz | <t>Long specific non location format (fallback to OOOO)</t><t>位置无关长格式（默认为 0000）</t> | GMT-08:00 |
* | | Z, ZZ & ZZZ | ISO8601 <t>basic format</t><t>基本格式</t> | -0800 |
* | | ZZZZ | <t>Long localized GMT format</t><t>本地化 GMT 长格式</t> | GMT-8:00 |
* | | ZZZZZ | ISO8601 <t>extended format + Z indicator for offset 0</t><t>扩展格式 + 偏移为 0 时用 Z 表示</t> (= XXXXX) | -08:00 |
* | | O, OO & OOO | <t>Short localized GMT format</t><t>本地化 GMT 短格式</t> | GMT-8 |
* | | OOOO | <t>Long localized GMT format</t><t>本地化 GMT 长格式</t> | GMT-08:00 |
*
* Note that timezone correction is not applied to an ISO string that has no time component, such as "2016-09-19"
*
* 请注意，时区校正不适用于没有时间部分的ISO字符串，例如“2016-09-19”
* 请注意，时区校正不适用于没有时间部分的 ISO 字符串，例如“2016-09-19”
*
* ### Format examples
*
@ -243,7 +245,7 @@ export class DatePipe implements PipeTransform {
* UTC/GMT or continental US timezone abbreviation.
* When not supplied, uses the end-user's local system timezone.
*
* 一个时区偏移（比如`'+0430'`）或标准的 UTC/GMT 或美国大陆时区的缩写。默认为最终用户机器上的本地系统时区。
* 一个时区偏移（比如 `'+0430'`）或标准的 UTC/GMT 或美国大陆时区的缩写。默认为最终用户机器上的本地系统时区。
*
* @param locale A locale code for the locale format rules to use.
* When not supplied, uses the value of `LOCALE_ID`, which is `en-US` by default.

12
packages/common/src/pipes/i18n_plural_pipe.ts
View File

@ -20,10 +20,14 @@ const _INTERPOLATION_REGEXP: RegExp = /#/g;
*
* Maps a value to a string that pluralizes the value according to locale rules.
*
* 将值映射到根据语言环境规则对该值进行复数化的字符串。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* {@example common/pipes/ts/i18n_pipe.ts region='I18nPluralPipeComponent'}
*
* @publicApi
@ -34,10 +38,18 @@ export class I18nPluralPipe implements PipeTransform {
/**
* @param value the number to be formatted
*
* 要格式化的数字
*
* @param pluralMap an object that mimics the ICU format, see
* http://userguide.icu-project.org/formatparse/messages.
*
* 模仿 ICU 格式的对象，请参见<http://userguide.icu-project.org/formatparse/messages> 。
*
* @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by
* default).
*
* 定义要使用的语言环境的 `string`（默认情况下使用当前的 {@link LOCALE_ID}）。
*/
transform(value: number|null|undefined, pluralMap: {[count: string]: string}, locale?: string):
string {

12
packages/common/src/pipes/i18n_select_pipe.ts
View File

@ -15,13 +15,19 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
*
* Generic selector that displays the string that matches the current value.
*
* 通用选择器，用于显示与当前值匹配的字符串。
*
* If none of the keys of the `mapping` match the `value`, then the content
* of the `other` key is returned when present, otherwise an empty string is returned.
*
* 如果 `mapping` 中的任何键都不与 `value` 匹配，`other` 键的内容如果存在则返回，否则返回空字符串。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* {@example common/pipes/ts/i18n_pipe.ts region='I18nSelectPipeComponent'}
*
* @publicApi
@ -30,8 +36,14 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
export class I18nSelectPipe implements PipeTransform {
/**
* @param value a string to be internationalized.
*
* 要国际化的字符串。
*
* @param mapping an object that indicates the text that should be displayed
* for different values of the provided `value`.
*
* 一个对象，指示对不同于所提供 `value` 的值应该显示的文本。
*
*/
transform(value: string|null|undefined, mapping: {[key: string]: string}): string {
if (value == null) return '';

11
packages/common/src/pipes/keyvalue_pipe.ts
View File

@ -16,6 +16,8 @@ function makeKeyValuePair<K, V>(key: K, value: V): KeyValue<K, V> {
* A key value pair.
* Usually used to represent the key value pairs from a Map or Object.
*
* 一个键值对。通常用于表示 Map 或 Object 中的键值对。
*
* @publicApi
*/
export interface KeyValue<K, V> {
@ -29,16 +31,25 @@ export interface KeyValue<K, V> {
*
* Transforms Object or Map into an array of key value pairs.
*
* 将 Object 或 Map 转换为键值对数组。
*
* The output array will be ordered by keys.
* By default the comparator will be by Unicode point value.
* You can optionally pass a compareFn if your keys are complex types.
*
* 输出数组将通过键名排序。默认情况下，比较器将使用 Unicode 点位值。如果你的键名是复杂类型，则可以选择传入一个 compareFn。
*
* @usageNotes
*
* ### Examples
*
* ### 例子
*
* This examples show how an Object or a Map can be iterated by ngFor with the use of this
* keyvalue pipe.
*
* 此示例演示了 ngFor 如何使用此键值管道对 Object 或 Map 进行迭代。
*
* {@example common/pipes/ts/keyvalue_pipe.ts region='KeyValuePipe'}
*
* @publicApi

3
packages/common/src/pipes/number_pipe.ts
View File

@ -45,6 +45,7 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
* @see `formatNumber()`
*
* @usageNotes
*
* The following code shows how the pipe transforms numbers
* into text strings, according to various format specifications,
* where the caller's default locale is `en-US`.
@ -131,6 +132,7 @@ export class DecimalPipe implements PipeTransform {
* @see `formatPercent()`
*
* @usageNotes
*
* The following code shows how the pipe transforms numbers
* into text strings, according to various format specifications,
* where the caller's default locale is `en-US`.
@ -234,6 +236,7 @@ export class PercentPipe implements PipeTransform {
* @see `formatCurrency()`
*
* @usageNotes
*
* The following code shows how the pipe transforms numbers
* into text strings, according to various format specifications,
* where the caller's default locale is `en-US`.

12
packages/common/src/platform_id.ts
View File

@ -13,6 +13,9 @@ export const PLATFORM_WORKER_UI_ID = 'browserWorkerUi';
/**
* Returns whether a platform id represents a browser platform.
*
* 返回平台 ID 是否代表浏览器平台。
*
* @publicApi
*/
export function isPlatformBrowser(platformId: Object): boolean {
@ -21,6 +24,9 @@ export function isPlatformBrowser(platformId: Object): boolean {
/**
* Returns whether a platform id represents a server platform.
*
* 返回平台 ID 是否代表服务器平台。
*
* @publicApi
*/
export function isPlatformServer(platformId: Object): boolean {
@ -29,6 +35,9 @@ export function isPlatformServer(platformId: Object): boolean {
/**
* Returns whether a platform id represents a web worker app platform.
*
* 返回平台 ID 是否代表 Web Worker 应用平台。
*
* @publicApi
*/
export function isPlatformWorkerApp(platformId: Object): boolean {
@ -37,6 +46,9 @@ export function isPlatformWorkerApp(platformId: Object): boolean {
/**
* Returns whether a platform id represents a web worker UI platform.
*
* 返回平台 ID 是否代表 Web Worker UI 平台。
*
* @publicApi
*/
export function isPlatformWorkerUi(platformId: Object): boolean {

28
packages/common/src/viewport_scroller.ts
View File

@ -15,6 +15,8 @@ import {DOCUMENT} from './dom_tokens';
/**
* Defines a scroll position manager. Implemented by `BrowserViewportScroller`.
*
* 定义滚动位置管理器。由 `BrowserViewportScroller` 实现。
*
* @publicApi
*/
export abstract class ViewportScroller {
@ -29,27 +31,50 @@ export abstract class ViewportScroller {
/**
* Configures the top offset used when scrolling to an anchor.
*
* 配置滚动到锚点时使用的顶部偏移量。
*
* @param offset A position in screen coordinates (a tuple with x and y values)
* or a function that returns the top offset position.
*
* 屏幕坐标中的位置（具有 x 和 y 值的元组）或返回顶部偏移位置的函数。
*
*/
abstract setOffset(offset: [number, number]|(() => [number, number])): void;
/**
* Retrieves the current scroll position.
*
* 检索当前滚动位置。
*
* @returns A position in screen coordinates (a tuple with x and y values).
*
* 屏幕坐标中的位置（具有 x 和 y 值的元组）。
*
*/
abstract getScrollPosition(): [number, number];
/**
* Scrolls to a specified position.
*
* 滚动到指定位置。
*
* @param position A position in screen coordinates (a tuple with x and y values).
*
* 屏幕坐标中的位置（具有 x 和 y 值的元组）。
*
*/
abstract scrollToPosition(position: [number, number]): void;
/**
* Scrolls to an anchor element.
*
* 滚动到锚点元素。
*
* @param anchor The ID of the anchor element.
*
* 锚点元素的 ID。
*
*/
abstract scrollToAnchor(anchor: string): void;
@ -57,6 +82,9 @@ export abstract class ViewportScroller {
* Disables automatic scroll restoration provided by the browser.
* See also [window.history.scrollRestoration
* info](https://developers.google.com/web/updates/2015/09/history-api-scroll-restoration).
*
* 禁用浏览器提供的自动滚动恢复功能。另请参见 [window.history.scrollRestoration 信息](https://developers.google.com/web/updates/2015/09/history-api-scroll-restoration)。
*
*/
abstract setHistoryScrollRestoration(scrollRestoration: 'auto'|'manual'): void;
}

2
packages/common/testing/src/location_mock.ts
View File

@ -13,6 +13,8 @@ import {SubscriptionLike} from 'rxjs';
/**
* A spy for {@link Location} that allows tests to fire simulated location events.
*
* {@link Location} 的间谍对象，它允许测试者触发模拟的位置事件。
*
* @publicApi
*/
@Injectable()

2
packages/common/testing/src/mock_location_strategy.ts
View File

@ -15,6 +15,8 @@ import {EventEmitter, Injectable} from '@angular/core';
* A mock implementation of {@link LocationStrategy} that allows tests to fire simulated
* location events.
*
* {@link LocationStrategy} 的模拟实现，允许测试触发模拟的 location 事件。
*
* @publicApi
*/
@Injectable()

6
packages/common/testing/src/mock_platform_location.ts
View File

@ -81,6 +81,8 @@ function parseUrl(urlStr: string, baseHref: string) {
/**
* Mock platform location config
*
* 模拟平台的 location 配置
*
* @publicApi
*/
export interface MockPlatformLocationConfig {
@ -91,6 +93,8 @@ export interface MockPlatformLocationConfig {
/**
* Provider for mock platform location config
*
* 模拟平台 location 配置的提供者
*
* @publicApi
*/
export const MOCK_PLATFORM_LOCATION_CONFIG =
@ -99,6 +103,8 @@ export const MOCK_PLATFORM_LOCATION_CONFIG =
/**
* Mock implementation of URL state.
*
* URL 状态的模拟实现。
*
* @publicApi
*/
@Injectable()

82
packages/common/upgrade/src/location_shim.ts
View File

@ -26,8 +26,12 @@ const DEFAULT_PORTS: {[key: string]: number} = {
* Location service that provides a drop-in replacement for the $location service
* provided in AngularJS.
*
* 位置服务，提供对 AngularJS 中提供的 $location 服务的直接替代品。
*
* @see [Using the Angular Unified Location Service](guide/upgrade#using-the-unified-angular-location-service)
*
* [使用 Angular 统一位置服务](guide/upgrade#using-the-unified-angular-location-service)
*
* @publicApi
*/
export class $locationShim {
@ -290,6 +294,9 @@ export class $locationShim {
/**
* This function emulates the $browser.state() function from AngularJS. It will cause
* history.state to be cached unless changed with deep equality check.
*
* 此函数模拟 AngularJS 中的 $browser.state() 函数。除非使用深度相等性检查进行更改，否则它将导致 history.state 被缓存。
*
*/
private browserState(): unknown {
return this.cachedState;
@ -340,12 +347,22 @@ export class $locationShim {
* `$locationChangeSuccess` events which fire when AngularJS updates its internally-referenced
* version of the browser URL.
*
* 注册对 URL 更改的监听器。该 API 用于捕获 AngularJS 框架执行的更新。`$locationChangeStart` 和 `$locationChangeSuccess` 事件的子集，这些事件在 AngularJS 更新其内部引用的浏览器 URL 版本时触发。
*
* It's possible for `$locationChange` events to happen, but for the browser URL
* (window.location) to remain unchanged. This `onChange` callback will fire only when AngularJS
* actually updates the browser URL (window.location).
*
* `$locationChange` 事件有可能发生，但浏览器的 URL（window.location）保持不变。仅当 AngularJS 实际上更新浏览器 URL（window.location）时，才会触发此 `onChange`
*
* @param fn The callback function that is triggered for the listener when the URL changes.
*
* URL 更改时为监听器触发的回调函数。
*
* @param err The callback function that is triggered when an error occurs.
*
* 发生错误时触发的回调函数。
*
*/
onChange(
fn: (url: string, state: unknown, oldUrl: string, oldState: unknown) => void,
@ -368,7 +385,12 @@ export class $locationShim {
/**
* Parses the provided URL, and sets the current URL to the parsed result.
*
* 解析此 URL，并将当前 URL 设置为解析结果。
*
* @param url The URL string.
*
* URL 字符串。
*
*/
$$parse(url: string) {
let pathUrl: string|undefined;
@ -393,8 +415,16 @@ export class $locationShim {
/**
* Parses the provided URL and its relative URL.
*
* 解析提供的 URL 及其相对 URL。
*
* @param url The full URL string.
*
* 完整的 URL 字符串。
*
* @param relHref A URL string relative to the full URL string.
*
* 相对于完整 URL 字符串的 URL 字符串。
*
*/
$$parseLinkUrl(url: string, relHref?: string|null): boolean {
// When relHref is passed, it should be a hash and is handled separately
@ -446,6 +476,7 @@ export class $locationShim {
* rules specified in
* [RFC 3986](https://tools.ietf.org/html/rfc3986).
*
* 检索完整的 URL 表示形式，其中包含根据 [RFC 3986 中](https://tools.ietf.org/html/rfc3986) 指定的规则编码过的所有段。
*
* ```js
* // given URL http://example.com/#/some/path?foo=bar&baz=xoxo
@ -461,6 +492,8 @@ export class $locationShim {
* Retrieves the current URL, or sets a new URL. When setting a URL,
* changes the path, search, and hash, and returns a reference to its own instance.
*
* 检索当前 URL，或设置新 URL。设置 URL 时，更改路径、搜索和哈希，并返回对其自身实例的引用。
*
* ```js
* // given URL http://example.com/#/some/path?foo=bar&baz=xoxo
* let url = $location.url();
@ -491,6 +524,8 @@ export class $locationShim {
/**
* Retrieves the protocol of the current URL.
*
* 检索当前 URL 的协议。
*
* ```js
* // given URL http://example.com/#/some/path?foo=bar&baz=xoxo
* let protocol = $location.protocol();
@ -504,9 +539,12 @@ export class $locationShim {
/**
* Retrieves the protocol of the current URL.
*
* 检索当前 URL 的协议。
*
* In contrast to the non-AngularJS version `location.host` which returns `hostname:port`, this
* returns the `hostname` portion only.
*
* 与非 AngularJS 版本不同，其 `location.host` 会返回 `hostname:port` ，而这里会返回 `hostname` 部分。
*
* ```js
* // given URL http://example.com/#/some/path?foo=bar&baz=xoxo
@ -527,6 +565,8 @@ export class $locationShim {
/**
* Retrieves the port of the current URL.
*
* 检索当前 URL 的端口。
*
* ```js
* // given URL http://example.com/#/some/path?foo=bar&baz=xoxo
* let port = $location.port();
@ -541,9 +581,13 @@ export class $locationShim {
* Retrieves the path of the current URL, or changes the path and returns a reference to its own
* instance.
*
* 检索当前 URL 的路径，或更改路径并返回对其自身实例的引用。
*
* Paths should always begin with forward slash (/). This method adds the forward slash
* if it is missing.
*
* 路径应始终以正斜杠（/）开头。如果缺少此斜杠，则此方法将添加它。
*
* ```js
* // given URL http://example.com/#/some/path?foo=bar&baz=xoxo
* let path = $location.path();
@ -571,6 +615,7 @@ export class $locationShim {
* Retrieves a map of the search parameters of the current URL, or changes a search
* part and returns a reference to its own instance.
*
* 检索当前 URL 的搜索参数的映射，或更改搜索部分并返回对其自身实例的引用。
*
* ```js
* // given URL http://example.com/#/some/path?foo=bar&baz=xoxo
@ -585,25 +630,41 @@ export class $locationShim {
* @param {string|Object.<string>|Object.<Array.<string>>} search New search params - string or
* hash object.
*
* 新的搜索参数-字符串或哈希对象。
*
* When called with a single argument the method acts as a setter, setting the `search` component
* of `$location` to the specified value.
*
* 当使用单个参数调用它时，该方法会充当设置器，将 `$location` 的 `search` 组件设置为指定值。
*
* If the argument is a hash object containing an array of values, these values will be encoded
* as duplicate search parameters in the URL.
*
* 如果参数是包含值数组的哈希对象，则这些值将被编码为 URL 中的重复搜索参数。
*
* @param {(string|Number|Array<string>|boolean)=} paramValue If `search` is a string or number,
* then `paramValue`
* will override only a single search property.
*
* 如果 `search` 是字符串或数字，则 `paramValue` 将仅覆盖单个搜索属性。
*
* If `paramValue` is an array, it will override the property of the `search` component of
* `$location` specified via the first argument.
*
* 如果 `paramValue` 是一个数组，它将覆盖通过第一个参数指定的 `$location` 的 `search` 的部分。
*
* If `paramValue` is `null`, the property specified via the first argument will be deleted.
*
* 如果 `paramValue` 为 `null` ，则将删除通过第一个参数指定的属性。
*
* If `paramValue` is `true`, the property specified via the first argument will be added with no
* value nor trailing equal sign.
*
* 如果 `paramValue` 为 `true` ，则将通过第一个参数指定的属性添加为无值或结尾等号。
*
* @return {Object} The parsed `search` object of the current URL, or the changed `search` object.
*
* 当前 URL 的已解析 `search` 对象，或更改后的 `search` 对象。
*/
search(): {[key: string]: unknown};
search(search: string|number|{[key: string]: unknown}): this;
@ -653,6 +714,8 @@ export class $locationShim {
* Retrieves the current hash fragment, or changes the hash fragment and returns a reference to
* its own instance.
*
* 检索当前哈希片段，或更改哈希片段并返回对其自身实例的引用。
*
* ```js
* // given URL http://example.com/#/some/path?foo=bar&baz=xoxo#hashValue
* let hash = $location.hash();
@ -675,6 +738,9 @@ export class $locationShim {
/**
* Changes to `$location` during the current `$digest` will replace the current
* history record, instead of adding a new one.
*
* 当前 `$digest` 期间对 `$location` 更改将替换当前历史记录，而不是添加新的记录。
*
*/
replace(): this {
this.$$replace = true;
@ -684,13 +750,18 @@ export class $locationShim {
/**
* Retrieves the history state object when called without any parameter.
*
* 当不带任何参数调用时将检索历史状态对象。
*
* Change the history state object when called with one parameter and return `$location`.
* The state object is later passed to `pushState` or `replaceState`.
*
* 使用一个参数调用时将更改历史状态对象，并返回 `$location` 。状态对象随后传递给 `pushState` 或 `replaceState` 。
*
* This method is supported only in HTML5 mode and only in browsers supporting
* the HTML5 History API methods such as `pushState` and `replaceState`. If you need to support
* older browsers (like Android < 4.0), don't use this method.
*
* 仅在 HTML5 模式下以及在支持 HTML5 History API 方法（例如 `pushState` 和 `replaceState`）的浏览器中才支持此方法。如果你需要支持较旧的浏览器（例如 Android &lt;4.0），请不要使用此方法。
*/
state(): unknown;
state(state: unknown): this;
@ -708,6 +779,8 @@ export class $locationShim {
* The factory function used to create an instance of the `$locationShim` in Angular,
* and provides an API-compatiable `$locationProvider` for AngularJS.
*
* Angular 中用于创建 `$locationShim` 实例的工厂函数，并为 AngularJS 提供与 API 兼容的 `$locationProvider`。
*
* @publicApi
*/
export class $locationShimProvider {
@ -718,6 +791,9 @@ export class $locationShimProvider {
/**
* Factory method that returns an instance of the $locationShim
*
* 返回 $locationShim 实例的工厂方法
*
*/
$get() {
return new $locationShim(
@ -728,6 +804,9 @@ export class $locationShimProvider {
/**
* Stub method used to keep API compatible with AngularJS. This setting is configured through
* the LocationUpgradeModule's `config` method in your Angular app.
*
* 用于使 API 与 AngularJS 兼容的存根方法。此设置是通过 Angular 应用中 LocationUpgradeModule 的 `config` 方法配置的。
*
*/
hashPrefix(prefix?: string) {
throw new Error('Configure LocationUpgrade through LocationUpgradeModule.config method.');
@ -736,6 +815,9 @@ export class $locationShimProvider {
/**
* Stub method used to keep API compatible with AngularJS. This setting is configured through
* the LocationUpgradeModule's `config` method in your Angular app.
*
* 用于使 API 与 AngularJS 兼容的存根方法。此设置是通过 Angular 应用中 LocationUpgradeModule 的 `config` 方法配置的。
*
*/
html5Mode(mode?: any) {
throw new Error('Configure LocationUpgrade through LocationUpgradeModule.config method.');

23
packages/common/upgrade/src/location_upgrade_module.ts
View File

@ -17,28 +17,45 @@ import {AngularJSUrlCodec, UrlCodec} from './params';
/**
* Configuration options for LocationUpgrade.
*
* LocationUpgrade 的配置选项。
*
* @publicApi
*/
export interface LocationUpgradeConfig {
/**
* Configures whether the location upgrade module should use the `HashLocationStrategy`
* or the `PathLocationStrategy`
*
* 配置 location 升级模块应使用 `HashLocationStrategy` 还是 `PathLocationStrategy`
*
*/
useHash?: boolean;
/**
* Configures the hash prefix used in the URL when using the `HashLocationStrategy`
*
* 配置使用 `HashLocationStrategy` 时 URL 中要使用的哈希前缀
*
*/
hashPrefix?: string;
/**
* Configures the URL codec for encoding and decoding URLs. Default is the `AngularJSCodec`
*
* 配置 URL 编解码器以对 URL 进行编码和解码。默认为 `AngularJSCodec`
*
*/
urlCodec?: typeof UrlCodec;
/**
* Configures the base href when used in server-side rendered applications
*
* 配置在服务器端渲染的应用程序中使用时的 base href
*
*/
serverBaseHref?: string;
/**
* Configures the base href when used in client-side rendered applications
*
* 配置在客户端渲染的应用程序中使用时的 base href
*
*/
appBaseHref?: string;
}
@ -46,6 +63,8 @@ export interface LocationUpgradeConfig {
/**
* A provider token used to configure the location upgrade module.
*
* 提供者令牌，用于配置 location 升级模块。
*
* @publicApi
*/
export const LOCATION_UPGRADE_CONFIGURATION =
@ -56,8 +75,12 @@ const APP_BASE_HREF_RESOLVED = new InjectionToken<string>('APP_BASE_HREF_RESOLVE
/**
* `NgModule` used for providing and configuring Angular's Unified Location Service for upgrading.
*
* `NgModule` 用于提供和配置 Angular 的统一 location 服务以进行升级。
*
* @see [Using the Unified Angular Location Service](guide/upgrade#using-the-unified-angular-location-service)
*
* [使用统一的 Angular location 服务](guide/upgrade#using-the-unified-angular-location-service)
*
* @publicApi
*/
@NgModule({imports: [CommonModule]})

70
packages/common/upgrade/src/params.ts
View File

@ -9,55 +9,92 @@
/**
* A codec for encoding and decoding URL parts.
*
* 用于编码和解码 URL 部分的编解码器。
*
* @publicApi
**/
export abstract class UrlCodec {
/**
* Encodes the path from the provided string
*
* 解码所提供的字符串的路径
*
* @param path The path string
*
* 路径字符串
*
*/
abstract encodePath(path: string): string;
/**
* Decodes the path from the provided string
*
* 解码所提供的字符串的路径
*
* @param path The path string
*
* 路径字符串
*
*/
abstract decodePath(path: string): string;
/**
* Encodes the search string from the provided string or object
*
* 从所提供的字符串或对象中编码搜索字符串
*
* @param path The path string or object
*
* 路径字符串或对象
*
*/
abstract encodeSearch(search: string|{[k: string]: unknown}): string;
/**
* Decodes the search objects from the provided string
*
* 从所提供的字符串中解码搜索对象
*
* @param path The path string
*
* 路径字符串
*
*/
abstract decodeSearch(search: string): {[k: string]: unknown};
/**
* Encodes the hash from the provided string
*
* 对所提供的字符串中的哈希进行编码
*
* @param path The hash string
*
* 哈希字符串
*
*/
abstract encodeHash(hash: string): string;
/**
* Decodes the hash from the provided string
*
* 从所提供的字符串中解码哈希
*
* @param path The hash string
*
* 哈希字符串
*
*/
abstract decodeHash(hash: string): string;
/**
* Normalizes the URL from the provided string
*
* 从所提供的字符串中标准化 URL
*
* @param path The URL string
*
* URL 字符串
*
*/
abstract normalize(href: string): string;
@ -65,26 +102,57 @@ export abstract class UrlCodec {
/**
* Normalizes the URL from the provided string, search, hash, and base URL parameters
*
* 根据所提供的字符串、搜索、哈希和基本 URL 参数标准化 URL
*
* @param path The URL path
*
* 网址路径
*
* @param search The search object
*
* 搜索对象
*
* @param hash The has string
*
* 哈希字符串
*
* @param baseUrl The base URL for the URL
*
* 此 URL 的基本 URL
*
*/
abstract normalize(path: string, search: {[k: string]: unknown}, hash: string, baseUrl?: string):
string;
/**
* Checks whether the two strings are equal
*
* 检查两个字符串是否相等
*
* @param valA First string for comparison
*
* 要比较的第一个字符串
*
* @param valB Second string for comparison
*
* 要比较的第二个字符串
*
*/
abstract areEqual(valA: string, valB: string): boolean;
/**
* Parses the URL string based on the base URL
*
* 根据基本 URL 解析 URL 字符串
*
* @param url The full URL string
*
* 完整的 URL 字符串
*
* @param base The base for the URL
*
* URL 的 base 部分
*
*/
abstract parse(url: string, base?: string): {
href: string,
@ -102,6 +170,8 @@ export abstract class UrlCodec {
* A `UrlCodec` that uses logic from AngularJS to serialize and parse URLs
* and URL parameters.
*
* 一个 `UrlCodec`，它使用 AngularJS 中的逻辑来序列化和解析 URL 和 URL 参数。
*
* @publicApi
*/
export class AngularJSUrlCodec implements UrlCodec {

2
packages/common/upgrade/test/upgrade_location_test_module.ts
View File

@ -28,6 +28,8 @@ export interface LocationUpgradeTestingConfig {
*
* Is used in DI to configure the router.
*
* 用于在 DI 中配置路由器。
*
* @publicApi
*/
export const LOC_UPGRADE_TEST_CONFIG =

8
packages/core/src/application_init.ts
View File

@ -15,15 +15,21 @@ import {noop} from './util/noop';
* A [DI token](guide/glossary#di-token "DI token definition") that you can use to provide
* one or more initialization functions.
*
* 可用于提供一个或多个初始化功能的 [DI 令牌。](guide/glossary#di-token "DI 令牌定义")
*
* The provided functions are injected at application startup and executed during
* app initialization. If any of these functions returns a Promise, initialization
* does not complete until the Promise is resolved.
*
* 所提供的函数是在应用程序启动时注入的，并在应用程序初始化期间执行。如果这些函数中的任何一个返回 Promise，则直到 Promise 被解析之前，初始化都不会完成。
*
* You can, for example, create a factory function that loads language data
* or an external configuration, and provide that function to the `APP_INITIALIZER` token.
* The function is executed during the application bootstrap process,
* and the needed data is available on startup.
*
* 例如，你可以创建一个工厂函数来加载语言数据或外部配置，并将该函数提供给 `APP_INITIALIZER` 令牌。该功能在应用程序引导过程中执行，并且所需的数据在启动时可用。
*
* @see `ApplicationInitStatus`
*
* @publicApi
@ -33,6 +39,8 @@ export const APP_INITIALIZER = new InjectionToken<Array<() => void>>('Applicatio
/**
* A class that reflects the state of running {@link APP_INITIALIZER} functions.
*
* 反映正在运行的 {@link APP_INITIALIZER} 函数状态的类。
*
* @publicApi
*/
@Injectable()

4
packages/core/src/application_module.ts
View File

@ -124,9 +124,13 @@ export function zoneSchedulerFactory(ngZone: NgZone): (fn: () => void) => void {
* providers of `@angular/core` dependencies that `ApplicationRef` needs
* to bootstrap components.
*
* 为应用配置根注入器，它带有 `ApplicationRef` 在引导组件时所需的来自 `@angular/core` 的提供者。
*
* Re-exported by `BrowserModule`, which is included automatically in the root
* `AppModule` when you create a new app with the CLI `new` command.
*
* 由 `BrowserModule` 重新导出，当你使用 CLI `new` 命令创建新应用时，它会自动包含在根 `AppModule` 中。
*
* @publicApi
*/
@NgModule({providers: APPLICATION_MODULE_PROVIDERS})

80
packages/core/src/application_ref.ts
View File

@ -130,6 +130,8 @@ export const ALLOW_MULTIPLE_PLATFORMS = new InjectionToken<boolean>('AllowMultip
/**
* A token for third-party components that can register themselves with NgProbe.
*
* 本令牌可以在 NgProbe 中注册自己的第三方组件。
*
* @publicApi
*/
export class NgProbeToken {
@ -140,6 +142,8 @@ export class NgProbeToken {
* Creates a platform.
* Platforms must be created on launch using this function.
*
* 创建一个平台。必须使用此函数在启动时创建平台。
*
* @publicApi
*/
export function createPlatform(injector: Injector): PlatformRef {
@ -158,12 +162,23 @@ export function createPlatform(injector: Injector): PlatformRef {
/**
* Creates a factory for a platform. Can be used to provide or override `Providers` specific to
* your applciation's runtime needs, such as `PLATFORM_INITIALIZER` and `PLATFORM_ID`.
*
* 为平台创建工厂。可用于提供或覆盖针对你的应用程序的运行时需求的 `Providers`，比如 `PLATFORM_INITIALIZER` 和 `PLATFORM_ID` 。
*
* @param parentPlatformFactory Another platform factory to modify. Allows you to compose factories
* to build up configurations that might be required by different libraries or parts of the
* application.
*
* 要修改的另一个平台工厂。允许你组合多个工厂来构建一些配置，其它库或应用程序的其它部分可能需要的它们。
*
* @param name Identifies the new platform factory.
*
* 标识新的平台工厂。
*
* @param providers A set of dependency providers for platforms created with the new factory.
*
* 使用新工厂创建的平台的一组依赖项提供者。
*
* @publicApi
*/
export function createPlatformFactory(
@ -193,6 +208,8 @@ export function createPlatformFactory(
/**
* Checks that there is currently a platform that contains the given token as a provider.
*
* 检查当前是否存在以给定令牌为提供者的平台。
*
* @publicApi
*/
export function assertPlatform(requiredToken: any): PlatformRef {
@ -214,6 +231,8 @@ export function assertPlatform(requiredToken: any): PlatformRef {
* Destroys the current Angular platform and all Angular applications on the page.
* Destroys all modules and listeners registered with the platform.
*
* 销毁页面上的当前 Angular 平台和所有 Angular 应用程序。销毁在平台上注册的所有模块和监听器。
*
* @publicApi
*/
export function destroyPlatform(): void {
@ -225,6 +244,8 @@ export function destroyPlatform(): void {
/**
* Returns the current platform.
*
* 返回当前平台。
*
* @publicApi
*/
export function getPlatform(): PlatformRef|null {
@ -294,6 +315,8 @@ export interface BootstrapOptions {
* A page's platform is initialized implicitly when a platform is created using a platform
* factory such as `PlatformBrowser`, or explicitly by calling the `createPlatform()` function.
*
* Angular 平台是 Angular 在网页上的入口点。每个页面只有一个平台。页面上运行的每个 Angular 应用程序所共有的服务（例如反射）都在其范围内绑定。当使用 `PlatformBrowser` 这样的平台工厂创建平台时，将隐式初始化此页面的平台；也可以通过调用 `createPlatform()` 函数来显式初始化此页面的平台。
*
* @publicApi
*/
@Injectable()
@ -308,10 +331,14 @@ export class PlatformRef {
/**
* Creates an instance of an `@NgModule` for the given platform for offline compilation.
*
* 为给定的平台创建 `@NgModule` 的实例，以进行离线编译。
*
* @usageNotes
*
* The following example creates the NgModule for a browser platform.
*
* 以下示例为浏览器平台创建 NgModule。
*
* ```typescript
* my_module.ts:
*
@ -375,9 +402,14 @@ export class PlatformRef {
/**
* Creates an instance of an `@NgModule` for a given platform using the given runtime compiler.
*
* 使用给定的运行时编译器为给定的平台创建 `@NgModule` 的实例。
*
* @usageNotes
*
* ### Simple Example
*
* ### 简单的例子
*
* ```typescript
* @NgModule({
* imports: [BrowserModule]
@ -416,6 +448,9 @@ export class PlatformRef {
/**
* Registers a listener to be called when the platform is destroyed.
*
* 注册销毁平台时要调用的监听器。
*
*/
onDestroy(callback: () => void): void {
this._destroyListeners.push(callback);
@ -424,6 +459,9 @@ export class PlatformRef {
/**
* Retrieves the platform {@link Injector}, which is the parent injector for
* every Angular application on the page and provides singleton providers.
*
* 检索平台 {@link Injector}，该平台是页面上每个 Angular 应用程序的父注入器，并提供单例提供者。
*
*/
get injector(): Injector {
return this._injector;
@ -432,6 +470,9 @@ export class PlatformRef {
/**
* Destroys the current Angular platform and all Angular applications on the page.
* Destroys all modules and listeners registered with the platform.
*
* 销毁页面上的当前 Angular 平台和所有 Angular 应用程序。销毁在平台上注册的所有模块和监听器。
*
*/
destroy() {
if (this._destroyed) {
@ -496,6 +537,8 @@ function optionsReducer<T extends Object>(dst: any, objs: T|T[]): T {
/**
* A reference to an Angular application running on a page.
*
* 对页面上运行的 Angular 应用程序的引用。
*
* @usageNotes
*
* {@a is-stable-examples}
@ -598,18 +641,29 @@ export class ApplicationRef {
/**
* Get a list of component types registered to this application.
* This list is populated even before the component is created.
*
* 获取注册到该应用程序的组件类型的列表。在创建组件之前，会填充此列表。
*
*/
public readonly componentTypes: Type<any>[] = [];
/**
* Get a list of components registered to this application.
*
* 获取已注册到该应用中的组件的列表。
*
*/
public readonly components: ComponentRef<any>[] = [];
/**
* Returns an Observable that indicates when the application is stable or unstable.
*
* 返回一个 Observable，指示应用程序何时变得稳定或不稳定。
*
* @see [Usage notes](#is-stable-examples) for examples and caveats when using this API.
*
* [用法说明](#is-stable-examples)的例子和使用此 API 时的注意事项。
*
*/
// TODO(issue/24571): remove '!'.
public readonly isStable!: Observable<boolean>;
@ -682,17 +736,29 @@ export class ApplicationRef {
/**
* Bootstrap a new component at the root level of the application.
*
* 在应用程序的根级引导新组件。
*
* @usageNotes
*
* ### Bootstrap process
*
* ### 引导过程
*
* When bootstrapping a new root component into an application, Angular mounts the
* specified application component onto DOM elements identified by the componentType's
* selector and kicks off automatic change detection to finish initializing the component.
*
* 将新的根组件引导到应用程序时，Angular 将指定的应用程序组件安装到由 componentType 的选择器标识的 DOM 元素上，并启动自动变更检测以完成组件的初始化。
*
* Optionally, a component can be mounted onto a DOM element that does not match the
* componentType's selector.
*
* （可选）可以将组件安装到与 componentType 的选择器不匹配的 DOM 元素上。
*
* ### Example
*
* ### 例子
*
* {@example core/ts/platform/platform.ts region='longform'}
*/
bootstrap<C>(componentOrFactory: ComponentFactory<C>|Type<C>, rootSelectorOrNode?: string|any):
@ -736,12 +802,17 @@ export class ApplicationRef {
/**
* Invoke this method to explicitly process change detection and its side-effects.
*
* 调用此方法可以显式处理变更检测及其副作用。
*
* In development mode, `tick()` also performs a second change detection cycle to ensure that no
* further changes are detected. If additional changes are picked up during this second cycle,
* bindings in the app have side-effects that cannot be resolved in a single change detection
* pass.
* In this case, Angular throws an error, since an Angular application can only have one change
* detection pass during which all change detection must complete.
*
* 在开发模式下，`tick()` 还会执行第二个变更检测周期，以确保没有检测到其他更改。如果在第二个周期内获取了其他更改，则应用程序中的绑定就会产生副作用，这些副作用无法通过一次变更检测过程解决。在这种情况下，Angular 就会引发错误，因为 Angular 应用程序只能进行一次变更检测遍历，在此过程中必须完成所有变更检测。
*
*/
tick(): void {
if (this._runningTick) {
@ -770,6 +841,9 @@ export class ApplicationRef {
* Attaches a view so that it will be dirty checked.
* The view will be automatically detached when it is destroyed.
* This will throw if the view is already attached to a ViewContainer.
*
* 附加视图，以便对其进行脏检查。视图销毁后将自动分离。如果视图已附加到 ViewContainer，则会抛出此错误。
*
*/
attachView(viewRef: ViewRef): void {
const view = (viewRef as InternalViewRef);
@ -779,6 +853,9 @@ export class ApplicationRef {
/**
* Detaches a view from dirty checking again.
*
* 再次从脏检查中分离视图。
*
*/
detachView(viewRef: ViewRef): void {
const view = (viewRef as InternalViewRef);
@ -809,6 +886,9 @@ export class ApplicationRef {
/**
* Returns the number of attached views.
*
* 返回已附加视图的数量。
*
*/
get viewCount() {
return this._views.length;

20
packages/core/src/application_tokens.ts
View File

@ -15,10 +15,14 @@ import {ComponentRef} from './linker/component_factory';
* primarily for prefixing application attributes and CSS styles when
* {@link ViewEncapsulation#Emulated ViewEncapsulation.Emulated} is being used.
*
* 表示唯一字符串 ID 的 [DI 令牌](guide/glossary#di-token "DI 令牌定义")，主要用于在使用 {@link ViewEncapsulation#Emulated ViewEncapsulation.Emulated} 时为应用程序属性和 CSS 样式添加前缀。
*
* BY default, the value is randomly generated and assigned to the application by Angular.
* To provide a custom ID value, use a DI provider <!-- TODO: provider --> to configure
* the root {@link Injector} that uses this token.
*
* 默认情况下，该值是随机生成的，并且由 Angular 赋值给此应用。要提供一个自定义的 ID 值，可以使用一个 DI 提供者，根 {@link Injector} 会使用此令牌。
*
* @publicApi
*/
export const APP_ID = new InjectionToken<string>('AppId');
@ -29,6 +33,9 @@ export function _appIdRandomProviderFactory() {
/**
* Providers that generate a random `APP_ID_TOKEN`.
*
* 生成随机 `APP_ID_TOKEN` 的提供者。
*
* @publicApi
*/
export const APP_ID_RANDOM_PROVIDER = {
@ -43,12 +50,18 @@ function _randomChar(): string {
/**
* A function that is executed when a platform is initialized.
*
* 平台初始化时执行的函数。
*
* @publicApi
*/
export const PLATFORM_INITIALIZER = new InjectionToken<Array<() => void>>('Platform Initializer');
/**
* A token that indicates an opaque platform ID.
*
* 标识不透明平台 ID 的令牌。
*
* @publicApi
*/
export const PLATFORM_ID = new InjectionToken<Object>('Platform ID');
@ -57,8 +70,12 @@ export const PLATFORM_ID = new InjectionToken<Object>('Platform ID');
* A [DI token](guide/glossary#di-token "DI token definition") that provides a set of callbacks to
* be called for every component that is bootstrapped.
*
* 一个 [DI 令牌](guide/glossary#di-token "DI 令牌定义")，该令牌提供了一组针对每个要引导的组件调用的回调。
*
* Each callback must take a `ComponentRef` instance and return nothing.
*
* 每个回调都必须接受 `ComponentRef` 实例，并且不返回任何内容。
*
* `(componentRef: ComponentRef) => void`
*
* @publicApi
@ -69,6 +86,9 @@ export const APP_BOOTSTRAP_LISTENER =
/**
* A [DI token](guide/glossary#di-token "DI token definition") that indicates the root directory of
* the application
*
* 一个 [DI 令牌](guide/glossary#di-token "DI 令牌定义")，指示应用程序的根目录
*
* @publicApi
*/
export const PACKAGE_ROOT_URL = new InjectionToken<string>('Application Packages Root URL');

3
packages/core/src/change_detection/change_detection_util.ts
View File

@ -50,6 +50,9 @@ export function devModeEqual(a: any, b: any): boolean {
*
* @publicApi
* @deprecated from v10 stop using. (No replacement, deemed unnecessary.)
*
* 从 v10 开始停止使用。 （无替代品，没必要。）
*
*/
export class WrappedValue {
/** @deprecated from 5.3, use `unwrap()` instead - will switch to protected

18
packages/core/src/change_detection/change_detector_ref.ts
View File

@ -25,14 +25,20 @@ const SWITCH_CHANGE_DETECTOR_REF_FACTORY: typeof injectChangeDetectorRef =
* Use the methods to add and remove views from the tree, initiate change-detection,
* and explicitly mark views as _dirty_, meaning that they have changed and need to be re-rendered.
*
* @see [Using change detection hooks](guide/lifecycle-hooks#using-change-detection-hooks)
* @see [Defining custom change detection](guide/lifecycle-hooks#defining-custom-change-detection)
*
* Angular 各种视图的基础类，提供变更检测功能。
* 变更检测树会收集要检查的所有视图。
* 使用这些方法从树中添加或移除视图、初始化变更检测并显式地把这些视图标记为*脏的*，意思是它们变了、需要重新渲染。
*
* @usageNotes
* @see [Using change detection hooks](guide/lifecycle-hooks#using-change-detection-hooks)
*
* [使用变更检测钩子](guide/lifecycle-hooks#using-change-detection-hooks)
*
* @see [Defining custom change detection](guide/lifecycle-hooks#defining-custom-change-detection)
*
* [定义自定义变更检测](guide/lifecycle-hooks#defining-custom-change-detection)
*
*
*@usageNotes
*
* The following examples demonstrate how to modify default change-detection behavior
* to perform explicit detection when needed.
@ -171,6 +177,8 @@ export abstract class ChangeDetectorRef {
/**
* This marker is need so that the JIT compiler can correctly identify this class as special.
*
* 使用此标记，以便 JIT 编译器可以正确地将此类标识为特殊类。
*
* @internal
* @nocollapse
*/
@ -208,4 +216,4 @@ function createViewRef(tNode: TNode, lView: LView, isPipe: boolean): ChangeDetec
return new R3_ViewRef(hostComponentView, lView);
}
return null!;
}
}

10
packages/core/src/change_detection/constants.ts
View File

@ -11,8 +11,12 @@
* The strategy that the default change detector uses to detect changes.
* When set, takes effect the next time change detection is triggered.
*
* 默认变更检测器用来检测更改的策略。设置后，将在下次触发变更检测时生效。
*
* @see {@link ChangeDetectorRef#usage-notes Change detection usage}
*
* {@link ChangeDetectorRef#usage-notes 变更检测的用法}
*
* @publicApi
*/
export enum ChangeDetectionStrategy {
@ -21,12 +25,18 @@ export enum ChangeDetectionStrategy {
* until reactivated by setting the strategy to `Default` (`CheckAlways`).
* Change detection can still be explicitly invoked.
* This strategy applies to all child directives and cannot be overridden.
*
* 使用 `CheckOnce` 策略，这意味着把此策略设置为 `Default`（ `CheckAlways` ）将禁用自动变更检测，直到重新激活。变更检测仍然可以显式调用。此策略适用于所有子指令，并且不能被覆盖。
*
*/
OnPush = 0,
/**
* Use the default `CheckAlways` strategy, in which change detection is automatic until
* explicitly deactivated.
*
* 使用默认的 `CheckAlways` 策略，在该策略中，变更检测将自动执行，直到显式停用为止。
*
*/
Default = 1,
}

70
packages/core/src/change_detection/differs/default_iterable_differ.ts
View File

@ -27,6 +27,9 @@ const trackByIdentity = (index: number, item: any) => item;
/**
* @deprecated v4.0.0 - Should not be part of public API.
*
* v4.0.0-不应成为公共 API 的一部分。
*
* @publicApi
*/
export class DefaultIterableDiffer<V> implements IterableDiffer<V>, IterableChanges<V> {
@ -231,6 +234,8 @@ export class DefaultIterableDiffer<V> implements IterableDiffer<V>, IterableChan
* Set the previousIndexes of moved and added items to their currentIndexes
* Reset the list of additions, moves and removals
*
* 重置更改对象的状态以便不显示任何更改。这意味着将 previousKey 设置为 currentKey，并清除所有队列（添加、移动、移除）。将已移动和已添加条目的 previousIndexes 设置为其 currentIndexes。重置包含添加、移动和删除的列表
*
* @internal
*/
_reset() {
@ -261,11 +266,21 @@ export class DefaultIterableDiffer<V> implements IterableDiffer<V>, IterableChan
/**
* This is the core function which handles differences between collections.
*
* 这是处理集合之间差异的核心函数。
*
* - `record` is the record which we saw at this position last time. If null then it is a new
* item.
*
* `record` 是我们上次在此位置看到的记录。如果为 null，则为新条目。
*
* - `item` is the current item in the collection
*
* `item` 是集合中的当前条目
*
* - `index` is the position of the item in the collection
*
* `index` 是条目在集合中的位置
*
* @internal
*/
_mismatch(record: IterableChangeRecord_<V>|null, item: V, itemTrackBy: any, index: number):
@ -310,20 +325,51 @@ export class DefaultIterableDiffer<V> implements IterableDiffer<V>, IterableChan
/**
* This check is only needed if an array contains duplicates. (Short circuit of nothing dirty)
*
* 仅当数组包含重复项时才需要进行此检查。 （不脏时跳过）
*
* Use case: `[a, a]` => `[b, a, a]`
*
* 用例： `[a, a]` => `[b, a, a]`
*
* If we did not have this check then the insertion of `b` would:
* 1) evict first `a`
* 2) insert `b` at `0` index.
* 3) leave `a` at index `1` as is. <-- this is wrong!
* 3) reinsert `a` at index 2. <-- this is wrong!
*
* 如果我们不做这项检查，则插入 `b` 时会：
*
* 1. evict first `a`
*
* 移出第一个 `a`
*
* 1. insert `b` at `0` index.
*
* 把 `b` 插入在 `0` 号索引处。
*
* 1. leave `a` at index `1` as is. &lt;-- this is wrong!
*
* 把 `a` 留在现在的 `1` 号索引处。&lt;-- 这是错的！
*
* 1. reinsert `a` at index 2. &lt;-- this is wrong!
*
* 重新把 `a` 插入在 `2` 号索引处。 &lt;-- 这是错的！
*
* The correct behavior is:
* 1) evict first `a`
* 2) insert `b` at `0` index.
* 3) reinsert `a` at index 1.
* 3) move `a` at from `1` to `2`.
*
* 正确的行为是：
*
* 1. evict first `a`
*
* 移出第一个 `a`
*
* 1. insert `b` at `0` index.
*
* 把 `b` 插入在 `0` 号索引处。
*
* 1. reinsert `a` at index 1.
*
* 把 `a` 插入在 `1` 号索引处。
*
* 1. move `a` at from `1` to `2`.
*
* 把 `a` 从 `1` 号位移到 `2` 号位。
*
* Double check that we have not evicted a duplicate item. We need to check if the item type may
* have already been removed:
@ -332,6 +378,8 @@ export class DefaultIterableDiffer<V> implements IterableDiffer<V>, IterableChan
* better way to think of it is as insert of 'b' rather then switch 'a' with 'b' and then add 'a'
* at the end.
*
* 再次确认我们没有移出重复的条目。我们需要检查此条目类型是否已被删除：插入 b 将移出第一个 “a”。如果我们现在不重新插入，它将重新在最后插入。这将表现为两个 “a” 调换了位置。这是不正确的，因为更好的方法是插入 “b”，而不是将 “a” 和 “b” 互换，然后在末尾添加 “a”。
*
* @internal
*/
_verifyReinsertion(record: IterableChangeRecord_<V>, item: V, itemTrackBy: any, index: number):
@ -350,7 +398,11 @@ export class DefaultIterableDiffer<V> implements IterableDiffer<V>, IterableChan
/**
* Get rid of any excess {@link IterableChangeRecord_}s from the previous collection
*
* - `record` The first excess {@link IterableChangeRecord_}.
* 摆脱上一个集合中任何多余的 {@link IterableChangeRecord_}
*
* - `record` The first excess {@link IterableChangeRecord\_}.
*
* `record` 是指第一个多余的{@link IterableChangeRecord\_}。
*
* @internal
*/

103
packages/core/src/change_detection/differs/iterable_differs.ts
View File

@ -16,6 +16,8 @@ import {DefaultIterableDifferFactory} from '../differs/default_iterable_differ';
/**
* A type describing supported iterable types.
*
* 描述受支持的可迭代类型的类型。
*
* @publicApi
*/
export type NgIterable<T> = Array<T>|Iterable<T>;
@ -24,15 +26,25 @@ export type NgIterable<T> = Array<T>|Iterable<T>;
* A strategy for tracking changes over time to an iterable. Used by {@link NgForOf} to
* respond to changes in an iterable by effecting equivalent changes in the DOM.
*
* 用来跟踪一个迭代内的更改的策略。{@link NgForOf} 使用它通过对 DOM 进行等效更改来响应此迭代内的更改。
*
* @publicApi
*/
export interface IterableDiffer<V> {
/**
* Compute a difference between the previous state and the new `object` state.
*
* 计算先前状态和新 `object` 状态之间的差异。
*
* @param object containing the new value.
*
* 包含新值。
*
* @returns an object describing the difference. The return value is only valid until the next
* `diff()` invocation.
*
* 描述差异的对象。返回值仅在下一次 `diff()` 调用之前有效。
*
*/
diff(object: NgIterable<V>|undefined|null): IterableChanges<V>|null;
}
@ -41,12 +53,17 @@ export interface IterableDiffer<V> {
* An object describing the changes in the `Iterable` collection since last time
* `IterableDiffer#diff()` was invoked.
*
* 本对象描述自上次调用 `IterableDiffer#diff()` 以来 `Iterable` 集合中的变更。
*
* @publicApi
*/
export interface IterableChanges<V> {
/**
* Iterate over all changes. `IterableChangeRecord` will contain information about changes
* to each item.
*
* 遍历所有更改。`IterableChangeRecord` 将包含有关每个条目更改的信息。
*
*/
forEachItem(fn: (record: IterableChangeRecord<V>) => void): void;
@ -54,17 +71,30 @@ export interface IterableChanges<V> {
* Iterate over a set of operations which when applied to the original `Iterable` will produce the
* new `Iterable`.
*
* 遍历一组操作，将这些操作应用于原始 `Iterable`，将产生新的 `Iterable` 。
*
* NOTE: These are not necessarily the actual operations which were applied to the original
* `Iterable`, rather these are a set of computed operations which may not be the same as the
* ones applied.
*
* 注意：这些不一定是应用于原始 `Iterable` 的实际操作，而是这些计算的操作集合，可能与所应用的操作不同。
*
* @param record A change which needs to be applied
*
* 需要应用的更改
*
* @param previousIndex The `IterableChangeRecord#previousIndex` of the `record` refers to the
* original `Iterable` location, where as `previousIndex` refers to the transient location
* of the item, after applying the operations up to this point.
*
* 此 `record` 的 `IterableChangeRecord#previousIndex` 是指原来 `Iterable` 中的位置，这个 `previousIndex` 是指应用此操作之后条目的瞬时位置。
*
* @param currentIndex The `IterableChangeRecord#currentIndex` of the `record` refers to the
* original `Iterable` location, where as `currentIndex` refers to the transient location
* of the item, after applying the operations up to this point.
*
* 此 `record` 的 `IterableChangeRecord#currentIndex` 是指原来 `Iterable` 中的位置，这个 `currentIndex` 是指应用此操作之后条目的瞬时位置。
*
*/
forEachOperation(
fn:
@ -74,21 +104,42 @@ export interface IterableChanges<V> {
/**
* Iterate over changes in the order of original `Iterable` showing where the original items
* have moved.
*
* 按原始 `Iterable` 中的顺序遍历这些变更，以找出原始条目移动到的位置。
*
*/
forEachPreviousItem(fn: (record: IterableChangeRecord<V>) => void): void;
/** Iterate over all added items. */
/**
* Iterate over all added items.
*
* 遍历所有添加的条目。
*
*/
forEachAddedItem(fn: (record: IterableChangeRecord<V>) => void): void;
/** Iterate over all moved items. */
/**
* Iterate over all moved items.
*
* 遍历所有移动过的条目。
*
*/
forEachMovedItem(fn: (record: IterableChangeRecord<V>) => void): void;
/** Iterate over all removed items. */
/**
* Iterate over all removed items.
*
* 遍历所有已删除的条目。
*
*/
forEachRemovedItem(fn: (record: IterableChangeRecord<V>) => void): void;
/**
* Iterate over all items which had their identity (as computed by the `TrackByFunction`)
* changed.
*
* 遍历所有更改过标识（由 `TrackByFunction` 计算）的条目。
*
*/
forEachIdentityChange(fn: (record: IterableChangeRecord<V>) => void): void;
}
@ -96,19 +147,41 @@ export interface IterableChanges<V> {
/**
* Record representing the item change information.
*
* 代表条目变更信息的记录。
*
* @publicApi
*/
export interface IterableChangeRecord<V> {
/** Current index of the item in `Iterable` or null if removed. */
/**
* Current index of the item in `Iterable` or null if removed.
*
* 此条目在 `Iterable` 中的当前索引，如果已删除则为 null。
*
*/
readonly currentIndex: number|null;
/** Previous index of the item in `Iterable` or null if added. */
/**
* Previous index of the item in `Iterable` or null if added.
*
* 此条目在 `Iterable` 中以前的索引，如果是新添加的则为 null。
*
*/
readonly previousIndex: number|null;
/** The item. */
/**
* The item.
*
* 本条目。
*
*/
readonly item: V;
/** Track by identity as computed by the `TrackByFunction`. */
/**
* Track by identity as computed by the `TrackByFunction`.
*
* 通过 `TrackByFunction` 计算出的标识进行跟踪。
*
*/
readonly trackById: any;
}
@ -118,6 +191,8 @@ export interface IterableChangeRecord<V> {
* The function takes the iteration index and item ID.
* When supplied, Angular tracks changes by the return value of the function.
*
* 传给 `NgForOf` 指令的可选函数，该函数定义如何跟踪可迭代对象中条目的更改。该函数接受迭代索引和条目 ID 作为参数。提供后，Angular 将根据函数的返回值的变化进行跟踪。
*
* @publicApi
*/
export interface TrackByFunction<T> {
@ -127,6 +202,8 @@ export interface TrackByFunction<T> {
/**
* Provides a factory for {@link IterableDiffer}.
*
* 提供 {@link IterableDiffer} 的工厂。
*
* @publicApi
*/
export interface IterableDifferFactory {
@ -137,6 +214,8 @@ export interface IterableDifferFactory {
/**
* A repository of different iterable diffing strategies used by NgFor, NgClass, and others.
*
* NgFor、NgClass 等使用的不同迭代策略的存储库。
*
* @publicApi
*/
export class IterableDiffers {
@ -149,6 +228,9 @@ export class IterableDiffers {
/**
* @deprecated v4.0.0 - Should be private
*
* v4.0.0-应该是私有的
*
*/
factories: IterableDifferFactory[];
constructor(factories: IterableDifferFactory[]) {
@ -169,13 +251,20 @@ export class IterableDiffers {
* inherited {@link IterableDiffers} instance with the provided factories and return a new
* {@link IterableDiffers} instance.
*
* 接受一个 {@link IterableDifferFactory} 数组，并返回一个提供者，用于扩展继承的带有提供者工厂的 {@link IterableDiffers} 实例，并返回一个新的 {@link IterableDiffers} 实例。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* The following example shows how to extend an existing list of factories,
* which will only be applied to the injector for this component and its children.
* This step is all that's required to make a new {@link IterableDiffer} available.
*
* 以下示例演示了如何扩展现有工厂列表，该列表仅适用于该组件及其子组件的注入器。这就是使新的 {@link IterableDiffer} 可用的全部步骤。
*
* ```
* @Component({
* viewProviders: [

66
packages/core/src/change_detection/differs/keyvalue_differs.ts
View File

@ -13,24 +13,42 @@ import {DefaultKeyValueDifferFactory} from './default_keyvalue_differ';
/**
* A differ that tracks changes made to an object over time.
*
* 跟踪对象随时间变化的差异。
*
* @publicApi
*/
export interface KeyValueDiffer<K, V> {
/**
* Compute a difference between the previous state and the new `object` state.
*
* 计算先前状态和新 `object` 状态之间的差异。
*
* @param object containing the new value.
*
* 包含新值。
*
* @returns an object describing the difference. The return value is only valid until the next
* `diff()` invocation.
*
* 描述差异的对象。返回值仅在下一次 `diff()` 调用之前有效。
*
*/
diff(object: Map<K, V>): KeyValueChanges<K, V>|null;
/**
* Compute a difference between the previous state and the new `object` state.
*
* 计算先前状态和新 `object` 状态之间的差异。
*
* @param object containing the new value.
*
* 包含新值。
*
* @returns an object describing the difference. The return value is only valid until the next
* `diff()` invocation.
*
* 描述差异的对象。返回值仅在下一次 `diff()` 调用之前有效。
*
*/
diff(object: {[key: string]: V}): KeyValueChanges<string, V>|null;
// TODO(TS2.1): diff<KP extends string>(this: KeyValueDiffer<KP, V>, object: Record<KP, V>):
@ -41,33 +59,50 @@ export interface KeyValueDiffer<K, V> {
* An object describing the changes in the `Map` or `{[k:string]: string}` since last time
* `KeyValueDiffer#diff()` was invoked.
*
* 一个对象，描述自上次调用 `KeyValueDiffer#diff()` 以来的变化的 `Map` 或 `{[k:string]: string}`。
*
* @publicApi
*/
export interface KeyValueChanges<K, V> {
/**
* Iterate over all changes. `KeyValueChangeRecord` will contain information about changes
* to each item.
*
* 遍历所有更改。`KeyValueChangeRecord` 将包含有关每个条目更改的信息。
*
*/
forEachItem(fn: (r: KeyValueChangeRecord<K, V>) => void): void;
/**
* Iterate over changes in the order of original Map showing where the original items
* have moved.
*
* 按照原始映射表中的顺序遍历更改，以显示原始条目移动过的位置。
*
*/
forEachPreviousItem(fn: (r: KeyValueChangeRecord<K, V>) => void): void;
/**
* Iterate over all keys for which values have changed.
*
* 遍历所有更改了值的键名。
*
*/
forEachChangedItem(fn: (r: KeyValueChangeRecord<K, V>) => void): void;
/**
* Iterate over all added items.
*
* 遍历所有已添加的条目。
*
*/
forEachAddedItem(fn: (r: KeyValueChangeRecord<K, V>) => void): void;
/**
* Iterate over all removed items.
*
* 遍历所有已删除的条目。
*
*/
forEachRemovedItem(fn: (r: KeyValueChangeRecord<K, V>) => void): void;
}
@ -75,21 +110,32 @@ export interface KeyValueChanges<K, V> {
/**
* Record representing the item change information.
*
* 代表条目变更信息的记录。
*
* @publicApi
*/
export interface KeyValueChangeRecord<K, V> {
/**
* Current key in the Map.
*
* 地图中的当前键名。
*
*/
readonly key: K;
/**
* Current value for the key or `null` if removed.
*
* 键名的当前值；如果已删除，则为 `null`
*
*/
readonly currentValue: V|null;
/**
* Previous value for the key or `null` if added.
*
* 键名的先前值；如果是添加的，则为 `null`
*
*/
readonly previousValue: V|null;
}
@ -97,16 +143,24 @@ export interface KeyValueChangeRecord<K, V> {
/**
* Provides a factory for {@link KeyValueDiffer}.
*
* 提供 {@link KeyValueDiffer} 的工厂。
*
* @publicApi
*/
export interface KeyValueDifferFactory {
/**
* Test to see if the differ knows how to diff this kind of object.
*
* 测试看此差分器是否知道如何区分这种对象。
*
*/
supports(objects: any): boolean;
/**
* Create a `KeyValueDiffer`.
*
* 创建一个 `KeyValueDiffer` 。
*
*/
create<K, V>(): KeyValueDiffer<K, V>;
}
@ -114,6 +168,8 @@ export interface KeyValueDifferFactory {
/**
* A repository of different Map diffing strategies used by NgClass, NgStyle, and others.
*
* NgClass、NgStyle 等使用的不同映射表差异策略的存储库。
*
* @publicApi
*/
export class KeyValueDiffers {
@ -126,6 +182,9 @@ export class KeyValueDiffers {
/**
* @deprecated v4.0.0 - Should be private.
*
* v4.0.0-应该是私有的。
*
*/
factories: KeyValueDifferFactory[];
@ -146,13 +205,20 @@ export class KeyValueDiffers {
* inherited {@link KeyValueDiffers} instance with the provided factories and return a new
* {@link KeyValueDiffers} instance.
*
* 接受 {@link KeyValueDifferFactory} 的数组，并返回一个提供者，用于使用提供的工厂扩展所继承的 {@link KeyValueDiffers} 实例，并返回一个新的 {@link KeyValueDiffers} 实例。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* The following example shows how to extend an existing list of factories,
* which will only be applied to the injector for this component and its children.
* This step is all that's required to make a new {@link KeyValueDiffer} available.
*
* 以下示例显示如何扩展现有工厂列表，该列表仅适用于该组件及其子组件的注入器。这是使新的{@link KeyValueDiffer}可用的全部步骤。
*
* ```
* @Component({
* viewProviders: [

2
packages/core/src/debug/debug_node.ts
View File

@ -776,6 +776,8 @@ export function removeDebugNodeFromIndex(node: DebugNode) {
* A boolean-valued function over a value, possibly including context information
* regarding that value's position in an array.
*
* 根据参数值返回布尔值的函数，可能包括该值在数组中位置的上下文信息。
*
* @publicApi
*/
export interface Predicate<T> {

20
packages/core/src/di/forward_ref.ts
View File

@ -15,9 +15,14 @@ import {stringify} from '../util/stringify';
/**
* An interface that a function passed into {@link forwardRef} has to implement.
*
* 要传给 {@link forwardRef} 的函数时必须实现的接口。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* {@example core/di/ts/forward_ref/forward_ref_spec.ts region='forward_ref_fn'}
* @publicApi
*/
@ -30,12 +35,20 @@ const __forward_ref__ = getClosureSafeProperty({__forward_ref__: getClosureSafeP
/**
* Allows to refer to references which are not yet defined.
*
* 允许引用尚未定义的引用。
*
* For instance, `forwardRef` is used when the `token` which we need to refer to for the purposes of
* DI is declared, but not yet defined. It is also used when the `token` which we use when creating
* a query is not yet defined.
*
* 例如，当我们需要为所声明的 DI 而引用此 `token`，但尚未定义该令牌时，将使用 `forwardRef`。当我们创建尚未定义的查询的 `token` 时，也会使用它。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* {@example core/di/ts/forward_ref/forward_ref_spec.ts region='forward_ref'}
* @publicApi
*/
@ -50,11 +63,18 @@ export function forwardRef(forwardRefFn: ForwardRefFn): Type<any> {
/**
* Lazily retrieves the reference value from a forwardRef.
*
* 从 forwardRef 惰性检索引用值。
*
* Acts as the identity function when given a non-forward-ref value.
*
* 给定非前向引用值时，充当标识函数。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* {@example core/di/ts/forward_ref/forward_ref_spec.ts region='resolve_forward_ref'}
*
* @see `forwardRef`

19
packages/core/src/di/injectable.ts
View File

@ -19,7 +19,7 @@ import {convertInjectableProviderToFactory} from './util';
/**
* Injectable providers used in `@Injectable` decorator.
*
* `@Injectable` 装饰器中使用的可注入对象提供商。
* `@Injectable` 装饰器中使用的可注入对象提供者。
*
* @publicApi
*/
@ -41,14 +41,21 @@ export interface InjectableDecorator {
* 标记性元数据，表示一个类可以由 `Injector` 进行创建。
*
* @see [Introduction to Services and DI](guide/architecture-services)
*
* [服务和 DI 简介](guide/architecture-services)
*
* @see [Dependency Injection Guide](guide/dependency-injection)
*
* [依赖注入指南](guide/dependency-injection)
*
* @usageNotes
*
* Marking a class with `@Injectable` ensures that the compiler
* will generate the necessary metadata to create the class's
* dependencies when the class is injected.
*
* 使用 `@Injectable` 标记一个类可确保编译器将在注入类时生成必要的元数据，以创建类的依赖项。
*
* The following example shows how a service class is properly
* marked so that a supporting service can be injected upon creation.
*
@ -77,12 +84,22 @@ export interface Injectable {
* Determines which injectors will provide the injectable,
* by either associating it with an `@NgModule` or other `InjectorType`,
* or by specifying that this injectable should be provided in one of the following injectors:
*
* 通过与 `@NgModule` 或其他 `InjectorType` 关联，或通过指定应在以下注入器之一中提供此可注入对象，来确定将提供该对象的注入器：
*
* - 'root' : The application-level injector in most apps.
*
* 'root'：在大多数应用程序中是指应用程序级注入器。
*
* - 'platform' : A special singleton platform injector shared by all
* applications on the page.
*
* 'platform' ：页面上所有应用程序共享的平台注入器的特殊单例。
*
* - 'any' : Provides a unique instance in each lazy loaded module while all eagerly loaded
* modules share one instance.
*
* 'any'：在每个惰性加载的模块中提供一个唯一的实例，而所有急性加载的模块共享一个实例。
*/
providedIn?: Type<any>|'root'|'platform'|'any'|null;
}

15
packages/core/src/di/injection_token.ts
View File

@ -14,13 +14,19 @@ import {ɵɵdefineInjectable} from './interface/defs';
/**
* Creates a token that can be used in a DI Provider.
*
* 创建可用于 DI 提供者的令牌。
*
* Use an `InjectionToken` whenever the type you are injecting is not reified (does not have a
* runtime representation) such as when injecting an interface, callable type, array or
* parameterized type.
*
* 每当你要注入的类型无法确定（没有运行时表示形式）时，例如在注入接口、可调用类型、数组或参数化类型时，都应使用 `InjectionToken`。
*
* `InjectionToken` is parameterized on `T` which is the type of object which will be returned by
* the `Injector`. This provides additional level of type safety.
*
* `InjectionToken` 在 `T` 上的参数化版本，`T` 是 `Injector` 返回的对象的类型。这提供了更高级别的类型安全性。
*
* ```
* interface MyInterface {...}
* var myInterface = injector.get(new InjectionToken<MyInterface>('SomeToken'));
@ -33,15 +39,24 @@ import {ɵɵdefineInjectable} from './interface/defs';
* application's root injector. If the factory function, which takes zero arguments, needs to inject
* dependencies, it can do so using the `inject` function. See below for an example.
*
* 当创建 `InjectionToken` 时，可以选择指定一个工厂函数，该函数返回（可能通过创建）参数化类型 `T` 的默认值。这将使用工厂型提供者设置 `InjectionToken`，就像它是在应用程序的根注入器中显式定义的一样。如果使用需要注入依赖项的零参数工厂函数，则可以使用 `inject` 函数来这样做。参见以下示例。
*
* Additionally, if a `factory` is specified you can also specify the `providedIn` option, which
* overrides the above behavior and marks the token as belonging to a particular `@NgModule`. As
* mentioned above, `'root'` is the default value for `providedIn`.
*
* 此外，如果指定了 `factory`，也可以指定 `providedIn` 选项，它会覆盖上述行为，并把这些令牌标记为属于特定 `@NgModule`。如上所述，`'root'` 是 `providedIn` 的默认值。
*
* @usageNotes
*
* ### Basic Example
*
* ### 基本范例
*
* ### Plain InjectionToken
*
* ### 普通注入令牌
*
* {@example core/di/ts/injector_spec.ts region='InjectionToken'}
*
* ### Tree-shakable InjectionToken

40
packages/core/src/di/injector.ts
View File

@ -38,17 +38,26 @@ export const INJECTOR_IMPL = INJECTOR_IMPL__PRE_R3__;
* with [providers](guide/glossary#provider) that associate
* dependencies of various types with [injection tokens](guide/glossary#di-token).
*
* 具体的注入器会实现此接口。配置有[某些提供者](guide/glossary#provider)的注入器，这些提供者会将各种类型的依赖项与[注入令牌](guide/glossary#di-token)相关联。
*
* @see ["DI Providers"](guide/dependency-injection-providers).
*
* [“DI 提供者”](guide/dependency-injection-providers) 。
*
* @see `StaticProvider`
*
* @usageNotes
*
* The following example creates a service injector instance.
*
* 以下示例创建一个服务注入器实例。
*
* {@example core/di/ts/provider_spec.ts region='ConstructorProvider'}
*
* ### Usage example
*
* ### 使用范例
*
* {@example core/di/ts/injector_spec.ts region='Injector'}
*
* `Injector` returns itself when given `Injector` as a token:
@ -63,19 +72,34 @@ export abstract class Injector {
/**
* Retrieves an instance from the injector based on the provided token.
*
* 根据提供的令牌从注入器中检索实例。
*
* @returns The instance from the injector if defined, otherwise the `notFoundValue`.
*
* 注入器的实例（如果已定义），否则为 `notFoundValue` 。
*
* @throws When the `notFoundValue` is `undefined` or `Injector.THROW_IF_NOT_FOUND`.
*
* 当 `notFoundValue` 为 `undefined` 或 `Injector.THROW_IF_NOT_FOUND` 时。
*
*/
abstract get<T>(
token: Type<T>|AbstractType<T>|InjectionToken<T>, notFoundValue?: T, flags?: InjectFlags): T;
/**
* @deprecated from v4.0.0 use Type<T>, AbstractType<T> or InjectionToken<T>
*
* 从 v4.0.0 开始，改用 Type<T>、AbstractType<T> 或 InjectionToken<T>
*
* @suppress {duplicate}
*/
abstract get(token: any, notFoundValue?: any): any;
/**
* @deprecated from v5 use the new signature Injector.create(options)
*
* 从 v5 开始使用新的签名 Injector.create（options）
*
*/
static create(providers: StaticProvider[], parent?: Injector): Injector;
@ -83,13 +107,27 @@ export abstract class Injector {
* Creates a new injector instance that provides one or more dependencies,
* according to a given type or types of `StaticProvider`.
*
* 创建一个新的注入器实例，该实例会根据指定的类型或 `StaticProvider` 的类型提供一个或多个依赖项。
*
* @param options An object with the following properties:
*
* 具有以下属性的对象：
*
* * `providers`: An array of providers of the [StaticProvider type](api/core/StaticProvider).
*
* `providers` ：一组 [StaticProvider 类型](api/core/StaticProvider)的提供者。
*
* * `parent`: (optional) A parent injector.
* * `name`: (optional) A developer-defined identifying name for the new injector.
*
* `parent` ：（可选）父注入器。
*
* - `name`: (optional) A developer-defined identifying name for the new injector.
*
* `name` ：（可选）新注入器的开发人员自定义的标识名称。
*
* @returns The new injector instance.
*
* 新的注入器实例。
*/
static create(options: {providers: StaticProvider[], parent?: Injector, name?: string}): Injector;

25
packages/core/src/di/injector_compatibility.ts
View File

@ -63,13 +63,22 @@ export function injectInjectorOnly<T>(
/**
* Generated instruction: Injects a token from the currently active injector.
*
* 生成的方式：从当前活动的注入器注入令牌。
*
* Must be used in the context of a factory function such as one defined for an
* `InjectionToken`. Throws an error if not called from such a context.
*
* 必须在工厂函数的上下文中使用，比如为 `InjectionToken` 定义的函数。如果未从这样的上下文中调用，则会引发错误。
*
* (Additional documentation moved to `inject`, as it is the public API, and an alias for this
* instruction)
*
* （其他文档移到了 `inject` ，因为它是公共 API，并且是此指令的别名）
*
* @see inject
*
* 注入
*
* @codeGenApi
* @publicApi This instruction has been emitted by ViewEngine for some time and is deployed to npm.
*/
@ -108,23 +117,39 @@ Please check that 1) the type for the parameter at index ${
/**
* Injects a token from the currently active injector.
*
* 从当前活动的注入器中注入令牌。
*
* Must be used in the context of a factory function such as one defined for an
* `InjectionToken`. Throws an error if not called from such a context.
*
* 必须在工厂函数的上下文中使用，比如为 `InjectionToken` 定义的函数。如果未从这样的上下文中调用，则会引发错误。
*
* Within such a factory function, using this function to request injection of a dependency
* is faster and more type-safe than providing an additional array of dependencies
* (as has been common with `useFactory` providers).
*
* 在这样的工厂函数中，使用此函数来请求注入依赖项比提供额外的依赖项数组（在 `useFactory` 提供者中这很常见）要更快且类型安全性更高。
*
* @param token The injection token for the dependency to be injected.
*
* 用于注入依赖项的注入令牌。
*
* @param flags Optional flags that control how injection is executed.
* The flags correspond to injection strategies that can be specified with
* parameter decorators `@Host`, `@Self`, `@SkipSef`, and `@Optional`.
*
* 控制执行注入方式的可选标志。这些标志对应于可以使用参数装饰器 `@Host`、`@Self`、`@SkipSef` 和 `@Optional` 指定的注入策略。
*
* @returns True if injection is successful, null otherwise.
*
* 如果注入成功，则为 true，否则为 null。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* {@example core/di/ts/injector_spec.ts region='ShakableInjectionToken'}
*
* @publicApi

4
packages/core/src/di/injector_token.ts
View File

@ -15,9 +15,13 @@ import {InjectorMarkers} from './injector_marker';
/**
* An InjectionToken that gets the current `Injector` for `createInjector()`-style injectors.
*
* 一个 InjectionToken，用于获取当前 `Injector` 的 `createInjector()` 式的注入器。
*
* Requesting this token instead of `Injector` allows `StaticInjector` to be tree-shaken from a
* project.
*
* 请求此令牌而不是 `Injector` 可使 `StaticInjector` 能在项目中摇树优化掉。
*
* @publicApi
*/
export const INJECTOR = new InjectionToken<Injector>(

61
packages/core/src/di/interface/defs.ts
View File

@ -15,13 +15,19 @@ import {ClassProvider, ConstructorProvider, ExistingProvider, FactoryProvider, S
/**
* Information about how a type or `InjectionToken` interfaces with the DI system.
*
* 有关类型或 `InjectionToken` 如何接入 DI 体系的接口信息。
*
* At a minimum, this includes a `factory` which defines how to create the given type `T`, possibly
* requesting injection of other types if necessary.
*
* 至少，这要包括一个 `factory` ，该工厂定义如何创建给定类型 `T` ，如有必要，可能会请求注入其他类型。
*
* Optionally, a `providedIn` parameter specifies that the given type belongs to a particular
* `InjectorDef`, `NgModule`, or a special scope (e.g. `'root'`). A value of `null` indicates
* that the injectable does not belong to any scope.
*
* 可选的参数 `providedIn` 规定给定的类型属于某个特定的 `InjectorDef`、`NgModule` 还是一个特殊的范围（例如 `'root'`）。如果值为 `null` 表示可注入对象不属于任何范围。
*
* @codeGenApi
* @publicApi The ViewEngine compiler emits code with this type for injectables. This code is
* deployed to npm, and should be treated as public api.
@ -30,28 +36,54 @@ import {ClassProvider, ConstructorProvider, ExistingProvider, FactoryProvider, S
export interface ɵɵInjectableDef<T> {
/**
* Specifies that the given type belongs to a particular injector:
*
* 指定给定类型属于特定的注入器：
*
* - `InjectorType` such as `NgModule`,
*
* `InjectorType` 例如 `NgModule` ，
*
* - `'root'` the root injector
*
* `'root'` 根注入器
*
* - `'any'` all injectors.
*
* `'any'` 所有注入器。
*
* - `null`, does not belong to any injector. Must be explicitly listed in the injector
* `providers`.
*
* `null` ，不属于任何注入器。必须在注入器的 `providers` 列表中显式列出。
*
*/
providedIn: InjectorType<any>|'root'|'platform'|'any'|null;
/**
* The token to which this definition belongs.
*
* 此定义所属的令牌。
*
* Note that this may not be the same as the type that the `factory` will create.
*
* 请注意，这可能与 `factory` 将创建的类型不同。
*
*/
token: unknown;
/**
* Factory method to execute to create an instance of the injectable.
*
* 本工厂方法用于创建可注入实例。
*
*/
factory: (t?: Type<any>) => T;
/**
* In a case of no explicit injector, a location where the instance of the injectable is stored.
*
* 在没有显式注入器的情况下，存储可注入实例的位置。
*
*/
value: T|undefined;
}
@ -82,14 +114,21 @@ export interface ɵɵInjectorDef<T> {
/**
* A `Type` which has an `InjectableDef` static field.
*
* 具有 `InjectableDef` 静态字段的 `Type`
*
* `InjectableDefType`s contain their own Dependency Injection metadata and are usable in an
* `InjectorDef`-based `StaticInjector.
*
* `InjectableDefType` 包含其自己的依赖注入元数据，并且可在基于 `InjectorDef` 的 `StaticInjector` 中使用。
*
* @publicApi
*/
export interface InjectableType<T> extends Type<T> {
/**
* Opaque type whose structure is highly version dependent. Do not rely on any properties.
*
* 不透明类型，其结构高度依赖版本。不要依赖它的任何属性。
*
*/
ɵprov: never;
}
@ -97,13 +136,20 @@ export interface InjectableType<T> extends Type<T> {
/**
* A type which has an `InjectorDef` static field.
*
* 具有 `InjectorDef` 静态字段的类型。
*
* `InjectorDefTypes` can be used to configure a `StaticInjector`.
*
* 可用于配置 `StaticInjector` 的 `InjectorDefTypes`。
*
* @publicApi
*/
export interface InjectorType<T> extends Type<T> {
/**
* Opaque type whose structure is highly version dependent. Do not rely on any properties.
*
* 不透明类型，其结构高度依赖版本。不要依赖它的任何属性。
*
*/
ɵinj: never;
}
@ -127,16 +173,28 @@ export interface InjectorTypeWithProviders<T> {
* Construct an `InjectableDef` which defines how a token will be constructed by the DI system, and
* in which injectors (if any) it will be available.
*
* 构造一个 `InjectableDef` ，它定义 DI 体系将如何构造令牌以及在哪些注入器中可用（如果有的话）。
*
* This should be assigned to a static `ɵprov` field on a type, which will then be an
* `InjectableType`.
*
* 应该将其赋值给静态的 `ɵprov` 字段，然后将其作为 `InjectableType` 。
*
* Options:
*
* 选项：
*
* * `providedIn` determines which injectors will include the injectable, by either associating it
* with an `@NgModule` or other `InjectorType`, or by specifying that this injectable should be
* provided in the `'root'` injector, which will be the application-level injector in most apps.
*
* `providedIn` 决定哪些注入器应该包含此可注入对象：或者将其与 `@NgModule` 关联，或者将其与其他 `InjectorType` 关联，或者指定应该在 `'root'` 注入器（对大多数应用来说这是全应用级注入器）中提供它。
*
* * `factory` gives the zero argument function which will create an instance of the injectable.
* The factory can call `inject` to access the `Injector` and request injection of dependencies.
*
* `factory` 是一个零参数函数，该函数将创建可注入的实例。工厂可以调用 `inject` 来访问 `Injector` 并请求注入依赖项。
*
* @codeGenApi
* @publicApi This instruction has been emitted by ViewEngine for some time and is deployed to npm.
*/
@ -155,6 +213,9 @@ export function ɵɵdefineInjectable<T>(opts: {
/**
* @deprecated in v8, delete after v10. This API should be used only by generated code, and that
* code should now use ɵɵdefineInjectable instead.
*
* 在 v8 中弃用，在 v10 之后删除。此 API 仅应由生成的代码使用，并且该代码现在应改用 ɵɵdefineInjectable。
*
* @publicApi
*/
export const defineInjectable = ɵɵdefineInjectable;

33
packages/core/src/di/interface/injector.ts
View File

@ -10,22 +10,47 @@
/**
* Injection flags for DI.
*
* DI 的注入标志。
*
* @publicApi
*/
export enum InjectFlags {
// TODO(alxhub): make this 'const' when ngc no longer writes exports of it into ngfactory files.
/** Check self and check parent injector if needed */
/**
* Check self and check parent injector if needed
*
* 检查自身并检查父注入器（如果需要）
*
*/
Default = 0b0000,
/**
* Specifies that an injector should retrieve a dependency from any injector until reaching the
* host element of the current component. (Only used with Element Injector)
*
* 指定注入器应从任何注入器中检索依赖项，直到到达当前组件的宿主元素为止。（仅与元素注入器一起使用）
*
*/
Host = 0b0001,
/** Don't ascend to ancestors of the node requesting injection. */
/**
* Don't ascend to ancestors of the node requesting injection.
*
* 不要上升到请求注入的节点的祖先去处理。
*
*/
Self = 0b0010,
/** Skip the node that is requesting injection. */
/**
* Skip the node that is requesting injection.
*
* 跳过请求注入的节点。
*
*/
SkipSelf = 0b0100,
/** Inject `defaultValue` instead if token not found. */
/**
* Inject `defaultValue` instead if token not found.
*
* 如果找不到令牌，则注入 `defaultValue`
*
*/
Optional = 0b1000,
}

124
packages/core/src/di/interface/provider.ts
View File

@ -12,23 +12,35 @@ import {Type} from '../../interface/type';
* Configures the `Injector` to return a value for a token.
* Base for `ValueProvider` decorator.
*
* 配置 `Injector` 以返回令牌的值。是 `ValueProvider` 装饰器的基接口。
*
* @publicApi
*/
export interface ValueSansProvider {
/**
* The value to inject.
*
* 要注入的值。
*
*/
useValue: any;
}
/**
* Configures the `Injector` to return a value for a token.
*
* 配置此 `Injector` 以返回令牌的值。
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* [“依赖注入指南”](guide/dependency-injection) 。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* {@example core/di/ts/provider_spec.ts region='ValueProvider'}
*
* ### Multi-value example
@ -40,12 +52,18 @@ export interface ValueSansProvider {
export interface ValueProvider extends ValueSansProvider {
/**
* An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`.
*
* 注入令牌。通常是 `Type` 或 `InjectionToken` 的实例，但也可以是 `any` 实例。
*
*/
provide: any;
/**
* When true, injector returns an array of instances. This is useful to allow multiple
* providers spread across many files to provide configuration information to a common token.
*
* 如果为 true，则注入器返回实例数组。这对于允许多个提供者散布在多个文件中以向公共令牌提供配置信息很有用。
*
*/
multi?: boolean;
}
@ -54,26 +72,39 @@ export interface ValueProvider extends ValueSansProvider {
* Configures the `Injector` to return an instance of `useClass` for a token.
* Base for `StaticClassProvider` decorator.
*
* 配置 `Injector` 以返回 `useClass` 的令牌实例。这是 `StaticClassProvider` 装饰器的基接口。
*
* @publicApi
*/
export interface StaticClassSansProvider {
/**
* An optional class to instantiate for the `token`. By default, the `provide`
* class is instantiated.
*
* 供 `token` 实例化的可选类。默认情况下，会把 `provide` 类实例化。
*
*/
useClass: Type<any>;
/**
* A list of `token`s to be resolved by the injector. The list of values is then
* used as arguments to the `useClass` constructor.
*
* 由注入器解析的 `token` 列表。将这个值列表用作 `useClass` 构造函数的参数。
*
*/
deps: any[];
}
/**
* Configures the `Injector` to return an instance of `useClass` for a token.
*
* 配置 `Injector` 以返回 `useClass` 的令牌实例。
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* [“依赖注入指南”](guide/dependency-injection) 。
*
* @usageNotes
*
* {@example core/di/ts/provider_spec.ts region='StaticClassProvider'}
@ -91,12 +122,18 @@ export interface StaticClassSansProvider {
export interface StaticClassProvider extends StaticClassSansProvider {
/**
* An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`.
*
* 注入令牌。通常是 `Type` 或 `InjectionToken` 的实例，但也可以是 `any` 实例。
*
*/
provide: any;
/**
* When true, injector returns an array of instances. This is useful to allow multiple
* providers spread across many files to provide configuration information to a common token.
*
* 如果为 true，则注入器返回实例数组。这在允许多个提供者散布在多个文件中，以向某个公共令牌提供配置信息时很有用。
*
*/
multi?: boolean;
}
@ -104,8 +141,11 @@ export interface StaticClassProvider extends StaticClassSansProvider {
/**
* Configures the `Injector` to return an instance of a token.
*
* 配置此 `Injector` 以返回令牌的实例。
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* [“依赖注入指南”](guide/dependency-injection) 。
* @usageNotes
*
* ```ts
@ -118,6 +158,9 @@ export interface StaticClassProvider extends StaticClassSansProvider {
export interface ConstructorSansProvider {
/**
* A list of `token`s to be resolved by the injector.
*
* 注入器要解析的 `token` 列表。
*
*/
deps?: any[];
}
@ -125,8 +168,12 @@ export interface ConstructorSansProvider {
/**
* Configures the `Injector` to return an instance of a token.
*
* 配置此 `Injector`，以返回令牌的实例。
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* [“依赖注入指南”](guide/dependency-injection) 。
*
* @usageNotes
*
* {@example core/di/ts/provider_spec.ts region='ConstructorProvider'}
@ -140,12 +187,18 @@ export interface ConstructorSansProvider {
export interface ConstructorProvider extends ConstructorSansProvider {
/**
* An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`.
*
* 注入令牌。通常是 `Type` 或 `InjectionToken` 的实例，但也可以是 `any` 实例。
*
*/
provide: Type<any>;
/**
* When true, injector returns an array of instances. This is useful to allow multiple
* providers spread across many files to provide configuration information to a common token.
*
* 如果为 true，则注入器返回实例数组。这对于允许多个提供者散布在多个文件中，以向某个公共令牌提供配置信息很有用。
*
*/
multi?: boolean;
}
@ -153,14 +206,21 @@ export interface ConstructorProvider extends ConstructorSansProvider {
/**
* Configures the `Injector` to return a value of another `useExisting` token.
*
* 配置此 `Injector` 以返回另一个 `useExisting` 令牌的值。
*
* @see `ExistingProvider`
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* [“依赖注入指南”](guide/dependency-injection) 。
*
* @publicApi
*/
export interface ExistingSansProvider {
/**
* Existing `token` to return. (Equivalent to `injector.get(useExisting)`)
*
* 返回现有的 `token`。 （等效于 `injector.get(useExisting)` ）
*
*/
useExisting: any;
}
@ -168,8 +228,12 @@ export interface ExistingSansProvider {
/**
* Configures the `Injector` to return a value of another `useExisting` token.
*
* 配置此 `Injector` 以返回另一个 `useExisting` 令牌的值。
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* [“依赖注入指南”](guide/dependency-injection) 。
*
* @usageNotes
*
* {@example core/di/ts/provider_spec.ts region='ExistingProvider'}
@ -183,12 +247,18 @@ export interface ExistingSansProvider {
export interface ExistingProvider extends ExistingSansProvider {
/**
* An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`.
*
* 注入令牌。通常是 `Type` 或 `InjectionToken` 的实例，但也可以是 `any` 实例。
*
*/
provide: any;
/**
* When true, injector returns an array of instances. This is useful to allow multiple
* providers spread across many files to provide configuration information to a common token.
*
* 如果为 true，则注入器返回实例数组。这对于允许多个提供者散布在多个文件中，以向某个公共令牌提供配置信息很有用。
*
*/
multi?: boolean;
}
@ -196,29 +266,44 @@ export interface ExistingProvider extends ExistingSansProvider {
/**
* Configures the `Injector` to return a value by invoking a `useFactory` function.
*
* 把此 `Injector` 配置为调用 `useFactory` 函数返回一个值。
*
* @see `FactoryProvider`
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* [“依赖注入指南”](guide/dependency-injection) 。
*
* @publicApi
*/
export interface FactorySansProvider {
/**
* A function to invoke to create a value for this `token`. The function is invoked with
* resolved values of `token`s in the `deps` field.
*
* 供调用，来为此 `token` 创建值的函数。调用该函数时，会在 `deps` 字段中的传入 `token` 的解析结果。。
*
*/
useFactory: Function;
/**
* A list of `token`s to be resolved by the injector. The list of values is then
* used as arguments to the `useFactory` function.
*
* 供注入器解析的 `token` 列表。然后，将值列表将用作 `useFactory` 函数的参数。
*
*/
deps?: any[];
}
/**
* Configures the `Injector` to return a value by invoking a `useFactory` function.
*
* 配置此 `Injector` 以便调用 `useFactory` 函数返回一个值。
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* [“依赖注入指南”](guide/dependency-injection) 。
*
* @usageNotes
*
* {@example core/di/ts/provider_spec.ts region='FactoryProvider'}
@ -236,12 +321,18 @@ export interface FactorySansProvider {
export interface FactoryProvider extends FactorySansProvider {
/**
* An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`).
*
* 注入令牌。（通常是 `Type` 或 `InjectionToken` 的实例，但也可以是 `any` 实例）。
*
*/
provide: any;
/**
* When true, injector returns an array of instances. This is useful to allow multiple
* providers spread across many files to provide configuration information to a common token.
*
* 如果为 true，则注入器返回实例数组。这对于允许多个提供者散布在多个文件中，以向某个公共令牌提供配置信息很有用。
*
*/
multi?: boolean;
}
@ -250,9 +341,13 @@ export interface FactoryProvider extends FactorySansProvider {
* Describes how an `Injector` should be configured as static (that is, without reflection).
* A static provider provides tokens to an injector for various types of dependencies.
*
* 描述如何将 `Injector` 配置为静态的（即不需要反射）。静态提供者为各种类型的依赖项提供令牌给注入器。
*
* @see [Injector.create()](/api/core/Injector#create).
* @see ["Dependency Injection Guide"](guide/dependency-injection-providers).
*
* [“依赖注入指南”](guide/dependency-injection-providers) 。
*
* @publicApi
*/
export type StaticProvider =
@ -262,11 +357,17 @@ export type StaticProvider =
/**
* Configures the `Injector` to return an instance of `Type` when `Type' is used as the token.
*
* 配置此 `Injector`，以将“类型”用作令牌时返回 `Type` 的实例。
*
* Create an instance by invoking the `new` operator and supplying additional arguments.
* This form is a short form of `TypeProvider`;
*
* 通过调用 `new` 运算符并提供其他参数来创建实例。这种形式是 `TypeProvider` 的缩写形式；
*
* For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
*
* 欲知详情，请参见[“依赖项注入指南”](guide/dependency-injection) 。
*
* @usageNotes
*
* {@example core/di/ts/provider_spec.ts region='TypeProvider'}
@ -279,21 +380,33 @@ export interface TypeProvider extends Type<any> {}
* Configures the `Injector` to return a value by invoking a `useClass` function.
* Base for `ClassProvider` decorator.
*
* 配置 `Injector` 以通过调用 `useClass` 函数返回某个值。是 `ClassProvider` 装饰器的基接口。
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* [“依赖注入指南”](guide/dependency-injection) 。
*
* @publicApi
*/
export interface ClassSansProvider {
/**
* Class to instantiate for the `token`.
*
* 用于将此 `token` 实例化的类。
*
*/
useClass: Type<any>;
}
/**
* Configures the `Injector` to return an instance of `useClass` for a token.
*
* 配置此 `Injector` 以便为令牌返回 `useClass` 的实例。
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* [“依赖注入指南”](guide/dependency-injection) 。
*
* @usageNotes
*
* {@example core/di/ts/provider_spec.ts region='ClassProvider'}
@ -311,20 +424,31 @@ export interface ClassSansProvider {
export interface ClassProvider extends ClassSansProvider {
/**
* An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`).
*
* 注入令牌。（通常是 `Type` 或 `InjectionToken` 的实例，但也可以是 `any` 实例）。
*
*/
provide: any;
/**
* When true, injector returns an array of instances. This is useful to allow multiple
* providers spread across many files to provide configuration information to a common token.
*
* 如果为 true，则注入器返回实例数组。这对于允许多个提供者散布在多个文件中，以向某个公共令牌提供配置信息时很有用。
*
*/
multi?: boolean;
}
/**
* Describes how the `Injector` should be configured.
*
* 描述应该如何配置 `Injector`。
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* [“依赖注入指南”](guide/dependency-injection) 。
*
* @see `StaticProvider`
*
* @publicApi

71
packages/core/src/di/metadata.ts
View File

@ -12,6 +12,8 @@ import {makeParamDecorator} from '../util/decorators';
/**
* Type of the Inject decorator / constructor function.
*
* 注入装饰器/构造函数的类型。
*
* @publicApi
*/
export interface InjectDecorator {
@ -19,18 +21,27 @@ export interface InjectDecorator {
* Parameter decorator on a dependency parameter of a class constructor
* that specifies a custom provider of the dependency.
*
* 类构造函数中依赖项参数上的参数装饰器，用于指定依赖项的自定义提供者。
*
* @usageNotes
*
* The following example shows a class constructor that specifies a
* custom provider of a dependency using the parameter decorator.
*
* 下面的示例显示了一个类构造函数，该构造函数使用参数装饰器指定了依赖项的自定义提供者。
*
* When `@Inject()` is not present, the injector uses the type annotation of the
* parameter as the provider.
*
* 如果有 `@Inject()`，则注入器将参数的类型注解用作提供者。
*
* <code-example path="core/di/ts/metadata_spec.ts" region="InjectWithoutDecorator">
* </code-example>
*
* @see ["Dependency Injection Guide"](guide/dependency-injection)
*
* [“依赖注入指南”](guide/dependency-injection)
*
*/
(token: any): any;
new(token: any): Inject;
@ -39,11 +50,16 @@ export interface InjectDecorator {
/**
* Type of the Inject metadata.
*
* 注入元数据的类型。
*
* @publicApi
*/
export interface Inject {
/**
* A [DI token](guide/glossary#di-token) that maps to the dependency to be injected.
*
* 一个 [DI 令牌](guide/glossary#di-token)，映射到要注入的依赖项。
*
*/
token: any;
}
@ -51,6 +67,8 @@ export interface Inject {
/**
* Inject decorator and metadata.
*
* 注入装饰器和元数据。
*
* @Annotation
* @publicApi
*/
@ -60,6 +78,8 @@ export const Inject: InjectDecorator = makeParamDecorator('Inject', (token: any)
/**
* Type of the Optional decorator / constructor function.
*
* 可选装饰器/构造函数的类型。
*
* @publicApi
*/
export interface OptionalDecorator {
@ -68,17 +88,26 @@ export interface OptionalDecorator {
* which marks the parameter as being an optional dependency.
* The DI framework provides null if the dependency is not found.
*
* 用于构造函数参数的参数装饰器，将参数标记为可选依赖项。如果找不到依赖项，则 DI 框架提供 null。
*
* Can be used together with other parameter decorators
* that modify how dependency injection operates.
*
* 可以与其他修改依赖注入方式的参数装饰器一起使用。
*
* @usageNotes
*
* The following code allows the possibility of a null result:
*
* 以下代码允许结果为空的可能性：
*
* <code-example path="core/di/ts/metadata_spec.ts" region="Optional">
* </code-example>
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* [“依赖注入指南”](guide/dependency-injection) 。
*
*/
(): any;
new(): Optional;
@ -87,6 +116,8 @@ export interface OptionalDecorator {
/**
* Type of the Optional metadata.
*
* 可选元数据的类型。
*
* @publicApi
*/
export interface Optional {}
@ -94,6 +125,8 @@ export interface Optional {}
/**
* Optional decorator and metadata.
*
* 可选的装饰器和元数据。
*
* @Annotation
* @publicApi
*/
@ -102,6 +135,8 @@ export const Optional: OptionalDecorator = makeParamDecorator('Optional');
/**
* Type of the Self decorator / constructor function.
*
* Self 装饰器/构造函数的类型。
*
* @publicApi
*/
export interface SelfDecorator {
@ -109,15 +144,21 @@ export interface SelfDecorator {
* Parameter decorator to be used on constructor parameters,
* which tells the DI framework to start dependency resolution from the local injector.
*
* 将在构造函数参数上使用参数装饰器，该装饰器告诉 DI 框架从本地注入器开始解析依赖项。
*
* Resolution works upward through the injector hierarchy, so the children
* of this class must configure their own providers or be prepared for a null result.
*
* 解析器在注入器层次结构中向上查找，因此此类的子级必须配置其自己的提供者或为空结果做好准备。
*
* @usageNotes
*
* In the following example, the dependency can be resolved
* by the local injector when instantiating the class itself, but not
* when instantiating a child.
*
* 在以下示例中，依赖关系可以在实例化类本身时由本地注入器解析，而在实例化子代时不能解析。
*
* <code-example path="core/di/ts/metadata_spec.ts" region="Self">
* </code-example>
*
@ -132,6 +173,8 @@ export interface SelfDecorator {
/**
* Type of the Self metadata.
*
* Self 元数据的类型。
*
* @publicApi
*/
export interface Self {}
@ -139,6 +182,8 @@ export interface Self {}
/**
* Self decorator and metadata.
*
* Self 装饰器和元数据。
*
* @Annotation
* @publicApi
*/
@ -148,6 +193,8 @@ export const Self: SelfDecorator = makeParamDecorator('Self');
/**
* Type of the `SkipSelf` decorator / constructor function.
*
* `SkipSelf` 装饰器/构造函数的类型。
*
* @publicApi
*/
export interface SkipSelfDecorator {
@ -157,15 +204,22 @@ export interface SkipSelfDecorator {
* Resolution works upward through the injector hierarchy, so the local injector
* is not checked for a provider.
*
* 将在构造函数参数上使用的参数装饰器，该参数指示 DI 框架从父注入器启动依赖项解析。解析器在注入器层次结构中向上查找，因此不会检查本地注入器的提供者。
*
* @usageNotes
*
* In the following example, the dependency can be resolved when
* instantiating a child, but not when instantiating the class itself.
*
* 在以下示例中，可以在实例化子级时解析依赖项，但在实例化类本身时不解析。
*
* <code-example path="core/di/ts/metadata_spec.ts" region="SkipSelf">
* </code-example>
*
* @see [Dependency Injection guide](guide/dependency-injection-in-action#skip).
*
* [依赖注入指南](guide/dependency-injection-in-action#skip)。
*
* @see `Self`
* @see `Optional`
*
@ -177,6 +231,8 @@ export interface SkipSelfDecorator {
/**
* Type of the `SkipSelf` metadata.
*
* `SkipSelf` 元数据的类型。
*
* @publicApi
*/
export interface SkipSelf {}
@ -184,6 +240,8 @@ export interface SkipSelf {}
/**
* `SkipSelf` decorator and metadata.
*
* `SkipSelf` 装饰器和元数据。
*
* @Annotation
* @publicApi
*/
@ -192,6 +250,8 @@ export const SkipSelf: SkipSelfDecorator = makeParamDecorator('SkipSelf');
/**
* Type of the `Host` decorator / constructor function.
*
* `Host` 装饰器/构造函数的类型。
*
* @publicApi
*/
export interface HostDecorator {
@ -200,15 +260,22 @@ export interface HostDecorator {
* that tells the DI framework to resolve the view by checking injectors of child
* elements, and stop when reaching the host element of the current component.
*
* 类构造函数的视图提供者参数上的参数修饰器，用于指示 DI 框架通过检查子元素的注入器来解析视图，并在到达当前组件的宿主元素时停止。
*
* @usageNotes
*
* The following shows use with the `@Optional` decorator, and allows for a null result.
*
* 以下显示了与 `@Optional` 装饰器一起使用的情况，并允许空结果。
*
* <code-example path="core/di/ts/metadata_spec.ts" region="Host">
* </code-example>
*
* For an extended example, see ["Dependency Injection
* Guide"](guide/dependency-injection-in-action#optional).
*
* 有关扩展的示例，请参见[“依赖项注入指南”](guide/dependency-injection-in-action#optional) 。
*
*/
(): any;
new(): Host;
@ -217,6 +284,8 @@ export interface HostDecorator {
/**
* Type of the Host metadata.
*
* 宿主元数据的类型。
*
* @publicApi
*/
export interface Host {}
@ -224,6 +293,8 @@ export interface Host {}
/**
* Host decorator and metadata.
*
* 宿主装饰器和元数据。
*
* @Annotation
* @publicApi
*/

15
packages/core/src/di/metadata_attr.ts
View File

@ -13,6 +13,8 @@ import {makeParamDecorator} from '../util/decorators';
/**
* Type of the Attribute decorator / constructor function.
*
* 属性装饰器/构造函数的类型。
*
* @publicApi
*/
export interface AttributeDecorator {
@ -20,16 +22,22 @@ export interface AttributeDecorator {
* Parameter decorator for a directive constructor that designates
* a host-element attribute whose value is injected as a constant string literal.
*
* 指令构造函数的参数修饰器，用于指定宿主元素属性，其值作为常量字符串文字注入。
*
* @usageNotes
*
* Suppose we have an `<input>` element and want to know its `type`.
*
* 假设我们有一个 `<input>` 元素，并且想知道它的 `type` 。
*
* ```html
* <input type="text">
* ```
*
* The following example uses the decorator to inject the string literal `text` in a directive.
*
* 以下示例使用装饰器将字符串文字 `text` 注入指令中。
*
* {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
*
* The following example uses the decorator in a component constructor.
@ -44,11 +52,16 @@ export interface AttributeDecorator {
/**
* Type of the Attribute metadata.
*
* 属性元数据的类型。
*
* @publicApi
*/
export interface Attribute {
/**
* The name of the attribute whose value can be injected.
*
* 可以注入其值的属性的名称。
*
*/
attributeName: string;
}
@ -69,6 +82,8 @@ const CREATE_ATTRIBUTE_DECORATOR_IMPL = CREATE_ATTRIBUTE_DECORATOR__PRE_R3__;
/**
* Attribute decorator and metadata.
*
* 属性装饰器和元数据。
*
* @Annotation
* @publicApi
*/

2
packages/core/src/di/r3_injector.ts
View File

@ -75,6 +75,8 @@ interface Record<T> {
/**
* Create a new `Injector` which is configured using a `defType` of `InjectorType<any>`s.
*
* 创建一个新的 `Injector`， 它是使用 `InjectorType<any>` 的 `defType` 配置的。
*
* @publicApi
*/
export function createInjector(

7
packages/core/src/di/reflective_errors.ts
View File

@ -70,6 +70,7 @@ function addKey(this: InjectionError, injector: ReflectiveInjector, key: Reflect
* {@link Injector} does not have a {@link Provider} for the given key.
*
* @usageNotes
*
* ### Example
*
* ```typescript
@ -91,6 +92,7 @@ export function noProviderError(injector: ReflectiveInjector, key: ReflectiveKey
* Thrown when dependencies form a cycle.
*
* @usageNotes
*
* ### Example
*
* ```typescript
@ -118,6 +120,7 @@ export function cyclicDependencyError(
* this object to be instantiated.
*
* @usageNotes
*
* ### Example
*
* ```typescript
@ -153,6 +156,7 @@ export function instantiationError(
* creation.
*
* @usageNotes
*
* ### Example
*
* ```typescript
@ -171,6 +175,7 @@ export function invalidProviderError(provider: any) {
* need to be injected into the constructor.
*
* @usageNotes
*
* ### Example
*
* ```typescript
@ -215,6 +220,7 @@ export function noAnnotationError(typeOrFunc: Type<any>|Function, params: any[][
* Thrown when getting an object by index.
*
* @usageNotes
*
* ### Example
*
* ```typescript
@ -235,6 +241,7 @@ export function outOfBoundsError(index: number) {
* Thrown when a multi provider and a regular provider are bound to the same token.
*
* @usageNotes
*
* ### Example
*
* ```typescript

65
packages/core/src/di/reflective_injector.ts
View File

@ -22,17 +22,28 @@ const UNDEFINED = {};
* A ReflectiveDependency injection container used for instantiating objects and resolving
* dependencies.
*
* 一个 ReflectiveDependency 注入容器，用于实例化对象和解析依赖关系。
*
* An `Injector` is a replacement for a `new` operator, which can automatically resolve the
* constructor dependencies.
*
* `Injector` 替代了 `new` 操作符，该操作符可以自动解析构造函数的依赖关系。
*
* In typical use, application code asks for the dependencies in the constructor and they are
* resolved by the `Injector`.
*
* 在典型的用法中，应用程序代码会在构造函数中要求依赖项，并由 `Injector` 进行解析。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* The following example creates an `Injector` configured to create `Engine` and `Car`.
*
* 以下示例创建一个配置为创建 `Engine` 和 `Car` 的 `Injector`。
*
* ```typescript
* @Injectable()
* class Engine {
@ -53,18 +64,28 @@ const UNDEFINED = {};
* resolve all of the object's dependencies automatically.
*
* @deprecated from v5 - slow and brings in a lot of code, Use `Injector.create` instead.
*
* 从 v5 开始 - 速度慢，并且引入了大量代码，请改用 `Injector.create` 。
*
* @publicApi
*/
export abstract class ReflectiveInjector implements Injector {
/**
* Turns an array of provider definitions into an array of resolved providers.
*
* 将一组提供者定义转换为一组已解析的提供者。
*
* A resolution is a process of flattening multiple nested arrays and converting individual
* providers into an array of `ResolvedReflectiveProvider`s.
*
* 解析是展平多个嵌套数组并将其各个提供者转换为 `ResolvedReflectiveProvider` 数组的过程。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* ```typescript
* @Injectable()
* class Engine {
@ -96,12 +117,19 @@ export abstract class ReflectiveInjector implements Injector {
/**
* Resolves an array of providers and creates an injector from those providers.
*
* 解析供应商数组，并从这些供应商创建注入器。
*
* The passed-in providers can be an array of `Type`, `Provider`,
* or a recursive array of more providers.
*
* 传入的提供者可以是 `Type`、`Provider` 或更多提供者的递归数组。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* ```typescript
* @Injectable()
* class Engine {
@ -124,11 +152,18 @@ export abstract class ReflectiveInjector implements Injector {
/**
* Creates an injector from previously resolved providers.
*
* 从先前解析的提供者创建注入器。
*
* This API is the recommended way to construct injectors in performance-sensitive parts.
*
* 建议使用此 API 在对性能敏感的部分构建注入器。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* ```typescript
* @Injectable()
* class Engine {
@ -153,6 +188,8 @@ export abstract class ReflectiveInjector implements Injector {
/**
* Parent of this injector.
*
* 此注入器的父代。
*
* <!-- TODO: Add a link to the section of the user guide talking about hierarchical injection.
* -->
*/
@ -161,15 +198,22 @@ export abstract class ReflectiveInjector implements Injector {
/**
* Resolves an array of providers and creates a child injector from those providers.
*
* 解析一组提供者，并从这些提供者创建子注入器。
*
* <!-- TODO: Add a link to the section of the user guide talking about hierarchical injection.
* -->
*
* The passed-in providers can be an array of `Type`, `Provider`,
* or a recursive array of more providers.
*
* 传入的提供者可以是 `Type`、`Provider` 或更多提供者的递归数组。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* ```typescript
* class ParentProvider {}
* class ChildProvider {}
@ -187,14 +231,21 @@ export abstract class ReflectiveInjector implements Injector {
/**
* Creates a child injector from previously resolved providers.
*
* 从先前解析的提供者中创建子注入器。
*
* <!-- TODO: Add a link to the section of the user guide talking about hierarchical injection.
* -->
*
* This API is the recommended way to construct injectors in performance-sensitive parts.
*
* 建议使用此 API 在对性能敏感的部分构造注入器。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* ```typescript
* class ParentProvider {}
* class ChildProvider {}
@ -215,11 +266,18 @@ export abstract class ReflectiveInjector implements Injector {
/**
* Resolves a provider and instantiates an object in the context of the injector.
*
* 解析提供者并在注入器的上下文中实例化对象。
*
* The created object does not get cached by the injector.
*
* 注入器不会缓存创建的对象。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* ```typescript
* @Injectable()
* class Engine {
@ -242,11 +300,18 @@ export abstract class ReflectiveInjector implements Injector {
/**
* Instantiates an object using a resolved provider in the context of the injector.
*
* 在注入器的上下文中使用解析的提供者实例化对象。
*
* The created object does not get cached by the injector.
*
* 注入器不会缓存创建的对象。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* ```typescript
* @Injectable()
* class Engine {

26
packages/core/src/di/reflective_key.ts
View File

@ -13,25 +13,45 @@ import {resolveForwardRef} from './forward_ref';
/**
* A unique object used for retrieving items from the {@link ReflectiveInjector}.
*
* 用于从 {@link ReflectiveInjector} 中检索项目的唯一对象。
*
* Keys have:
*
* 其键名有：
*
* - a system-wide unique `id`.
*
* 系统范围内的唯一 `id` 。
*
* - a `token`.
*
* `token`。
*
* `Key` is used internally by {@link ReflectiveInjector} because its system-wide unique `id` allows
* the
* injector to store created objects in a more efficient way.
*
* `Key` 由 {@link ReflectiveInjector} 内部使用，因为它在系统范围内的唯一 `id` 允许注入器以更有效的方式存储所创建的对象。
*
* `Key` should not be created directly. {@link ReflectiveInjector} creates keys automatically when
* resolving
* providers.
*
* `Key` 不应直接创建。{@link ReflectiveInjector} 在解析提供者时会自动创建键名。
*
* @deprecated No replacement
*
* 无替代品
*
* @publicApi
*/
export class ReflectiveKey {
public readonly displayName: string;
/**
* Private
*
* 私人的
*
*/
constructor(public token: Object, public id: number) {
if (!token) {
@ -42,6 +62,9 @@ export class ReflectiveKey {
/**
* Retrieves a `Key` for a token.
*
* 根据令牌检索出一个 `Key`。
*
*/
static get(token: Object): ReflectiveKey {
return _globalKeyRegistry.get(resolveForwardRef(token));
@ -49,6 +72,9 @@ export class ReflectiveKey {
/**
* @returns the number of keys registered in the system.
*
* 在系统中注册的 `Key` 数。
*
*/
static get numberOfKeys(): number {
return _globalKeyRegistry.numberOfKeys;

21
packages/core/src/di/reflective_provider.ts
View File

@ -38,13 +38,22 @@ const _EMPTY_LIST: any[] = [];
/**
* An internal resolved representation of a `Provider` used by the `Injector`.
*
* 供 `Injector` 使用的 `Provider` 的内部解析表示形式。
*
* @usageNotes
*
* This is usually created automatically by `Injector.resolveAndCreate`.
*
* 这通常是由 `Injector.resolveAndCreate` 自动创建的。
*
* It can be created manually, as follows:
*
* 也可以手动创建，如下所示：
*
* ### Example
*
* ### 例子
*
* ```typescript
* var resolvedProviders = Injector.resolve([{ provide: 'message', useValue: 'Hello' }]);
* var injector = Injector.fromResolvedProviders(resolvedProviders);
@ -57,16 +66,25 @@ const _EMPTY_LIST: any[] = [];
export interface ResolvedReflectiveProvider {
/**
* A key, usually a `Type<any>`.
*
* 一个 Key，通常是 `Type<any>` 。
*
*/
key: ReflectiveKey;
/**
* Factory function which can return an instance of an object represented by a key.
*
* 可以返回 Key 表示的对象实例的工厂函数。
*
*/
resolvedFactories: ResolvedReflectiveFactory[];
/**
* Indicates if the provider is a multi-provider or a regular provider.
*
* 指示提供者是多重提供者还是常规提供者。
*
*/
multiProvider: boolean;
}
@ -83,6 +101,9 @@ export class ResolvedReflectiveProvider_ implements ResolvedReflectiveProvider {
/**
* An internal resolved representation of a factory function created by resolving `Provider`.
*
* `Provider` 创建的工厂函数的内部解析表示形式。
*
* @publicApi
*/
export class ResolvedReflectiveFactory {

7
packages/core/src/error_handler.ts
View File

@ -13,13 +13,20 @@ import {getDebugContext, getErrorLogger, getOriginalError} from './errors';
/**
* Provides a hook for centralized exception handling.
*
* 提供用于集中式异常处理的挂钩。
*
* The default implementation of `ErrorHandler` prints error messages to the `console`. To
* intercept error handling, write a custom exception handler that replaces this default as
* appropriate for your app.
*
* `ErrorHandler` 的默认实现将错误消息打印到 `console`。要拦截错误处理，请编写一个自定义的异常处理器，该异常处理器将把此默认行为改成你应用所需的。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* ```
* class MyErrorHandler implements ErrorHandler {
* handleError(error) {

29
packages/core/src/event_emitter.ts
View File

@ -15,16 +15,22 @@ import {Subject, Subscription} from 'rxjs';
* synchronously or asynchronously, and register handlers for those events
* by subscribing to an instance.
*
* 用在带有 `@Output` 指令的组件中，以同步或异步方式发出自定义事件，并通过订阅实例来为这些事件注册处理器。
*
* @usageNotes
*
* Extends
* [RxJS `Subject`](https://rxjs.dev/api/index/class/Subject)
* for Angular by adding the `emit()` method.
*
* 通过添加 `emit()` 方法来扩展 [Angular 的 RxJS `Subject`](https://rxjs.dev/api/index/class/Subject)。
*
* In the following example, a component defines two output properties
* that create event emitters. When the title is clicked, the emitter
* emits an open or close event to toggle the current visibility state.
*
* 在以下示例中，组件定义了两个创建事件发射器的输出属性。单击标题后，发射器将发出打开或关闭事件以切换当前可见性状态。
*
* ```html
* @Component({
* selector: 'zippy',
@ -59,6 +65,9 @@ import {Subject, Subscription} from 'rxjs';
* ```
*
* @see [Observables in Angular](guide/observables-in-angular)
*
* [Angular 中的可观察对象](guide/observables-in-angular)
*
* @publicApi
*/
export interface EventEmitter<T> extends Subject<T> {
@ -71,6 +80,8 @@ export interface EventEmitter<T> extends Subject<T> {
* Creates an instance of this class that can
* deliver events synchronously or asynchronously.
*
* 创建此类的实例，该实例可以同步或异步发送事件。
*
* @param [isAsync=false] When true, deliver events asynchronously.
*
*/
@ -78,16 +89,34 @@ export interface EventEmitter<T> extends Subject<T> {
/**
* Emits an event containing a given value.
*
* 发出包含给定值的事件。
*
* @param value The value to emit.
*
* 要发出的值。
*
*/
emit(value?: T): void;
/**
* Registers handlers for events emitted by this instance.
*
* 注册此实例发出的事件的处理器。
*
* @param generatorOrNext When supplied, a custom handler for emitted events.
*
* 如果提供，则为所发出事件的自定义处理器。
*
* @param error When supplied, a custom handler for an error notification
* from this emitter.
*
* 如果提供，则为这里发出的错误通知的自定义处理器。
*
* @param complete When supplied, a custom handler for a completion
* notification from this emitter.
*
* 如果提供，则为这里发出的完成通知的自定义处理器。
*
*/
subscribe(generatorOrNext?: any, error?: any, complete?: any): Subscription;
}

53
packages/core/src/i18n/tokens.ts
View File

@ -13,11 +13,18 @@ import {InjectionToken} from '../di/injection_token';
* It is used for i18n extraction, by i18n pipes (DatePipe, I18nPluralPipe, CurrencyPipe,
* DecimalPipe and PercentPipe) and by ICU expressions.
*
* 提供此令牌以设置应用程序的语言环境。它通过 i18n 管道（DatePipe、I18nPluralPipe、CurrencyPipe、DecimalPipe 和 PercentPipe）和 ICU 表达式用于 i18n 提取。
*
* See the [i18n guide](guide/i18n#setting-up-locale) for more information.
*
* 有关更多信息，请参见《 [i18n 指南》。](guide/i18n#setting-up-locale)
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* ```typescript
* import { LOCALE_ID } from '@angular/core';
* import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
@ -37,19 +44,31 @@ export const LOCALE_ID = new InjectionToken<string>('LocaleId');
* CurrencyPipe when there is no currency code passed into it. This is only used by
* CurrencyPipe and has no relation to locale currency. Defaults to USD if not configured.
*
* 如果没有传递任何货币代码，请提供此令牌来设置你的应用程序用于 CurrencyPipe 的默认货币代码。仅由 CurrencyPipe 使用，与语言环境的货币无关。如果未配置，则默认为 USD。
*
* See the [i18n guide](guide/i18n#setting-up-locale) for more information.
*
* 有关更多信息，请参见[《i18n 指南》](guide/i18n#setting-up-locale)。
*
* <div class="alert is-helpful">
*
* **Deprecation notice:**
*
* **弃用通知：**
*
* The default currency code is currently always `USD` but this is deprecated from v9.
*
* 默认货币代码当前始终为 `USD` 但自 v9 起已弃用。
*
* **In v10 the default currency code will be taken from the current locale.**
*
* **在 v10 中，默认货币代码将从当前语言环境中获取。**
*
* If you need the previous behavior then set it by creating a `DEFAULT_CURRENCY_CODE` provider in
* your application `NgModule`:
*
* 如果你需要以前的行为，请通过应用 `NgModule` 中的 `DEFAULT_CURRENCY_CODE` 提供者来进行设置：
*
* ```ts
* {provide: DEFAULT_CURRENCY_CODE, useValue: 'USD'}
* ```
@ -57,8 +76,11 @@ export const LOCALE_ID = new InjectionToken<string>('LocaleId');
* </div>
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* ```typescript
* import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
* import { AppModule } from './app/app.module';
@ -76,11 +98,18 @@ export const DEFAULT_CURRENCY_CODE = new InjectionToken<string>('DefaultCurrency
* Use this token at bootstrap to provide the content of your translation file (`xtb`,
* `xlf` or `xlf2`) when you want to translate your application in another language.
*
* 当你想用另一种语言翻译应用程序时，可以在引导程序中使用此令牌来提供翻译文件的内容（ `xtb`、`xlf` 或 `xlf2`）
*
* See the [i18n guide](guide/i18n#merge) for more information.
*
* 有关更多信息，请参见[《i18n 指南》](guide/i18n#setting-up-locale)。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* ```typescript
* import { TRANSLATIONS } from '@angular/core';
* import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
@ -102,11 +131,18 @@ export const TRANSLATIONS = new InjectionToken<string>('Translations');
* Provide this token at bootstrap to set the format of your {@link TRANSLATIONS}: `xtb`,
* `xlf` or `xlf2`.
*
* 在引导程序中提供此令牌以设置 {@link TRANSLATIONS} 的格式： `xtb`、`xlf` 或 `xlf2`。
*
* See the [i18n guide](guide/i18n#merge) for more information.
*
* 有关更多信息，请参见[《i18n 指南》](guide/i18n#setting-up-locale)。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* ```typescript
* import { TRANSLATIONS_FORMAT } from '@angular/core';
* import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
@ -124,14 +160,31 @@ export const TRANSLATIONS_FORMAT = new InjectionToken<string>('TranslationsForma
/**
* Use this enum at bootstrap as an option of `bootstrapModule` to define the strategy
* that the compiler should use in case of missing translations:
*
* 在系统启动时使用此枚举作为 `bootstrapModule` 的一个选项来定义策略，编译器应该在缺少翻译的情况下使用：
*
* - Error: throw if you have missing translations.
*
* Error：如果缺少翻译，则抛出该错误。
*
* - Warning (default): show a warning in the console and/or shell.
*
* Warning（默认）：在控制台和/或应用外壳中显示警告。
*
* - Ignore: do nothing.
*
* Ignore：什么都不做。
*
* See the [i18n guide](guide/i18n#missing-translation) for more information.
*
* 有关更多信息，请参见[《i18n 指南》](guide/i18n#setting-up-locale)。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* ```typescript
* import { MissingTranslationStrategy } from '@angular/core';
* import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

8
packages/core/src/interface/lifecycle_hooks.ts
View File

@ -23,6 +23,7 @@ import {SimpleChanges} from './simple_change';
* [生命周期钩子](guide/lifecycle-hooks#onchanges)
*
* @usageNotes
*
* The following snippet shows how a component can implement this interface to
* define an on-changes handler for an input property.
*
@ -63,6 +64,7 @@ export interface OnChanges {
* [生命周期钩子](guide/lifecycle-hooks#onchanges)
*
* @usageNotes
*
* The following snippet shows how a component can implement this interface to
* define its own initialization method.
*
@ -113,6 +115,7 @@ export interface OnInit {
* [生命周期钩子](guide/lifecycle-hooks#onchanges)
*
* @usageNotes
*
* The following snippet shows how a component can implement this interface
* to invoke it own change-detection cycle.
*
@ -151,6 +154,7 @@ export interface DoCheck {
* [生命周期钩子](guide/lifecycle-hooks#onchanges)
*
* @usageNotes
*
* The following snippet shows how a component can implement this interface
* to define its own custom clean-up method.
*
@ -186,6 +190,7 @@ export interface OnDestroy {
* [生命周期钩子](guide/lifecycle-hooks#onchanges)
*
* @usageNotes
*
* The following snippet shows how a component can implement this interface to
* define its own content initialization method.
*
@ -222,6 +227,7 @@ export interface AfterContentInit {
* [生命周期钩子](guide/lifecycle-hooks#onchanges)
*
* @usageNotes
*
* The following snippet shows how a component can implement this interface to
* define its own after-check functionality.
*
@ -258,6 +264,7 @@ export interface AfterContentChecked {
* [生命周期钩子](guide/lifecycle-hooks#onchanges)
*
* @usageNotes
*
* The following snippet shows how a component can implement this interface to
* define its own view initialization method.
*
@ -292,6 +299,7 @@ export interface AfterViewInit {
* [生命周期钩子](guide/lifecycle-hooks#onchanges)
*
* @usageNotes
*
* The following snippet shows how a component can implement this interface to
* define its own after-check functionality.
*

7
packages/core/src/interface/simple_change.ts
View File

@ -11,6 +11,8 @@
* property on a directive instance. Passed as a value in a
* {@link SimpleChanges} object to the `ngOnChanges` hook.
*
* 表示指令实例上单个属性从先前值到新值的基本变更对象。在 {@link SimpleChanges} 对象中作为值传递给 `ngOnChanges` 挂钩。
*
* @see `OnChanges`
*
* @publicApi
@ -19,6 +21,9 @@ export class SimpleChange {
constructor(public previousValue: any, public currentValue: any, public firstChange: boolean) {}
/**
* Check whether the new value is the first value assigned.
*
* 检查新值是否是首次赋值的。
*
*/
isFirstChange(): boolean {
return this.firstChange;
@ -30,6 +35,8 @@ export class SimpleChange {
* at the declared property name they belong to on a Directive or Component. This is
* the type passed to the `ngOnChanges` hook.
*
* 用 {@link SimpleChange} 对象表示的变更的哈希表，这些对象以声明的属性名称存储在指令或组件上，这些属性属于它们。这是传递给 `ngOnChanges` 钩子的类型。
*
* @see `OnChanges`
*
* @publicApi

6
packages/core/src/interface/type.ts
View File

@ -11,9 +11,13 @@
*
* Represents a type that a Component or other object is instances of.
*
* 表示 Component 或其他对象的类型。
*
* An example of a `Type` is `MyCustomComponent` class, which in JavaScript is represented by
* the `MyCustomComponent` constructor function.
*
* `Type` 的例子之一是 `MyCustomComponent` 类，该类在 JavaScript 中由 `MyCustomComponent` 构造函数表示。
*
* @publicApi
*/
export const Type = Function;
@ -28,6 +32,8 @@ export function isType(v: any): v is Type<any> {
* Represents an abstract class `T`, if applied to a concrete class it would stop being
* instantiable.
*
* 表示抽象类 `T`，如果将其应用于具体类，它将无法被实例化。
*
* @publicApi
*/
export interface AbstractType<T> extends Function {

33
packages/core/src/linker/compiler.ts
View File

@ -25,6 +25,8 @@ import {NgModuleFactory} from './ng_module_factory';
/**
* Combination of NgModuleFactory and ComponentFactorys.
*
* NgModuleFactory 和一些 ComponentFactory 的组合。
*
* @publicApi
*/
export class ModuleWithComponentFactories<T> {
@ -88,10 +90,14 @@ const Compiler_compileModuleAndAllComponentsAsync =
* to create {@link ComponentFactory}s, which
* can later be used to create and render a Component instance.
*
* 本底层服务用于供 Angular 编译器在运行期间创建 {@link ComponentFactory}，该工厂以后可用于创建和渲染组件实例。
*
* Each `@NgModule` provides an own `Compiler` to its injector,
* that will use the directives/pipes of the ng module for compilation
* of components.
*
* 每个 `@NgModule` 为其注入器提供一个自己的编译器，它将使用此 NgModule 的指令/管道来编译组件。
*
* @publicApi
*/
@Injectable()
@ -99,39 +105,60 @@ export class Compiler {
/**
* Compiles the given NgModule and all of its components. All templates of the components listed
* in `entryComponents` have to be inlined.
*
* 编译给定的 NgModule 及其所有组件。必须内联 `entryComponents` 列出的组件的所有模板。
*
*/
compileModuleSync: <T>(moduleType: Type<T>) => NgModuleFactory<T> = Compiler_compileModuleSync;
/**
* Compiles the given NgModule and all of its components
*
* 编译给定的 NgModule 及其所有组件
*
*/
compileModuleAsync:
<T>(moduleType: Type<T>) => Promise<NgModuleFactory<T>> = Compiler_compileModuleAsync;
/**
* Same as {@link #compileModuleSync} but also creates ComponentFactories for all components.
*
* 与 {@link #compileModuleSync} 相同，但还会为所有组件创建 ComponentFactory。
*
*/
compileModuleAndAllComponentsSync: <T>(moduleType: Type<T>) => ModuleWithComponentFactories<T> =
Compiler_compileModuleAndAllComponentsSync;
/**
* Same as {@link #compileModuleAsync} but also creates ComponentFactories for all components.
*
* 与 {@link #compileModuleAsync} 相同，但还会为所有组件创建 ComponentFactory。
*
*/
compileModuleAndAllComponentsAsync: <T>(moduleType: Type<T>) =>
Promise<ModuleWithComponentFactories<T>> = Compiler_compileModuleAndAllComponentsAsync;
/**
* Clears all caches.
*
* 清除所有缓存。
*
*/
clearCache(): void {}
/**
* Clears the cache for the given component/ngModule.
*
* 清除给定组件/ngModule 的缓存。
*
*/
clearCacheFor(type: Type<any>) {}
/**
* Returns the id for a given NgModule, if one is defined and known to the compiler.
*
* 返回给定 NgModule 的 ID（如果已定义且对编译器已知）。
*
*/
getModuleId(moduleType: Type<any>): string|undefined {
return undefined;
@ -141,6 +168,8 @@ export class Compiler {
/**
* Options for creating a compiler
*
* 用于创建编译器的选项
*
* @publicApi
*/
export type CompilerOptions = {
@ -154,6 +183,8 @@ export type CompilerOptions = {
/**
* Token to provide CompilerOptions in the platform injector.
*
* 在平台注入器中提供 CompilerOptions 的令牌。
*
* @publicApi
*/
export const COMPILER_OPTIONS = new InjectionToken<CompilerOptions[]>('compilerOptions');
@ -161,6 +192,8 @@ export const COMPILER_OPTIONS = new InjectionToken<CompilerOptions[]>('compilerO
/**
* A factory for creating a Compiler
*
* 用于创建编译器的工厂
*
* @publicApi
*/
export abstract class CompilerFactory {

51
packages/core/src/linker/component_factory.ts
View File

@ -19,50 +19,79 @@ import {ViewRef} from './view_ref';
* Provides access to the component instance and related objects,
* and provides the means of destroying the instance.
*
* 表示由 `ComponentFactory` 创建的组件。提供对组件实例和相关对象的访问，并提供销毁实例的方法。
*
* @publicApi
*/
export abstract class ComponentRef<C> {
/**
* The host or anchor [element](guide/glossary#element) for this component instance.
*
* 此组件实例的宿主或锚点[元素](guide/glossary#element)。
*
*/
abstract get location(): ElementRef;
/**
* The [dependency injector](guide/glossary#injector) for this component instance.
*
* 此组件实例的[依赖项注入器](guide/glossary#injector)。
*
*/
abstract get injector(): Injector;
/**
* This component instance.
*
* 该组件实例。
*
*/
abstract get instance(): C;
/**
* The [host view](guide/glossary#view-tree) defined by the template
* for this component instance.
*
* 模板为此组件实例定义的[宿主视图](guide/glossary#view-tree)。
*
*/
abstract get hostView(): ViewRef;
/**
* The change detector for this component instance.
*
* 此组件实例的变更检测器。
*
*/
abstract get changeDetectorRef(): ChangeDetectorRef;
/**
* The type of this component (as created by a `ComponentFactory` class).
*
* 此组件的类型（由 `ComponentFactory` 类创建）。
*
*/
abstract get componentType(): Type<any>;
/**
* Destroys the component instance and all of the data structures associated with it.
*
* 销毁组件实例以及与其关联的所有数据结构。
*
*/
abstract destroy(): void;
/**
* A lifecycle hook that provides additional developer-defined cleanup
* functionality for the component.
*
* 一个生命周期钩子，为组件提供其他由开发人员定义的清理功能。
*
* @param callback A handler function that cleans up developer-defined data
* associated with this component. Called when the `destroy()` method is invoked.
*
* 一个处理器函数，用于清理与此组件关联的由开发人员定义的数据。在调用 `destroy()` 方法时调用。
*
*/
abstract onDestroy(callback: Function): void;
}
@ -72,33 +101,55 @@ export abstract class ComponentRef<C> {
* Instantiate a factory for a given type of component with `resolveComponentFactory()`.
* Use the resulting `ComponentFactory.create()` method to create a component of that type.
*
* 可用来动态创建组件的工厂的基类。`resolveComponentFactory()` 实例化给定类型的组件的工厂。使用生成的 `ComponentFactory.create()` 方法创建该类型的组件。
*
* @see [Dynamic Components](guide/dynamic-component-loader)
*
* [动态组件](guide/dynamic-component-loader)
*
* @publicApi
*/
export abstract class ComponentFactory<C> {
/**
* The component's HTML selector.
*
* 组件的 HTML 选择器。
*
*/
abstract get selector(): string;
/**
* The type of component the factory will create.
*
* 工厂将创建的组件的类型。
*
*/
abstract get componentType(): Type<any>;
/**
* Selector for all <ng-content> elements in the component.
*
* 组件中所有 <ng-content> 元素的选择器。
*
*/
abstract get ngContentSelectors(): string[];
/**
* The inputs of the component.
*
* 组件的输入。
*
*/
abstract get inputs(): {propName: string, templateName: string}[];
/**
* The outputs of the component.
*
* 组件的输出。
*
*/
abstract get outputs(): {propName: string, templateName: string}[];
/**
* Creates a new component.
*
* 创建一个新组件。
*
*/
abstract create(
injector: Injector, projectableNodes?: any[][], rootSelectorOrNode?: string|any,

11
packages/core/src/linker/component_factory_resolver.ts
View File

@ -39,14 +39,25 @@ class _NullComponentFactoryResolver implements ComponentFactoryResolver {
* Use to obtain the factory for a given component type,
* then use the factory's `create()` method to create a component of that type.
*
* 一个简单的注册表，它将 `Components` 映射到生成的 `ComponentFactory` 类，该类可用于创建组件的实例。用于获取给定组件类型的工厂，然后使用工厂的 `create()` 方法创建该类型的组件。
*
* @see [Dynamic Components](guide/dynamic-component-loader)
*
* [动态组件](guide/dynamic-component-loader)
*
* @publicApi
*/
export abstract class ComponentFactoryResolver {
static NULL: ComponentFactoryResolver = new _NullComponentFactoryResolver();
/**
* Retrieves the factory object that creates a component of the given type.
*
* 检索能创建给定类型的组件的工厂对象。
*
* @param component The component type.
*
* 组件类型。
*
*/
abstract resolveComponentFactory<T>(component: Type<T>): ComponentFactory<T>;
}

17
packages/core/src/linker/ng_module_factory.ts
View File

@ -16,32 +16,49 @@ import {ComponentFactoryResolver} from './component_factory_resolver';
* Represents an instance of an `NgModule` created by an `NgModuleFactory`.
* Provides access to the `NgModule` instance and related objects.
*
* `NgModule` 创建的 `NgModuleFactory` 的实例。提供对 `NgModule` 实例和相关对象的访问。
*
* @publicApi
*/
export abstract class NgModuleRef<T> {
/**
* The injector that contains all of the providers of the `NgModule`.
*
* 包含 `NgModule` 所有提供者的注入器。
*
*/
abstract get injector(): Injector;
/**
* The resolver that can retrieve the component factories
* declared in the `entryComponents` property of the module.
*
* 此解析器可以检索本模块的 `entryComponents` 属性中声明的组件工厂。
*
*/
abstract get componentFactoryResolver(): ComponentFactoryResolver;
/**
* The `NgModule` instance.
*
* `NgModule` 实例。
*
*/
abstract get instance(): T;
/**
* Destroys the module instance and all of the data structures associated with it.
*
* 销毁模块实例以及与其关联的所有数据结构。
*
*/
abstract destroy(): void;
/**
* Registers a callback to be executed when the module is destroyed.
*
* 注册一个销毁模块时要执行的回调。
*
*/
abstract onDestroy(callback: () => void): void;
}

8
packages/core/src/linker/ng_module_factory_loader.ts
View File

@ -16,9 +16,14 @@ import {getRegisteredNgModuleType} from './ng_module_factory_registration';
/**
* Used to load ng module factories.
*
* 用来加载 ng 模块工厂。
*
* @publicApi
* @deprecated the `string` form of `loadChildren` is deprecated, and `NgModuleFactoryLoader` is
* part of its implementation. See `LoadChildren` for more details.
*
* 不建议使用 `loadChildren` 的 `string` 形式，`NgModuleFactoryLoader` 是其实现的一部分。欲知详情，请参见 `LoadChildren`
*
*/
export abstract class NgModuleFactoryLoader {
abstract load(path: string): Promise<NgModuleFactory<any>>;
@ -40,6 +45,9 @@ export function getModuleFactory__POST_R3__(id: string): NgModuleFactory<any> {
* Returns the NgModuleFactory with the given id, if it exists and has been loaded.
* Factories for modules that do not specify an `id` cannot be retrieved. Throws if the module
* cannot be found.
*
* 返回具有给定 id 的 NgModuleFactory（如果存在并且已加载）。无法检索未指定过 `id` 的模块工厂。如果找不到模块，则抛出该异常。
*
* @publicApi
*/
export const getModuleFactory: (id: string) => NgModuleFactory<any> = getModuleFactory__PRE_R3__;

3
packages/core/src/linker/ng_module_factory_registration.ts
View File

@ -25,6 +25,9 @@ const modules = new Map<string, NgModuleFactory<any>|NgModuleType>();
/**
* Registers a loaded module. Should only be called from generated NgModuleFactory code.
*
* 注册已加载的模块。仅应从生成的 NgModuleFactory 代码中调用。
*
* @publicApi
*/
export function registerModuleFactory(id: string, factory: NgModuleFactory<any>) {

14
packages/core/src/linker/query_list.ts
View File

@ -42,6 +42,7 @@ function symbolIterator<T>(this: QueryList<T>): Iterator<T> {
* 注意：将来此类将会实现 `Observable` 接口。
*
* @usageNotes
*
* ### Example
*
* ### 例子
@ -78,6 +79,9 @@ export class QueryList<T> implements Iterable<T> {
/**
* Returns the QueryList entry at `index`.
*
* 返回位于 `index` 处的 QueryList 条目。
*
*/
get(index: number): T|undefined {
return this._results[index];
@ -145,6 +149,9 @@ export class QueryList<T> implements Iterable<T> {
/**
* Returns a copy of the internal results list as an Array.
*
* 以数组形式返回内部结果列表的副本。
*
*/
toArray(): T[] {
return this._results.slice();
@ -159,7 +166,11 @@ export class QueryList<T> implements Iterable<T> {
* on change detection, it will not notify of changes to the queries, unless a new change
* occurs.
*
* 更新查询列表中存储的数据，并将 `dirty` 标志重置为 `false`，以便当检测到变更时，除非发生新变更，否则不会通知这些查询的变更。
*
* @param resultsTree The query results to store
*
* 要存储的查询结果
*/
reset(resultsTree: Array<T|any[]>): void {
this._results = flatten(resultsTree);
@ -171,6 +182,9 @@ export class QueryList<T> implements Iterable<T> {
/**
* Triggers a change event by emitting on the `changes` {@link EventEmitter}.
*
* 通过发出 `changes` {@link EventEmitter} 来触发变更事件。
*
*/
notifyOnChanges(): void {
(this.changes as EventEmitter<any>).emit(this);

17
packages/core/src/linker/system_js_ng_module_factory_loader.ts
View File

@ -23,19 +23,30 @@ declare var System: any;
* Configuration for SystemJsNgModuleLoader.
* token.
*
* SystemJsNgModuleLoader 的配置。令牌。
*
* @publicApi
* @deprecated the `string` form of `loadChildren` is deprecated, and `SystemJsNgModuleLoaderConfig`
* is part of its implementation. See `LoadChildren` for more details.
*
* 不推荐使用 `loadChildren` 的 `string` 形式 `SystemJsNgModuleLoaderConfig` 是其实现的一部分。有关更多详细信息，请参见 `LoadChildren`
*
*/
export abstract class SystemJsNgModuleLoaderConfig {
/**
* Prefix to add when computing the name of the factory module for a given module name.
*
* 计算给定模块名称的工厂模块名称时添加的前缀。
*
*/
// TODO(issue/24571): remove '!'.
factoryPathPrefix!: string;
/**
* Suffix to add when computing the name of the factory module for a given module name.
*
* 计算给定模块名称的工厂模块名称时添加的后缀。
*
*/
// TODO(issue/24571): remove '!'.
factoryPathSuffix!: string;
@ -48,9 +59,15 @@ const DEFAULT_CONFIG: SystemJsNgModuleLoaderConfig = {
/**
* NgModuleFactoryLoader that uses SystemJS to load NgModuleFactory
*
* 使用 SystemJS 加载 NgModuleFactory 的 NgModuleFactoryLoader
*
* @publicApi
* @deprecated the `string` form of `loadChildren` is deprecated, and `SystemJsNgModuleLoader` is
* part of its implementation. See `LoadChildren` for more details.
*
* 该 `string` 的形式 `loadChildren` 已被弃用， `SystemJsNgModuleLoader` 是其实现的一部分。有关更多详细信息，请参见 `LoadChildren`
*
*/
@Injectable()
export class SystemJsNgModuleLoader implements NgModuleFactoryLoader {

7
packages/core/src/linker/view_container_ref.ts
View File

@ -88,7 +88,12 @@ export abstract class ViewContainerRef {
*/
abstract get injector(): Injector;
/** @deprecated No replacement */
/**
* @deprecated No replacement
*
* 无替代品
*
*/
abstract get parentInjector(): Injector;
/**

35
packages/core/src/linker/view_ref.ts
View File

@ -11,6 +11,8 @@ import {ChangeDetectorRef} from '../change_detection/change_detector_ref';
/**
* Represents an Angular [view](guide/glossary#view "Definition").
*
* 表示一个 Angular [视图](guide/glossary#view "Definition")。
*
* @see {@link ChangeDetectorRef#usage-notes Change detection usage}
*
* @publicApi
@ -18,20 +20,35 @@ import {ChangeDetectorRef} from '../change_detection/change_detector_ref';
export abstract class ViewRef extends ChangeDetectorRef {
/**
* Destroys this view and all of the data structures associated with it.
*
* 销毁该视图以及与之关联的所有数据结构。
*
*/
abstract destroy(): void;
/**
* Reports whether this view has been destroyed.
*
* 报告此视图是否已被销毁。
*
* @returns True after the `destroy()` method has been called, false otherwise.
*
* 调用 `destroy()` 方法后为 true，否则为 false。
*
*/
abstract get destroyed(): boolean;
/**
* A lifecycle hook that provides additional developer-defined cleanup
* functionality for views.
*
* 生命周期钩子，为视图提供其他由开发人员定义的清理功能。
*
* @param callback A handler function that cleans up developer-defined data
* associated with a view. Called when the `destroy()` method is invoked.
*
* 处理函数，用于清理与视图关联的由开发人员定义的数据。在调用 `destroy()` 方法时调用。
*
*/
abstract onDestroy(callback: Function): any /** TODO #9100 */;
}
@ -42,10 +59,14 @@ export abstract class ViewRef extends ChangeDetectorRef {
* other than the hosting component whose template defines it, or it can be defined
* independently by a `TemplateRef`.
*
* 表示视图容器中的 Angular [视图](guide/glossary#view)。[嵌入视图](guide/glossary#view-tree)可以从在模板中定义它的宿主组件之外的组件中引用，也可以由 `TemplateRef` 进行独立定义。
*
* Properties of elements in a view can change, but the structure (number and order) of elements in
* a view cannot. Change the structure of elements by inserting, moving, or
* removing nested views in a view container.
*
* 视图中元素的属性可以更改，但是视图中元素的结构（数量和顺序）不能更改。通过在视图容器中插入，移动或删除嵌套视图来更改元素的结构。
*
* @see `ViewContainerRef`
*
* @usageNotes
@ -53,6 +74,8 @@ export abstract class ViewRef extends ChangeDetectorRef {
* The following template breaks down into two separate `TemplateRef` instances,
* an outer one and an inner one.
*
* 以下模板分为两个单独的 `TemplateRef` 实例，一个外部实例和一个内部实例。
*
* ```
* Count: {{items.length}}
* <ul>
@ -62,6 +85,8 @@ export abstract class ViewRef extends ChangeDetectorRef {
*
* This is the outer `TemplateRef`:
*
* 这是外部 `TemplateRef` ：
*
* ```
* Count: {{items.length}}
* <ul>
@ -71,12 +96,16 @@ export abstract class ViewRef extends ChangeDetectorRef {
*
* This is the inner `TemplateRef`:
*
* 这是内部的 `TemplateRef` ：
*
* ```
* <li>{{item}}</li>
* ```
*
* The outer and inner `TemplateRef` instances are assembled into views as follows:
*
* 外部和内部 `TemplateRef` 实例按如下方式组装到视图中：
*
* ```
* <!-- ViewRef: outer-0 -->
* Count: 2
@ -92,11 +121,17 @@ export abstract class ViewRef extends ChangeDetectorRef {
export abstract class EmbeddedViewRef<C> extends ViewRef {
/**
* The context for this view, inherited from the anchor element.
*
* 该视图的上下文，继承自锚点元素。
*
*/
abstract get context(): C;
/**
* The root nodes for this embedded view.
*
* 此嵌入式视图的根节点。
*
*/
abstract get rootNodes(): any[];
}

97
packages/core/src/metadata/di.ts
View File

@ -17,12 +17,16 @@ import {makePropDecorator} from '../util/decorators';
* All components that are referenced in the `useValue` value (either directly
* or in a nested array or map) are added to the `entryComponents` property.
*
* 可用于创建虚拟[提供者](guide/glossary#provider)的 DI 令牌，该虚拟提供者将基于其 `useValue` 属性值填充组件和 NgModule 的 `entryComponents` 字段。`useValue` 值中引用的所有组件（无论是直接还是在嵌套数组还是在映射表中）都将添加到 `entryComponents` 属性。
*
* @usageNotes
*
* The following example shows how the router can populate the `entryComponents`
* field of an NgModule based on a router configuration that refers
* to components.
*
* 以下示例演示了路由器如何基于引用组件的路由器配置设置 `entryComponents` 字段。
*
* ```typescript
* // helper function inside the router
* function provideRoutes(routes) {
@ -46,30 +50,42 @@ import {makePropDecorator} from '../util/decorators';
*
* @publicApi
* @deprecated Since 9.0.0. With Ivy, this property is no longer necessary.
*
* 从 9.0.0 开始。使用 Ivy，不再需要此属性。
*/
export const ANALYZE_FOR_ENTRY_COMPONENTS = new InjectionToken<any>('AnalyzeForEntryComponents');
/**
* Type of the `Attribute` decorator / constructor function.
*
* `Attribute` 装饰器/构造函数的类型。
*
* @publicApi
*/
export interface AttributeDecorator {
/**
* Specifies that a constant attribute value should be injected.
*
* 指定应注入的常量属性值。
*
* The directive can inject constant string literals of host element attributes.
*
* 该指令可以注入宿主元素属性的字符串字面常量。
*
* @usageNotes
*
* Suppose we have an `<input>` element and want to know its `type`.
*
* 假设我们有一个 `<input>` 元素，并且想知道它的 `type` 。
*
* ```html
* <input type="text">
* ```
*
* A decorator can inject string literal `text` as in the following example.
*
* 装饰器可以注入字符串字面量 `text` ，如下面的例子。
*
* {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
*
* @publicApi
@ -82,11 +98,16 @@ export interface AttributeDecorator {
/**
* Type of the Attribute metadata.
*
* 属性元数据的类型。
*
* @publicApi
*/
export interface Attribute {
/**
* The name of the attribute to be injected into the constructor.
*
* 要注入到构造函数中的属性的名称。
*
*/
attributeName?: string;
}
@ -94,6 +115,8 @@ export interface Attribute {
/**
* Type of the Query metadata.
*
* 查询元数据的类型。
*
* @publicApi
*/
export interface Query {
@ -108,6 +131,8 @@ export interface Query {
/**
* Base class for query metadata.
*
* 查询元数据的基类。
*
* @see `ContentChildren`.
* @see `ContentChild`.
* @see `ViewChildren`.
@ -120,6 +145,8 @@ export abstract class Query {}
/**
* Type of the ContentChildren decorator / constructor function.
*
* ContentChildren 装饰器/构造函数的类型。
*
* @see `ContentChildren`.
* @publicApi
*/
@ -127,25 +154,45 @@ export interface ContentChildrenDecorator {
/**
* Parameter decorator that configures a content query.
*
* 用于配置内容查询的参数装饰器。
*
* Use to get the `QueryList` of elements or directives from the content DOM.
* Any time a child element is added, removed, or moved, the query list will be
* updated, and the changes observable of the query list will emit a new value.
*
* 用于从内容 DOM 中获取元素或指令的 `QueryList`。每当添加、删除或移动子元素时，此查询列表都会更新，并且其可观察对象 changes 都会发出新值。
*
* Content queries are set before the `ngAfterContentInit` callback is called.
*
* 在调用 `ngAfterContentInit` 回调之前设置的内容查询。
*
* Does not retrieve elements or directives that are in other components' templates,
* since a component's template is always a black box to its ancestors.
*
* 不检索其他组件模板中的元素或指令，因为组件模板对其祖先来说始终是黑匣子。
*
* **Metadata Properties**:
*
* **元数据属性**：
*
* * **selector** - The directive type or the name used for querying.
*
* **selector** - 要查询的指令类型或名称。
*
* * **descendants** - True to include all descendants, otherwise include only direct children.
*
* **后代** - 包含所有后代时为 true，否则仅包括直接子代。
*
* * **read** - Used to read a different token from the queried elements.
*
* **read** - 用于从查询到的元素中读取不同的令牌。
*
* @usageNotes
*
* Here is a simple demonstration of how the `ContentChildren` decorator can be used.
*
* 这里是如何使用 `ContentChildren` 装饰器的简单演示。
*
* {@example core/di/ts/contentChildren/content_children_howto.ts region='HowTo'}
*
* ### Tab-pane example
@ -166,6 +213,7 @@ export interface ContentChildrenDecorator {
/**
* Type of the ContentChildren metadata.
*
* ContentChildren 元数据的类型。
*
* @Annotation
* @publicApi
@ -175,6 +223,7 @@ export type ContentChildren = Query;
/**
* ContentChildren decorator and metadata.
*
* ContentChildren 装饰器和元数据。
*
* @Annotation
* @publicApi
@ -188,28 +237,47 @@ export const ContentChildren: ContentChildrenDecorator = makePropDecorator(
/**
* Type of the ContentChild decorator / constructor function.
*
* ContentChild 装饰器/构造函数的类型。
*
* @publicApi
*/
export interface ContentChildDecorator {
/**
* Parameter decorator that configures a content query.
*
* 用于配置内容查询的参数装饰器。
*
* Use to get the first element or the directive matching the selector from the content DOM.
* If the content DOM changes, and a new child matches the selector,
* the property will be updated.
*
* 用于从内容 DOM 获取与此选择器匹配的第一个元素或指令。如果内容 DOM 发生了更改，并且有一个新的子项与选择器匹配，则该属性将被更新。
*
* Content queries are set before the `ngAfterContentInit` callback is called.
*
* 在调用 `ngAfterContentInit` 之前设置的内容查询。
*
* Does not retrieve elements or directives that are in other components' templates,
* since a component's template is always a black box to its ancestors.
*
* 不检索其他组件模板中的元素或指令，因为组件模板对其祖先来说始终是黑匣子。
*
* **Metadata Properties**:
*
* **元数据属性**：
*
* * **selector** - The directive type or the name used for querying.
*
* **selector** - 要查询的指令类型或名称。
*
* * **read** - Used to read a different token from the queried element.
*
* **read** - 用于从查询到的元素读取不同的令牌。
*
* * **static** - True to resolve query results before change detection runs,
* false to resolve after change detection. Defaults to false.
*
* **static** - 如果为 true，则在变更检测运行之前解析查询结果，如果为 false，则在变更检测之后解析。默认为 false。
* @usageNotes
*
* {@example core/di/ts/contentChild/content_child_howto.ts region='HowTo'}
@ -229,6 +297,8 @@ export interface ContentChildDecorator {
/**
* Type of the ContentChild metadata.
*
* ContentChild 元数据的类型。
*
* @publicApi
*/
export type ContentChild = Query;
@ -236,6 +306,7 @@ export type ContentChild = Query;
/**
* ContentChild decorator and metadata.
*
* ContentChild 装饰器和元数据。
*
* @Annotation
*
@ -250,6 +321,8 @@ export const ContentChild: ContentChildDecorator = makePropDecorator(
/**
* Type of the ViewChildren decorator / constructor function.
*
* ViewChildren 装饰器/构造函数的类型。
*
* @see `ViewChildren`.
*
* @publicApi
@ -258,17 +331,29 @@ export interface ViewChildrenDecorator {
/**
* Parameter decorator that configures a view query.
*
* 用于配置视图查询的参数装饰器。
*
* Use to get the `QueryList` of elements or directives from the view DOM.
* Any time a child element is added, removed, or moved, the query list will be updated,
* and the changes observable of the query list will emit a new value.
*
* 用于从视图 DOM 中获取元素或指令的 `QueryList`。每当添加、删除或移动子元素时，此查询列表都将更新，并且其可观察对象 changes 将发出新值。
*
* View queries are set before the `ngAfterViewInit` callback is called.
*
* 在调用 `ngAfterViewInit` 前设置的视图查询。
*
* **Metadata Properties**:
*
* **元数据属性**：
*
* * **selector** - The directive type or the name used for querying.
*
* **selector** - 要查询的指令类型或名称。
*
* * **read** - Used to read a different token from the queried elements.
*
* **read** - 用于从查询的元素中读取不同的令牌。
* @usageNotes
*
* {@example core/di/ts/viewChildren/view_children_howto.ts region='HowTo'}
@ -287,6 +372,8 @@ export interface ViewChildrenDecorator {
/**
* Type of the ViewChildren metadata.
*
* ViewChildren 元数据的类型。
*
* @publicApi
*/
export type ViewChildren = Query;
@ -294,6 +381,8 @@ export type ViewChildren = Query;
/**
* ViewChildren decorator and metadata.
*
* ViewChildren 装饰器和元数据。
*
* @Annotation
* @publicApi
*/
@ -342,6 +431,8 @@ export interface ViewChildDecorator {
* * **static** - True to resolve query results before change detection runs,
* false to resolve after change detection. Defaults to false.
*
* **static** - 如果为 true，则在变更检测运行之前解析查询结果，如果为 false，则在变更检测之后解析。默认为 false。
*
* The following selectors are supported.
*
* 支持下列选择器：
@ -358,13 +449,13 @@ export interface ViewChildDecorator {
* * Any provider defined in the child component tree of the current component (e.g.
* `@ViewChild(SomeService) someService: SomeService`)
*
* 组件树中任何当前组件的子组件所定义的提供商（比如 `@ViewChild(SomeService) someService: SomeService` ）
* 组件树中任何当前组件的子组件所定义的提供者（比如 `@ViewChild(SomeService) someService: SomeService` ）
*
* * Any provider defined through a string token (e.g. `@ViewChild('someToken') someTokenVal:
* any`)
*
* 任何通过字符串令牌定义的提供商（比如 `@ViewChild('someToken') someTokenVal:
* any` ）
* 任何通过字符串令牌定义的提供者（比如 `@ViewChild('someToken') someTokenVal:
* any`）
*
* * A `TemplateRef` (e.g. query `<ng-template></ng-template>` with `@ViewChild(TemplateRef)
* template;`)

44
packages/core/src/metadata/directives.ts
View File

@ -30,6 +30,8 @@ export interface DirectiveDecorator {
* Decorator that marks a class as an Angular directive.
* You can define your own directives to attach custom behavior to elements in the DOM.
*
* 将类标记为 Angular 指令的装饰器。你可以定义自己的指令，以将自定义行为附加到 DOM 中的元素。
*
* The options provide configuration metadata that determines
* how the directive should be processed, instantiated and used at
* runtime.
@ -44,6 +46,7 @@ export interface DirectiveDecorator {
*
*
* @usageNotes
*
* To define a directive, mark the class with the decorator and provide metadata.
*
* 要想定义一个指令，请为该类加上此装饰器，并提供元数据。
@ -99,6 +102,8 @@ export interface DirectiveDecorator {
/**
* Directive decorator and metadata.
*
* 指令装饰器和元数据。
*
* @Annotation
* @publicApi
*/
@ -302,7 +307,6 @@ export interface Directive {
* View queries are set before the `ngAfterViewInit` callback is called.
*
* 内容查询会在调用 `ngAfterContentInit` 回调之前设置好。
* 试图查询会在调用 `ngAfterViewInit` 回调之前设置好。
*
* @usageNotes
*
@ -387,6 +391,9 @@ export interface Directive {
* It remains in distributed code, and the JIT compiler attempts to compile it
* at run time, in the browser.
* To ensure the correct behavior, the app must import `@angular/compiler`.
*
* 如果存在，则该指令/组件将被 AOT 编译器忽略。它会保留在发布代码中，并且 JIT 编译器会尝试在运行时在浏览器中对其进行编译。为了确保其行为正确，该应用程序必须导入 `@angular/compiler` 。
*
*/
jit?: true;
}
@ -470,12 +477,12 @@ export interface ComponentDecorator {
*
* ### Injecting a class with a view provider
*
* ### 使用视图提供商注入一个类
* ### 使用视图提供者注入一个类
*
* The following simple example injects a class into a component
* using the view provider specified in component metadata:
*
* 下面的例子示范了如何在组件元数据中使用视图提供商来把一个类注入到组件中：
* 下面的例子示范了如何在组件元数据中使用视图提供者来把一个类注入到组件中：
*
* ```ts
* class Greeter {
@ -684,6 +691,9 @@ export interface Component extends Directive {
*
* - `ViewEncapsulation.None`: Use global CSS without any
* encapsulation.
*
* `ViewEncapsulation.None` ：使用不带任何封装的全局 CSS。
*
* - `ViewEncapsulation.ShadowDom`: Use Shadow DOM v1 to encapsulate styles.
*
* `ViewEncapsulation.None`：使用全局 CSS，不做任何封装。
@ -716,6 +726,9 @@ export interface Component extends Directive {
* 一个组件的集合，它应该和当前组件一起编译。对于这里列出的每个组件，Angular 都会创建一个 {@link ComponentFactory} 并保存进 {@link ComponentFactoryResolver} 中。
*
* @deprecated Since 9.0.0. With Ivy, this property is no longer necessary.
*
* 从 9.0.0 开始。使用 Ivy，不再需要此属性。
*
*/
entryComponents?: Array<Type<any>|any[]>;
@ -756,22 +769,32 @@ export interface PipeDecorator {
*
* Decorator that marks a class as pipe and supplies configuration metadata.
*
* 本装饰器用于将类标记为管道并提供配置元数据。
*
* A pipe class must implement the `PipeTransform` interface.
* For example, if the name is "myPipe", use a template binding expression
* such as the following:
*
* 管道类必须实现 `PipeTransform` 接口。例如，如果其名称为 “myPipe”，则使用模板绑定表达式，例如：
*
* ```
* {{ exp | myPipe }}
* ```
*
* The result of the expression is passed to the pipe's `transform()` method.
*
* 此表达式的结果会传给管道的 `transform()` 方法。
*
* A pipe must belong to an NgModule in order for it to be available
* to a template. To make it a member of an NgModule,
* list it in the `declarations` field of the `NgModule` metadata.
*
* 管道必须属于某个 NgModule，才能用于模板。要使其成为 NgModule 的成员，请把它加入 `NgModule` 元数据的 `declarations` 中。
*
* @see [Style Guide: Pipe Names](guide/styleguide#02-09)
*
* [样式指南：管道名称](guide/styleguide#02-09)
*
*/
(obj: Pipe): TypeDecorator;
@ -884,6 +907,8 @@ export interface InputDecorator {
* ```
*
* @see [Input and Output properties](guide/inputs-outputs)
*
* [输入和输出属性](guide/inputs-outputs)
*/
(bindingPropertyName?: string): any;
new(bindingPropertyName?: string): any;
@ -944,6 +969,8 @@ export interface OutputDecorator {
*
* @see [Input and Output properties](guide/inputs-outputs)
*
* [输入和输出属性](guide/inputs-outputs)
*
*/
(bindingPropertyName?: string): any;
new(bindingPropertyName?: string): any;
@ -959,6 +986,9 @@ export interface OutputDecorator {
export interface Output {
/**
* The name of the DOM property to which the output property is bound.
*
* 输出属性绑定到的 DOM 属性的名称。
*
*/
bindingPropertyName?: string;
}
@ -1029,6 +1059,9 @@ export interface HostBindingDecorator {
export interface HostBinding {
/**
* The DOM property that is bound to a data property.
*
* 要绑定到数据属性的 DOM 属性。
*
*/
hostPropertyName?: string;
}
@ -1052,6 +1085,9 @@ export interface HostListenerDecorator {
/**
* Decorator that declares a DOM event to listen for,
* and provides a handler method to run when that event occurs.
*
* 一个装饰器，用于声明要监听的 DOM 事件，并提供在该事件发生时要运行的处理器方法。
*
*/
(eventName: string, args?: string[]): any;
new(eventName: string, args?: string[]): any;
@ -1084,6 +1120,8 @@ export interface HostListener {
* Angular invokes the supplied handler method when the host element emits the specified event,
* and updates the bound element with the result.
*
* 将 DOM 事件绑定到宿主监听器并提供配置元数据的装饰器。当宿主元素发出指定事件时，Angular 就会调用所提供的处理器方法，并使用其结果更新绑定的元素。
*
* If the handler method returns false, applies `preventDefault` on the bound element.
*
* 把一个事件绑定到一个宿主监听器，并提供配置元数据。

3
packages/core/src/metadata/do_boostrap.ts
View File

@ -14,11 +14,14 @@ import {ApplicationRef} from '../application_ref';
* Hook for manual bootstrapping of the application instead of using bootstrap array in @NgModule
* annotation.
*
* 挂钩以手动引导应用程序，而不是在 @NgModule 标记中的 bootstrap 数组。
*
* Reference to the current application is provided as a parameter.
*
* See ["Bootstrapping"](guide/bootstrapping) and ["Entry components"](guide/entry-components).
*
* @usageNotes
*
* ```typescript
* class AppModule implements DoBootstrap {
* ngDoBootstrap(appRef: ApplicationRef) {

18
packages/core/src/metadata/ng_module.ts
View File

@ -31,6 +31,8 @@ export type ɵɵNgModuleDefWithMeta<T, Declarations, Imports, Exports> = NgModul
*
* @see [Deprecations](guide/deprecations#modulewithproviders-type-without-a-generic)
*
* [弃用](guide/deprecations#modulewithproviders-type-without-a-generic)
*
* @publicApi
*/
export interface ModuleWithProviders<T> {
@ -72,8 +74,13 @@ export interface NgModule {
* 在当前模块的注入器中可用的一组可注入对象。
*
* @see [Dependency Injection guide](guide/dependency-injection)
*
* [依赖注入指南](guide/dependency-injection)
*
* @see [NgModule guide](guide/providers)
*
* [NgModule 指南](guide/providers)
*
* @usageNotes
*
* Dependencies whose providers are listed here become available for injection
@ -81,7 +88,7 @@ export interface NgModule {
* The NgModule used for bootstrapping uses the root injector, and can provide dependencies
* to any part of the app.
*
* 在这里列出了提供商的依赖项可用于注入到任何组件、指令、管道或该注入器下的服务。
* 在这里列出了提供者的依赖项可用于注入到任何组件、指令、管道或该注入器下的服务。
* 引导用的 NgModule 使用的是根注入器，可以为应用中的任何部件提供依赖。
*
* A lazy-loaded module has its own injector, typically a child of the app root injector.
@ -274,7 +281,13 @@ export interface NgModule {
* 该选项用于添加那些需要写代码来创建的组件，比如 `ViewContainerRef.createComponent()`。
*
* @see [Entry Components](guide/entry-components)
*
* [入口组件](guide/entry-components)
*
* @deprecated Since 9.0.0. With Ivy, this property is no longer necessary.
*
* 从 9.0.0 开始。使用 Ivy，不再需要此属性。
*
*/
entryComponents?: Array<Type<any>|any[]>;
@ -321,6 +334,9 @@ export interface NgModule {
* It remains in distributed code, and the JIT compiler attempts to compile it
* at run time, in the browser.
* To ensure the correct behavior, the app must import `@angular/compiler`.
*
* 如果存在，则该指令/组件将被 AOT 编译器忽略。它会保留在发布代码中，并且 JIT 编译器会尝试在运行时在浏览器中对其进行编译。为了确保其行为正确，该应用程序必须导入 `@angular/compiler` 。
*
*/
jit?: true;
}

14
packages/core/src/metadata/schema.ts
View File

@ -10,10 +10,14 @@
/**
* A schema definition associated with an NgModule.
*
* 与 NgModule 关联的架构定义。
*
* @see `@NgModule`, `CUSTOM_ELEMENTS_SCHEMA`, `NO_ERRORS_SCHEMA`
*
* @param name The name of a defined schema.
*
* 定义的架构的名称。
*
* @publicApi
*/
export interface SchemaMetadata {
@ -22,10 +26,18 @@ export interface SchemaMetadata {
/**
* Defines a schema that allows an NgModule to contain the following:
*
* 定义一个架构，该架构允许 NgModule 包含以下内容：
*
* - Non-Angular elements named with dash case (`-`).
*
* 使用（`-`）命名法的非 Angular 元素。
*
* - Element properties named with dash case (`-`).
* Dash case is the naming convention for custom elements.
*
* 使用（`-`）命名的元素属性。中线命名法是自定义元素的命名约定。
*
* @publicApi
*/
export const CUSTOM_ELEMENTS_SCHEMA: SchemaMetadata = {
@ -35,6 +47,8 @@ export const CUSTOM_ELEMENTS_SCHEMA: SchemaMetadata = {
/**
* Defines a schema that allows any property on any element.
*
* 定义一个架构，该架构允许任何元素上的任何属性。
*
* @publicApi
*/
export const NO_ERRORS_SCHEMA: SchemaMetadata = {

19
packages/core/src/metadata/view.ts
View File

@ -9,11 +9,18 @@
/**
* Defines template and style encapsulation options available for Component's {@link Component}.
*
* 定义可用于 Component 的 {@link Component} 的模板和样式封装选项。
*
* See {@link Component#encapsulation encapsulation}.
*
* 请参阅 {@link Component#encapsulation encapsulation}。
*
* @usageNotes
*
* ### Example
*
* ### 例子
*
* {@example core/ts/metadata/encapsulation.ts region='longform'}
*
* @publicApi
@ -25,7 +32,11 @@ export enum ViewEncapsulation {
* {@link Component#styleUrls styleUrls}, and adding the new Host Element attribute to all
* selectors.
*
* 通过向宿主元素添加包含替代 ID 的属性并预处理通过 {@link Component#styles styles} 或 {@link Component#styleUrls styleUrls} 提供的样式规则，来模拟 `Native` 所有选择器。
*
* This is the default option.
*
* 这是默认选项。
*/
Emulated = 0,
@ -33,15 +44,23 @@ export enum ViewEncapsulation {
/**
* Don't provide any template or style encapsulation.
*
* 不要提供任何模板或样式封装。
*
*/
None = 2,
/**
* Use Shadow DOM to encapsulate styles.
*
* 使用 Shadow DOM 封装样式。
*
* For the DOM this means using modern [Shadow
* DOM](https://w3c.github.io/webcomponents/spec/shadow/) and
* creating a ShadowRoot for Component's Host Element.
*
* 对于 DOM，这意味着使用现代的 [Shadow DOM](https://w3c.github.io/webcomponents/spec/shadow/) 并为组件的 Host 元素创建 ShadowRoot。
*
*/
ShadowDom = 3
}

2
packages/core/src/platform_core_providers.ts
View File

@ -23,6 +23,8 @@ const _CORE_PLATFORM_PROVIDERS: StaticProvider[] = [
/**
* This platform has to be included in any other platform
*
* 任何其他平台都必须包含此平台
*
* @publicApi
*/
export const platformCore = createPlatformFactory(null, 'core', _CORE_PLATFORM_PROVIDERS);

29
packages/core/src/render/api.ts
View File

@ -22,27 +22,53 @@ export const Renderer2Interceptor = new InjectionToken<Renderer2[]>('Renderer2In
/**
* Creates and initializes a custom renderer that implements the `Renderer2` base class.
*
* 创建并初始化实现 `Renderer2` 基类的自定义渲染器。
*
* @publicApi
*/
export abstract class RendererFactory2 {
/**
* Creates and initializes a custom renderer for a host DOM element.
*
* 为宿主 DOM 元素创建并初始化自定义渲染器。
*
* @param hostElement The element to render.
*
* 要渲染的元素。
*
* @param type The base class to implement.
*
* 要实现的基类。
*
* @returns The new custom renderer instance.
*
* 新的自定义渲染器实例。
*
*/
abstract createRenderer(hostElement: any, type: RendererType2|null): Renderer2;
/**
* A callback invoked when rendering has begun.
*
* 渲染开始时调用的回调。
*
*/
abstract begin?(): void;
/**
* A callback invoked when rendering has completed.
*
* 渲染完成时调用的回调。
*
*/
abstract end?(): void;
/**
* Use with animations test-only mode. Notifies the test when rendering has completed.
*
* 与动画的“仅测试”模式一起使用。渲染完成后通知该测试。
*
* @returns The asynchronous result of the developer-defined function.
*
* 由开发人员定义函数的异步结果。
*
*/
abstract whenRenderingDone?(): Promise<any>;
}
@ -182,6 +208,9 @@ export abstract class Renderer2 {
* would always assume that any `insertBefore` is a move. This is not strictly true because
* with runtime i18n it is possible to invoke `insertBefore` as a result of i18n and it should
* not trigger an animation move.
*
* 可选参数，指示当前的 `insertBefore` 是否是移动的结果。动画使用此信息来触发移动动画。过去，Animation 始终假定任何 `insertBefore` 都是一次移动。但严格来说这是不正确的，因为在支持 i18n 的运行环境中，可以调用 `insertBefore`，而不应触发移动动画。
*
*/
abstract insertBefore(parent: any, newChild: any, refChild: any, isMove?: boolean): void;
/**

36
packages/core/src/render/api_flags.ts
View File

@ -12,32 +12,59 @@ import {ViewEncapsulation} from '../metadata/view';
/**
* Used by `RendererFactory2` to associate custom rendering data and styles
* with a rendering implementation.
*
* 供 `RendererFactory2` 用于将自定义渲染数据和样式与某个渲染器的实现相关联。
*
* @publicApi
*/
export interface RendererType2 {
/**
* A unique identifying string for the new renderer, used when creating
* unique styles for encapsulation.
*
* 创建新的封装样式时使用的新渲染器的唯一标识字符串。
*
*/
id: string;
/**
* The view encapsulation type, which determines how styles are applied to
* DOM elements. One of
*
* 视图封装类型，它确定如何将样式应用于 DOM 元素。为下列值之一
*
* - `Emulated` (default): Emulate native scoping of styles.
*
* `Emulated`（默认）：模拟样式的原生作用域。
*
* - `Native`: Use the native encapsulation mechanism of the renderer.
*
* `Native` ：使用渲染器的原生封装机制。
*
* - `ShadowDom`: Use modern [Shadow
* DOM](https://w3c.github.io/webcomponents/spec/shadow/) and
* create a ShadowRoot for component's host element.
*
* `ShadowDom` ：使用现代的 [Shadow DOM](https://w3c.github.io/webcomponents/spec/shadow/) 并为组件的宿主元素创建 ShadowRoot。
*
* - `None`: Do not provide any template or style encapsulation.
*
* `None` ：不提供任何模板或样式封装。
*
*/
encapsulation: ViewEncapsulation;
/**
* Defines CSS styles to be stored on a renderer instance.
*
* 定义要存储在渲染器实例上的 CSS 样式。
*
*/
styles: (string|any[])[];
/**
* Defines arbitrary developer-defined data to be stored on a renderer instance.
* This is useful for renderers that delegate to other renderers.
*
* 定义要存储在渲染器实例上的任意由开发人员定义的数据。这对于要委托其他渲染器实现的渲染器很有用。
*
*/
data: {[kind: string]: any};
}
@ -45,6 +72,9 @@ export interface RendererType2 {
/**
* Flags for renderer-specific style modifiers.
*
* 渲染器特有样式修饰符的标志。
*
* @publicApi
*/
export enum RendererStyleFlags2 {
@ -53,10 +83,16 @@ export enum RendererStyleFlags2 {
// the tests. The work around is to have hard coded value in `node_manipulation.ts` for now.
/**
* Marks a style as important.
*
* 将样式标记为重要。
*
*/
Important = 1 << 0,
/**
* Marks a style as using dash case naming (this-is-dash-case).
*
* 将样式标记为使用中线命名法（this-is-dash-case）。
*
*/
DashCase = 1 << 1
}

Some files were not shown because too many files have changed in this diff Show More