diff --git a/packages/forms/src/directives/ng_model.ts b/packages/forms/src/directives/ng_model.ts index 966bbe04b2..e46b59e367 100644 --- a/packages/forms/src/directives/ng_model.ts +++ b/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.: + *

当输入发生变化时,`ngModel` 会强制运行额外的变更检测,比如:

* ``` *
{{myModel.valid}}
* @@ -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. + *

根据领域对象创建一个 `FormControl` 实例,并把它绑定到一个表单控件元素上。

* * 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 `
` tags, you'll also need to supply a `name` attribute * so that the control can be registered with the parent form under that name. * + * 当在 `` 标签中使用 `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: + *

当前 `ngModel` 实例的配置对象。你可以配置下列属性:

* * **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 * * @@ -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 `` tag that control the display of the form, but don't contain form data. * + * **standalone**:默认为 `false`。如果设置为 `true`,那么 `ngModel` 就不会把自己注册到它的父表单上,其行为就像它没有在表单中一样。 + * 如果要使用表单元控件,这会很方便。表单元控件是指嵌在 `` 标签中的表单元素,它控制表单的显示,但不包含表单数据。 + * * ```html * * @@ -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 * * ```