Backbone.js

Backbone.Events（事件）
Events 是一个可以融合到任何对象的模块, 给予 对象绑定和触发自定义事件的能力. Events 在绑定之前 不需要声明, 并且还可以传递参数. 


onobject.on(event, callback, [context])
offobject.off([event], [callback], [context])
triggerobject.trigger(event, [*args]) 
onceobject.once(event, callback, [context]) 
listenToobject.listenTo(other, event, callback) 
stopListeningobject.stopListening([other], [event], [callback]) 
listenToOnceobject.listenToOnce(other, event, callback) 
"add" (model, collection, options) — 当一个model（模型）被添加到一个collection（集合）时触发。
"remove" (model, collection, options) — 当一个model（模型）从一个collection（集合）中被删除时触发。
"reset" (collection, options) — 当该collection（集合）的全部内容已被替换时触发。
"sort" (collection, options) — 当该collection（集合）已被重新排序时触发。
"change" (model, options) — 当一个model（模型）的属性改变时触发。
"change:[attribute]" (model, value, options) — 当一个model（模型）的某个特定属性被更新时触发。
"destroy" (model, collection, options) —当一个model（模型）被destroyed（销毁）时触发。
"request" (model_or_collection, xhr, options) — 当一个model（模型）或collection（集合）开始发送请求到服务器时触发。
"sync" (model_or_collection, resp, options) — 当一个model（模型）或collection（集合）成功同步到服务器时触发。
"error" (model_or_collection, resp, options) — 当一个model（模型）或collection（集合）的请求远程服务器失败时触发。
"invalid" (model, error, options) — 当model（模型）在客户端 validation（验证）失败时触发。
"route:[name]" (params) —  当一个特定route（路由）相匹配时通过路由器触发。
"route" (route, params) — 当任何一个route（路由）相匹配时通过路由器触发。
"route" (router, route, params) — 当任何一个route（路由）相匹配时通过history（历史记录）触发。
"all" — 所有事件发生都能触发这个特别的事件，第一个参数是触发事件的名称。






Backbone.Model（模型）
Models（模型）是任何Javascript应用的核心，包括数据交互及与其相关的大量逻辑： 转换、验证、计算属性和访问控制。你可以用特定的方法扩展 Backbone.Model，Model 也提供了一组基本的管理变化的功能。


extend  Backbone.Model.extend(properties, [classProperties]) 
constructor / initializenew Model([attributes], [options]) 
get      model.get(attribute) 从当前model中获取当前属性(attributes)值，比如： note.get("title")
set      model.set(attributes, [options]) 向model设置一个或多个hash属性(attributes)。
escape   model.escape(attribute)  与get类似，只是返回的是HTML转义后版本的model属性值。如果从model插入数据到HTML，使用escape取数据可以避免XSS攻击。
e.g. var hacker = new Backbone.Model({ name: "<script>alert('xss')</script>" });
 alert(hacker.escape('name'));


has      model.has(attribute) 属性值为非 null 或非 undefined 时返回 true。
unset    model.unset(attribute, [options])从内部属性散列表中删除指定属性(attribute).
clear    model.clear([options]) 从model中删除所有属性， 包括id属性。
id       model.id 是model的特殊属性，可以是任意字符串（整型 id 或 UUID）。在属性中设置的 id 会被直接拷贝到model属性上。 我们可以从集合（collections）中通过 id 获取model，另外 id 通常用于生成model的 URLs。


idAttribute   model.idAttribute  一个model的唯一标示符，被储存在 id 属性下。
cid           model.cid  model的特殊属性，cid 或客户 id 是当所有model创建时自动产生的唯一标识符。
attributes    model.attributes 
attributes 属性是包含模型状态的内部散列表 — 通常（但不一定）JSON对象的形式表示在服务器上模型数据 。它通常是数据库中一个行的简单的序列，但它也可以是客户端的计算状态。
建议采用 set 更新 attributes而不要直接修改。  如果您想检索和获取模型属性的副本， 用 _.clone(model.attributes) 取而代之。


changed   model.changed 
changed属性是一个包含所有属性的内部散列，自最后 set 已改变。 自最后一组已改变。 请不要直接更新 changed，因为它的状态是由set内部维护。


defaults   model.defaults or model.defaults() 
defaults 散列（或函数）用于为模型指定默认属性。 创建模型实例时，任何未指定的属性会被设置为其默认值。


toJSON    model.toJSON([options]) 
返回一个模型的 attributes 浅拷贝副本的 JSON 字符串化形式。 它可用于模型的持久化、序列化，或者发送到服务之前的扩充。 该方法名称比较混乱，因为它事实上并不返回 JSON 字符串， 但这是对 JavaScript API 的 JSON.stringify 实现。


sync    model.sync(method, model, [options]) 
使用 Backbone.sync 可以将一个模型的状态持续发送到服务器。 可以自定义行为覆盖。


fetch   model.fetch([options]) 
通过委托给Backbone.sync从服务器重置模型的状态。返回jqXHR。 如果模型从未填充数据时非常有用， 或者如果你想确保你有最新的服务器状态。 如果服务器的状态不同于当前属性的"change"事件将被触发。 接受 success 和 error回调的选项散列， 这两个回调都可以传递(model, response, options)作为参数。




save  model.save([attributes], [options]) 
通过委托给Backbone.sync，保存模型到数据库（或替代持久化层）。 如果验证成功，返回jqXHR，否则为 false


destroy   model.destroy([options]) 
通过委托给Backbone.sync，保存模型到数据库（或替代持久化层）。 


validate  model.validate(attributes, options) 
这种方法是未定义的， 如果您有任何可以在JavaScript中执行的代码 并且我们鼓励你用你自定义验证逻辑覆盖它 。


validationError    model.validationError   用validate最后验证失败时返回的值。


isValid    model.isValid()   运行validate来检查模型状态。


url  model.url() 
返回模型资源在服务器上位置的相对 URL 。 如果模型放在其它地方，可通过合理的逻辑重载该方法。 生成 URLs 的默认形式为："/[collection.url]/[id]"， 如果模型不是集合的一部分，你可以通过指定明确的urlRoot覆盖。


urlRoot   model.urlRoot or model.urlRoot() 
如果使用的集合外部的模型，通过指定 urlRoot 来设置生成基于模型 id 的 URLs 的默认 url 函数。 "[urlRoot]/id"。通常情况下，你不会需要定义这一点。 需要注意的是urlRoot也可以是一个函数。


parse     model.parse(response, options) 
parse 会在通过 fetch 从服务器返回模型数据，以及 save 时执行。 传入本函数的为原始 response 对象，并且应当返回可以 set 到模型的属性散列表。 默认实现是自动进行的，仅简单传入 JSON 响应。 如果需要使用已存在的 API，或者更好的命名空间响应，可以重载它。


clone     model.clone() 
返回该模型的具有相同属性的新实例。


isNew    model.isNew() 
模型是否已经保存到服务器。 如果模型尚无 id，则被视为新的。


hasChanged    model.hasChanged([attribute]) 
标识模型从上次 set 事件发生后是否改变过。 如果传入 attribute ，当指定属性改变后返回 true。


changedAttributes    model.changedAttributes([attributes]) 
只从最后一次set开始检索已改变的模型属性散列（hash），  或者如果没有，返回 false。 作为可选，可以传递外部属性哈希（hash）， 返回与该模型不同的属性的哈希（hash）。 这可以用来找出视图的哪些部分应该更新，或者确定哪些需要与服务器进行同步。


previous   model.previous(attribute) 
在 "change" 事件发生的过程中，本方法可被用于获取已改变属性的旧值。


previousAttributes    model.previousAttributes() 
返回模型的上一个属性的副本。一般用于获取模型的不同版本之间的区别，或者当发生错误时回滚模型状态。






Backbone.Collection（集合）
集合是模型的有序组合，我们可以在集合上绑定 "change" 事件，从而当集合中的模型发生变化时fetch（获得）通知，集合也可以监听 "add" 和 "remove" 事件， 从服务器更新，并能使用 Underscore.js 提供的方法。
集合中的模型触发的任何事件都可以在集合身上直接触发，所以我们可以监听集合中模型的变化： documents.on("change:selected", ...)


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


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




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


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


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


sync    collection.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
 
add    collection.add(models, [options]) 
向集合中增加一个模型（或一个模型数组），触发"add"事件。  


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


reset  collection.reset([models], [options]) 
每次都是只添加和删除一个模型那没问题， 但有时，你需要改变很多模型，那么你宁愿只更新集合。


set    collection.set(models, [options]) 
set方法通过传递模型列表执行一个集合的"smart(智能)"的更新。


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


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


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


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


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


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


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


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


comparator    collection.comparator 
默认情况下，集合没有声明 comparator 函数。如果定义了该函数，集合中的模型会按照指定的算法进行排序。


sort   collection.sort([options]) 
强制对集合进行重排序。一般情况下不需要调用本函数，因为当一个模型被添加时， comparator 函数会实时排序。


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


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


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


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


parse    collection.parse(response, options) 
每一次调用 fetch 从服务器拉取集合的模型数据时，parse都会被调用。


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


fetch    collection.fetch([options]) 
从服务器拉取集合的默认模型设置 ，成功接收数据后会setting（设置）集合。


create    collection.create(attributes, [options]) 
方便的在集合中创建一个模型的新实例。 相当于使用属性哈希（键值对象）实例化一个模型， 然后将该模型保存到服务器， 创建成功后将模型添加到集合中。 












Backbone.Router（路由）
web应用程序通常需要为应用的重要位置提供可链接，可收藏，可分享的 URLs。 直到最近， 猫点（hash）片段（#page）可以被用来提供这种链接， 同时随着 History API 的到来，猫点已经可以用于处理标准 URLs （/page）。 Backbone.Router 为客户端路由提供了许多方法，并能连接到指定的动作（actions）和事件（events）。 对于不支持 History API 的旧浏览器，路由提供了优雅的回调函数并可以透明的进行 URL 片段的转换。
extend Backbone.Router.extend(properties, [classProperties]) 
开始创建一个自定义的路由类。当匹配了 URL 片段便执行定义的动作，并可以通过 routes 定义路由动作键值对。 请注意，你要避免在路由定义时使用前导斜杠：


routes    router.routes 
routes 将带参数的 URLs 映射到路由实例的方法上（或只是直接的函数定义，如果你喜欢），这与 View（视图） 的 events hash（事件键值对） 非常类似。


constructor / initialize    new Router([options]) 
当创建一个新路由是，你可以直接传入 routes 键值对象作为参数。 如果定义该参数， 它们将被传入 initialize 构造函数中初始化。


route    router.route(route, name, [callback]) 
为路由对象手动创建路由，route 参数可以是 routing string（路由字符串） 或 正则表达式。


navigate    router.navigate(fragment, [options]) 
每当你达到你的应用的一个点时，你想保存为一个URL，  可以调用navigate以更新的URL。 


execute    router.execute(callback, args) 
这种方法在路由内部被调用，  每当路由和其相应的callback匹配时被执行。




Backbone.history
History 作为全局路由服务用于处理 hashchange 事件或 pushState，匹配适合的路由，并触发回调函数。


start    Backbone.history.start([options]) 
当所有的 Routers 创建并设置完毕，调用 Backbone.history.start() 开始监控 hashchange 事件并分配路由。






Backbone.sync（同步）
Backbone.sync 是 Backbone 每次向服务器读取或保存模型时都要调用执行的函数。 默认情况下，它使用 jQuery.ajax 方法发送 RESTful json 请求，并且返回一个 jqXHR。 如果想采用不同的持久化方案，比如 WebSockets, XML, 或 Local Storage，我们可以重载该函数。

ajax    Backbone.ajax = function(request) { ... }; 
如果你想使用自定义的AJAX功能， 或者你的客户端不支持的jQuery.ajax API，你需要调整的东西， 您可以通过设置Backbone.ajax这样做。

emulateHTTP    Backbone.emulateHTTP = true 
如果你想在不支持Backbone的默认REST/ HTTP方式的Web服务器上工作， 您可以选择开启Backbone.emulateHTTP。

emulateJSON    Backbone.emulateJSON = true 
如果你想在不支持发送 application/json 编码请求的Web服务器上工作，设置Backbone.emulateJSON = true;




Backbone.View（视图）


Backbone 视图几乎约定比他们的代码多 — 他们并不限定你的HTML或CSS， 并可以配合使用任何JavaScript模板库。 一般是组织您的接口转换成逻辑视图， 通过模型的支持， 模型变化时， 每一个都可以独立地进行更新， 而不必重新绘制该页面。我们再也不必钻进 JSON 对象中，查找 DOM 元素，手动更新 HTML 了，通过绑定视图的 render 函数到模型的 "change" 事件 — 模型数据会即时的显示在 UI 中。


extend    Backbone.View.extend(properties, [classProperties]) 
开始创建自定义的视图类。 通常我们需要重载 render 函数，声明 events， 以及通过 tagName, className, 或 id 为视图指定根元素。


constructor / initialize    new View([options]) 
有几个特殊的选项， 如果传入，则直接注册到视图中去： model, collection, el, id, className, tagName, attributes 和 events。


el    view.el 所有的视图都拥有一个 DOM 元素（el 属性），即使该元素仍未插入页面中去。 
$el   view.$el 一个视图元素的缓存jQuery对象。 一个简单的引用，而不是重新包装的DOM元素。
setElement    view.setElement(element) 
如果你想应用一个Backbone视图到不同的DOM元素， 使用setElement，这也将创造缓存$el引用，视图的委托事件从旧元素移动到新元素上。


attributes    view.attributes 
属性的键值对， 将被设置为视图el上的HTML DOM元素的属性， 或者是返回这样的键值对的一个函数。


$ (jQuery)    view.$(selector) 
如果页面中引入了 jQuery，每个视图都将拥有 $ 函数，可以在视图元素查询作用域内运行。


template    view.template([data]) 
虽然模板化的视图 不是Backbone直接提供的一个功能， 它往往是一个在你视图定义template函数很好的约定。 如此， 渲染你的视图时， 您方便地访问实例数据。 例如，使用Underscore的模板：


render    view.render() 
render 默认实现是没有操作的。 重载本函数可以实现从模型数据渲染视图模板，并可用新的 HTML 更新 this.el。 推荐的做法是在 render 函数的末尾 return this 以开启链式调用。


remove    view.remove() 
从 DOM 中移除一个视图。同事调用stopListening来移除通过 listenTo绑定在视图上的 所有事件。


delegateEvents     delegateEvents([events]) 
采用 jQuery 的on函数来为视图内的 DOM 事件提供回调函数声明。


undelegateEvents    undelegateEvents() 
删除视图所有委托事件。如果要从临时的DOM中禁用或删除视图时，比较有用。






Utility（实用功能）


Backbone.noConflict    var backbone = Backbone.noConflict(); 
返回 Backbone 对象的原始值。 您可以使用Backbone.noConflict()的返回值以保持局部引用Backbone。 




Backbone.$    Backbone.$ = $; 
如果页面上有多个jQuery副本， 或者只是想告诉Backbone使用特定对象作为其DOM / Ajax库， 那么这个属性可以为您服务。如果您正在使用CommonJS加载Backbone （例如，节点，组件，或browserify） 您必须手动设置该属性。