入门

监控属性

使用内置绑定

控制文本和外观

绑定逻辑控制

处理表单属性

解析模板

高级应用

插件

更多信息

"options" 绑定

目的

options 绑定控制options在drop-down列表里 （例如： ）或者 multi-select 列表里 （例如： ）显示。此绑定不能用于 之外的元素。

The options binding controls what options should appear in a drop-down list (i.e., a element) or multi-select list (e.g., ). This binding cannot be used with anything other than elements.

关联的数据应是数组（或者是observable数组）， 会遍历显示数组里的所有的项。

The value you assign should be an array (or observable array). The element will then display one item for each item in your array.

注：对于multi-select列表，设置或者获取选择的多项需要使用 selectedOptions 绑定。对于single-select列表，你也可以使用 value 绑定读取或者设置元素的selected项。

Note: For a multi-select list, to set which of the options are selected, or to read which of the options are selected, use the selectedOptions binding. For a single-select list, you can also read and write the selected option using the value binding.

例1: Drop-down list

  1. <p>Destination country: <select data-bind="options: availableCountries"></select></p>
  3. <script type="text/javascript">
  4.     var viewModel = {
  5.         availableCountries : ko.observableArray(['France', 'Germany', 'Spain']) // These are the initial options
  6.     };
  8.     // ... then later ...
  9.     viewModel.availableCountries.push('China'); // Adds another option
  10. </script>

例2: Multi-select list

  1. <p>Choose some countries you'd like to visit: <select data-bind="options: availableCountries" size="5" multiple="true"></select></p>
  3. <script type="text/javascript">
  4.     var viewModel = {
  5.         availableCountries : ko.observableArray(['France', 'Germany', 'Spain'])
  6.     };
  7. </script>

例3：Drop-down list展示的任意JavaScript对象，不仅仅是字符串

  1. <p>
  2.     Your country: 
  3.     <select data-bind="options: availableCountries, optionsText: 'countryName', value: selectedCountry, optionsCaption: 'Choose...'"></select>
  4. </p>
  6. <div data-bind="visible: selectedCountry"> <!-- Appears when you select something -->
  7.     You have chosen a country with population 
  8.     <span data-bind="text: selectedCountry() ? selectedCountry().countryPopulation : 'unknown'"></span>.
  9. </div>
  11. <script type="text/javascript">
  12.     // Constructor for an object with two properties
  13.     var country = function(name, population) {
  14.         this.countryName = name;
  15.         this.countryPopulation = population;    
  16.     };        
  18.     var viewModel = {
  19.         availableCountries : ko.observableArray([
  20.             new country("UK", 65000000),
  21.             new country("USA", 320000000),
  22.             new country("Sweden", 29000000)
  23.         ]),
  24.         selectedCountry : ko.observable() // Nothing selected by default
  25.     };
  26. </script>

例4：Drop-down list展示的任意JavaScript对象，显示text是function的返回值

  1. <!-- Same as example 3, except the <select> box expressed as follows: -->
  2. <select data-bind="options: availableCountries, 
  3.                    optionsText: function(item) { 
  4.                        return item.countryName + ' (pop: ' + item.countryPopulation + ')' 
  5.                    }, 
  6.                    value: selectedCountry, 
  7.                    optionsCaption: 'Choose...'"></select>

注意例3和例4在 optionsText 值定义上的不同。

Note that the only difference between examples 3 and 4 is the optionsText value.

参数

  • 主参数

该参数是一个数组（或者observable数组）。对每个item，KO都会将它作为一个 添加到 里，之前的options都将被删除。

You should supply an array (or observable array). For each item, KO will add an to the associated node. Any previous options will be removed.

如果参数是一个string数组，那你不需要再声明任何其它参数。 元素会将每个string显示为一个option。不过，如果你让用户选择的是一个JavaScript对象数组（不仅仅是string），那就需要设置 optionsText 和 optionsValue 这两个参数了。

If your parameter’s value is an array of strings, you don’t need to give any other parameters. The element will display an option for each string value. However, if you want to let the user choose from an array of arbitrary JavaScript objects (not merely strings), then see the optionsText and optionsValue parameters below.

如果参数是监控属性observable的，那元素的options项将根据参数值的变化而更新，如果不是，那元素的value值将只设置一次并且以后不在更新。

If this parameter is an observable value, the binding will update the element’s available options whenever the value changes. If the parameter isn’t observable, it will only set the element’s available options once and will not update them again later.

  • 其它参数

    • optionsCaption

    有时候，默认情况下不想选择任何option项。但是single-select drop-down列表由于每次都有默认选择以项目，怎么避免这个问题呢？常用的方案是加一个“请选择的”或者“Select an item”的提示语，或者其它类似的，然后让这个项作为默认选项。

Sometimes, you might not want to select any particular option by default. But a single-select drop-down list always has one item selected, so how can you avoid preselecting something? The usual solution is to prefix the list of options with a special dummy option that just reads “Select an item” or “Please choose an option” or similar, and have that one selected by default.

我们使用 optionsCaption 参数就能很容易实现，它的值是字符串型，作为默认项显示。例如：

This easy to do: just add an additional parameter with name optionsCaption, with its value being a string to display. For example:

KO会在所有选项上加上这一个项，并且设置value值为 undefined。所以，如果 myChosenValue 被设置为 undefined （默认是observable的），那么上述的第一个项就会被选中。

KO will prefix the list of items with one that displays the text “Select an item…” and has the value undefined. So, if myChosenValue holds the value undefined (which observables do by default), then the dummy option will be selected.

  • optionsText

上面的例3展示的绑定JavaScript对象到 options 上 – 不仅仅是字符串。这时候你需要设置这个对象的那个属性作为drop-down列表或multi-select列表的text来显示。例如，例3中使用的是设置额外的参数 optionsText 将对象的属性名countryName作为显示的文本。

See Example 3 above to see how you can bind options to an array of arbitrary JavaScript object - not just strings. In this case, you need to choose which of the objects’ properties should be displayed as the text in the drop-down list or multi-select list. Example 3 shows how you can specify that property name by passing an additional parameter called optionsText.

如果不想仅仅显示对象的属性值作为每个item项的text值，那你可以设置 optionsText 为JavaScript 函数，然后再函数里通过自己的逻辑返回相应的值（该函数参数为item项本身）。例4展示的就是返回item的2个属性值合并的结果。

If you don’t want to display just a simple property value as the text for each item in the dropdown, you can pass a JavaScript function for the optionsText option and supply your own arbitrary logic for computing the displayed text in terms of the represented object. See Example 4 above, which shows how you could generate the displayed text by concatenating together multiple property values.

  • optionsValue

和 optionsText 类似, 你也可以通过额外参数 optionsValue 来声明对象的那个属性值作为该 的 value 值。

Similar to optionsText, you can also pass an additional parameter called optionsValue to specify which of the objects’ properties should be used to set the value attribute on the elements that KO generates.

经典场景：如在更新options的时候想保留原来的已经选择的项。例如，当你重复多次调用Ajax获取car列表的时候，你要确保已经选择的某个car一直都是被选择上，那你就需要设置 optionsValue 为 "carId" 或者其它的unique标示符，否则的话KO找不知道之前选择的car是新options里的哪一项。

Typically you’d only want to do this as a way of ensuring that KO can correctly retain selection when you update the set of available options. For example, if you’re repeatedly getting a list of “car” objects via Ajax calls and want to ensure that the selected car is preserved, you might need to set optionsValue to "carId" or whatever unique identifier each “car” object has, otherwise KO won’t necessarily know which of the previous “car” objects corresponds to which of the new ones.

  • selectedOptions

对于multi-select列表，你可以用 selectedOptions读取和设置多个选择项。技术上看它是一个单独的绑定，有自己的文档，请参考： selectedOptions绑定。

For a multi-select list, you can read and write the selection state using selectedOptions. Technically this is a separate binding, so it has its own documentation.

注：已经被选择的项会再options改变的时候保留

当使用 options 绑定 元素的时候，如果options改变，KO将尽可能第保留之前已经被选择的项不变（除非是你事先手工删除一个或多个已经选择的项）。

When the options binding changes the set of options in your element, KO will leave the user’s selection unchanged where possible. So, for a single-select drop-down list, the previously selected option value will still be selected, and for a multi-select list, all the previously selected option values will still be selected (unless, of course, you’re removed one or more of those options).

这是因为 options 绑定尝试依赖 value 值的绑定（single-select列表）和 selectedOptions绑定（multi-select列表）。

That’s because the options binding tries to be independent of the value binding (which controls selection for a single-select list) and the selectedOptions binding (which controls selection for a multi-select list).

依赖性

除KO核心类库外，无依赖。

(c) knockoutjs.com