jquery-1.2.6-vsdoc-cn.js

Jquery 1.2.6 最新版本的文档

/*
 * This file has been commented to support Visual Studio Intellisense.
 * You should not use this file at runtime inside the browser--it is only
 * intended to be used only for design-time IntelliSense.  Please use the
 * standard jQuery library for all production use.
 *
 * Comment version: 1.2.6a
 */
/*
 *billsquall汉化
 *感谢之前为API1.1 1.2汉化的各位高手，参考了不少^^
 *感谢shawphy，鼓励我的好人！
 *不知道有没有侵权的说法，反正这汉化仅供大家参考，版权方面不负任何责任。
 *估计不会有人拿去做什么吧？不要用做商业用途，否则后果自负。
 */
(function(){
/*
 * jQuery 1.2.6 - New Wave Javascript
 *
 * Copyright (c) 2008 John Resig, http://jquery.com/
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 * $Date: 2008-05-24 14:22:17 -0400 (Sat, 24 May 2008) $
 * $Rev: 5685 $
 */

// Map over jQuery in case of overwrite
var _jQuery = window.jQuery,
// Map over the $ in case of overwrite
	_$ = window.$;

var jQuery = window.jQuery = window.$ = function( selector, context ) {
	///	<summary>
    ///		1: $(expression, context) - 这个函数接收一个包含 CSS 选择器的字符串，然后用这个字符串去匹配一组元素。
    ///		2: $(html) - 根据提供的原始 HTML 标记字符串，动态创建由 jQuery 对象包装的 DOM 元素。
    ///		3: $(elements) - 将一个或多个DOM元素转化为jQuery对象。
    ///		4: $(callback) - $(document).ready()的简写。
	///	</summary>
	///	<param name="selector" type="String">
    ///		1: expression - 用来查找的表达式。
    ///		2: html -用于动态创建DOM元素的HTML标记字符串
    ///		3: elements - 用于封装成jQuery对象的DOM元素
    ///		4: callback - 当DOM加载完成后，执行其中的函数。
	///	</param>
	///	<param name="context" type="jQuery">
    ///		1: context - (可选) 作为待查找的 DOM 元素集、文档或 jQuery 对象。
	///	</param>
	///	<returns type="jQuery" />

	// The jQuery object is actually just the init constructor 'enhanced'
	return new jQuery.fn.init( selector, context );
};

// A simple way to check for HTML strings or ID strings
// (both of which we optimize for)
var quickExpr = /^[^<]*(<(.|\s)+>)[^>]*$|^#(\w+)$/,

// Is it a simple selector
	isSimple = /^.[^:#\[\.]*$/,

// Will speed up references to undefined, and allows munging its name.
	undefined;

jQuery.fn = jQuery.prototype = {
	init: function( selector, context ) {
		///	<summary>
	    ///		1: $(expression, context) - 这个函数接收一个包含 CSS 选择器的字符串，然后用这个字符串去匹配一组元素。
    	///		2: $(html) - 根据提供的原始 HTML 标记字符串，动态创建由 jQuery 对象包装的 DOM 元素。
	    ///		3: $(elements) - 将一个或多个DOM元素转化为jQuery对象。
	    ///		4: $(callback) - $(document).ready()的简写。
		///	</summary>
		///	<param name="selector" type="String">
	    ///		1: expression - 用来查找的表达式。
	    ///		2: html -用于动态创建DOM元素的HTML标记字符串
	    ///		3: elements - 用于封装成jQuery对象的DOM元素
	    ///		4: callback - 当DOM加载完成后，执行其中的函数。
		///	</param>
		///	<param name="context" type="jQuery">
    	///		1: context - (可选) 作为待查找的 DOM 元素集、文档或 jQuery 对象。
		///	</param>
		///	<returns type="jQuery" />

		// Make sure that a selection was provided
		selector = selector || document;

		// Handle $(DOMElement)
		if ( selector.nodeType ) {
			this[0] = selector;
			this.length = 1;
			return this;
		}
		// Handle HTML strings
		if ( typeof selector == "string" ) {
			// Are we dealing with HTML string or an ID?
			var match = quickExpr.exec( selector );

			// Verify a match, and that no context was specified for #id
			if ( match && (match[1] || !context) ) {

				// HANDLE: $(html) -> $(array)
				if ( match[1] )
					selector = jQuery.clean( [ match[1] ], context );

				// HANDLE: $("#id")
				else {
					var elem = document.getElementById( match[3] );

					// Make sure an element was located
					if ( elem ){
						// Handle the case where IE and Opera return items
						// by name instead of ID
						if ( elem.id != match[3] )
							return jQuery().find( selector );

						// Otherwise, we inject the element directly into the jQuery object
						return jQuery( elem );
					}
					selector = [];
				}

			// HANDLE: $(expr, [context])
			// (which is just equivalent to: $(content).find(expr)
			} else
				return jQuery( context ).find( selector );

		// HANDLE: $(function)
		// Shortcut for document ready
		} else if ( jQuery.isFunction( selector ) )
			return jQuery( document )[ jQuery.fn.ready ? "ready" : "load" ]( selector );

		return this.setArray(jQuery.makeArray(selector));
	},

	// The current version of jQuery being used
	jquery: "1.2.6",

	// The number of elements contained in the matched element set
	size: function() {
		///	<summary>
		///		The number of elements currently matched.
		///		Part of Core
		///	</summary>
		///	<returns type="Number" />

		return this.length;
	},

	// The number of elements contained in the matched element set
	length: 0,

	// Get the Nth element in the matched element set OR
	// Get the whole matched element set as a clean array
	get: function( num ) {
		///	<summary>
		///		Access a single matched element. num is used to access the
		///		Nth element matched.
		///		Part of Core
		///	</summary>
		///	<returns type="Element" />
		///	<param name="num" type="Number">
		///		Access the element in the Nth position.
		///	</param>

		return num == undefined ?

			// Return a 'clean' array
			jQuery.makeArray( this ) :

			// Return just the object
			this[ num ];
	},

	// Take an array of elements and push it onto the stack
	// (returning the new matched element set)
	pushStack: function( elems ) {
		///	<summary>
		///		Set the jQuery object to an array of elements, while maintaining
		///		the stack.
		///		Part of Core
		///	</summary>
		///	<returns type="jQuery" />
		///	<param name="elems" type="Elements">
		///		An array of elements
		///	</param>
		
		// Build a new jQuery matched element set
		var ret = jQuery( elems );

		// Add the old object onto the stack (as a reference)
		ret.prevObject = this;

		// Return the newly-formed element set
		return ret;
	},

	// Force the current matched set of elements to become
	// the specified array of elements (destroying the stack in the process)
	// You should use pushStack() in order to do this, but maintain the stack
	setArray: function( elems ) {
		///	<summary>
		///		Set the jQuery object to an array of elements. This operation is
		///		completely destructive - be sure to use .pushStack() if you wish to maintain
		///		the jQuery stack.
		///		Part of Core
		///	</summary>
		///	<returns type="jQuery" />
		///	<param name="elems" type="Elements">
		///		An array of elements
		///	</param>
		
		// Resetting the length to 0, then using the native Array push
		// is a super-fast way to populate an object with array-like properties
		this.length = 0;
		Array.prototype.push.apply( this, elems );

		return this;
	},

	// Execute a callback for every element in the matched set.
	// (You can seed the arguments with an array of args, but this is
	// only used internally.)
	each: function( callback, args ) {
		///	<summary>
	    ///		以每一个匹配的元素作为上下文来执行一个函数。
	    ///		意味着，每次执行传递进来的函数时，
	    ///		函数中的this关键字都指向一个不同的DOM元素
	    ///		（每次都是一个不同的匹配元素）。
	    ///		而且，在每次执行函数时，
	    ///		都会给函数传递一个表示作为执行环境的元素在匹配的元素集合中所处位置的数字值作为参数
	    ///		（从零开始的整形）。 
		///	</summary>
		///	<returns type="jQuery" />
		///	<param name="callback" type="Function">
	    ///		对于每个匹配的元素所要执行的函数
		///	</param>

		return jQuery.each( this, callback, args );
	},

	// Determine the position of an element within
	// the matched set of elements
	index: function( elem ) {
		///	<summary>
	    ///		搜索与参数表示的对象匹配的元素，
	    ///		并返回相应元素的索引值值。
	    ///		如果找到了匹配的元素，从0开始返回；如果没有找到匹配的元素，返回-1。
		///		Part of Core
		///	</summary>
		///	<returns type="Number" />
		///	<param name="elem" type="Element">
	    ///		要搜索的对象
		///	</param>

		var ret = -1;

		// Locate the position of the desired element
		return jQuery.inArray(
			// If it receives a jQuery object, the first element is used
			elem && elem.jquery ? elem[0] : elem
		, this );
	},

	attr: function( name, value, type ) {
		///	<summary>
	    ///		为所有匹配的元素设置一个计算的属性值。
	    ///		不提供值，而是提供一个函数，由这个函数计算的值作为属性值。
		///		Part of DOM/Attributes
		///	</summary>
		///	<returns type="jQuery" />
		///	<param name="name" type="String">
	    ///		属性名称
		///	</param>
		///	<param name="value" type="Function">
	    ///		返回值的函数 范围:当前元素, 参数: 当前元素的索引值
		///	</param>

		var options = name;

		// Look for the case where we're accessing a style value
		if ( name.constructor == String )
			if ( value === undefined )
				return this[0] && jQuery[ type || "attr" ]( this[0], name );

			else {
				options = {};
				options[ name ] = value;
			}

		// Check to see if we're setting style values
		return this.each(function(i){
			// Set all the styles
			for ( name in options )
				jQuery.attr(
					type ?
						this.style :
						this,
					name, jQuery.prop( this, options[ name ], type, i, name )
				);
		});
	},

	css: function( key, value ) {
		///	<summary>
	    ///		在所有匹配的元素中，设置一个样式属性的值。
	    ///		数字将自动转化为像素值
		///		Part of CSS
		///	</summary>
		///	<returns type="jQuery" />
		///	<param name="key" type="String">
	    ///		属性名
		///	</param>
		///	<param name="value" type="String">
	    ///		属性值
		///	</param>

		// ignore negative width and height values
		if ( (key == 'width' || key == 'height') && parseFloat(value) < 0 )
			value = undefined;
		return this.attr( key, value, "curCSS" );
	},

	text: function( text ) {
		///	<summary>
	    ///		设置所有匹配元素的文本内容
		///		与 html() 类似, 但将编码 HTML (将 "<" 和 ">" 替换成相应的HTML实体)。
		///		Part of DOM/Attributes
		///	</summary>
		///	<returns type="String" />
		///	<param name="text" type="String">
	    ///		用于设置元素内容的文本
		///	</param>

		if ( typeof text != "object" && text != null )
			return this.empty().append( (this[0] && this[0].ownerDocument || document).createTextNode( text ) );

		var ret = "";

		jQuery.each( text || this, function(){
			jQuery.each( this.childNodes, function(){
				if ( this.nodeType != 8 )
					ret += this.nodeType != 1 ?
						this.nodeValue :
						jQuery.fn.text( [ this ] );
			});
		});

		return ret;
	},

	wrapAll: function( html ) {
		///	<summary>
	    ///		将所有匹配的元素用单个元素包裹起来
	    ///		这于 '.wrap()' 是不同的，
	    ///		'.wrap()'为每一个匹配的元素都包裹一次。
	    ///		这种包装对于在文档中插入额外的结构化标记最有用，
	    ///		而且它不会破坏原始文档的语义品质。
	    ///		这个函数的原理是检查提供的第一个元素并在它的代码结构中找到最上层的祖先元素－－这个祖先元素就是包装元素。
		///		Part of DOM/Manipulation
		///	</summary>
		///	<returns type="jQuery" />
		///	<param name="html" type="Element">
	    ///		HTML标记代码字符串，用于动态生成元素并包装目标元素
		///	</param>

		if ( this[0] )
			// The elements to wrap the target around
			jQuery( html, this[0].ownerDocument )
				.clone()
				.insertBefore( this[0] )
				.map(function(){
					var elem = this;

					while ( elem.firstChild )
						elem = elem.firstChild;

					return elem;
				})
				.append(this);

		return this;
	},

	wrapInner: function( html ) {