AngularJS 1.3 新機能 ngModelOptions

AngularJS 1.3.0 で導入された新機能から、ng-model でのモデル更新を調整できる directive の ngModelOptions について取り上げます。

ngModelOptions

すぐに覚えて使ってみるべきオプションは、updateOndebounce ですね。

updateOn

updateOn は、input などの UI に対するどのイベントの場合にモデルを更新するかを指定できます。

1
2
3
<input type="text" name="userName"
    ng-model="user.name"
    ng-model-options="{ updateOn: 'blur' }">

これで、blur(フォーカスが外れる)イベントまでは、この input で入力値を変更してもモデルに反映されなくなります。blur イベントではじめてモデル更新されます。

debounce

debounce は、モデルの更新を待機しておく時間を、ミリ秒単位で指定できます。

1
2
3
<input type="text" name="userName"
    ng-model="user.name"
    ng-model-options="{ debounce: 1000 }">

これで、変更から 1 秒(1,000 ミリ秒)経過後にモデルが更新されるようになります。変更から 1 秒経過するまでに別の変更があった場合には、待機中の更新処理は破棄されます。

複数オプションの指定

ngModelOptions は、以下のように複数のオプションを一度に指定できます。この指定は、モデル更新を 500 ミリ秒遅延させるが、blur イベントのみすぐに更新という意味になります。

1
ng-model-options="{ updateOn: 'default blur', debounce: {'default': 500, 'blur': 0} }"

使用上の注意

ngModelOptions で updateOndebounce を利用すると、input フィールドの入力値と、実際のモデルの値が異なっている状態が増えます。そのため、モデルのほうを変更するときには、関係する input フィールドに対して $rollbackViewValue を呼び出すことで、モデルの値と一致させ、遅延されている更新処理をキャンセルさせます。

$rollbackViewValue function は、userForm.userName.$rollbackViewValue() のように参照して呼び出せます。

submit イベントで更新完了

待機中の更新処理は、submit イベントによって即座に実行されます。ngClick イベントはモデル更新前となるので、更新後のモデルにアクセスしたい場合には ngSubmit を利用します。

ngModelOptions は子孫要素にも適用

ngModelOptions は、input 要素に直接指定するだけでなく、祖先要素となる form などに指定することもできます。

その他のオプション

  • allowInvalid

invalid なモデル値を許容するか、undefined(デフォルト動作)にするかを boolean で指定。

  • getterSetter

getters/setters として ngModel に function をバインドするかを boolean で指定。

  • timezone

<input type="date"> <input type="time"> の Date インスタンスを読み書きするときに利用するタイムゾーンを指定する。