jq 工具庫

mdui 內建了一個輕量級的 JavaScript 工具庫，它提供了類似於 jQuery 的 API 和鏈式呼叫方式，但其體積只有 jQuery 的六分之一。

你可以按需引入該工具函式：

import { $ } from 'mdui/jq.js';

核心

$()

該函式有多種用法：

傳入 CSS 選擇器作為參數，回傳包含匹配元素的 JQ 物件。

$('.box');

傳入 DOM 元素、任意陣列、NodeList 或 JQ 物件，回傳包含指定元素的 JQ 物件。

$(document);

傳入 HTML 字串，回傳包含根據 HTML 建立的 DOM 的 JQ 物件。

$(`<div id="wrapper">
  <span id="inner"></span>
</div>`);

傳入一個函式，當 DOM 載入完畢後會呼叫該函式。

$(function () {
  console.log('DOM Loaded');
});

擴充

$.extend()

如果只傳入一個物件，該物件中的屬性將合併到 $ 物件中，相當於在 $ 的命名空間下新增功能。

$.extend({
  customFunc: function () {},
});

// 然後就可以這樣呼叫自訂方法了
$.customFunc();

如果傳入了兩個或更多個物件，所有物件的屬性都加入到第一個物件，並回傳合併後的物件。不過值為 undefined 的屬性不會合併。

const object = $.extend({ key1: val1 }, { key2: val2 }, { key3: val3 });

// 此時第一個物件和回傳值都是 { key1: val1, key2: val2, key3: val3 }

$.fn.extend()

在 $ 的原型鏈上擴充方法。

$.fn.extend({
  customFunc: function () {},
});

// 然後就可以這樣使用擴充的方法了
$(document).customFunc();

URL

$.param()

將陣列或物件序列化為 URL 查詢字串。

$.param({ width: 1680, height: 1050 });
// width=1680&height=1050

$.param({ foo: { one: 1, two: 2 } });
// foo[one]=1&foo[two]=2

$.param({ ids: [1, 2, 3] });
// ids[]=1&ids[]=2&ids[]=3

如果傳入的參數是陣列，那麼該陣列的格式必須與 .serializeArray() 回傳的格式一致。

$.param([
  { name: 'name', value: 'mdui' },
  { name: 'password', value: '123456' },
]);
// name=mdui&password=123456

陣列和物件操作

$.each()

走訪陣列或物件。它回傳的是第一個參數，即被走訪的陣列或物件。

回呼函式的第一個參數是陣列的索引或物件的鍵，第二個參數是陣列或物件對應位置的值。

在回呼函式中，this 指向陣列或物件對應位置的值。如果回呼函式回傳 false，則停止走訪。

// 走訪陣列
$.each(['a', 'b', 'c'], function (index, value) {
  console.log(index + ':' + value);
});

// 結果：
// 0:a
// 1:b
// 2:c

// 走訪物件
$.each({ name: 'mdui', lang: 'zh' }, function (key, value) {
  console.log(key + ':' + value);
});

// 結果
// name:mdui
// lang:zh

$.merge()

將第二個陣列的元素追加到第一個陣列中，並回傳合併後的陣列。

const first = ['a', 'b', 'c'];
const second = ['c', 'd', 'e'];
const result = $.merge(first, second);

console.log(first); // ['a', 'b', 'c', 'c', 'd', 'e']
console.log(result); // ['a', 'b', 'c', 'c', 'd', 'e']

$.unique()

移除陣列中的重複元素。

const result = $.unique([1, 2, 12, 3, 2, 1, 2, 1, 1, 1, 1]);
console.log(result); // [1, 2, 12, 3]

$.map()

走訪陣列或物件，回傳一個由回呼函式的回傳值組成的新陣列。

回呼函式的第一個參數是陣列或物件對應位置的值，第二個參數是陣列的索引或物件的鍵。

回呼函式可以回傳任何值。如果回傳的是陣列，那麼這個陣列會被展開。如果回傳的是 null 或 undefined，那麼這個值會被忽略。在回呼函式內部，this 指向 window 物件。

// 走訪陣列
const result = $.map(['a', 'b', 'c'], function (value, index) {
  return index + value;
});
console.log(result); // ['0a', '1b', '2c']

// 當回呼函式回傳陣列時，陣列會被展開
const result = $.map([1, 2, 3], function (value, index) {
  return [value, value + 1];
});
console.log(result); // [1, 2, 2, 3, 3, 4]

// 走訪物件
const result = $.map(
  { name: 'mdui', password: '123456' },
  function (value, key) {
    return key + ':' + value;
  },
);
console.log(result); // ['name:mdui', 'password:123456']

$.contains()

判斷一個節點是否包含另一個節點。如果父節點包含子節點，回傳 true；否則，回傳 false。

$.contains(document, document.body); // true
$.contains(document.body, document); // false

資料型別判斷

.is()

判斷集合中是否至少有一個元素與參數匹配。如果匹配，回傳 true；否則，回傳 false。

參數可以是 CSS 選擇器、DOM 元素、DOM 元素陣列、JQ 物件，或者回呼函式。

如果參數是回呼函式，函式的第一個參數是索引，第二個參數是目前元素。在函式內部，this 指向目前元素。如果函式回傳 true，表示目前元素與參數匹配；如果回傳 false，表示目前元素與參數不匹配。

$('.box').is('.box'); // true
$('.box').is('.boxss'); // false
$('.box').is($('.box')[0]); // true

// 透過回呼函式的回傳值做判斷
$(document).is(function (index, element) {
  return element === document;
});
// true

物件存取

.length

回傳目前集合中元素的數量。

$('body').length; // 1

.each()

走訪目前集合，為集合中的每個元素執行一個函式。如果函式回傳 false，則停止走訪。

函式的第一個參數是元素的索引位置，第二個參數是目前元素。在函式內部，this 指向目前元素。

$('img').each(function (index, element) {
  this.src = 'test' + index + '.jpg';
});

.map()

走訪目前集合，為集合中的每個元素執行一個函式，回傳由函式回傳值組成的新集合。

函式可以回傳單一資料或資料陣列。如果回傳陣列，那麼會將陣列中的元素依序加入新集合中。如果函式回傳 null 或 undefined，那麼這個值不會被加入新集合中。

函式的第一個參數是元素的索引位置，第二個參數是目前元素。在函式內部，this 指向目前元素。

const result = $('input.checked').map(function (i, element) {
  return element.value;
});

// result 是一個由匹配元素的值組成的 JQ 物件

.eq()

回傳一個新集合，該集合只包含指定索引位置的元素。

$('div').eq(0); // 回傳僅包含第一個元素的集合
$('div').eq(-1); // 回傳僅包含最後一個元素的集合
$('div').eq(-2); // 回傳僅包含倒數第二個元素的集合

.first()

回傳一個新集合，該集合只包含目前集合中的第一個元素。

$('div').first(); // 回傳僅包含第一個 div 的集合

.last()

回傳一個新集合，該集合只包含目前集合中的最後一個元素。

$('div').last(); // 回傳僅包含最後一個 div 的集合

.get()

回傳指定索引位置的元素。未傳入參數時，會回傳由集合中所有元素組成的陣列。

$('div').get(); // 回傳所有 div 元素組成的陣列
$('div').get(0); // 回傳第一個 div 元素
$('div').get(-1); // 回傳最後一個 div 元素

.index()

未傳入參數時，會回傳目前集合中第一個元素相對於其同輩元素的索引值。

傳入一個 CSS 選擇器時，會回傳目前集合中第一個元素相對於 CSS 選擇器匹配元素的索引值。

傳入一個 DOM 元素時，會回傳該元素在目前集合中的索引值。

傳入一個 JQ 物件時，會回傳物件中第一個元素在目前集合中的索引值。

<div id="child">
  <div id="child1"></div>
  <div id="child2"></div>
  <div id="child3"></div>
  <div id="child4"></div>
</div>

$('#child3').index(); // 2
$('#child3').index('#child div'); // 2
$('#child div').index($('#child3').get(0)); // 2

.slice()

回傳目前集合的子集。

你可以透過傳入兩個參數來指定子集的起始和結束位置（不包含結束位置的元素）。如果沒有傳入第二個參數，它將回傳從起始位置到集合末尾的所有元素。

// 回傳集合中第三個（包含第三個）之後的所有元素
$('div').slice(3);

// 回傳集合中第三個到第五個（包含第三個，不包含第五個）之間的元素
$('div').slice(3, 5);

.filter()

從目前集合中篩選出與指定表達式匹配的元素。參數可以是 CSS 選擇器、DOM 元素、DOM 元素陣列或回呼函式。

如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是目前元素。在函式內部，this 指向目前元素。如果函式回傳 true，目前元素會被保留；如果回傳 false，目前元素會被移除。

// 篩選出所有含 .box 的 div 元素
$('div').filter('.box');

// 篩選出所有已選取的選項
$('#select option').filter(function (index, element) {
  return element.selected;
});

.not()

從目前集合中篩選出與指定表達式不匹配的元素。

參數可以是 CSS 選擇器、DOM 元素、DOM 元素陣列、JQ 物件，或回傳 boolean 值的回呼函式。

如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是目前元素。在函式內部，this 指向目前元素。如果函式回傳 true，目前元素會被移除；如果回傳 false，目前元素會被保留。

// 篩選出所有不含 .box 類別的 div 元素
$('div').not('.box');

// 篩選出所有未選取的選項
$('#select option').not(function (index, element) {
  return element.selected;
});

CSS 類別

.hasClass()

判斷集合中的第一個元素是否含有指定的 CSS 類別。

// 判斷第一個 div 元素是否含有 .item
$('div').hasClass('item');

.addClass()

為集合中的每個元素新增 CSS 類別，多個類別名稱之間可以用空格分隔。

參數可以是字串，也可以是一個回傳 CSS 類別名稱的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是該元素上原有的 CSS 類別名稱。在函式內部，this 指向目前元素。

// 為所有 div 元素新增 .item
$('div').addClass('item');

// 為所有 div 元素新增 .item1 和 .item2
$('div').addClass('item1 item2');

// 為所有 div 元素新增由回呼函式回傳的 CSS 類別
$('div').addClass(function (index, currentClassName) {
  return currentClassName + '-' + index;
});

.removeClass()

移除集合中每個元素上的指定 CSS 類別，多個類別名稱之間可以用空格分隔。

參數可以是字串，也可以是一個回傳 CSS 類別名稱的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是該元素上原有的 CSS 類別名稱。在函式內部，this 指向目前元素。

如果沒有傳入參數，該方法將直接移除元素上的 class 屬性。

// 移除所有 div 元素上的 .item
$('div').removeClass('item');

// 移除所有 div 元素上的 .item1 和 .item2
$('div').removeClass('item1 item2');

// 移除所有 div 元素上的由回呼函式回傳的 CSS 類別
$('div').removeClass(function (index, currentClassName) {
  return 'item';
});

.toggleClass()

如果元素上有指定的 CSS 類別，則刪除它；如果沒有，則新增它。多個類別名稱之間可以用空格分隔。

參數可以是字串，也可以是一個回傳 CSS 類別名稱的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是該元素上原有的 CSS 類別名稱。在函式內部，this 指向目前元素。

// 切換所有 div 元素上的 .item 類別
$('div').toggleClass('item');

// 切換所有 div 元素上的 .item1 和 .item2 類別
$('div').toggleClass('item1 item2');

// 切換所有 div 元素上的由回呼函式回傳的 CSS 類別
$('div').toggleClass(function (index, currentClassName) {
  return 'item';
});

節點屬性

.prop()

取得集合中第一個元素的 JavaScript 屬性值。

// 取得第一個元素 checked 屬性值
$('input').prop('checked');

傳入兩個參數時，會設定集合中所有元素的指定 JavaScript 屬性值。

屬性值可以是任意類型的值，也可以是一個回傳屬性值的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是該元素上原有的屬性值。在函式內部，this 指向目前元素。

如果屬性值或回呼函式的回傳值為 undefined，該方法將不會修改元素的原有屬性。

// 設定所有選取元素的 checked 屬性值為 true
$('input').prop('checked', true);

// 透過回呼函式的回傳值設定屬性值
$('input').prop('checked', function (index, oldPropValue) {
  return true;
});

也可以透過傳入一個物件來同時設定多個屬性。

// 同時設定元素的多個屬性值
$('input').prop({
  checked: false,
  disabled: function (index, oldPropValue) {
    return true;
  },
});

.removeProp()

刪除集合中所有元素上指定的 JavaScript 屬性值。

$('input').removeProp('disabled');

.attr()

取得集合中第一個元素的 HTML 屬性值。

// 取得第一個元素的屬性值
$('div').attr('username');

傳入兩個參數時，會設定集合中所有元素的指定 HTML 屬性值。

屬性值可以是字串或數值，也可以是一個回傳屬性值的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是該元素上原有的屬性值。在函式內部，this 指向目前元素。

如果屬性值或回呼函式的回傳值為 null，該方法將刪除指定屬性；如果為 undefined，則不會修改元素的原有屬性。

// 設定所有選取元素的屬性值
$('div').attr('username', 'mdui');

// 透過回呼函式的回傳值設定屬性值
$('div').attr('username', function (index, oldAttrValue) {
  return 'mdui';
});

也可以透過傳入一個物件來同時設定多個屬性。

// 同時設定元素的多個屬性值
$('div').attr({
  username: 'mdui',
  lastname: function (index, oldAttrValue) {
    return 'test';
  },
});

.removeAttr()

刪除集合中所有元素上指定的 HTML 屬性，多個屬性名稱之間可以用空格分隔。

// 刪除集合中所有元素上的一個屬性
$('div').removeAttr('username');

// 刪除集合中所有元素上的多個屬性
$('div').removeAttr('username lastname');

.val()

回傳集合中第一個元素的值。

如果元素是 <select multiple="multiple">，則回傳一個包含所有選取項目的陣列。

// 取得選取的第一個元素的值
$('#input').val();

傳入參數時，會設定集合中所有元素的值。

值可以是字串、數值、字串陣列，或一個回傳值的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是元素的原有值。在函式內部，this 指向目前元素。

如果元素是 <input type="checkbox">、<input type="radio">、<option>，則值或回呼函式的回傳值可以是陣列，此時將選取陣列中的值，並取消不在陣列中的值。

當值或回呼函式回傳 undefined 時，則將元素值設為空。

// 設定選取元素的值
$('#input').val('mdui');

// 透過回呼函式的回傳值設定元素值
$('#input').val(function (index, oldValue) {
  return 'mdui';
});

.text()

回傳集合中所有元素（包含它們的後代元素）的文字內容。

// 取得所有 .box 元素的文字
$('.box').text();

傳入參數時，會設定集合中所有元素的文字內容。

值可以是字串、數值、布林值，或一個回傳文字內容的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是元素的原有文字內容。在函式內部，this 指向目前元素。

當值或回呼函式回傳 undefined 時，則不修改元素的文字內容。

// 設定選取元素的文字內容
$('.box').text('text content');

// 透過回呼函式的回傳值設定元素的文字內容
$('.box').text(function (index, oldTextContent) {
  return 'new text content';
});

.html()

回傳集合中第一個元素的 HTML 內容。

// 取得第一個 .box 元素的 HTML 內容
$('.box').html();

傳入參數時，會設定集合中所有元素的 HTML 內容。

值可以是 HTML 字串、DOM 元素，或一個回傳 HTML 字串或 DOM 元素的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是元素的原有 HTML 內容。在函式內部，this 指向目前元素。

當值或回呼函式回傳 undefined 時，則不修改元素的 HTML 內容。

// 設定選取元素的 HTML
$('.box').html('<div>new html content</div>');

// 透過回呼函式的回傳值設定元素的 HTML 內容
$('.box').html(function (index, oldHTMLContent) {
  return '<div>new html content</div>';
});

資料儲存

$.data()

在指定元素上讀取或儲存資料。

儲存資料時，如果值為 undefined，則相當於讀取元素上對應的資料。即 $.data(element, 'key', undefined) 和 $.data(element, 'key') 等效。

注意：該方法不會讀取元素上的 data-* 屬性。

// 在指定元素上儲存資料，回傳儲存的值
$.data(document.body, 'layout', 'dark'); // 回傳 dark

// 在指定元素上同時儲存多個資料
$.data(document.body, {
  primary: 'indigo',
  accent: 'pink',
}); // 回傳 { primary: 'indigo', accent: 'pink' }

// 取得在指定元素上儲存的資料
$.data(document.body, 'layout'); // 回傳 dark

// 取得在指定元素上儲存的所有資料
$.data(document.body); // 回傳 { layout: 'dark', primary: 'indigo', accent: 'pink' }

$.removeData()

移除指定元素上儲存的資料。

可以指定多個鍵名，用空格分隔，或者用陣列表示。如果不指定鍵名，將移除元素上的所有資料。

// 移除元素上鍵名為 name 的資料
$.removeData(document.body, 'name');

// 移除元素上鍵名為 name1 和 name2 的資料。下面兩種方法等效：
$.removeData(document.body, 'name1 name2');
$.removeData(document.body, ['name1', 'name2']);

// 移除元素上儲存的所有資料
$.removeData(document.body);

.data()

在目前集合的元素上讀取或儲存資料。

如果儲存的值為 undefined，則不進行儲存。

注意：該方法讀取的資料會包含元素上的 data-* 屬性。

// 在目前集合中的元素上儲存資料
$('.box').data('layout', 'dark');

// 在目前集合中的元素上同時儲存多個資料
$('.box').data({
  primary: 'indigo',
  accent: 'pink',
});

// 取得目前集合中第一個元素上儲存的指定資料
$('.box').data('layout'); // 回傳 dark

// 取得目前集合中第一個元素上儲存的所有資料
$('.box').data(); // 回傳 { layout: 'dark', primary: 'indigo', accent: 'pink' }

.removeData()

移除目前集合的元素上儲存的資料。

可以指定多個鍵名，用空格分隔，或者用陣列表示。如果不指定鍵名，將移除元素上的所有資料。

注意：該方法只會移除透過 .data() 方法設定的資料，不會移除 data-* 屬性上的資料。

// 移除鍵名為 name 的資料
$('.box').removeData('name');

// 移除鍵名為 name1 和 name2 的資料。下面兩種方法等效：
$('.box').removeData('name1 name2');
$('.box').removeData(['name1', 'name2']);

// 移除元素上儲存的所有資料
$('.box').removeData();

樣式

.css()

取得集合中第一個元素的 CSS 屬性值。

$('.box').css('color');

傳入參數時，會設定集合中所有元素的 CSS 屬性值。

屬性值可以是字串、數值，或一個回傳字串或數值的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是元素的原有 CSS 屬性值。在函式內部，this 指向目前元素。

當值或回呼函式回傳 undefined 時，則不修改元素的 CSS 屬性值。如果值為 null，則移除元素的對應 CSS 屬性。如果值為數值，將自動加上 px 作為單位，若該屬性無法使用 px 作為單位，則會直接把值轉為字串。

// 設定集合中所有元素的樣式值
$('.box').css('color', 'red');

// 透過回呼函式的回傳值設定所有元素的樣式值
$('.box').css('color', function (index, oldCSSValue) {
  return 'green';
});

// 透過傳入一個物件同時設定多個樣式
$('.box').css({
  'background-color': 'white',
  color: function (index, oldCSSValue) {
    return 'blue';
  },
});

.width()

取得集合中第一個元素的寬度（不包含 padding、border、margin）。

$('.box').width();

傳入參數時，會設定集合中所有元素的寬度。

值可以是帶單位的字串、數值，或一個回傳帶單位的字串或數值的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是元素的原有寬度。在函式內部，this 指向目前元素。

如果值或回呼函式的回傳值為 null 或 undefined，則不修改元素的寬度。如果值為數值，將自動加上 px 作為單位。

// 設定集合中所有元素的寬度
$('.box').width('20%');

// 值為數值時，預設單位為 px
$('.box').width(10);

// 透過回呼函式的回傳值設定寬度
$('.box').width(function (index, oldWidth) {
  return 10;
});

.height()

取得集合中第一個元素的高度（不包含 padding、border、margin）。

$('.box').height();

傳入參數時，會設定集合中所有元素的高度。

值可以是帶單位的字串、數值，或一個回傳帶單位的字串或數值的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是元素的原有高度。在函式內部，this 指向目前元素。

如果值或回呼函式的回傳值為 null 或 undefined，則不修改元素的高度。如果值為數值，將自動加上 px 作為單位。

// 設定集合中所有元素的高度
$('.box').height('20%');

// 值為數值時，預設單位為 px
$('.box').height(10);

// 透過回呼函式的回傳值設定高度
$('.box').height(function (index, oldHeight) {
  return 10;
});

.innerWidth()

取得集合中第一個元素的寬度（包含 padding，不包含 border、margin）。

$('.box').innerWidth();

傳入參數時，會設定集合中所有元素的寬度。

值可以是帶單位的字串、數值，或一個回傳帶單位的字串或數值的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是元素的原有寬度。在函式內部，this 指向目前元素。

如果值或回呼函式的回傳值為 null 或 undefined，則不修改元素的寬度。如果值為數值，將自動加上 px 作為單位。

// 設定集合中所有元素的寬度
$('.box').innerWidth('20%');

// 值為數值時，預設單位為 px
$('.box').innerWidth(10);

// 透過回呼函式的回傳值設定寬度
$('.box').innerWidth(function (index, oldWidth) {
  return 10;
});

.innerHeight()

取得集合中第一個元素的高度（包含 padding，不包含 border、margin）。

$('.box').innerHeight();

傳入參數時，會設定集合中所有元素的高度。

值可以是帶單位的字串、數值，或一個回傳帶單位的字串或數值的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是元素的原有高度。在函式內部，this 指向目前元素。

如果值或回呼函式的回傳值為 null 或 undefined，則不修改元素的高度。如果值為數值，將自動加上 px 作為單位。

// 設定集合中所有元素的高度
$('.box').innerHeight('20%');

// 值為數值時，預設單位為 px
$('.box').innerHeight(10);

// 透過回呼函式的回傳值設定高度
$('.box').innerHeight(function (index, oldHeight) {
  return 10;
});

.outerWidth()

取得集合中第一個元素的寬度（包含 padding、border，不包含 margin。可以傳入參數 true，使寬度包含 margin）。

// 包含 padding、border 的寬度
$('.box').outerWidth();

// 包含 padding、border、margin 的寬度
$('.box').outerWidth(true);

也可以使用該方法設定集合中所有元素的寬度（包含 padding、border，不包含 margin。可以在第二個參數中傳入 true，使寬度包含 margin）。

第一個參數可以是帶單位的字串、數值、或一個回傳帶單位的字串或數值的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是元素的原有寬度。在函式內部，this 指向目前元素。

如果值或回呼函式的回傳值為 null 或 undefined，則不修改元素的寬度。如果值為數值，將自動加上 px 作為單位。

// 設定集合中所有元素的寬度
$('.box').outerWidth('20%');

// 值為數值時，預設單位為 px
$('.box').outerWidth(10);

// 第二個參數為 true，則寬度將包含 margin
$('.box').outerWidth(10, true);

// 透過回呼函式的回傳值設定寬度
$('.box').outerWidth(function (index, oldWidth) {
  return 10;
});

.outerHeight()

取得集合中第一個元素的高度（包含 padding、border，不包含 margin。可以傳入參數 true，使高度包含 margin）。

// 包含 padding、border 的高度
$('.box').outerHeight();

// 包含 padding、border、margin 的高度
$('.box').outerHeight(true);

也可以用該方法設定集合中所有元素的高度（包含 padding、border，不包含 margin。可以在第二個參數中傳入 true，使高度包含 margin）。

第一個參數可以是帶單位的字串、數值、或一個回傳帶單位的字串或數值的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是元素的原有高度。在函式內部，this 指向目前元素。

如果值或回呼函式的回傳值為 null 或 undefined，則不修改元素的高度。如果值為數值，將自動加上 px 作為單位。

// 設定集合中所有元素的高度
$('.box').outerHeight('20%');

// 值為數值時，預設單位為 px
$('.box').outerHeight(10);

// 第二個參數為 true，則高度將包含 margin
$('.box').outerHeight(10, true);

// 透過回呼函式的回傳值設定高度
$('.box').outerHeight(function (index, oldHeight) {
  return 10;
});

.hide()

隱藏集合中的所有元素。

$('.box').hide();

.show()

顯示集合中的所有元素。

$('.box').show();

.toggle()

切換集合中所有元素的顯示狀態。

$('.box').toggle();

.offset()

取得目前集合中第一個元素相對於 document 的座標。

$('.box').offset(); // { top: 20, left: 30 }

傳入參數時，會設定集合中所有元素相對於 document 的座標。

參數可以是一個包含 top 和 left 屬性的物件，或一個回傳此格式物件的回呼函式。如果參數是回呼函式，函式的第一個參數是元素的索引位置，第二個參數是元素的原有座標。在函式內部，this 指向目前元素。

如果參數中 top 或 left 的值為 undefined，則不修改對應的值。

// 設定集合中所有元素的座標
$('.box').offset({ top: 20, left: 30 });

// 透過回呼函式的回傳值設定元素的座標
$('.box').offset(function (index, oldOffset) {
  return { top: 20, left: 30 };
});

.offsetParent()

取得集合中第一個元素的定位父元素。即父元素中第一個 position 屬性為 relative 或 absolute 的元素。

$('.box').offsetParent();

.position()

取得集合中第一個元素相對於其定位父元素的偏移。

$('.box').position(); // { top: 20, left: 30 }

查找節點

.find()

在目前集合中，根據 CSS 選擇器找到指定的後代節點集合。

// 找到 #box 的後代節點中，包含 .box 的節點集合
$('#box').find('.box');

.children()

在目前集合中，取得直接子元素組成的集合。可以傳入一個 CSS 選擇器作為參數，對子元素進行過濾。

// 找到 #box 的所有直接子元素
$('#box').children();

// 找到 #box 的所有直接子元素中，包含 .box 的元素
$('#box').children('.box');

.has()

在目前集合中，篩選出含有指定子元素的元素。參數可以是 CSS 選擇器或 DOM 元素。

// 給含有 ul 的 li 加上背景色
$('li').has('ul').css('background-color', 'red');

.parent()

取得目前集合中，所有元素的直接父元素的集合。可以傳入一個 CSS 選擇器作為參數，僅回傳與該參數匹配的父元素的集合。

// 回傳 .box 元素的直接父元素
$('.box').parent();

// 回傳 .box 元素的直接父元素中含有 .parent 類別的元素
$('.box').parent('.parent');

.parents()

取得目前集合中，所有元素的祖先元素的集合。可以傳入一個 CSS 選擇器作為參數，僅回傳與該參數匹配的祖先元素的集合。

// 回傳 span 元素的所有祖先元素
$('span').parents();

// 回傳 span 元素的所有是 p 元素的祖先元素
$('span').parents('p');

.parentsUntil()

取得目前集合中，每個元素的所有父輩元素，直到遇到和第一個參數匹配的元素為止（不包含匹配元素）。

第一個參數可以是 CSS 選擇器、DOM 元素、JQ 物件。

可以傳入第二個參數，必須是 CSS 選擇器，表示僅回傳和該參數匹配的元素。

若沒有指定參數，則所有的祖先元素都將被匹配，即和 .parents() 效果一樣。

// 取得 .item 元素的所有祖先元素
$('.item').parentsUntil();

// 查找 .item 元素的所有父輩元素，直到遇到 .parent 元素為止
$('.item').parentsUntil('.parent');

// 取得 .item 元素的所有是 div 元素的祖先元素，直到遇到 .parent 元素為止
$('.item').parentsUntil('.parent', 'div');

.prev()

取得目前集合中，每個元素的前一個同級元素組成的集合。可以傳入一個 CSS 選擇器作為參數，僅回傳與該參數匹配的同級元素的集合。

// 取得 .box 元素的前一個同級元素的集合
$('.box').prev();

// 取得 .box 元素的前一個是 div 的同級元素的集合
$('.box').prev('div');

.prevAll()

取得目前集合中，每個元素前面的所有同級元素組成的集合。可以傳入一個 CSS 選擇器作為參數，僅回傳與該參數匹配的同級元素的集合。

// 取得 .box 元素前面的所有同級元素
$('.box').prevAll();

// 取得 .box 元素前面的所有含 .selected 的同級元素
$('.box').prevAll('.selected');

.prevUntil()

取得目前集合中，每個元素前面的所有同級元素，直到遇到與第一個參數匹配的元素為止（不包含匹配元素）。

第一個參數可以是 CSS 選擇器、DOM 元素、JQ 物件。可以傳入第二個參數，必須是 CSS 選擇器，表示僅回傳和該參數匹配的元素。

若沒有指定參數，則回傳前面的所有同級元素，即與 .prevAll() 方法的效果相同。

// 取得 .box 元素前面的所有同級元素
$('.box').prevUntil();

// 取得 .box 元素前面的所有同級元素，直到遇到 .until 元素為止
$('.box').prevUntil('.until');

// 取得 .box 元素前面的所有是 div 的同級元素，直到遇到 .until 元素為止
$('.box').prevUntil('.until', 'div');

.next()

取得目前集合中，每個元素的後一個同級元素組成的集合。可以傳入一個 CSS 選擇器作為參數，僅回傳與該參數匹配的同級元素的集合。

// 取得 .box 元素的後一個同級元素的集合
$('.box').next();

// 取得 .box 元素的後一個是 div 的同級元素的集合
$('.box').next('div');

.nextAll()

取得目前集合中，每個元素後面的所有同級元素組成的集合。可以傳入一個 CSS 選擇器作為參數，僅回傳與該參數匹配的同級元素的集合。

// 取得 .box 元素後面的所有同級元素
$('.box').nextAll();

// 取得 .box 元素後面的所有含 .selected 的同級元素
$('.box').nextAll('.selected');

.nextUntil()

取得目前集合中，每個元素後面的所有同級元素，直到遇到與第一個參數匹配的元素為止（不包含匹配元素）。

第一個參數可以是 CSS 選擇器、DOM 元素、JQ 物件。可以傳入第二個參數，必須是 CSS 選擇器，表示僅回傳與該參數匹配的元素。

若沒有指定參數，則回傳後面的所有同級元素，即與 .nextAll() 方法的效果相同。

// 取得 .box 元素後面的所有同級元素
$('.box').nextUntil();

// 取得 .box 元素後面的所有同級元素，直到遇到 .until 元素為止
$('.box').nextUntil('.until');

// 取得 .box 元素後面同級的 div 元素，直到遇到 .until 元素為止
$('.box').nextUntil('.until', 'div');

.closest()

從目前元素開始向上逐級查找，回傳最先匹配到的元素。參數可以是 CSS 選擇器、DOM 元素、JQ 物件。

// 取得 .box 元素的父元素中最近的 .parent 元素
$('.box').closest('.parent');

.siblings()

取得目前集合中，每個元素的所有同級元素。可以傳入一個 CSS 選擇器作為參數，僅回傳與該參數匹配的同級元素的集合。

// 取得 .box 元素的所有同級元素
$('.box').siblings();

// 取得 .box 元素的所有同級元素中含 .selected 的元素
$('.box').siblings('.selected');

.add()

將元素加入目前集合中。參數可以是 HTML 字串、CSS 選擇器、JQ 物件、DOM 元素、DOM 元素陣列、NodeList。

// 把含 .selected 的元素加入目前集合中
$('.box').add('.selected');

節點操作

.empty()

移除目前元素中所有的子元素。

$('.box').empty();

.remove()

從 DOM 中移除目前集合中的元素。可以傳入一個 CSS 選擇器作為參數，僅移除與該參數匹配的元素。

// 移除所有 p 元素
$('p').remove();

// 移除所有含 .box 的 p 元素
$('p').remove('.box');

.prepend()

在目前集合中每個元素的開頭插入指定內容。參數可以是 HTML 字串、DOM 元素、DOM 元素陣列、JQ 物件。支援傳入多個參數。

也可以傳入一個回傳 HTML 字串、DOM 元素、DOM 元素陣列、JQ 物件的回呼函式。函式的第一個參數是目前元素的索引位置，第二個參數是元素的原始 HTML，函式中的 this 指向目前元素。

該方法回傳原始集合。

// 插入一個元素
$('<p>I would like to say: </p>').prepend('<b>Hello</b>');
// 結果：<p><b>Hello</b>I would like to say: </p>

// 插入多個元素
$('<p>I would like to say: </p>').prepend('<b>Hello</b>', '<b>World</b>');
// 結果：<p><b>Hello</b><b>World</b>I would like to say: </p>

// 透過回呼函式插入一個元素
$('<p>Hello</p>').prepend(function (index, oldHTML) {
  return '<b>' + oldHTML + index + '</b>';
});
// 結果：<p><b>Hello0</b>Hello</p>

.prependTo()

將目前集合中的元素插入到指定元素內容的開頭。參數可以是 CSS 選擇器、HTML 字串、DOM 元素、DOM 元素陣列、JQ 物件。

該方法回傳原始集合。

$('<p>Hello</p>').prependTo('<p>I would like to say: </p>');
// 結果：[ <p><p>Hello</p>I would like to say: </p> ]

.append()

在目前集合中每個元素的結尾插入指定內容。參數可以是 HTML 字串、DOM 元素、DOM 元素陣列、JQ 物件。支援傳入多個參數。

也可以傳入一個回傳 HTML 字串、DOM 元素、DOM 元素陣列、JQ 物件的回呼函式，函式的第一個參數是目前元素的索引位置，第二個參數是元素的原始 HTML，函式中的 this 指向目前元素。

該方法回傳原始集合。

// 插入一個元素
$('<p>I would like to say: </p>').append('<b>Hello</b>');
// 結果：<p>I would like to say: <b>Hello</b></p>

// 插入多個元素
$('<p>I would like to say: </p>').append('<b>Hello</b>', '<b>World</b>');
// 結果：<p>I would like to say: <b>Hello</b><b>World</b></p>

// 透過回呼函式插入一個元素
$('<p>Hello</p>').append(function (index, oldHTML) {
  return '<b>' + oldHTML + index + '</b>';
});
// 結果：<p>Hello<b>Hello0</b></p>

.appendTo()

將目前集合中的元素插入到指定元素內容的最後。參數可以是 CSS 選擇器、HTML 字串、DOM 元素、DOM 元素陣列、JQ 物件。

該方法回傳原始集合。

$('<p>Hello</p>').appendTo('<p>I would like to say: </p>');
// 結果：<p>I would like to say: <p>Hello</p></p>

.after()

在目前集合的元素後面插入指定內容，作為其同級元素。參數可以是 HTML 字串、DOM 元素、DOM 元素陣列、JQ 物件。支援傳入多個參數。

也可以傳入一個回傳 HTML 字串、DOM 元素、DOM 元素陣列、JQ 物件的回呼函式，函式的第一個參數是目前元素的索引位置，第二個參數是元素的原始 HTML，函式中的 this 指向目前元素。

該方法回傳原始集合。

// 插入一個元素
$('<p>I would like to say: </p>').after('<b>Hello</b>');
// 結果：<p>I would like to say: </p><b>Hello</b>

// 插入多個元素
$('<p>I would like to say: </p>').after('<b>Hello</b>', '<b>World</b>');
// 結果：<p>I would like to say: </p><b>Hello</b><b>World</b>

// 透過回呼函式插入一個元素
$('<p>Hello</p>').after(function (index, oldHTML) {
  return '<b>' + oldHTML + index + '</b>';
});
// 結果：<p>Hello</p><b>Hello0</b>

.insertAfter()

將目前集合中的元素插入到目標元素的後面，作為其同級元素。

如果目前集合中的元素是頁面中已有的元素，則將移動該元素，而不是複製。如果有多個目標，則將複製目前集合中的元素，並加入到每個目標元素的後面。

可以傳入一個 HTML 字串、CSS 選擇器、DOM 元素、DOM 元素陣列、JQ 物件作為參數，來指定目標元素。

$('<b>Hello</b>').insertAfter('<p>I would like to say: </p>');
// 結果：<p>I would like to say: </p><b>Hello</b>

.before()

在目前集合的元素前面插入指定內容，作為其同級元素。參數可以是 HTML 字串、DOM 元素、DOM 元素陣列、JQ 物件。支援傳入多個參數。

也可以傳入一個回傳 HTML 字串、DOM 元素、DOM 元素陣列、JQ 物件的回呼函式，函式的第一個參數是目前元素的索引位置，第二個參數是元素的原始 HTML，函式中的 this 指向目前元素。

該方法回傳原始集合。

// 插入一個元素
$('<p>I would like to say: </p>').before('<b>Hello</b>');
// 結果：<b>Hello</b><p>I would like to say: </p>

// 插入多個元素
$('<p>I would like to say: </p>').before('<b>Hello</b>', '<b>World</b>');
// 結果：<b>Hello</b><b>World</b><p>I would like to say: </p>

// 透過回呼函式插入一個元素
$('<p>Hello</p>').before(function (index, oldHTML) {
  return '<b>' + oldHTML + index + '</b>';
});
// 結果：<b>Hello0</b><p>Hello</p>

.insertBefore()

將目前集合中的元素插入到目標元素的前面，作為其同級元素。

如果目前集合中的元素是頁面中已有的元素，則將移動該元素，而不是複製。如果有多個目標，則將複製目前集合中的元素，並加入到每個目標元素的前面。

可以傳入一個 HTML 字串、CSS 選擇器、DOM 元素、DOM 元素陣列、JQ 物件作為參數，來指定目標元素。

$('<p>I would like to say: </p>').insertBefore('<b>Hello</b>');
// 結果：<p>I would like to say: </p><b>Hello</b>

.replaceWith()

用指定元素來替換目前集合中的元素。

參數可以是 HTML 字串、DOM 元素、DOM 元素陣列、JQ 物件。

也可以傳入一個回傳 HTML 字串、DOM 元素、DOM元素陣列、JQ 物件的回呼函式，函式的第一個參數是目前元素的索引位置，第二個參數是元素的原始 HTML，函式中的 this 指向目前元素。

該方法回傳被替換掉的原始集合。

// 用 <p>Hello</p> 替換所有的 .box 元素
$('.box').replaceWith('<p>Hello</p>');

// 用回呼函式的回傳值替換所有 .box 元素
$('.box').replaceWith(function (index, oldHTML) {
  return oldHTML + index;
});

.replaceAll()

用目前集合中的元素替換指定元素。

參數為被替換的元素，可以是 CSS 選擇器、DOM 元素、DOM 元素陣列、JQ 物件。

該方法回傳原始集合，即用於替換的元素的集合。

// 用 .new 元素替換所有 .box 元素
$('.new').replaceAll('.box');

.clone()

透過深度複製來複製集合中的所有元素。

該方法使用原生 cloneNode 方法進行深度複製，但不會複製資料和事件處理程式到新的元素。這點和 jQuery 中利用一個參數來確定是否複製資料和事件處理不相同。

$('body').append($('#box').clone());

表單

.serializeArray()

將表單元素的值組合成由 name 和 value 的鍵值對組成的陣列。

該方法可以對單獨的表單元素進行操作，也可以對整個 <form> 表單進行操作。

$('form').serializeArray();
// [
//   { "name": "golang", "value":"456" },
//   { "name": "name", "value": "mdui" },
//   { "name": "password", "value": "" }
// ]

.serializeObject()

將表單元素的值轉換為物件。

如果存在相同的鍵名，那麼對應的值會被轉換為陣列。

該方法可以對單獨的表單元素進行操作，也可以對整個 <form> 表單進行操作。

$('form').serializeObject();
// { name: mdui, password: 123456 }

.serialize()

將表單元素的值序列化為 URL 編碼字串。

$('form').serialize();
// golang=456&name=mdui&password=

事件

.on()

為集合中每個元素的特定事件繫結事件處理函式。具體用法見下方範例：

// 繫結點擊事件
$('.box').on('click', function (e) {
  console.log('點擊了 .box 元素');
});

// 繫結多個事件
$('.box').on('click focus', function (e) {
  console.log('click 和 focus 事件都會觸發該函式');
});

// 事件委託
$(document).on('click', '.box', function (e) {
  console.log('點擊 .box 時會觸發該函式');
});

// 同時繫結多個事件和事件處理函式
$('.box').on({
  click: function (e) {
    console.log('觸發了 click 事件');
  },
  focus: function (e) {
    console.log('觸發了 focus 事件');
  },
});

// 傳入參數
$('.box').on('click', { key1: 'value1', key2: 'value2' }, function (e) {
  console.log('點擊了 .box 元素，並為事件處理函式傳入了參數');
  // e._data 為 {key1: 'value1', key2: 'value2'}
});

// 同時繫結多個事件和事件處理函式，並傳入參數
$('.box').on(
  {
    click: function (e) {
      console.log('觸發了 click 事件');
      // e._data 為 {key1: 'value1', key2: 'value2'}
    },
    focus: function (e) {
      console.log('觸發了 focus 事件');
      // e._data 為 {key1: 'value1', key2: 'value2'}
    },
  },
  { key1: 'value1', key2: 'value2' },
);

// 透過事件委託繫結事件，並傳入參數
$(document).on(
  'click',
  '.box',
  { key1: 'value1', keys: 'value2' },
  function (e) {
    console.log('點擊了 .box 元素，並為事件處理函式傳入了參數');
    // e._data 為 {key1: 'value1', key2: 'value2'}
  },
);

// 透過事件委託同時繫結多個事件和事件處理函式
$(document).on(
  {
    click: function (e) {
      console.log('觸發了 click 事件');
    },
    focus: function (e) {
      console.log('觸發了 focus 事件');
    },
  },
  '.box',
);

// 透過事件委託同時繫結多個事件和事件處理函式，並傳入參數
$(document).on(
  {
    click: function (e) {
      console.log('觸發了 click 事件');
      // e._data 為 {key1: 'value1', key2: 'value2'}
    },
    focus: function (e) {
      console.log('觸發了 focus 事件');
      // e._data 為 {key1: 'value1', key2: 'value2'}
    },
  },
  '.box',
  { key1: 'value1', key2: 'value2' },
);

// 取得事件參數
$('.box').on('click', function (e, data) {
  // data 等於 e.detail
});

// 事件名稱支援使用命名空間
$('.box').on('click.myPlugin', function () {
  console.log('點擊了 .box 元素');
});

.one()

為每個匹配元素的特定事件繫結事件處理函式，但事件只會觸發一次。

該方法的用法和 .on() 相同，所以不再舉例了。

.off()

解除集合中的元素繫結的事件。具體用法見下方範例：

// 解除所有繫結的事件處理函式
$('.box').off();

// 解除繫結的指定事件
$('.box').off('click');

// 同時解除多個繫結的事件
$('.box').off('click focus');

// 解除繫結的指定事件處理函式
$('.box').off('click', callback);

// 解除透過事件委託繫結的事件
$(document).off('click', '.box');

// 解除透過事件委託繫結的指定事件處理函式
$(document).off('click', '.box', callback);

// 同時解除繫結多個事件處理函式
$('.box').off({
  click: callback1,
  focus: callback2,
});

// 同時解除繫結多個透過事件委託繫結的事件處理函式
$(document).off(
  {
    click: callback1,
    focus: callback2,
  },
  '.box',
);

// 事件名稱支援使用命名空間，下面的用法將解除繫結所有以 .myPlugin 結尾的事件
$(document).off('.myPlugin');

.trigger()

觸發指定的事件。具體用法見下方範例：

// 觸發指定的事件
$('.box').trigger('click');

// 觸發事件時傳入參數
$('.box').trigger('click', { key1: 'value1', key2: 'value2' });

// 事件名稱支援命名空間
$('.box').trigger('click.myPlugin');

// 傳入 CustomEvent 的參數
$('.box').trigger('click', undefined, {
  bubbles: true,
  cancelable: true,
  composed: true,
});

ajax

$.ajaxSetup()

設定全域的 AJAX 請求參數。

$.ajaxSetup({
  // 預設不觸發全域 AJAX 事件
  global: false,

  // 預設使用 POST 方法送出請求
  method: 'POST',
});

詳細參數清單參見下方的 ajax 參數。

$.ajax()

送出 AJAX 請求，並回傳 Promise。

const promise = $.ajax({
  method: 'POST',
  url: './test.php',
  data: {
    key1: 'val1',
    key2: 'val2',
  },
  success: function (response) {
    console.log(response);
  },
});

promise
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.log(error);
  });

詳細參數清單請參見下方的 AJAX 參數。

還可以使用 .on() 方法來監聽 AJAX 的全域事件。

// 當 AJAX 請求開始時，會觸發此事件
$(document).on('ajaxStart', function (e, { xhr, options }) {
  // xhr: XMLHttpRequest 物件
  // options: $.ajax() 方法的參數
});

// 當 AJAX 請求成功時，會觸發此事件
$(document).on('ajaxSuccess', function (e, { xhr, options, response }) {
  // xhr: XMLHttpRequest 物件
  // options: $.ajax() 方法的參數
  // response: 請求的回應
});

// 當 AJAX 請求失敗時，會觸發此事件
$(document).on('ajaxError', function (e, { xhr, options }) {
  // xhr: XMLHttpRequest 物件
  // options: $.ajax() 方法的參數
});

// 當 AJAX 請求完成時（無論成功或失敗），會觸發此事件
$(document).on('ajaxComplete', function (e, { xhr, options }) {
  // xhr: XMLHttpRequest 物件
  // options: $.ajax() 方法的參數
});

ajax 參數

$.ajax({
  url: '一個跨域 URL',
  xhrFields: {
    withCredentials: true
  }
});

$.ajax({
  statusCode: {
    404: function (xhr, textStatus) {
      alert('回傳狀態碼為 404 時被呼叫');
    },
    200: function (data, textStatus, xhr) {
      alert('回傳狀態碼為 200 時被呼叫');
    }
  }
});

$.ajax({
  beforeSend: function (xhr) {
    // xhr 為 XMLHttpRequest 物件
  }
});

$.ajax({
  success: function (data, textStatus, xhr) {
    // data 為 AJAX 請求回傳的資料
    // textStatus 為包含成功代碼的字串
    // xhr 為 XMLHttpRequest 物件
  }
});

$.ajax({
  error: function (xhr, textStatus) {
    // xhr 為 XMLHttpRequest 物件
    // textStatus 為包含錯誤代碼的字串
  }
});

$.ajax({
  complete: function (xhr, textStatus) {
    // xhr 為 XMLHttpRequest 物件
    // textStatus 為一個包含成功或錯誤代碼的字串
  }
});