返回值:jQuerybind(eventType, [eventData], handler(eventObject))
Attach a handler to an event for the elements.
-
1.0 新增bind(eventType, [eventData], handler(eventObject))
eventType (String) A string containing one or more JavaScript event types, such as "click" or "submit," or custom event names.eventData (Object) 可选参数,将要传递给事件处理函数的数据映射。handler(eventObject) (Function) 每当事件触发时执行的函数。 -
1.4.3 新增bind(eventType, [eventData], false)
eventType (String) A string containing one or more JavaScript event types, such as "click" or "submit," or custom event names.eventData (Object) 可选参数,将要传递给事件处理函数的数据映射。false (Boolean) Setting the third argument to false will attach a function that prevents the default action from occurring and stops the event from bubbling. -
1.4 新增bind(events)
events (Object) A map of one or more JavaScript event types and functions to execute for them.
The .bind()
method is the primary means of attaching behavior to a document. All JavaScript event types, such as focus
, mouseover
, and resize
, are allowed for eventType.
(The beforeunload
and error
events on the window
object use nonstandard conventions and are not supported by jQuery; attach a handler directly to the window
object instead.)
The jQuery library provides shortcut methods for binding the standard event types, such as .click()
for .bind('click')
. A description of each can be found in the discussion of its shortcut method: blur, focus, focusin, focusout, load, resize, scroll, unload, click, dblclick, mousedown, mouseup, mousemove, mouseover, mouseout, mouseenter, mouseleave, change, select, submit, keydown, keypress, keyup, error
Any string is legal for eventType
; if the string is not the name of a native JavaScript event, then the handler is bound to a custom event. These events are
never called by the browser, but may be triggered manually from other JavaScript code using .trigger()
or .triggerHandler()
.
If the eventType
string contains a period (.
) character, then the event is namespaced. The period character separates the event from its namespace. For example, in the
call .bind('click.name', handler)
, the string click
is the event type, and the string name
is the namespace. Namespacing allows us to unbind or trigger some events of a type without affecting others. See the discussion
of .unbind()
for more information.
When an event reaches an element, all handlers bound to that event type for the element are fired. If there are multiple handlers registered, they will always execute in the order in which they were bound. After all handlers have executed, the event continues along the normal event propagation path.
A basic usage of .bind()
is:
$('#foo').bind('click', function() { alert('User clicked on "foo."'); });
This code will cause the element with an ID of foo
to respond to the click
event. When a user clicks inside this element thereafter, the alert will be shown.
Multiple Events
Multiple event types can be bound at once by including each one separated by a space:
$('#foo').bind('mouseenter mouseleave', function() { $(this).toggleClass('entered'); });
The effect of this on <div id="foo">
(when it does not initially have the "entered" class) is to add the "entered" class when the mouse enters the <div>
and remove the class when the mouse leaves.
As of jQuery 1.4 we can bind multiple event handlers simultaneously by passing a map of event type/handler pairs:
$('#foo').bind({ click: function() { // do something on click }, mouseenter: function() { // do something on mouseenter } });
Event Handlers
The handler
parameter takes a callback function, as shown above. Within the handler, the keyword this
refers to the DOM element to which the handler is bound. To make use of the element in jQuery, it can be passed to the normal
$()
function. For example:
$('#foo').bind('click', function() { alert($(this).text()); });
After this code is executed, when the user clicks inside the element with an ID of foo
, its text contents will be shown as an alert.
As of jQuery 1.4.2 duplicate event handlers can be bound to an element instead of being discarded. For example:
function test(){ alert("Hello"); } $("button").click( test ); $("button").click( test );
The above will generate two alerts when the button is clicked.
In jQuery 1.4.3 you can now pass in 'false' in place of an event handler. This will bind an event handler that's equivalent
to: function(){ return false; }
. This function can be removed at a later time by calling: .unbind( eventName, false )
.
The Event object
The handler
callback function can also take parameters. When the function is called, the JavaScript event object will be passed to the
first parameter.
The event object is often unnecessary and the parameter omitted, as sufficient context is usually available when the handler is bound to know exactly what needs to be done when the handler is triggered. However, at times it becomes necessary to gather more information about the user's environment at the time the event was initiated. View the full Event Object.
Returning false
from a handler is equivalent to calling both .preventDefault()
and .stopPropagation()
on the event object.
Using the event object in a handler looks like this:
$(document).ready(function() { $('#foo').bind('click', function(event) { alert('The mouse cursor is at (' + event.pageX + ', ' + event.pageY + ')'); }); });
Note the parameter added to the anonymous function. This code will cause a click on the element with ID foo
to report the page coordinates of the mouse cursor at the time of the click.
Passing Event Data
The optional eventData
parameter is not commonly used. When provided, this argument allows us to pass additional information to the handler. One
handy use of this parameter is to work around issues caused by closures. For example, suppose we have two event handlers that
both refer to the same external variable:
var message = 'Spoon!'; $('#foo').bind('click', function() { alert(message); }); message = 'Not in the face!'; $('#bar').bind('click', function() { alert(message); });
Because the handlers are closures that both have message
in their environment, both will display the message Not in the face! when triggered. The variable's value has changed. To sidestep this, we can pass the message in using eventData
:
var message = 'Spoon!'; $('#foo').bind('click', {msg: message}, function(event) { alert(event.data.msg); }); message = 'Not in the face!'; $('#bar').bind('click', {msg: message}, function(event) { alert(event.data.msg); });
This time the variable is not referred to directly within the handlers; instead, the variable is passed in by value through eventData
, which fixes the value at the time the event is bound. The first handler will now display Spoon! while the second will alert Not in the face!
Note that objects are passed to functions by reference, which further complicates this scenario.
If eventData
is present, it is the second argument to the .bind()
method; if no additional data needs to be sent to the handler, then the callback is passed as the second and final argument.
See the
.trigger()
method reference for a way to pass data to a handler at the time the event happens rather than when the handler is bound.
As of jQuery 1.4 we can no longer attach data (and thus, events) to object, embed, or applet elements because critical errors occur when attaching data to Java applets.
示例:
Handle click and double-click for the paragraph. Note: the coordinates are window relative, so in this case relative to the demo iframe.
<!DOCTYPE html>
<html>
<head>
<style>
p { background:yellow; font-weight:bold; cursor:pointer;
padding:5px; }
p.over { background: #ccc; }
span { color:red; }
</style>
<script src="jquery.min.js"></script>
</head>
<body>
<p>Click or double click here.</p>
<span></span>
<script>
$("p").bind("click", function(event){
var str = "( " + event.pageX + ", " + event.pageY + " )";
$("span").text("Click happened! " + str);
});
$("p").bind("dblclick", function(){
$("span").text("Double-click happened in " + this.nodeName);
});
$("p").bind("mouseenter mouseleave", function(event){
$(this).toggleClass("over");
});
</script>
</body>
</html>
演示:
示例:
To display each paragraph's text in an alert box whenever it is clicked:
jQuery 代码:
$("p").bind("click", function(){
alert( $(this).text() );
});
示例:
You can pass some extra data before the event handler:
jQuery 代码:
function handler(event) {
alert(event.data.foo);
}
$("p").bind("click", {foo: "bar"}, handler)
示例:
Cancel a default action and prevent it from bubbling up by returning false:
jQuery 代码:
$("form").bind("submit", function() { return false; })
示例:
Cancel only the default action by using the .preventDefault() method.
jQuery 代码:
$("form").bind("submit", function(event) {
event.preventDefault();
});
示例:
Stop an event from bubbling without preventing the default action by using the .stopPropagation() method.
jQuery 代码:
$("form").bind("submit", function(event) {
event.stopPropagation();
});
示例:
Bind custom events.
<!DOCTYPE html>
<html>
<head>
<style>
p { color:red; }
span { color:blue; }
</style>
<script src="jquery.min.js"></script>
</head>
<body>
<p>Has an attached custom event.</p>
<button>Trigger custom event</button>
<span style="display:none;"></span>
<script>
$("p").bind("myCustomEvent", function(e, myName, myValue){
$(this).text(myName + ", hi there!");
$("span").stop().css("opacity", 1)
.text("myName = " + myName)
.fadeIn(30).fadeOut(1000);
});
$("button").click(function () {
$("p").trigger("myCustomEvent", [ "John" ]);
});
</script>
</body>
</html>
演示:
示例:
Bind multiple events simultaneously.
jQuery 代码:
$("div.test").bind({
click: function(){
$(this).addClass("active");
},
mouseenter: function(){
$(this).addClass("inside");
},
mouseleave: function(){
$(this).removeClass("inside");
}
});