KnockoutJS 3.X API 第八章 映射(mapping)外掛程式

標籤：

Knockout旨在允許您將任意JavaScript對象用作視圖模型。 只要一些視圖模型的屬性是observables，您可以使用KO將它們綁定到您的UI，並且UI將在可觀察屬性更改時自動更新。

大多數應用程式需要從後端伺服器擷取資料。 由於伺服器沒有任何可觀察的概念，它只提供一個純JavaScript對象（通常序列化為JSON）。 映射外掛程式提供了一種簡單的方法來將該簡單的JavaScript對象映射到具有適當的observables的視圖模型中。 這是替代手動編寫自己的JavaScript代碼，根據您從伺服器擷取的一些資料構建視圖模型。

下載映射外掛程式(你需要翻個牆)

• Version 2.0 (8.6kb minified)，

<br class="Apple-interchange-newline"><div id="inner-editor"></div>

樣本：不帶ko.mapping外掛程式的手動映射

您要顯示當前伺服器時間和您的網頁上的使用者數。 您可以使用以下視圖模型表示此資訊：

var viewModel = {    serverTime: ko.observable(),    numUsers: ko.observable()}

您可以將此視圖模型繫結到一些HTML元素，如下所示：

The time on the server is: <span data-bind=‘text: serverTime‘></span>and <span data-bind=‘text: numUsers‘></span> user(s) are connected.

由於視圖模型屬性是可觀察的，KO將在這些屬性更改時自動更新HTML元素。

接下來，您要從伺服器擷取最新資料。 每5秒您可以發出一個Ajax請求（例如，使用jQuery的$ .getJSON或$ .ajax函數）：

var data = getDataUsingAjax();          // Gets the data from the server

伺服器可能返回類似於以下內容的JSON資料：

{    serverTime: ‘2010-01-07‘,    numUsers: 3}

最後，要使用此資料更新視圖模型（不使用映射外掛程式），您應該寫：

// Every time data is received from the server:viewModel.serverTime(data.serverTime);viewModel.numUsers(data.numUsers);

你必須為你想在頁面上顯示的每個變數這樣做。 如果您的資料結構變得更加複雜（例如，它們包含子節點或包含數組），則手動處理變得非常麻煩。 映射外掛程式允許您做的是建立從常規JavaScript對象（或JSON結構）到可觀察視圖模型的映射。

<br class="Apple-interchange-newline"><div id="inner-editor"></div>

樣本：使用ko.mapping

要通過映射外掛程式建立視圖模型，請將上面代碼中的viewModel的建立替換為ko.mapping.fromJS函數：

// Every time data is received from the server:ko.mapping.fromJS(data, viewModel);

如何映射

• 對象的所有屬性都將轉換為observable。 如果更新將更改值，它將更新observable。
• 數組被轉換為可觀察數組。 如果更新會更改項目數，則它將執行適當的添加/刪除操作。 它還將嘗試保持與原始JavaScript數組相同的順序。

取消映射

如果要將映射對象轉換回常規JS對象，請使用：

var unmapped = ko.mapping.toJS(viewModel);

這將建立一個未映射的對象，只包含作為原始JS對象的一部分的映射對象的屬性。 因此，換句話說，您手動添加到視圖模型的任何屬性或函數都將被忽略。 預設情況下，此規則的唯一例外是_destroy屬性，它也將被映射回來，因為它是Knockout在從ko.observableArray中銷毀項目時可能產生的屬性。 有關如何配置此項的更多詳細資料，請參閱“進階應用程式”章節。

使用JSON字串

如果您的Ajax調用返回一個JSON字串（並且不將其還原序列化為JavaScript對象），那麼您可以使用函數ko.mapping.fromJSON來建立和更新視圖模型。 要取消映射，可以使用ko.mapping.toJSON。

除了它們使用JSON字串而不是JS對象的事實，這些函數與它們的JS對象完全相同。

進階用法

有時，可能有必要對如何執行映射有更多的控制。 這是使用映射選項實現的。 它們可以在ko.mapping.fromJS調用期間指定。 在後續調用中，您不需要再次指定它們。

在這種情況下，您可能需要使用這些映射選項。

使用“key”唯一標識對象

假設您有一個類似於以下內容的JavaScript對象：

var data = {    name: ‘Scot‘,    children: [        { id : 1, name : ‘Alicw‘ }    ]}

您可以將此映射到視圖模型沒有任何問題：

var viewModel = ko.mapping.fromJS(data);

現在，假設資料更新為沒有任何拼字錯誤：

var data = {    name: ‘Scott‘,    children: [        { id : 1, name : ‘Alice‘ }    ]}

這裡發生了兩件事情：name從Scot改為Scott，children[0] .name從Alicw變成了Alice。 您可以基於此新資料更新viewModel：

ko.mapping.fromJS(data, viewModel);

和名稱會改變，如預期。 但是，在children數組中，子（Alicw）將被完全刪除，並添加一個新的（Alice）。 這不是完全你會期望的。 相反，你會希望只有孩子的name屬性從Alicw更新到Alice，而不是整個孩子被替換！

這是因為，預設情況下，映射外掛程式只是比較數組中的兩個對象。 因為在JavaScript中，對象{id：1，name：‘Alicw‘}不等於{id：1，name：‘Alice‘}，它認為整個孩子需要被刪除並被一個新的替換。

要解決這個問題，你可以指定映射外掛程式應該使用哪個鍵來確定對象是新的還是舊的。 你可以這樣設定：

var mapping = {    ‘children‘: {        key: function(data) {            return ko.utils.unwrapObservable(data.id);        }    }}var viewModel = ko.mapping.fromJS(data, mapping);

這樣，每次映射外掛程式檢查children數組中的一個項目時，它只會查看id屬性來確定一個對象是否被完全替換或只是需要更新。

使用“create”定製物件建構

如果你想自己處理映射的一部分，你也可以提供一個create回調。 如果這個回調存在，映射外掛程式將允許你自己做這部分的映射。

假設您有一個類似於以下內容的JavaScript對象：

var data = {    name: ‘Graham‘,    children: [        { id : 1, name : ‘Lisa‘ }    ]}

如果你想自己映射children數組，你可以這樣指定：

var mapping = {    ‘children‘: {        create: function(options) {            return new myChildModel(options.data);        }    }}var viewModel = ko.mapping.fromJS(data, mapping);

提供給create回調的options參數是一個JavaScript對象，其中包含：

• data: 包含此子項的資料的JavaScript對象
• parent: 此子項所屬的父物件或數組

當然，在建立回調中你可以做另一個調用ko.mapping.fromJS如果你願意。 一個典型的用例可能是，如果你想用一些額外的計算observables擴充原始的JavaScript對象：

var myChildModel = function(data) {    ko.mapping.fromJS(data, {}, this);         this.nameLength = ko.computed(function() {        return this.name().length;    }, this);}

使用“update”定製對象更新

您還可以通過指定更新回調來自訂對象的更新方式。 它將接收它試圖更新的對象和一個與create回調所使用的相同的選項對象。 您應該返回更新的值。

提供給更新回調的options參數是一個JavaScript對象，包含：* data：包含此子節點資料的JavaScript對象* parent：此子節點所屬的父物件或數組* observable：如果屬性是可觀察的 將被設定為實際可觀察的

下面是一個配置樣本，將在更新之前向輸入資料添加一些文本：

var data = {    name: ‘Graham‘,} var mapping = {    ‘name‘: {        update: function(options) {            return options.data + ‘foo!‘;        }    }}var viewModel = ko.mapping.fromJS(data, mapping);alert(viewModel.name());

這將彈窗提示Graham Foo！

使用“ignore”忽略某些屬性

如果你想映射外掛程式忽略你的JS對象的一些屬性（即不映射它們），你可以指定一個屬性名稱數組來忽略：

var mapping = {    ‘ignore‘: ["propertyToIgnore", "alsoIgnoreThis"]}var viewModel = ko.mapping.fromJS(data, mapping);

您在映射選項中指定的忽略數組與預設忽略數組相結合。 你可以像這樣操作這個預設數組：

var oldOptions = ko.mapping.defaultOptions().ignore;ko.mapping.defaultOptions().ignore = ["alwaysIgnoreThis"];

使用“include”包括某些屬性

當將視圖模型轉換回JS對象時，預設情況下，映射外掛程式將僅包含屬於原始視圖模型的屬性，但它也將包括Knockout產生的_destroy屬性，即使它不是原始對象的一部分 。 但是，您可以選擇自訂此數組：

var mapping = {    ‘include‘: ["propertyToInclude", "alsoIncludeThis"]}var viewModel = ko.mapping.fromJS(data, mapping);

您在映射選項中指定的include數組與預設的include數組相結合，預設情況下只包含_destroy。 你可以像這樣操作這個預設數組：

var oldOptions = ko.mapping.defaultOptions().include;ko.mapping.defaultOptions().include = ["alwaysIncludeThis"];

使用“copy”複製某些屬性

將視圖模型轉換回JS對象時，預設情況下，映射外掛程式將根據上述規則建立可觀察項。 如果你想強制映射外掛程式簡單地複製屬性而不是使其可見，添加其名稱到“複製”數組：

var mapping = {    ‘copy‘: ["propertyToCopy"]}var viewModel = ko.mapping.fromJS(data, mapping);

您在映射選項中指定的副本數組與預設副本數組相結合，預設情況下為空白。 你可以像這樣操作這個預設數組：

var oldOptions = ko.mapping.defaultOptions().copy;ko.mapping.defaultOptions().copy = ["alwaysCopyThis"];

僅使用“observe”觀察某些屬性

如果你希望映射外掛程式只建立你的JS對象的一些屬性的可觀察和複製，你可以指定一個屬性名稱數組觀察：

var mapping = {    ‘observe‘: ["propertyToObserve"]}var viewModel = ko.mapping.fromJS(data, mapping);

您在映射選項中指定的觀察數組與預設的觀察數組相結合，預設情況下為空白。 你可以像這樣操作這個預設數組：

var oldOptions = ko.mapping.defaultOptions().observe;ko.mapping.defaultOptions().observe = ["onlyObserveThis"];

數組忽略並包括仍然正常工作。 數組副本可用於複製數組或對象屬性（包括子項目）的效率。 如果在copy或observe中沒有指定數組或對象屬性，那麼它將被遞迴映射：

var data = {    a: "a",    b: [{ b1: "v1" }, { b2: "v2" }] }; var result = ko.mapping.fromJS(data, { observe: "a" });var result2 = ko.mapping.fromJS(data, { observe: "a", copy: "b" }); //will be faster to map.

結果和結果2將是：

{    a: observable("a"),    b: [{ b1: "v1" }, { b2: "v2" }] }

複製和觀察可以衝突：

var data = {    a: "a",    b: [{ b1: "v1" }, { b2: "v2" }] };var result = ko.mapping.fromJS(data, { observe: "b[0].b1"});var result2 = ko.mapping.fromJS(data, { observe: "b[0].b1", copy: "b" });

結果將是：

{    a: "a",    b: [{ b1: observable("v1") }, { b2: "v2" }] }

結果2將是：

{    a: "a",    b: [{ b1: "v1" }, { b2: "v2" }] }

指定更新目標

如果，像在上面的例子中，你正在一個類中執行映射，你希望有它作為你的映射操作的目標。 ko.mapping.fromJS的第三個參數指示目標。 例如，

ko.mapping.fromJS(data, {}, someObject); // overwrites properties on someObject

所以，如果你想映射一個JavaScript對象到這裡，你可以傳遞這個作為第三個參數：

ko.mapping.fromJS(data, {}, this);

從多個來源映射

您可以通過應用多個ko.mapping.fromJS調用在一個視圖模型中組合多個JS對象，例如：

var viewModel = ko.mapping.fromJS(alice, aliceMappingOptions);ko.mapping.fromJS(bob, bobMappingOptions, viewModel);

在每個調用中指定的映射選項將被合并。

映射監控屬性數組

由映射外掛程式產生的可觀察數組通過一些可以利用鍵映射的函數來擴充：

• mappedRemove
• mappedRemoveAll
• mappedDestroy
• mappedDestroyAll
• mappedIndexOf

它們在功能上等同於常規的ko.observableArray函數，但是可以基於對象的鍵來做事情。 例如：

var obj = [    { id : 1 },    { id : 2 }] var result = ko.mapping.fromJS(obj, {    key: function(item) {        return ko.utils.unwrapObservable(item.id);    }}); result.mappedRemove({ id : 2 });

映射的observablearray還公開了一個映射的Create函數：

var newItem = result.mappedCreate({ id : 3 });

它將首先檢查鍵是否已經存在，如果是，將拋出異常。 接下來，它將調用create和update回調（如果有的話）來建立新對象。 最後，它將把這個對象添加到數組並返回它。

KnockoutJS 3.X 結語

至此，所有KnockoutJS 3.X的API文檔撰寫完畢，希望這個完整的KnockoutJS中文文檔能對你有所協助，感謝你的閱讀。如果你覺得不錯，請點一波推薦，關注。如果你覺得文中有那些不妥，歡迎批評指正。

感謝您的閱讀。

轉載請註明出處：http://www.cnblogs.com/smallprogram/ 

再次感謝

KnockoutJS 3.X API 第八章 映射(mapping)外掛程式