docs(API): 翻译完了 FormControlName

2018-09-04 13:21:25 +08:00 · 2018-09-04 13:21:25 +08:00 · c3ec312159
parent 201976fd31
commit c3ec312159
2 changed files with 67 additions and 1 deletions
--- a/aio/content/translations/cn/api-plan.md
+++ b/aio/content/translations/cn/api-plan.md
@ -53,7 +53,7 @@
 [x]  | forms/FormBuilder  | 0.37
 [x]  | common/http/HttpParams  | 0.35
 [x]  | core/OnChanges  | 0.35
-[ ]  | forms/FormControlName  | 0.34
+[x]  | forms/FormControlName  | 0.34
 [x]  | core/Output  | 0.33
 [ ]  | common/http/HttpInterceptor  | 0.30
 [ ]  | common/http/HttpRequest  | 0.29
--- a/packages/forms/src/directives/reactive_directives/form_control_name.ts
+++ b/packages/forms/src/directives/reactive_directives/form_control_name.ts
@ -33,55 +33,96 @@ export const controlNameBinding: any = {
 * Syncs a `FormControl` in an existing `FormGroup` to a form control
 * element by name.
 *
+ * 根据名字将现有 `FormGroup` 中的 `FormControl` 与一个表单控件进行同步。
+ *
 * This directive ensures that any values written to the `FormControl`
 * instance programmatically will be written to the DOM element (model -> view). Conversely,
 * any values written to the DOM element through user input will be reflected in the
 * `FormControl` instance (view -> model).
 *
+ * 该指令会确保通过程序写入到该 `FormControl` 实例的任何值都会被写入到 DOM 元素上（模型 -> 视图）。
+ * 反过来，任何通过用户输入写入 DOM 元素上的值也会被反映到这个 `FormControl` 实例上（视图 -> 模型）。
+ *
 * This directive is designed to be used with a parent `FormGroupDirective` (selector:
 * `[formGroup]`).
 *
+ * 该指令旨在与父级 `FormGroupDirective`（选择器：`[formGroup]`）协同使用。
+ *
 * It accepts the string name of the `FormControl` instance you want to
 * link, and will look for a `FormControl` registered with that name in the
 * closest `FormGroup` or `FormArray` above it.
 *
+ * 它接受一个想要链接的 `FormControl` 实例的字符串名称，它会在最近的父级 `FormGroup`、`FormArray` 上根据该名称查找这个 `FormControl`。
+ *
 * **Access the control**: You can access the `FormControl` associated with
 * this directive by using the {@link AbstractControl#get get} method.
 * Ex: `this.form.get('first');`
 *
+ * **访问控件**：你可以使用 {@link AbstractControl#get get} 方法访问与此指令关联的`FormControl`。
+ * 例如：`this.form.get('first');`
+ *
 * **Get value**: the `value` property is always synced and available on the `FormControl`.
 * See a full list of available properties in `AbstractControl`.
 *
+ * **获取值**：这个 `value` 属性会一直和这个 `FormControl` 保持同步，并一直可用。
+ * 参见 `AbstractControl` 的所有可用属性的列表。
+ *
 *  **Set value**: You can set an initial value for the control when instantiating the
 *  `FormControl`, or you can set it programmatically later using
 *  {@link AbstractControl#setValue setValue} or {@link AbstractControl#patchValue patchValue}.
 *
+ *  **设置值**：当初始化 `FormControl` 时，可以为该控件设置一个初始值；
+ *  或者稍后也可以使用 {@link AbstractControl#setValue setValue} 或 {@link AbstractControl#patchValue patchValue} 来通过代码设置它。
+ *
 * **Listen to value**: If you want to listen to changes in the value of the control, you can
 * subscribe to the {@link AbstractControl#valueChanges valueChanges} event.  You can also listen to
 * {@link AbstractControl#statusChanges statusChanges} to be notified when the validation status is
 * re-calculated.
 *
+ * **监听值的变化**：如果想监听控件值的变化，你可以订阅 {@link AbstractControl#valueChanges valueChanges} 事件。
+ * 你还可以监听 {@link AbstractControl#statusChanges statusChanges} 以便在验证状态重新计算时得到通知。
+ *
 * ### Example
 *
+ * ### 例子
+ *
 * In this example, we create form controls for first name and last name.
 *
+ * 在这个例子中，我们为名和姓创建了两个表单控件。
+ *
 * {@example forms/ts/simpleFormGroup/simple_form_group_example.ts region='Component'}
 *
 * To see `formControlName` examples with different form control types, see:
 *
+ * 要查看把 `formControlName` 应用于不同类型的表单控件的例子，参见：
+ *
 * * Radio buttons: `RadioControlValueAccessor`
+ *
+ *   单选按钮: `RadioControlValueAccessor`
+ *
 * * Selects: `SelectControlValueAccessor`
 *
+ *   单选下拉框: `SelectControlValueAccessor`
+ *
 * **npm package**: `@angular/forms`
 *
+ * **npm 包**: `@angular/forms`
+ *
 * **NgModule**: `ReactiveFormsModule`
 *
 * ### Use with ngModel
 *
+ * ### 和 ngModel 一起使用
+ *
 * Support for using the `ngModel` input property and `ngModelChange` event with reactive
 * form directives has been deprecated in Angular v6 and will be removed in Angular v7.
 *
+ * 从 Angular v6 开始，已经废弃了在响应式表单中使用使用输入属性 `ngModel` 和事件 `ngModelChange` 的方式，并将在 Angular v7 中移除。
+ *
 * Now deprecated:
+ *
+ * 现已废弃：
+ *
 * ```html
 * <form [formGroup]="form">
 *   <input formControlName="first" [(ngModel)]="value">
@ -100,18 +141,33 @@ export const controlNameBinding: any = {
 * delaying updates with`ngModelOptions` or exporting the directive - simply don't work,
 * which has understandably caused some confusion.
 *
+ * 它被废弃有几个理由。
+ * 首先，一些开发者觉得这种用法让人困惑。它看起来好像是在使用 `ngModel` 指令，
+ * 但实际上它只是响应式表单指令上的一个名叫 `ngModel` 的输入/输出属性，只是在行为上和 `ngModel` 指令有点相似而已。
+ * 特别是，它运行获取 / 设置控件值，并拦截值变更事件。
+ * 不过，不支持 `ngModel` 的某些其它特性 - 比如不能用 `ngModelOptions` 进行延迟修改，也不能导出该指令，
+ * 如果没有理解这一点，就会带来一些困惑。
+ *
 * In addition, this pattern mixes template-driven and reactive forms strategies, which
 * we generally don't recommend because it doesn't take advantage of the full benefits of
 * either strategy. Setting the value in the template violates the template-agnostic
 * principles behind reactive forms, whereas adding a `FormControl`/`FormGroup` layer in
 * the class removes the convenience of defining forms in the template.
 *
+ * 此外，该模式混用了模板驱动表单和响应式表单的策略，我们通常不建议这么实用，因为它无法同时得到这两种策略的全部优点。
+ * 在模板中设置值，违背了响应式表单背后的 "模板无关性" 设计原则；而在类中增加 `FormControl`/`FormGroup` 层次则破坏了在模板中定义表单带来的便利性。
+ *
+ *
 * To update your code before v7, you'll want to decide whether to stick with reactive form
 * directives (and get/set values using reactive forms patterns) or switch over to
 * template-driven directives.
 *
+ * 要在 Angular v7 之前修改你的现有代码，就要决定是钉死在响应式表单指令（并通过响应式表单模式来获取/设置值）或切换到那些模板驱动表单的指令。
+ *
 * After (choice 1 - use reactive forms):
 *
+ * 以后的写法（选择 1 - 使用响应式表单）：
+ *
 * ```html
 * <form [formGroup]="form">
 *   <input formControlName="first">
@ -124,6 +180,8 @@ export const controlNameBinding: any = {
 *
 * After (choice 2 - use template-driven forms):
 *
+ * 以后的写法（选择 2 - 使用模板驱动表单）：
+ *
 * ```html
 * <input [(ngModel)]="value">
 * ```
@ -136,6 +194,9 @@ export const controlNameBinding: any = {
 * mode. You can choose to silence this warning by providing a config for
 * `ReactiveFormsModule` at import time:
 *
+ * 默认情况下，当你使用此模式时，你会在开发模式下看到一个废弃（deprecation）警告。
+ * 你可以在导入 `ReactiveFormsModule` 时提供一个配置项来消除这个警告：
+ *
 * ```ts
 * imports: [
 *   ReactiveFormsModule.withConfig({warnOnNgModelWithFormControl: 'never'});
@ -146,6 +207,8 @@ export const controlNameBinding: any = {
 * pattern with a config value of `"always"`. This may help to track down where in the code
 * the pattern is being used as the code is being updated.
 *
+ * 或者，你也可以选择指定一个配置值 `"always"` 来为每个符合这种模式的实例都单独显示一个警告。
+ * 这会帮助你在修改代码时追踪代码中用到这种模式的所有位置。
 *
 */
@Directive({selector: '[formControlName]', providers: [controlNameBinding]})
@ -174,6 +237,8 @@ export class FormControlName extends NgControl implements OnChanges, OnDestroy {
   * Static property used to track whether any ngModel warnings have been sent across
   * all instances of FormControlName. Used to support warning config of "once".
   *
+   * 静态属性，用于跟踪是否曾在所有的 `FormControlName` 实例中发出过这种 ngModel 警告。用于支持警告选项 `"once"`。
+   *
   * @internal
   */
  static _ngModelWarningSentOnce = false;
@ -182,6 +247,7 @@ export class FormControlName extends NgControl implements OnChanges, OnDestroy {
   * Instance property used to track whether an ngModel warning has been sent out for this
   * particular FormControlName instance. Used to support warning config of "always".
   *
+   * 实例属性，用于跟踪是否曾在特定的 `FormControlName` 实例中发出过这种 ngModel 警告。用于支持警告选项 `"always"`
   * @internal
   */
  _ngModelWarningSent = false;