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?"