Backbone.Collection（集合）

优质

小牛编辑

130浏览

2023-12-01

集合是模型的有序组合，我们可以在集合上绑定 "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(acoders, options) {
    if (condition) {
      return new PublicDocument(acoders, options);
    } else {
      return new PrivateDocument(acoders, options);
    }
  }

});

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

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

modelscollection.models
访问集合中模型的内置的JavaScript 数组。通常我们使用 get， at，或 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文档中全部详情…(注：下面链接已经替换成中文文档的地址)

forEach (each)
map (collect)
reduce (foldl, inject)
reduceRight (foldr)
find (detect)
filter (select)
reject
every (all)
some (any)
contains (include)
invoke
max
min
sortBy
groupBy
shuffle
toArray
size
first (head, take)
initial
rest (tail, drop)
last
without
indexOf
lastIndexOf
isEmpty
chain
difference
sample
partition
countBy
indexBy

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。
通过传递null给models选项来清空你的集合。

下面是一个例子使用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 acodeributes 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(acoderibute)
从集合中的每个模型中拉取 acoderibute（属性）。等价于调用 map，并从迭代器中返回单个属性。

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

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

alert(JSON.stringify(names));

wherecollection.where(acodeributes)
返回集合中所有匹配所传递 acodeributes（属性）的模型数组。对于简单的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(acodeributes)
就像where，不同的是findWhere直接返回匹配所传递 acodeributes（属性）的第一个模型。

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 Twicodeer Search API returns tweets under "results".
  parse: function(response) {
    return response.results;
  }
});

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

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