"option" バインディング

このページは現在翻訳中です。お待たせして申し訳ございません。

用途

options バインディングは <select> によるドロップダウンリスト、または <select size='6'> のような複数選択リストの選択肢を制御します。このバインディングは <select> エレメントのみで使用できます。

紐付ける値は配列または ObservableArray です。<select> エレメントは配列の各アイテムから一つを表示します。

※ 複数選択リストの場合、選択状態をセットまたは取得するのに selectedOptions バインディングを使います。択一のドロップダウンリストでは、他のフォーム部品同様に選択されたアイテムを value バインディングで管理できます。

例1: ドロップダウンリスト

<p>
    行き先:
    <select data-bind="options: availableCountries"></select>
</p>

<script type="text/javascript">
    var viewModel = {
        // 選択肢の初期値を設定
        availableCountries: ko.observableArray(['フランス', 'ドイツ', 'スペイン'])
    };

    // ... その後 ...
    viewModel.availableCountries.push('中国'); // 選択肢を追加
</script>

例2: 複数選択リスト

<p>
    言ってみたい国はどこですか:
    <select data-bind="options: availableCountries" size="5" multiple="true"></select>
</p>

<script type="text/javascript">
    var viewModel = {
        availableCountries: ko.observableArray(['フランス', 'ドイツ', 'スペイン'])
    };
</script>

例3: 単なる文字列ではなく任意の JavaScript オブジェクトを表示

<p>
    あなたの国:
    <select data-bind="options: availableCountries,
                       optionsText: 'countryName',
                       value: selectedCountry,
                       optionsCaption: '-選択してください-'"></select>
</p>

<div data-bind="visible: selectedCountry"> <!-- どれかを選択したときに表示される -->
    選択した国およびその人口
    <span data-bind="text: selectedCountry() ? selectedCountry().countryPopulation : '不明'"></span>.
</div>

<script type="text/javascript">
    // 2つのプロパティを持ったオブジェクトのコンストラクタ
    var Country = function(name, population) {
        this.countryName = name;
        this.countryPopulation = population;
    };

    var viewModel = {
        availableCountries : ko.observableArray([
            new Country("イギリス", 65000000),
            new Country("アメリカ", 320000000),
            new Country("スウェーデン", 29000000)
        ]),
        selectedCountry : ko.observable() // デフォルトでは何も選択されていない状態
    };
</script>

例4: 表示される選択肢のテキストとして、任意の JavaScript オブジェクトを処理した値を用いる

<!-- 下記の select 以外は例3と同じ: -->
<select data-bind="options: availableCountries,
                   optionsText: function(item) {
                       return item.countryName + ' (pop: ' + item.countryPopulation + ')'
                   },
                   value: selectedCountry,
                   optionsCaption: '-選択してください-'"></select>

例3と例4の違いは optionsText に指定した値のみです。

パラメタ

主パラメタ

配列または ObservableArray を指定します。Knockout は紐付けられた <select> ノードに各アイテムごとに <option> エレメントを追加します。既存の選択肢は削除されます。

文字列の配列を指定した場合、他に必要なパラメタはありません。<select> エレメントにそれぞれの文字列が選択肢として表示されます。ただし、単なる文字列ではなく任意の JavaScript オブジェクトをユーザーに選択してほしい場合は、optionsText と optionsValue パラメタを確認して下さい。

このパラメタが Observable である場合、このバインディングは値が変更される度に選択肢をを更新します。Observable でない場合は、選択肢は一度だけ設定され、以降は更新されません。
追加パラメタ
- optionsCaption
  
  時にはデフォルトでどの選択肢も選択されていない状態にしたいことがあります。しかし択一のドロップダウンリストでは通常、初期状態でいずれかが選択されてしまいます。どうしたら何も選択されないようにできるでしょう？よくある解決策として、選択肢リストに「選択してください」のようなダミーの選択肢を用意し、デフォルトでそれが選択されるようにします。
  
  これは optionsCaption という追加パラメタで次のように未選択状態のテキストを設定することで簡単に実現できます。
  
  <select data-bind='options: myOptions, optionsCaption: "選択してください", value: myChosenValue'></select>
  
  Knockout はリストの先頭に「選択してください」というテキストアイテムを、value を undefined として追加します。したがって myChosenValue の値が undefined であれば、そのダミーの選択肢が選択されます。optionsCaption に Observable を指定した場合、値の変更に従い初期アイテムのテキストも更新されます。
- optionsText
  
  上記の例3では options で単なる文字列ではなく任意の JavaScript オブジェクトの配列をバインドする方法を示しました。この場合、オブジェクトのどのおプロパティを選択肢のテキストとして表示すべきかを選ぶ必要があります。例3で optionsText パラメタを使って指定しました。
  
  各アイテムのプロパティの値をそのまま表示したくない場合、optionsText に表示されるテキストを処理するための任意の JavaScript 関数を設定することができます。上記の例4にて、複数のプロパティの値を結合して表示する方法を示しました。
- optionsValue
  
  optionsText と同様に、optionsValue パラメタによって Knockout が <option> エレメントを生成する際にオブジェクトのどのプロパティを value として設定すべきかを指定することができます。またこの値を決定するための関数を指定することもできます。この関数は選択されたアイテムを引数として受け取り、<option> エレメントの value 属性として使う文字列を返すようにします。
  
  一般的に optionsValue は、利用可能な選択肢を更新する際に Knockout が正しく選択を保持することを保証するための方法として使います。例えば選択肢として “car” オブジェクトのリストが Ajax によって何度も取得され、かつ選択した自動車が記憶されるようにしたいとします。optionsValue に "carId" など、“car” オブジェクトを一意に特定するプロパティを指定しないと、リストが更新されたときに、前に選択されていたものに相当するオブジェクトがどれか Knockout が知ることができなくなります。
- optionsIncludeDestroyed
  
  配列のアイテムを実際には削除せず、「削除済み」としてマークすることで論理削除したいときがあります。論理削除の方法については destroy と destroyAll を参照してください。
  
  通常、options バインディングは論理削除されたアイテムをスキップ（すなわち隠蔽）します。論理削除されたアイテムを表示したい場合は以下のように追加パラメタを指定してください。
  
  <select data-bind='options: myOptions, optionsIncludeDestroyed: true'></select>
- optionsAfterRender
  
  生成された各 option エレメントに対して独自のロジックを実行する必要がある場合、optionsAfterRender コールバックを使うことができます。注2を参照してください。
- selectedOptions
  
  複数選択リストのための選択状態を selectedOptions で読み書きできます。これは技術的には別のバインディングなので、selectedOptions 自体のドキュメントがあります。
- valueAllowUnset
  
  If you want Knockout to allow your model property to take values that have no corresponding entry in your <select> element (and display this by making the <select> element blank), then see documentation for valueAllowUnset.

注1: 選択肢を設定/変更しても選択は保持される

<select> エレメントの選択肢が options バインディングによって変更されたとき、Knockout は可能であればユーザの選択状態を変更せず維持します。したがって択一のドロップダウンリストでは、以前選択された値は選択されたままとなり、複数選択リストではすべての選択済みの値が（もちろん、そのうちの一つ以上の選択肢を削除したりしない限りは）選択されたままとなります。

これは options バインディングが value バインディング（択一ドロップダウンリストの場合）と selectedOptions バインディング（複数選択リストの場合）から独立して動作しようとするためです。

注2: 生成された選択肢の後処理

生成された option エレメントに対して独自のロジックを実行したいのであれば、optionsAfterRender コールバックを使用します。コールバック関数はリストに挿入される各 option エレメントに対して、以下のパラメタとともに呼び出されます。

挿入された option エレメント
バインドされたデータアイテム, キャプションエレメントに対しては undefined

以下に optionsAfterRender を使って選択肢に disable バインディングを追加する例を示します。

<select size=3 data-bind="
    options: myItems,
    optionsText: 'name',
    optionsValue: 'id',
    optionsAfterRender: setOptionDisable">
</select>

<script type="text/javascript">
    var vm = {
        myItems: [
            { name: 'Item 1', id: 1, disable: ko.observable(false)},
            { name: 'Item 3', id: 3, disable: ko.observable(true)},
            { name: 'Item 4', id: 4, disable: ko.observable(false)}
        ],
        setOptionDisable: function(option, item) {
            ko.applyBindingsToNode(option, {disable: item.disable}, item);
        }
    };
    ko.applyBindings(vm);
</script>

依存

Knockout コアライブラリ以外、なし。

原文はこちら