docs(API): 翻译 ng_model

packages/forms/src/directives/ng_model.ts

@@ -29,6 +29,7 @@ export const formControlBinding: any = {
 /**
  * `ngModel` forces an additional change detection run when its inputs change:
  * E.g.:
+ * <p>当输入发生变化时，`ngModel` 会强制运行额外的变更检测，比如：</p>
  * ```
  * <div>{{myModel.valid}}</div>
  * <input [(ngModel)]="myValue" #myModel="ngModel">
@@ -39,9 +40,22 @@ export const formControlBinding: any = {
  * dirty checked before. As this is a very common case for `ngModel`, we added this second change
  * detection run.
  *
+ * 也就是说，`ngModel` 可以把它自己导出到元素上，然后在模板中使用它。
+ * 通常，这将导致这个 `input` 前面的表达式中使用指令中的旧值，因为刚才它们已经完成了变更检测。
+ * 由于在 `ngModel` 中这是一种很常见的情况，所以我们额外执行了一次变更检测。
+ *
  * Notes:
+ *
+ * 注意：
+ *
  * - this is just one extra run no matter how many `ngModel` have been changed.
+ *
+ *   不管有多少个 `ngModel` 发生了变化，都只会有一轮额外的变更检测。
+ *
  * - this is a general problem when using `exportAs` for directives!
+ *
+ *   当在指令中使用 `exportAs` 时，这是一个常见问题！
+ *
  */
 const resolvedPromise = Promise.resolve(null);
 
@@ -50,21 +64,30 @@ const resolvedPromise = Promise.resolve(null);
  *
  * Creates a `FormControl` instance from a domain model and binds it
  * to a form control element.
+ * <p>根据领域对象创建一个 `FormControl` 实例，并把它绑定到一个表单控件元素上。</p>
  *
  * The `FormControl` instance will track the value, user interaction, and
  * validation status of the control and keep the view synced with the model. If used
  * within a parent form, the directive will also register itself with the form as a child
  * control.
  *
+ * 这个 `FormControl` 实例将会跟踪值、用户交互和控件的验证状态，以保持视图与模型的同步。
+ * 如果用在某个父表单中，该指令还会把自己注册为这个父表单的子控件。
+ *
  * This directive can be used by itself or as part of a larger form. All you need is the
  * `ngModel` selector to activate it.
  *
+ * 这个指令可以单独使用，也可以用作一个大表单的一部分。你所要做的一切就是用 `ngModel` 选择器来激活它。
+ *
  * It accepts a domain model as an optional `Input`. If you have a one-way binding
  * to `ngModel` with `[]` syntax, changing the value of the domain model in the component
  * class will set the value in the view. If you have a two-way binding with `[()]` syntax
  * (also known as 'banana-box syntax'), the value in the UI will always be synced back to
  * the domain model in your class as well.
  *
+ * 它可以接受一个领域模型作为可选的 `Input`。如果使用 `[]` 语法来单向绑定到 `ngModel`，那么在组件类中修改领域模型将会更新视图中的值。
+ * 如果使用 `[()]` 语法来双向绑定到 `ngModel`，那么视图中值的变化同样会随时同步回组件类中的领域模型。
+ *
  * If you wish to inspect the properties of the associated `FormControl` (like
  * validity state), you can also export the directive into a local template variable using
  * `ngModel` as the key (ex: `#myVar="ngModel"`). You can then access the control using the
@@ -72,33 +95,58 @@ const resolvedPromise = Promise.resolve(null);
  * will fall through to the control anyway, so you can access them directly. You can see a
  * full list of properties directly available in `AbstractControlDirective`.
  *
+ * 如果你希望查看与 `FormControl` 相关的属性（比如校验状态），你也可以使用 `ngModel` 作为键，把该指令导出到一个局部模板变量中（如：`#myVar="ngModel"`）。
+ * 你也可以使用该指令的 `control` 属性来访问此控件，实际上你要用到的大多数属性（如 `valid` 和 `dirty`）都会委托给该控件，这样你就可以直接访问这些属性了。
+ * 你可以在 `AbstractControlDirective` 中直接查看这些属性的完整列表。
+ *
  * The following is an example of a simple standalone control using `ngModel`:
  *
+ * 下面是一个在简单的独立控件中使用 `ngModel` 的例子：
+ *
  * {@example forms/ts/simpleNgModel/simple_ng_model_example.ts region='Component'}
  *
  * When using the `ngModel` within `<form>` tags, you'll also need to supply a `name` attribute
  * so that the control can be registered with the parent form under that name.
  *
+ * 当在 `<form>` 标签中使用 `ngModel` 时，你还需要提供一个 `name` 属性，以便该控件可以使用这个名字把自己注册到父表单中。
+ *
  * It's worth noting that in the context of a parent form, you often can skip one-way or
  * two-way binding because the parent form will sync the value for you. You can access
  * its properties by exporting it into a local template variable using `ngForm` (ex:
  * `#f="ngForm"`). Then you can pass it where it needs to go on submit.
  *
+ * 不用太关注父表单的上下文，你通常可以忽略它的单向或双向绑定，因为这个父表单将会为你同步该值。
+ * 你可以使用 `ngForm` 把它导出给一个模板局部变量（如 `#f="ngForm"`），以访问它的属性。
+ * 然后你就可以在提交时把它传给任何需要它的地方了。
+ *
  * If you do need to populate initial values into your form, using a one-way binding for
  * `ngModel` tends to be sufficient as long as you use the exported form's value rather
  * than the domain model's value on submit.
  *
+ * 如果你只是要为表单设置初始值，对 `ngModel` 使用单向绑定就够了。在提交时，你可以使用从表单导出的值，而不必使用领域模型的值。
+ *
  * Take a look at an example of using `ngModel` within a form:
  *
+ * 来看一个在表单中使用 `ngModel` 的例子：
+ *
  * {@example forms/ts/simpleForm/simple_form_example.ts region='Component'}
  *
  * To see `ngModel` examples with different form control types, see:
  *
+ * 要查看不同空间类型的 `ngModel` 范例，参见：
+ *
  * * Radio buttons: `RadioControlValueAccessor`
+ *
+ *   单选按钮组：`RadioControlValueAccessor`
+ *
  * * Selects: `SelectControlValueAccessor`
  *
+ *   下拉框：`SelectControlValueAccessor`
+ *
  * **npm package**: `@angular/forms`
  *
+ * **npm 包**: `@angular/forms`
+ *
  * **NgModule**: `FormsModule`
  *
  *
@@ -123,12 +171,16 @@ export class NgModel extends NgControl implements OnChanges,
 
   /**
    * Options object for this `ngModel` instance. You can configure the following properties:
+   * <p>当前 `ngModel` 实例的配置对象。你可以配置下列属性：</p>
    *
    * **name**: An alternative to setting the name attribute on the form control element.
    * Sometimes, especially with custom form components, the name attribute might be used
    * as an `@Input` property for a different purpose. In cases like these, you can configure
    * the `ngModel` name through this option.
    *
+   * **name**：设置这个表单控件元素名的一个替代方案。有时候，特别是在自定义表单控件上，name 属性可能被作为 `@Input` 属性用作其它目的。
+   * 这时，你就可以通过该选项来配置 `ngModel` 的名字。
+   *
    * ```html
    * <form>
    *   <my-person-control name="Nancy" ngModel [ngModelOptions]="{name: 'user'}">
@@ -142,6 +194,9 @@ export class NgModel extends NgControl implements OnChanges,
    * can be handy if you have form meta-controls, a.k.a. form elements nested in
    * the `<form>` tag that control the display of the form, but don't contain form data.
    *
+   * **standalone**：默认为 `false`。如果设置为 `true`，那么 `ngModel` 就不会把自己注册到它的父表单上，其行为就像它没有在表单中一样。
+   * 如果要使用表单元控件，这会很方便。表单元控件是指嵌在 `<form>` 标签中的表单元素，它控制表单的显示，但不包含表单数据。
+   *
    * ```html
    * <form>
    *   <input name="login" ngModel placeholder="Login">
@@ -153,6 +208,8 @@ export class NgModel extends NgControl implements OnChanges,
    * **updateOn**: Defaults to `'change'`. Defines the event upon which the form control
    * value and validity will update. Also accepts `'blur'` and `'submit'`.
    *
+   * **updateOn**：默认为 `'change'`。用来定义该何时更新表单控件的值和有效性。其它有效值为：`'blur'` 和 `'submit'`。
+   *
    * ```html
    * <input [(ngModel)]="firstName" [ngModelOptions]="{updateOn: 'blur'}">
    * ```