Backbone.Collection(集合)

集合是模型的有序组合,我们可以在集合上绑定 "change" 事件,从而当集合中的模型发生变化时fetch(获得)通知,集合也可以监听 "add""remove" 事件, 从服务器更新,并能使用 Underscore.js 提供的方法。

集合中的模型触发的任何事件都可以在集合身上直接触发,所以我们可以监听集合中模型的变化: documents.on("change:selected", ...)

extendBackbone.Collection.extend(properties, [classProperties]) 通过扩展 Backbone.Collection 创建一个 Collection 类。实例属性参数 properties 以及 类属性参数 classProperties 会被直接注册到集合的构造函数。

modelcollection.model 覆盖此属性来指定集合中包含的模型类。可以传入原始属性对象(和数组)来 add, create,和 reset,传入的属性会被自动转换为适合的模型类型。

var Library = Backbone.Collection.extend({
  model: Book
});

集合也可以包含多态模型,通过用构造函数重写这个属性,返回一个模型。

var Library = Backbone.Collection.extend({

  model: function(attrs, options) {
    if (condition) {
      return new PublicDocument(attrs, options);
    } else {
      return new PrivateDocument(attrs, options);
    }
  }

});

constructor / initializenew Backbone.Collection([models], [options]) 当创建集合时,你可以选择传入初始的 models 数组。 集合的 comparator 函数也可以作为选项传入。 传递false作为comparator选项将阻止排序。 如果定义了 initialize 函数,会在集合创建时被调用。 有几个选项, 如果提供的话,将直接附加到集合上:modelcomparator。 通过传递nullmodels选项来创建一个空的集合。

var tabs = new TabSet([tab1, tab2, tab3]);
var spaces = new Backbone.Collection([], {
  model: Space
});

modelscollection.models 访问集合中模型的内置的JavaScript 数组。通常我们使用 getat,或 Underscore方法 访问模型对象,但偶尔也需要直接访问。

toJSONcollection.toJSON([options]) 返回集合中包含的每个模型(通过 toJSON) 的属性哈希的数组。可用于集合的序列化和持久化。本方法名称容易引起混淆,因为它与 JavaScript's JSON API 命名相同。

var collection = new Backbone.Collection([
  {name: "Tim", age: 5},
  {name: "Ida", age: 26},
  {name: "Rob", age: 55}
]);

alert(JSON.stringify(collection));

synccollection.sync(method, collection, [options]) 使用 Backbone.sync来将一个集合的状态持久化到服务器。 可以自定义行为覆盖。

Underscore 方法 (32) Backbone 代理了 Underscore.js用来给Backbone.Collection提供 6 个对象函数。这里没有完全记录他们,但你可以看看Underscore文档中全部详情…(愚人码头注:下面链接已经替换成中文文档的地址)

books.each(function(book) {
  book.publish();
});

var titles = books.map(function(book) {
  return book.get("title");
});

var publishedBooks = books.filter(function(book) {
  return book.get("published") === true;
});

var alphabetical = books.sortBy(function(book) {
  return book.author.get("name").toLowerCase();
});

addcollection.add(models, [options]) 向集合中增加一个模型(或一个模型数组),触发"add"事件。 如果已经定义了model属性, 您也可以通过原始属性的对象让其看起来像一个模型实例。 返回已经添加的(或预先存在的,如果重复)模式。 传递{at: index}可以将模型插入集合中特定的index索引位置。 如果您要添加 集合中已经存在的模型 到集合,他们会被忽略, 除非你传递{merge: true}, 在这种情况下,它们的属性将被合并到相应的模型中, 触发任何适当的"change" 事件。

var ships = new Backbone.Collection;

ships.on("add", function(ship) {
  alert("Ahoy " + ship.get("name") + "!");
});

ships.add([
  {name: "Flying Dutchman"},
  {name: "Black Pearl"}
]);

请注意,添加相同的模型(具有相同id的模型)到一个集合,一次以上 是空操作。

removecollection.remove(models, [options]) 从集合中删除一个模型(或一个模型数组),并且返回他们。会触发 "remove" 事件,同样可以使用 silent 关闭。移除前该模型的index可用作options.index类监听。

resetcollection.reset([models], [options]) 每次都是只添加和删除一个模型那没问题, 但有时,你需要改变很多模型,那么你宁愿只更新集合。 使用reset,将一个新的模型(或属性散列)列表替换集合,最后触发一个但单独的"reset"事件。 到与模型的新列表替换集合(或属性散列),触发一个单一的“复位”事件在末端。 返回新的模型集合。 为方便起见, 在一个 "reset"事件中, 任何以前的模型列表可作为options.previousModels。 通过传递nullmodels选项来清空你的集合。

下面是一个例子 使用reset来引导一个集合在页面初始化时加载, 在Rails应用程序中:

<script>
  var accounts = new Backbone.Collection;
  accounts.reset(<%= @accounts.to_json %>);
</script>

调用collection.reset(),不传递任何模型作为参数 将清空整个集合。

setcollection.set(models, [options]) set方法通过传递模型列表执行一个集合的"smart(智能)"的更新。 如果列表中的一个模型尚不在集合中,那么它将被添加; 如果模型已经在集合中,其属性将被合并; 并且如果集合包含存在于列表中的任何模型,他们将被删除。 以上所有将触发相应的"add", "remove", 和 "change"事件。 返回集合中的模型。 如果您想自定义的行为, 你可以设置选项:{add: false}, {remove: false}, 或 {merge: false},将其禁用。

var vanHalen = new Backbone.Collection([eddie, alex, stone, roth]);

vanHalen.set([eddie, alex, stone, hagar]);

// Fires a "remove" event for roth, and an "add" event for "hagar".
// Updates any of stone, alex, and eddie's attributes that may have
// changed over the years.

getcollection.get(id) 通过一个id,一个cid,或者传递一个model来 获得集合中 的模型。

var book = library.get(110);

atcollection.at(index) 获得集合中指定索引的模型。不论你是否对模型进行了重新排序, at 始终返回其在集合中插入时的索引值。

pushcollection.push(model, [options]) 在集合尾部添加一个模型。选项和add相同。

popcollection.pop([options]) 删除并且返回集合中最后一个模型。选项和remove相同。

unshiftcollection.unshift(model, [options]) 在集合开始的地方添加一个模型。选项和add相同。

shiftcollection.shift([options]) 删除并且返回集合中第一个模型。选项和remove相同。

slicecollection.slice(begin, end) 返回一个集合的模型的浅拷贝副本,使用与原生Array#slice相同的选项。

lengthcollection.length 与数组类似,集合拥有 length 属性,返回该集合包含的模型数量。

comparatorcollection.comparator 默认情况下,集合没有声明 comparator 函数。如果定义了该函数,集合中的模型会按照指定的算法进行排序。 换言之,被增加模型,会被插入 collection.models中适合的位置。 comparator可以被定义为sortBy(传递带有一个参数的函数), 作为一个sort(传递一个一个参数函数需要两个参数), 或者作为一个表示属性的字符串进行排序。

"sortBy"比较函数接受一个模型,并且返回一个该模型相对于其他模型的排序数字或字符串值。 "sort"比较函数接受两个模型,并且,如果第一个模型应该在第二模型个之前,返回-1; 如果他们是同一等级的,返回0; 如果第一个模型应该在第二模型个之后,返回1需要注意的是 Backbone 这两种风格的比较功能的确定 取决于参数个数。所以如果你绑定了比较函数,需要格外小心。

注意即使下面例子中的 chapters 是后加入到集合中的,但它们都会遵循正确的排序:

var Chapter  = Backbone.Model;
var chapters = new Backbone.Collection;

chapters.comparator = 'page';

chapters.add(new Chapter({page: 9, title: "The End"}));
chapters.add(new Chapter({page: 5, title: "The Middle"}));
chapters.add(new Chapter({page: 1, title: "The Beginning"}));

alert(chapters.pluck('title'));

如果以后更改模型属性,带有比较函数的集合不会自动重新排序。 所以你不妨改变模型的属性后调用sort, 这会影响排序。

sortcollection.sort([options]) 强制对集合进行重排序。一般情况下不需要调用本函数,因为当一个模型被添加时, comparator 函数会实时排序。要禁用添加模型时的排序,可以传递{sort: false}add。 调用sort会触发的集合的"sort"事件。

pluckcollection.pluck(attribute) 从集合中的每个模型中拉取 attribute(属性)。等价于调用 map,并从迭代器中返回单个属性。

var stooges = new Backbone.Collection([
  {name: "Curly"},
  {name: "Larry"},
  {name: "Moe"}
]);

var names = stooges.pluck("name");

alert(JSON.stringify(names));

wherecollection.where(attributes) 返回集合中所有匹配所传递 attributes(属性)的模型数组。 对于简单的filter(过滤)比较有用。

var friends = new Backbone.Collection([
  {name: "Athos",      job: "Musketeer"},
  {name: "Porthos",    job: "Musketeer"},
  {name: "Aramis",     job: "Musketeer"},
  {name: "d'Artagnan", job: "Guard"},
]);

var musketeers = friends.where({job: "Musketeer"});

alert(musketeers.length);

findWherecollection.findWhere(attributes) 就像where, 不同的是findWhere直接返回匹配所传递 attributes(属性)的第一个模型。

urlcollection.url or collection.url() 设置 url 属性(或函数)以指定集合对应的服务器位置。集合内的模型使用 url 构造自身的 URLs。

var Notes = Backbone.Collection.extend({
  url: '/notes'
});

// Or, something more sophisticated:

var Notes = Backbone.Collection.extend({
  url: function() {
    return this.document.url() + '/notes';
  }
});

parsecollection.parse(response, options) 每一次调用 fetch 从服务器拉取集合的模型数据时,parse都会被调用。 本函数接收原始 response 对象,返回可以 added(添加) 到集合的模型属性数组。 默认实现是无需操作的,只需简单传入服务端返回的JSON对象。 如果需要处理遗留API,或者在返回数据定义自己的命名空间,可以重写本函数。

var Tweets = Backbone.Collection.extend({
  // The Twitter Search API returns tweets under "results".
  parse: function(response) {
    return response.results;
  }
});

clonecollection.clone() 返回一个模型列表完全相同的集合新实例。

fetchcollection.fetch([options]) 从服务器拉取集合的默认模型设置 ,成功接收数据后会setting(设置)集合。 options 支持 successerror 回调函数,两个回调函数接收 (collection, response, options)作为参数。当模型数据从服务器返回时, 它使用 set来(智能的)合并所获取到的模型, 除非你传递了 {reset: true}, 在这种情况下,集合将(有效地)重置。 可以委托Backbone.sync 在幕后自定义持久性策略 并返回一个jqXHRfetch请求的服务器处理器应该返回模型JSON数组。

Backbone.sync = function(method, model) {
  alert(method + ": " + model.url);
};

var accounts = new Backbone.Collection;
accounts.url = '/accounts';

accounts.fetch();

fetch行为可以通过使用有效的set选项进行定制。 例如,要获取一个集合,每一个新的模型会得到一个 "add"事件,和每改变现有的模型的 "change"事件, 不删除任何东西: collection.fetch({remove: false})

jQuery.ajax选项也可以直接传递作为 fetch选项, 所以要获取一个分页集合的特定页面使用:Documents.fetch({data: {page: 3}})

需要注意的是 fetch 不应该被用来在页面加载完毕时填充集合数据 — 所有页面初始数据应当在 bootstrapped 时已经就绪。 fetch 适用于惰性加载不需立刻展现的模型数据:例如:例如文档中 可切换打开和关闭的选项卡内容。

createcollection.create(attributes, [options]) 方便的在集合中创建一个模型的新实例。 相当于使用属性哈希(键值对象)实例化一个模型, 然后将该模型保存到服务器, 创建成功后将模型添加到集合中。 返回这个新模型。 如果客户端验证失败,该模型将不会被保存, 与验证错误。 为了能正常运行,需要在集合中设置 model 属性。 create 方法接收键值对象或者已经存在尚未保存的模型对象作为参数。

创建一个模型将立即触发集合上的"add"事件, 一个"request"的事件作为新的模型被发送到服务器, 还有一个 "sync" ”事件,一旦服务器响应成功创建模型。 如果你想在集合中添加这个模型前等待服务器相应,请传递{wait: true}

var Library = Backbone.Collection.extend({
  model: Book
});

var nypl = new Library;

var othello = nypl.create({
  title: "Othello",
  author: "William Shakespeare"
});