jQuery 学习十四(工具函数)

    ●  jQuery.boxModel

/**
 * 当前页面中浏览器是否使用标准盒模型渲染页面。
 * 
 * @return Boolean 标准盒模型为 true，否则为 false
 * @owner jQuery Namaspace
 */

// 例子：在 Internet Explorer 怪癖模式(QuirksMode)中返回 false
$.boxModel

    ●  jQuery.browser

/**
 * 浏览器内核标识。依据 navigator.userAgent 判断。
 * 可用值：safari, opera, msie, mozilla
 *
 * 此属性在 DOM 树加载完成前即有效，可用于为特定浏览器设置 ready 事件。
 * 浏览器对象检测技术与此属性共同使用可提供可靠的浏览器检测支持。
 * 
 * @return Map
 * @owner jQuery Namaspace
 */

// 例子一：在 Microsoft's Internet Explorer 浏览器中返回 true。
$.browser.msie

// 例子二：仅在 Safari 中提示 "this is safari!" 。
if ($.browser.safari) {
   alert("this is safari!");
}

    ●  jQuery.browser.version

/**
 * 浏览器渲染引擎版本号。
 * 
 * 典型结果: 
 * Internet Explorer: 6.0, 7.0
 * Mozilla/Firefox/Flock/Camino: 1.7.12, 1.8.1.3
 * Opera: 9.20
 * Safari/Webkit: 312.8, 418.9
 * 
 * @return String
 * @owner jQuery Namaspace
 */

// 例子：显示当前 IE 浏览器版本号。
if ( $.browser.msie ) {
  alert( $.browser.version ); 
}

    ●  jQuery.each(obj, callback)

/**
 * 通用遍历方法，可用于遍历对象和数组。不同于遍历 jQuery 对象的 $().each() 方法，此方法可用于遍历
 * 任何对象。
 *
 * 回调函数拥有两个参数：第一个为对象的成员或数组的索引，第二个为对应变量或内容。
 * 如果需要退出 each 循环可使回调函数返回 false，其它返回值将被忽略。
 * 
 * @obj(Object) 需要遍历的对象或数组
 * @callback(Function) (可选) 每个成员/元素执行的回调函数 
 * @return Object
 * @owner jQuery Namaspace
 */
jQuery.each(obj, callback);

// 例子一：遍历数组，同时使用元素索引和内容。
$.each( [0,1,2], function(i, n) {
  alert( "Item #" + i + ": " + n );
});

// 例子二：遍历对象，同时使用成员名称和变量内容
$.each( { name: "John", lang: "JS" }, function(i, n) {
  alert( "Name: " + i + ", Value: " + n );
});

    ●  jQuery.extend(target, obj1, [objN])

/**
 * 用一个或多个其他对象来扩展一个对象，返回被扩展的对象。用于简化继承。此方法也可以用来
 * 扩展 jQuery 的系统函数。
 * 
 * @target(Object) 待修改对象
 * @obj1(Object) 待合并到第一个对象的对象
 * @objN(Object) (可选) 待合并到第一个对象的对象
 * @return Object
 * @owner jQuery Namaspace
 */
jQuery.extend(target, obj1, [objN]);

// 例子一：合并 settings 和 options，修改并返回 settings。
var settings = { validate: false, limit: 5, name: "foo" };
var options = { validate: true, name: "bar" };
jQuery.extend(settings, options);

result: settings == { validate: true, limit: 5, name: "bar" }

// 例子二：合并 defaults 和 options, 不修改 defaults。
var empty = {}
var defaults = { validate: false, limit: 5, name: "foo" };
var options = { validate: true, name: "bar" };
var settings = jQuery.extend(empty, defaults, options);

result: settings == { validate: true, limit: 5, name: "bar" }
        empty    == { validate: true, limit: 5, name: "bar" }
        
// 例子三：扩展 jQuery 的系统函数，添加一名为 "hello" 的系统函数。
$.extend({
	hello: function(str) {
		return str + " hello"
	}
});

使用：$.hello("china") -> china hello

    ●  jQuery.grep(array, callback, [invert])

/**
 * 使用过滤函数过滤数组元素。
 *
 * 此函数至少传递两个参数：待过滤数组和过滤函数。过滤函数必须返回 true 以保留元素或 false 以删除元素
 * 
 * @array(Array) 待过滤数组
 * @callback(Function) 此函数将处理数组每个元素。第一个参数为当前元素，第二个参数为元素索引值。此函数
 *                     应返回一个布尔值。另外，此函数可设置为一个字符串，当设置为字符串时，将视为
 *                     "lambda-form"(缩写形式 ?)，其中 a 代表数组元素，i 代表元素索引值。
 *                     如 "a > 0" 代表 "function(a) { return a > 0; }"。
 * @invert(Boolean) (可选) 如果 "invert" 为 false 或未设置，则函数返回数组中由过滤函数返回
 *                  true 的 元素，当 "invert" 为 true，则返回过滤函数中返回 false 的元素集。
 * @return Array
 * @owner jQuery Namaspace
 */
jQuery.grep(array, callback, [invert]);

// 例子一：过滤数组中小于 0 的元素。
$.grep( [0, 1, 2], function(n, i) {
  return n > 0;
}); -> [1, 2]

// 例子二：排除数组中大于 0 的元素，使用第三个参数进行反向选择。
$.grep( [0, 1, 2], function(n, i) {
  return n > 0;
}, true); -> [0]

    ●  jQuery.inArray(value, array)

/**
 * 确定第一个参数在数组中的位置(如果没有找到则返回 -1)。
 * 
 * @value(Any) 用于在数组中查找是否存在的对象
 * @array(Array) 待处理数组
 * @return Integer
 * @owner jQuery Namaspace
 */
jQuery.inArray(value, array);

// 例子：删除重复 div 标签。
var arr = [ 4, "Pete", 8, "John" ];
jQuery.inArray("John", arr);  // 3
jQuery.inArray(4, arr);  // 0
jQuery.inArray("David", arr);  // -1

    ●  jQuery.makeArray(obj)

/**
 * 将类数组对象转换为数组对象。
 *
 * 类数组对象有 length 属性，其成员索引为 0 至 length - 1。实际中此函数在 jQuery 中将自动使用
 * 而无需特意转换。
 * 
 * @obj(Object) 类数组对象
 * @return Array
 * @owner jQuery Namaspace
 */
jQuery.makeArray(obj);

// 例子：
<div>First</div>
<div>Second</div>
<div>Third</div>
<div>Fourth</div> 

var arr = jQuery.makeArray(document.getElementsByTagName("div"));
arr.reverse(); // 使用数组翻转函数

Fourth
Third
Second
First

    ●  jQuery.map(array, callback)

/**
 * 将一个数组中的元素转换到另一个数组中。
 *
 * 作为参数的转换函数会为每个数组元素调用，而且会给这个转换函数传递一个表示被转换的元素作为参数。
 * 转换函数可以返回转换后的值、null(删除数组中的项目)或一个包含值的数组，并扩展至原始数组中。
 *
 * @array(Array) 待转换数组
 * @callback(Function) 为每个数组元素调用，而且会给这个转换函数传递一个表示被转换的元素作为参数。
 *                     函数可返回任何值。另外，此函数可设置为一个字符串，当设置为字符串时，将视
 *                     为 "lambda-form"(缩写形式 ?)，其中 a 代表数组元素。如 "a * a" 代表
 *                     function(a) { return a * a; }"。
 * @return Array
 * @owner jQuery Namaspace
 */
jQuery.map(array, callback);

// 例子一：将原数组中每个元素加 4 转换为一个新数组。
$.map( [0, 1, 2], function(n) {
  return n + 4;
}); -> [4, 5, 6]

// 例子二：原数组中大于 0 的元素加 1，否则删除。
$.map( [0, 1, 2], function(n) {
  return n > 0 ? n + 1 : null;
}); -> [2, 3]

// 例子三：原数组中每个元素扩展为一个包含其本身和其值加 1 的数组，并转换为一个新数组。 
$.map( [0, 1, 2], function(n) {
  return [ n, n + 1 ];
}); -> [0, 1, 1, 2, 2, 3]

    ●  jQuery.unique(array)

/**
 * 删除数组中重复元素。
 *
 * @array(Array) 待转换数组
 * @return jQuery Object
 * @owner jQuery Namaspace
 */
jQuery.unique(array);

// 例子：删除重复 div 标签。
$.unique(document.getElementsByTagName("div")) -> [<div>, <div>, ...]

    ●  jQuery.isFunction(obj)

/**
 * 测试对象是否为函数。
 *
 * @obj(Object) 用于测试是否为函数的对象
 * @return Boolean
 * @owner jQuery Namaspace
 */
jQuery.isFunction(obj);

// 例子：检测是否为函数。
function stub() {}
var objs = [
  function() {},
  { x:15, y:20 },
  null,
  stub,
  "function"
];

jQuery.each(objs, function(i) {
  var isFunc = jQuery.isFunction(objs[i]);
  $("span:eq( " + i + ")").text(isFunc);
}); -> [ true, false, false, true, false ]

    ●  jQuery.trim(str)

/**
 * 去掉字符串起始和结尾的空格。
 *
 * @str(String) 需要处理的字符串
 * @return Boolean
 * @owner jQuery Namaspace
 */
jQuery.trim(str);

// 例子：去掉字符串起始和结尾的空格。
$.trim(" hello, how are you? ") -> "hello, how are you?"