Backbone 1.0.0 版 API _ Backbone.Events 解析

Events is a module that can be mixed in to any object, giving the object the ability to bind and trigger custom named events. Events do not have to be declared before they are bound, and may take passed arguments. For example

var object = {};
_.extend(object, Backbone.Events);
object.on("alert", function(msg) {
  alert("Triggered " + msg);
});
object.trigger("alert", "an event");

Backbone.Events是一个能够被任何对象继承的模块，如果一个对象继承Events后，将拥有Events的一些能力，即能绑定和触发自定义事件。使用Events不需要声明，只需要传入相应的参数即可。

For example, to make a handy event dispatcher that can coordinate events among different areas of your application: var dispatcher = _.clone(Backbone.Events)

可以很简单的创建一个事件适配器，能够整合你的程序中不同地方用到的事件。

onobject.on(event, callback, [context])Alias: bind 
Bind a callback function to an object. The callback will be invoked whenever the eventis fired. If you have a large number of different events on a page, the convention is to use colons to namespace them: "poll:start", or "change:selection". The event string may also be a space-delimited list of several events...

 

on是Backbone.Events的一个方法，通过extend继承后的对象就可以调用on方法，bind是on的别名：

book.on === book.bind;  //true

 on支持多个自定义事件同时绑定，用空格分割。

 

book.on("change:title change:author", ...);

To supply a context value for this when the callback is invoked, pass the optional third argument: model.on('change', this.render, this)

 

绑定的事件被激活后，可以通过第三个参数，传递上下文。

 

Callbacks bound to the special "all" event will be triggered when any event occurs, and are passed the name of the event as the first argument. For example, to proxy all events from one object to another:

 

有一个特殊的事件，即 all，任何事件的触发都会触发all绑定的事件，同时会将事件名作为第一个参数传递给all绑定的事件。

 

proxy.on("all", function(eventName) {
  object.trigger(eventName);
});

All Backbone event methods also support an event map syntax, as an alternative to positional arguments:

Backbone.Events的所有方法都支持事件map映射，如下更容易使用：

 

book.on({
  "change:title": titleView.update,
  "change:author": authorPane.update,
  "destroy": bookView.remove
});

offobject.off([event], [callback], [context])Alias: unbind 
Remove a previously-bound callback function from an object. If no context is specified, all of the versions of the callback with different contexts will be removed. If no callback is specified, all callbacks for the event will be removed. If no event is specified, callbacks for all events will be removed.

 

off移除绑定事件，别名unbind，最多有三个参数，都是可选项。如果没有参数的话，就是移除所有事件的所有callback，如果有一个参数就是event的所有callback；如果有两个参数就是移除event的callback；如果有三个参数，就是移除context身上绑定的event对应的callback方法。

event和callback可能为null，表示不指定具体某一个event或callback，而是移除所有event或者callback.

 

// Removes just the `onChange` callback.
object.off("change", onChange);

// Removes all "change" callbacks.
object.off("change");

// Removes the `onChange` callback for all events.
object.off(null, onChange);

// Removes all callbacks for `context` for all events.
object.off(null, null, context);

// Removes all callbacks on `object`.
object.off();

Note that calling model.off(), for example, will indeed remove all events on the model — including events that Backbone uses for internal bookkeeping.

 triggerobject.trigger(event, [*args]) 

Trigger callbacks for the given event, or space-delimited list of events. Subsequent arguments to trigger will be passed along to the event callbacks.

 

触发事件，支持map映射

var object = {};
_.extend(object, Backbone.Events);
object.on("all", function (eventname) {
		alert(eventname);
	});
object.on({
		"test" : function (msg) {
			alert(msg);
		},
		"hello" : function (msg) {
			alert(msg);
		}
	});
object.trigger({
		"test" : "hello",
		"hello" : "hello world"
	});

 

onceobject.once(event, callback, [context]) 
Just like on, but causes the bound callback to only fire once before being removed. Handy for saying "the next time that X happens, do this".

 

once就是on事件的一个简单的封装，即自定义事件触发一次后就移除callback。

 

listenToobject.listenTo(other, event, callback) 
Tell an object to listen to a particular event on an other object. The advantage of using this form, instead of other.on(event, callback), is that listenTo allows the object to keep track of the events, and they can be removed all at once later on.

 

让一个对象监听另外一个对象发生的特殊事件，在表单应用中有优势。

 

view.listenTo(model, 'change', view.render);

stopListeningobject.stopListening([other], [event], [callback]) 
Tell an object to stop listening to events. Either call stopListening with no arguments to have the object remove all of its registered callbacks ... or be more precise by telling it to remove just the events it's listening to on a specific object, or a specific event, or just a specific callback.

相对于listenTo，停止监听。

 

view.stopListening();

view.stopListening(model);

listenToOnceobject.listenToOnce(other, event, callback) 
Just like listenTo, but causes the bound callback to only fire once before being removed.

只监听一次，一次后就stopListening

 

 

Catalog of Events 
Here's the complete list of built-in Backbone events, with arguments. You're also free to trigger your own events on Models, Collections and Views as you see fit. TheBackbone object itself mixes in Events, and can be used to emit any global events that your application needs.

下面的是Backbone.Events内置的一些儿事件，当然你也可以触发你绑定在Model上的自定义事件。

• "add" (model, collection, options) — when a model is added to a collection.
• "remove" (model, collection, options) — when a model is removed from a collection.
• "reset" (collection, options) — when the collection's entire contents have been replaced.
• "sort" (collection, options) — when the collection has been re-sorted.
• "change" (model, options) — when a model's attributes have changed.
• "change:[attribute]" (model, value, options) — when a specific attribute has been updated.
• "destroy" (model, collection, options) — when a model is destroyed.
• "request" (model, xhr, options) — when a model (or collection) has started a request to the server.
• "sync" (model, resp, options) — when a model (or collection) has been successfully synced with the server.
• "error" (model, xhr, options) — when a model's save call fails on the server.
• "invalid" (model, error, options) — when a model's validation fails on the client.
• "route:[name]" (params) — Fired by the router when a specific route is matched.
• "route" (router, route, params) — Fired by history (or router) when any route has been matched.
• "all" — this special event fires for any triggered event, passing the event name as the first argument.

Generally speaking, when calling a function that emits an event (model.set(),collection.add, and so on...), if you'd like to prevent the event from being triggered, you may pass {silent: true} as an option. Note that this is rarely, perhaps even never, a good idea. Passing through a specific flag in the options for your event callback to look at, and choose to ignore, will usually work out better.

整体来说，当触发一个事件的回调函数是，你也可以通过传递参数silent: true，来阻止回调函数的执行。