綁定語法（3） · Knockout應用開發指南

## 12 ? value 綁定 **目的** value綁定是關聯DOM元素的值到view model的屬性上。主要是用在表單控件，和上。當用戶編輯表單控件的時候， view model對應的屬性值會自動更新。同樣，當你更新view model屬性的時候，相對應的元素值在頁面上也會自動更新。注：如果你在checkbox或者radio button上使用checked綁定來讀取或者寫入元素的 checked狀態，而不是value 值的綁定。 **例子** ~~~ <p>Login name: <input data-bind="value: userName"/></p> <p>Password: <input type="password" data-bind="value: userPassword"/></p> <script type="text/javascript"> var viewModel = { userName: ko.observable(""), // Initially blank userPassword: ko.observable("abc"), // Prepopulate }; </script> ~~~ **參數** ????**主參數** ??? KO設置此參數為元素的value值。之前的值將被覆蓋。 ??? 如果參數是監控屬性observable的，那元素的value值將根據參數值的變化而更新，如果不是，那元素的value值將只設置一次并且以后不在更新。 ??? 如果你提供的參數不是一個數字或者字符串（而是對象或者數組）的話，那顯示的value值就是yourParameter.toString() 的內容（通常沒用，所以最好都設置為數字或者字符串）。 ??? 不管什么時候，只要你更新了元素的值，那 KO都會將view model對應的屬性值自動更新。默認情況下當用戶離開焦點（例如onchange事件）的時候，KO才更新這個值，但是你可以通過第2個參數valueUpdate來特別指定改變值的時機。 ????**其它參數** ????????**valueUpdate** ??????? 如果你使用valueUpdate參數，那就是意味著KO將使用自定義的事件而不是默認的離開焦點事件。下面是一些最常用的選項： ??????????? “change”（默認值） - 當失去焦點的時候更新view model的值，或者是元素被選擇的時候。 ??????????? “keyup” – 當用戶敲完一個字符以后立即更新view model。 ??????????? “keypress” – 當用戶正在敲一個字符但沒有釋放鍵盤的時候就立即更新view model。不像 keyup，這個更新和keydown是一樣的。 ??????????? “afterkeydown” – 當用戶開始輸入字符的時候就更新view model。主要是捕獲瀏覽器的keydown事件或異步handle事件。 ??????? 上述這些選項，如果你想讓你的view model進行實時更新，使用“afterkeydown”是最好的選擇。 **例子：** ~~~ <p>Your value: <input data-bind="value: someValue, valueUpdate: 'afterkeydown'"/></p> <p>You have typed: <span data-bind="text: someValue"></span></p>  <script type="text/javascript"> var viewModel = { someValue: ko.observable("edit me") }; </script> ~~~ **注1：綁定下拉菜單drop-down list（例如SELECT）** Knockout對下拉菜單drop-down list綁定有一個特殊的支持，那就是在讀取和寫入綁定的時候，這個值可以是任意JavaScript對象，而不必非得是字符串。在你讓你用戶選擇一組model對象的時候非常有用。具體例子，參考options綁定。類似，如果你想創建一個multi-select list，參考selectedOptions綁定。 **注2：更新observable和non-observable屬性值** 如果你用value綁定將你的表單元素和你的observable屬性關聯起來，KO設置的2-way的雙向綁定，任何一方改變都會更新另外一方的值。但是，如果你的元素綁定的是一個non-observable屬性（例如是一個原始的字符串或者JavaScript表達式） ,KO會這樣執行： * 如果你綁定的non-observable屬性是簡單對象，例如一個常見的屬性值，KO會設置這個值為form表單元素的初始值，如果你改變form表單元素的值，KO會將值重新寫回到view mode的這個屬性。但當這個屬性自己改變的時候，元素卻不會再變化了（因為不是observable的），所以它僅僅是1-way綁定。 * 如果你綁定的non-observable屬性是復雜對象，例如復雜的JavaScript 表達式或者子屬性，KO也會設置這個值為form表單元素的初始值，但是改變form表單元素的值的時候，KO不會再寫會view model屬性，這種情況叫one-time-only value setter，不是真正的綁定。 **例子：** ~~~ <p>First value: <input data-bind="value: firstValue"/></p>  <p>Second value: <input data-bind="value: secondValue"/></p>  <p>Third value: <input data-bind="value: secondValue.length"/></p>  <script type="text/javascript"> var viewModel = { firstValue: ko.observable("hello"), // Observable secondValue: "hello, again"// Not observable }; ko.applyBindings(viewModel); </script> ~~~ **依賴性** 除KO核心類庫外，無依賴。 ## 13 ? checked 綁定 **目的** checked綁定是關聯到checkable的form表單控件到view model上 - 例如checkbox（）或者radio button（）。當用戶check關聯的form表單控件的時候，view model對應的值也會自動更新，相反，如果view model的值改變了，那控件元素的check/uncheck狀態也會跟著改變。注：對text box，drop-down list和所有non-checkable的form表單控件，用[value綁定](http://www.cnblogs.com/TomXu/archive/2011/11/24/2256904.html#_value_%E7%BB%91%E5%AE%9A)來讀取和寫入是該元素的值，而不是checked綁定。 **例子** ~~~ <p>Send me spam: <input type="checkbox" data-bind="checked: wantsSpam"/></p> <script type="text/javascript"> var viewModel = { wantsSpam: ko.observable(true) // Initially checked }; // ... then later ... viewModel.wantsSpam(false); // The checkbox becomes unchecked </script> ~~~ **Checkbox**關聯到數組 ~~~ <p>Send me spam: <input type="checkbox" data-bind="checked: wantsSpam"/></p> <div data-bind="visible: wantsSpam"> Preferred flavors of spam: <div><input type="checkbox" value="cherry" data-bind="checked: spamFlavors"/> Cherry</div> <div><input type="checkbox" value="almond" data-bind="checked: spamFlavors"/> Almond</div> <div><input type="checkbox" value="msg" data-bind="checked: spamFlavors"/> Monosodium Glutamate</div> </div> <script type="text/javascript"> var viewModel = { wantsSpam: ko.observable(true), spamFlavors: ko.observableArray(["cherry", "almond"]) // Initially checks the Cherry and Almond checkboxes }; // ... then later ... viewModel.spamFlavors.push("msg"); // Now additionally checks the Monosodium Glutamate checkbox </script> ~~~ **添加radio button** ~~~ <p>Send me spam: <input type="checkbox" data-bind="checked: wantsSpam"/></p> <div data-bind="visible: wantsSpam"> Preferred flavor of spam: <div><input type="radio" name="flavorGroup" value="cherry" data-bind="checked: spamFlavor"/> Cherry</div> <div><input type="radio" name="flavorGroup" value="almond" data-bind="checked: spamFlavor"/> Almond</div> <div><input type="radio" name="flavorGroup" value="msg" data-bind="checked: spamFlavor"/> Monosodium Glutamate</div> </div> <script type="text/javascript"> var viewModel = { wantsSpam: ko.observable(true), spamFlavor: ko.observable("almond") // Initially selects only the Almond radio button }; // ... then later ... viewModel.spamFlavor("msg"); // Now only Monosodium Glutamate is checked </script> ~~~ **參數** ????**主參數** ??? KO會設置元素的checked狀態匹配到你的參數上，之前的值將被覆蓋。對參數的解析取決于你元素的類型： ??????? 對于checkbox，當參數為true的時候，KO會設置元素的狀態為checked，反正設置為unchecked。如果你傳的參數不是布爾值，那KO將會解析成布爾值。也就是說非0值和非null對象，非空字符串將被解析成true，其它值都被解析成false。 ??????? 當用戶check或者uncheck這個checkbox的時候，KO會將view model的屬性值相應地設置為true或者false。 ??????? 一個特殊情況是參數是一個數組，如果元素的值存在于數組，KO就會將元素設置為checked，如果數組里不存在，就設置為unchecked。如果用戶對checkbox進行check或uncheck，KO就會將元素的值添加數組或者從數組里刪除。 ??????? 對于radio buttons，KO只有當參數值等于radio button value屬性值的時候才設置元素為checked狀態。所以參數應是字符串。在上面的例子里只有當view model 的spamFlavor 屬性等于“almond”的時候，該radio button才會設置為checked。 ??????? 當用戶將一個radio button選擇上的時候 is selected，KO會將該元素的value屬性值更新到view model屬性里。上面的例子，當點擊value= “cherry”的選項上， viewModel.spamFlavor的值將被設置為“cherry”。 ??????? 當然，最有用的是設置一組radio button元素對應到一個單個的view model 屬性。確保一次只能選擇一個radio button需要將他們的name屬性名都設置成一樣的值（例如上個例子的flavorGroup值）。這樣的話，一次就只能選擇一個了。 ??? 如果參數是監控屬性observable的，那元素的checked狀態將根據參數值的變化而更新，如果不是，那元素的value值將只設置一次并且以后不在更新。 ???**其它參數** ??? 無 **依賴性** 除KO核心類庫外，無依賴。 ## 14 ? options 綁定 **目的** options綁定控制什么樣的options在drop-down列表里（例如：）或者 multi-select 列表里（例如：）顯示。此綁定不能用于之外的元素。關聯的數據應是數組（或者是observable數組），會遍歷顯示數組里的所有的項。注：對于multi-select列表，設置或者獲取選擇的多項需要使用[selectedOptions](http://www.cnblogs.com/TomXu/archive/2011/11/24/2256904.html#_selectedOptions_%E7%BB%91%E5%AE%9A)綁定。對于single-select列表，你也可以使用[value綁定](http://www.cnblogs.com/TomXu/archive/2011/11/24/2256904.html#_value_%E7%BB%91%E5%AE%9A)讀取或者設置元素的selected項。 **例1：Drop-down list** ~~~ <p>Destination country: <select data-bind="options: availableCountries"></select></p> <script type="text/javascript"> var viewModel = { availableCountries: ko.observableArray(['France', 'Germany', 'Spain']) // These are the initial options }; // ... then later ... viewModel.availableCountries.push('China'); // Adds another option </script> ~~~ **例2：Multi-select list** ~~~ <p>Choose some countries you'd like to visit: <select data-bind="options: availableCountries" size="5" multiple="true"></select></p> <script type="text/javascript"> var viewModel = { availableCountries: ko.observableArray(['France', 'Germany', 'Spain']) }; </script> ~~~ **例3：Drop-down list展示的任意JavaScript對象，不僅僅是字符串** ~~~ <p> Your country: <select data-bind="options: availableCountries, 　　　　　　　　　　　　　　optionsText: 'countryName', value: selectedCountry, optionsCaption: 'Choose...'"></select> </p> <div data-bind="visible: selectedCountry">  You have chosen a country with population <span data-bind="text: selectedCountry() ? selectedCountry().countryPopulation : 'unknown'"></span>. </div> <script type="text/javascript"> // Constructor for an object with two properties var country =function (name, population) { this.countryName = name; this.countryPopulation = population; }; var viewModel = { availableCountries: ko.observableArray([ new country("UK", 65000000), new country("USA", 320000000), new country("Sweden", 29000000) ]), selectedCountry: ko.observable() // Nothing selected by default }; </script> ~~~ **例4：Drop-down list展示的任意JavaScript對象，顯示text是function的返回值** ~~~  <select data-bind="options: availableCountries, optionsText: function(item) { return item.countryName + ' (pop: ' + item.countryPopulation + ')' }, value: selectedCountry, optionsCaption: 'Choose...'"></select> ~~~ 注意例3和例4在optionsText值定義上的不同。 **參數** ????**主參數** ??? 該參數是一個數組（或者observable數組）。對每個item，KO都會將它作為一個添加到里，之前的options都將被刪除。 ??? 如果參數是一個string數組，那你不需要再聲明任何其它參數。元素會將每個string顯示為一個option。不過，如果你讓用戶選擇的是一個JavaScript對象數組（不僅僅是string），那就需要設置optionsText和optionsValue這兩個參數了。 ??? 如果參數是監控屬性observable的，那元素的options項將根據參數值的變化而更新，如果不是，那元素的value值將只設置一次并且以后不在更新。 ????**其它參數** ????????**optionsCaption** ??????? 有時候，默認情況下不想選擇任何option項。但是single-select drop-down列表由于每次都要默認選擇以項目，怎么避免這個問題呢？常用的方案是加一個“請選擇的”或者“Select an item”的提示語，或者其它類似的，然后讓這個項作為默認選項。 ??????? 我們使用optionsCaption參數就能很容易實現，它的值是字符串型，作為默認項顯示。例如： ??????? ??????? KO會在所有選項上加上這一個項，并且設置value值為undefined。所以，如果myChosenValue被設置為undefined（默認是observable的），那么上述的第一個項就會被選中。 ????????**optionsText** ??????? 上面的例3展示的綁定JavaScript對象到option上 – 不僅僅是字符串。這時候你需要設置這個對象的那個屬性作為drop-down列表或multi-select列表的text來顯示。例如，例3中使用的是設置額外的參數optionsText將對象的屬性名countryName作為顯示的文本。 ??????? 如果不想僅僅顯示對象的屬性值作為每個item項的text值，那你可以設置optionsText 為JavaScript 函數，然后再函數里通過自己的邏輯返回相應的值（該函數參數為item項本身）。例4展示的就是返回item的2個屬性值合并的結果。 ????????**optionsValue** ??????? 和optionsText類似, 你也可以通過額外參數optionsValue來聲明對象的那個屬性值作為該的value值。 ??????? 經典場景：如在更新options的時候想保留原來的已經選擇的項。例如，當你重復多次調用Ajax獲取car列表的時候，你要確保已經選擇的某個car一直都是被選擇上，那你就需要設置optionsValue為“carId”或者其它的unique標示符，否則的話KO找不知道之前選擇的car是新options里的哪一項。 ????????**selectedOptions** ??????? 對于multi-select列表，你可以用selectedOptions讀取和設置多個選擇項。技術上看它是一個單獨的綁定，有自己的文檔，請參考： selectedOptions綁定。注：已經被選擇的項會再options改變的時候保留當使用options綁定元素的時候，如果options改變，KO將盡可能第保留之前已經被選擇的項不變（除非是你事先手工刪除一個或多個已經選擇的項）。這是因為options 綁定嘗試依賴value值的綁定（single-select列表）和selectedOptions綁定（multi-select列表）。 **依賴性** 除KO核心類庫外，無依賴。 ## 15 ? selectedOptions 綁定 **目的** selectedOptions綁定用于控制multi-select列表已經被選擇的元素，用在使用options綁定的元素上。當用戶在multi-select列表選擇或反選一個項的時候，會將view model的數組進行相應的添加或者刪除。同樣，如果view model上的這個數組是observable數組的話，你添加或者刪除任何item（通過push或者splice）的時候，相應的UI界面里的option項也會被選擇上或者反選。這種方式是2-way綁定。注：控制single-select下拉菜單選擇項，你可以使用value綁定。 **例子** ~~~ <p> Choose some countries you'd like to visit: <select data-bind="options: availableCountries, selectedOptions: chosenCountries" size="5" multiple="true"></select> </p> <script type="text/javascript"> var viewModel = { availableCountries: ko.observableArray(['France', 'Germany', 'Spain']), chosenCountries: ko.observableArray(['Germany']) // Initially, only Germany is selected }; // ... then later ... viewModel.chosenCountries.push('France'); // Now France is selected too </script> ~~~ **參數** ????**主參數** ??? 該參數是數組（或observable數組）。KO設置元素的已選項為和數組里match的項，之前的已選擇項將被覆蓋。 ??? 如果參數是依賴監控屬性observable數組，那元素的已選擇項selected options項將根據參數值的變化（通過push，pop，或其它[observable數組方法](http://www.cnblogs.com/TomXu/archive/2011/11/24/2256904.html#_%E4%BD%BF%E7%94%A8observable%E6%95%B0%E7%BB%84)）而更新，如果不是，那元素的已選擇項selected options將只設置一次并且以后不在更新。 ??? 不管該參數是不是observable數組，用戶在multi-select列表里選擇或者反選的時候，KO都會探測到，并且更新數組里的對象以達到同步的結果。這樣你就可以獲取options已選項。 ????**其它參數** ??? ?????? 無 **注：支持讓用戶選擇任意JavaScript對象** 在上面的例子里，用戶可以選擇數組里的字符串值，但是選擇不限于字符串，如果你愿意你可以聲明包含任意JavaScript對象的數組，查看[options綁定](http://www.cnblogs.com/TomXu/archive/2011/11/24/2256904.html#_options_%E7%BB%91%E5%AE%9A)如何顯示JavaScript對象到列表里。這種場景，你可以用selectedOptions來讀取或設置這些對象本身，而不是頁面上顯示的option表示形式，這樣做在大部分情況下都非常清晰。view model就可以探測到你從數組對象里選擇的項了，而不必關注每個項和頁面上展示的option項是如何map的。 **依賴性** 除KO核心類庫外，無依賴。 ## 16 ? uniqueName 綁定 **目的** uniqueName綁定確保所綁定的元素有一個非空的name屬性。如果該元素沒有name屬性，那綁定會給它設置一個unique的字符串值作為name屬性。你不會經常用到它，只有在某些特殊的場景下才用到，例如： * 在使用KO的時候，一些技術可能依賴于某些元素的name屬性，盡快他們沒有什么意義。例如，jQuery Validation驗證當前只驗證有name屬性的元素。為配合Knockout UI使用，有些時候需要使用uniqueName綁定避免讓jQuery Validation驗證出錯。 * IE 6下，如果radio button沒有name屬性是不允許被checked了。大部分時候都沒問題，因為大部分時候radio button元素都會有name屬性的作為一組互相的group。不過，如果你沒聲明，KO內部會在這些元素上使用uniqueName那么以確保他們可以被checked。 **例子** ~~~ <input data-bind="value: someModelProperty, uniqueName: true"/> ~~~ **參數** ????**主參數** ??? 就像上面的例子一樣，傳入true（或者可以轉成true的值）以啟用uniqueName綁定。 ????**其它參數** ??????? 無 **依賴性** 除KO核心類庫外，無依賴。