Knockout应用开发指南 第七章：Mapping插件

Mapping插件

Knockout设计成容许你使用任何JavaScript对象做为view model。必须view model的一些属性是observable的，你可使用KO绑定他们到你的UI元素上，当这些observable值改变的时候，这些UI元素就会自动更新。

绝大多数程序都须要从服务器端获取数据，可是因为服务器不知道observable的概念是什么，它只支持简单的JavaScript对象（一般是序列化之后的JSON），mapping插件可让你很方便地将简单JavaScript对象mapp到带有observable值的view model。你也能够本身写JavaScript代码将从服务器获取的数据来构建 view model，mapping插件只是一种很好的替代而已。

 下载

    Version 2.0 （最小版本8.6kb）

 

例子：手工mapping

显示当前服务器时间和你网站上的当前用户数。你应该使用以下的view model来表明你的这些信息：

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

而后绑定view model到HTML元素上，以下：

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

因为view model属性是observable的，在他们变化的时候，KO会自动更新绑定的HTML元素。

接下来，从服务器获取最新的数据。或许每隔5秒你要调用一次Ajax请求（例如，使用jQuery的$.getJSON或$.ajax函授）：

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

而后，服务器返回和下面类似的JSON数据：

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

最后，用这些数据更新你的view model（不使用mapping插件），代码以下：

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

为了使数据显示在页面上，全部的属性都要像这样写代码。若是你的数据结构很复杂的话（例如，包含子对象或者数组），那就维护起来就至关痛苦。mapping插件就是来让你让你的JavaScript简单对象（或JSON结构）转换成observable的view model的。

 

例子：使用ko.mapping

经过mapping插件建立view model，直接使用ko.mapping.fromJS函数来建立：

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

它会自动将data里全部的属性建立成observable类型的属性。你能够经过ko.mapping.fromJS 函数按期从服务器获取数据，而后更新你的view model：

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

 

如何mapping？

    对象的全部属性都被转换成observable类型值，若是获取的对象的值改变了，就会更新这个observable类型的值.

    数组也被转换成了observable数组，若是服务器更新改变了数组的个数，mapping插件也会添加或者删除相应的item项，也会尽可能保持和原生JavaScript数组相同的order顺序。

 

Unmapping

若是你想让map过的对象转换成原来的JavaScript对象，使用以下方式：

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

会建立一个unmapped对象，只包含你以前map过的对象属性，换句话说，你在view model上手工添加的属性或者函数都会被忽略的，惟一例外的是_destroy属性是能够unmapped回来的，由于你从ko.observableArray里destroy一个item项的时候会生成这个属性。 请参考“高级用户”小节如何配置使用。

 

与JSON字符串一块儿使用

若是你的Ajax调用返回的是JSON字符串（而不是反序列化后的JavaScript对象），你可使用ko.mapping.fromJSON函数来建立或者更新你的view model。用ko.mapping.toJSON实现unmap。

使用.from/toJSON函数处理JSON字符串和使用.from/toJS函数处理JS对象是等价的。

 

高级用法

有时候，在使用ko.mapping.fromJS的时候，可能有必要去使用mapping的高级用法来定义mapping的详细过程，之后定义了，之后再调用的时候就没必要再定义了。这里有一些情形，你可能须要使用这些option。

 

用法1：使用keys来使对象unique化

你有一个JavaScript对象，以下：

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

使用map插件，你能够将它map到view model上（没任何问题）：

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

如今，数据被更新成以下这样：

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

这里发生了两件事：name从Scot变成了Scott，children[0].name从Alicw变成了Alice。你能够用以下代码更新view model：

ko.mapping.fromJS(data, viewModel);

因而，name像咱们指望的同样更新了，可是在children数组里，子项Alicw被删除而新项Alice被添加到数组里。这不是咱们所指望的，咱们指望的是只是把name从Alicw更新成Alice，不是替换整个item项。发生的缘由是，默认状况下mapping plugin插件只是简单地比较数组里的两个对象是否相等。 由于JavaScript里{ id : 1, name : 'Alicw' }和{ id : 1, name : 'Alice' }是不相等的，因此它认为喜欢将新项替换掉老项。

解决这个问题，你须要声明一个key让mapping插件使用，用来判断一个对象是新对象仍是旧对象。代码以下：

var mapping = {
    'children': {
        key: function (data) {
            return ko.utils.unwrapObservable(data.id);
        }
    }
}

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

这样，每次map的时候，mapping插件都会检查数组项的id属性来判断这个数组项是须要合并的仍是全新replace的。

 

用法2：用create自定义对象的构造器

若是你想本身控制mapping，你也可使用create回调。使用回调可让你本身控制mapping。

举例，你有一个像这样的JavaScript对象：

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

若是你想本身map children 数组，你能够这样声明：

var mapping = {
    'children': {
        create: function (options) {
            return new myChildModel(options.data);
        }
    }
}

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

支持create回调的options参数是一个JavaScript对象，包含以下：

• data： JavaScript对象，包含child用到的数据
• parent：child对象所属的父对象或者数组

 固然，在内部的create回调里，你也能够再次调用ko.mapping.fromJS。一个例子就是：若是你想让初始的JavaScript对象带有额外的依赖属性dependent observables：

var myChildModel = function (data) {
    ko.mapping.fromJS(data, {}, this); 

    this.nameLength = ko.dependentObservable(function () {
        return this.name().length;
    }, this);
}

 

用法3：用update自定义对象的updating

你也可使用update 回调来自定义一个对象如何更新。它接受一个须要替代的对象以及和create 回调同样的options参数，你应该return更新后的值。

update 回调使用的options参数是一个JavaScript对象，包含以下内容：

• data：JavaScript对象，包含child用到的数据
• parent：child对象所属的父对象或者数组
• observable：若是属性是observable的，这将会写入到实际的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());

alert的结果是：Grahamfoo!。

 

用法4：使用ignore忽略不须要map的属性

若是在map的时候，你想忽略一些属性，你可使用ignore累声明须要忽略的属性名称集合：

var mapping = {
    'ignore': ["propertyToIgnore", "alsoIgnoreThis"]
}

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

你声明的忽略数组被编译到默认的ignore数组里。你能够像下面代码同样来维护它：

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

 

用法5：使用include声明须要map的属性

默认状况下，当map你的view model回到JS对象是时候，只map原始view model里拥有的属性（除了例外的_destroy属性），不过，你可使用include参数来定制：

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"];

 

用法6：使用copy来复制属性

默认状况下，map的时候是把全部的值都转换成observable的，若是你只是想copy属性值而不是替换成observable的，你能够将属性名称添加到copy数组：

var mapping = {
    'copy': ["propertyToCopy"]
}

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

你声明的copy数组被编译到默认的copy数组里，默认值是空。你能够像这样来维护：

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

 

用法7：Specifying the update target

在上面的例子，若是你想再一个class内map，你可使用第三个参数做为操做的目标，例如：

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

因此，若是你想map一个JavaScript对象到this上，你能够这样声明：

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

 

从多数据源map

你能够经过屡次使用ko.mapping.fromJS 来将多个JS对象的数据源map到一块儿，例如：

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

你声明的mapping选项option在每次调用的时候都会合并。

 

Map之后的observable数组

map插件map之后生产的observable数组，带有几个额外的函数来处理带有keys的mapping：

• mappedRemove
• mappedRemoveAll
• mappedDestroy
• mappedDestroyAll
• mappedIndexOf

 它们是和ko.observableArray里的函数等价的，不一样是他们经过key来处理对象。例如：

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 });

map过的observable数组，除了上面的函数还支持一个mappedCreate函数：

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

首先会检查key（id=3）在数组里是否存在（若是存在则抛出异常），而后，若是有create和 update回调的话会调用他们，最后建立一个新对象，并将新对象添加到数组而后返回该新对象。

 

下载

    Version 2.0 （最小版本8.6kb）