Библиотека jq

mdui включает в себя лёгкую JavaScript-библиотеку, которая предоставляет API и цепочечные вызовы, подобные jQuery, но её размер составляет лишь одну шестую от jQuery.

Вы можете импортировать эту библиотеку по мере необходимости:

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

Основное

`$()`

Функция имеет несколько вариантов использования:

Передайте CSS-селектор, чтобы получить JQ-объект, содержащий соответствующие элементы.

$('.box');

Передайте DOM-элемент, любой массив, NodeList или JQ-объект, чтобы получить JQ-объект, содержащий указанные элементы.

$(document);

Передайте HTML-строку, чтобы получить JQ-объект, содержащий DOM-элементы, созданные на основе этой строки.

$(`<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, это значение не добавляется.

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-селектор, возвращает индекс первого элемента текущей коллекции относительно элементов, соответствующих селектору.

Если передан 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 — удаляется.

// Отфильтровывает все div с классом .box
$('div').filter('.box');

// Отфильтровывает все выбранные опции
$('#select option').filter(function (index, element) {
  return element.selected;
});

`.not()`

Отфильтровывает из текущей коллекции элементы, не соответствующие указанному выражению.

Аргумент может быть CSS-селектором, DOM-элементом, массивом DOM-элементов, JQ-объектом или функцией обратного вызова, возвращающей boolean.

Если аргумент — функция обратного вызова, её первый аргумент — индекс элемента, второй — текущий элемент. Внутри функции this указывает на текущий элемент. Если функция возвращает true, элемент удаляется; если false — сохраняется.

// Отфильтровывает все div без класса .box
$('div').not('.box');

// Отфильтровывает все невыбранные опции
$('#select option').not(function (index, element) {
  return element.selected;
});

CSS-классы

`.hasClass()`

Определяет, имеет ли первый элемент коллекции указанный CSS-класс.

// Проверяет, есть ли у первого div класс .item
$('div').hasClass('item');

`.addClass()`

Добавляет CSS-классы каждому элементу коллекции. Несколько классов можно разделить пробелами.

Аргумент может быть строкой или функцией обратного вызова, возвращающей CSS-классы. Первый аргумент функции — индекс элемента, второй — существующие классы элемента. Внутри функции this указывает на текущий элемент.

// Добавляет класс .item всем div
$('div').addClass('item');

// Добавляет классы .item1 и .item2 всем div
$('div').addClass('item1 item2');

// Добавляет классы, возвращённые функцией обратного вызова
$('div').addClass(function (index, currentClassName) {
  return currentClassName + '-' + index;
});

`.removeClass()`

Удаляет указанные CSS-классы у каждого элемента коллекции. Несколько классов можно разделить пробелами.

Если аргумент не передан, метод удаляет атрибут class у элемента.

// Удаляет класс .item у всех div
$('div').removeClass('item');

// Удаляет классы .item1 и .item2 у всех div
$('div').removeClass('item1 item2');

// Удаляет классы, возвращённые функцией обратного вызова
$('div').removeClass(function (index, currentClassName) {
  return 'item';
});

`.toggleClass()`

Если у элемента есть указанный класс, он удаляется; если нет — добавляется. Несколько классов можно разделить пробелами.

// Переключает класс .item у всех div
$('div').toggleClass('item');

// Переключает классы .item1 и .item2 у всех div
$('div').toggleClass('item1 item2');

// Переключает классы, возвращённые функцией обратного вызова
$('div').toggleClass(function (index, currentClassName) {
  return 'item';
});

Атрибуты узлов

`.prop()`

Возвращает значение JavaScript-свойства первого элемента коллекции.

// Получает значение свойства checked первого input
$('input').prop('checked');

Если передано два аргумента, метод устанавливает указанное JavaScript-свойство для всех элементов коллекции.

Значение может быть любого типа или результатом функции обратного вызова. Первый аргумент функции — индекс элемента, второй — старое значение свойства. Внутри функции this указывает на текущий элемент.

Если значение или результат функции равен undefined, свойство не изменяется.

// Устанавливает checked=true для всех input
$('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
$('div').attr('username');

Если передано два аргумента, метод устанавливает указанный HTML-атрибут для всех элементов коллекции.

Значение может быть строкой, числом или результатом функции обратного вызова. Первый аргумент функции — индекс элемента, второй — старое значение атрибута. Внутри функции this указывает на текущий элемент.

Если значение или результат функции равен null, атрибут удаляется; если undefined — не изменяется.

// Устанавливает атрибут для всех div
$('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
$('#input').val('mdui');

// Устанавливает значение через функцию обратного вызова
$('#input').val(function (index, oldValue) {
  return 'mdui';
});

`.text()`

Возвращает текстовое содержимое всех элементов коллекции (включая их потомков).

// Получает текст всех .box
$('.box').text();

Если передан аргумент, метод устанавливает текстовое содержимое для всех элементов коллекции.

Значение может быть строкой, числом, булевым значением или результатом функции обратного вызова. Первый аргумент функции — индекс элемента, второй — старое текстовое содержимое. Внутри функции this указывает на текущий элемент.

Если значение или результат функции равен undefined, текстовое содержимое не изменяется.

// Устанавливает текст для .box
$('.box').text('text content');

// Устанавливает текст через функцию обратного вызова
$('.box').text(function (index, oldTextContent) {
  return 'new text content';
});

`.html()`

Возвращает HTML-содержимое первого элемента коллекции.

// Получает HTML-содержимое первого .box
$('.box').html();

Если передан аргумент, метод устанавливает HTML-содержимое для всех элементов коллекции.

Значение может быть HTML-строкой, DOM-элементом или результатом функции обратного вызова, возвращающей HTML-строку или DOM-элемент. Первый аргумент функции — индекс элемента, второй — старое HTML-содержимое. Внутри функции this указывает на текущий элемент.

Если значение или результат функции равен undefined, HTML-содержимое не изменяется.

// Устанавливает HTML для .box
$('.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, свойство не изменяется. Если значение равно null, свойство удаляется. Если значение — число, автоматически добавляется единица px; если свойство не может использовать px, значение преобразуется в строку.

// Устанавливает CSS-свойство для всех элементов коллекции
$('.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();

Если передан аргумент, метод устанавливает ширину для всех элементов коллекции.

// Устанавливает ширину
$('.box').innerWidth('20%');

// Числовое значение по умолчанию использует px
$('.box').innerWidth(10);

// Устанавливает через функцию обратного вызова
$('.box').innerWidth(function (index, oldWidth) {
  return 10;
});

`.innerHeight()`

Возвращает высоту первого элемента коллекции (включая padding, исключая border, margin).

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

Если передан аргумент, метод устанавливает высоту для всех элементов коллекции.

// Устанавливает высоту
$('.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 указывает на текущий элемент.

// Устанавливает ширину
$('.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 указывает на текущий элемент.

// Устанавливает высоту
$('.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 или position: 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-элементом.

// Добавляет фон всем li, содержащим ul
$('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 (не включая .parent)
$('.item').parentsUntil('.parent');

// Все предки .item, являющиеся div, до .parent
$('.item').parentsUntil('.parent', 'div');

`.prev()`

Получает коллекцию предыдущих соседних элементов для каждого элемента текущей коллекции. Можно передать CSS-селектор для фильтрации.

// Предыдущий соседний элемент .box
$('.box').prev();

// Предыдущий соседний 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');

// Все предыдущие соседние div до .until
$('.box').prevUntil('.until', 'div');

`.next()`

Получает коллекцию следующих соседних элементов для каждого элемента текущей коллекции. Можно передать CSS-селектор для фильтрации.

// Следующий соседний элемент .box
$('.box').next();

// Следующий соседний div
$('.box').next('div');

`.nextAll()`

Получает коллекцию всех следующих соседних элементов для каждого элемента текущей коллекции. Можно передать CSS-селектор для фильтрации.

// Все следующие соседние элементы .box
$('.box').nextAll();

// Все следующие соседние элементы .box с классом .selected
$('.box').nextAll('.selected');

`.nextUntil()`

Получает всех следующих соседей каждого элемента текущей коллекции до элемента, соответствующего первому аргументу (не включая его).

Если аргументы не указаны, возвращаются все следующие соседи (аналогично .nextAll()).

// Все следующие соседние элементы .box
$('.box').nextUntil();

// Все следующие соседние элементы .box до .until
$('.box').nextUntil('.until');

// Все следующие соседние div до .until
$('.box').nextUntil('.until', 'div');

`.closest()`

Начинает с текущего элемента и поднимается вверх, возвращая первый элемент, соответствующий селектору. Аргумент может быть CSS-селектором, DOM-элементом или JQ-объектом.

// Ближайший предок .parent у .box
$('.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();

// Удаляет все p с классом .box
$('p').remove('.box');

`.prepend()`

Вставляет содержимое в начало каждого элемента текущей коллекции. Аргумент может быть 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-объектом. Поддерживается несколько аргументов.

Метод возвращает исходную коллекцию.

// Вставляет элемент
$('<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-объектом. Поддерживается несколько аргументов.

Метод возвращает исходную коллекцию.

// Вставляет элемент
$('<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-объектом. Поддерживается несколько аргументов.

Метод возвращает исходную коллекцию.

// Вставляет элемент
$('<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-объектом.

Метод возвращает заменённую исходную коллекцию.

// Заменяет все .box на <p>Hello</p>
$('.box').replaceWith('<p>Hello</p>');

// Заменяет через функцию обратного вызова
$('.box').replaceWith(function (index, oldHTML) {
  return oldHTML + index;
});

`.replaceAll()`

Заменяет указанные элементы текущими элементами.

Аргумент — заменяемые элементы: CSS-селектор, DOM-элемент, массив DOM-элементов или JQ-объект.

Метод возвращает исходную коллекцию (заменяющие элементы).

// Заменяет все .box элементами .new
$('.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()`

Привязывает обработчик событий к определённым событиям для каждого элемента коллекции. Подробнее в примерах ниже:

// Привязка события click
$('.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('Клик с переданными данными');
  // 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

Имя свойства	Тип	Значение по умолчанию
`url`	`string`	URL текущей страницы
URL-адрес запроса.
`method`	`string`	`GET`
HTTP-метод запроса. Допустимые значения: `GET`, `POST`, `PUT`, `PATCH`, `HEAD`, `OPTIONS`, `DELETE`.
`data`	`any`	`''`
Данные, отправляемые на сервер.
`processData`	`boolean`	`true`
Преобразовывать ли переданные данные в строку запроса.
`async`	`boolean`	`true`
Асинхронный ли запрос.
`cache`	`boolean`	`true`
Использовать ли кэш. Работает только для `GET`, `HEAD`.
`username`	`string`	`''`
Имя пользователя для HTTP-авторизации.
`password`	`string`	`''`
Пароль для HTTP-авторизации.
`headers`	`object`	`{}`
Данные для добавления в HTTP-заголовок. Могут быть переопределены в колбэке `beforeSend`. Поля со значением строки или `null` отправляются, поля со значением `undefined` игнорируются.
`xhrFields`	`object`	`{}`
Данные для установки на объекте `XMLHttpRequest`. `$.ajax({ url: 'cross-domain url', xhrFields: { withCredentials: true } });`
`statusCode`	`object`	`{}`
Объект с соответствиями HTTP-кодов и функций обработки. `$.ajax({ statusCode: { 404: function (xhr, textStatus) { alert('Вызвано при коде 404'); }, 200: function (data, textStatus, xhr) { alert('Вызвано при коде 200'); } } });` Коды в диапазоне 200–299 или 304 считаются успешными, параметры колбэка такие же, как у `success`; иначе — как у `error`.
`dataType`	`string`	`text`
Ожидаемый тип данных от сервера. Варианты: `text`, `json`
`contentType`	`string`	`application/x-www-form-urlencoded`
MIME-тип содержимого запроса. Если `false`, заголовок `Content-Type` не устанавливается.
`timeout`	`number`	`0`
Таймаут запроса в миллисекундах. `0` означает отсутствие таймаута.
`global`	`boolean`	`true`
Генерировать ли глобальные AJAX-события.
`beforeSend`	`function`	-
Вызывается перед отправкой запроса. Если возвращает `false`, запрос отменяется. `$.ajax({ beforeSend: function (xhr) { // xhr: объект XMLHttpRequest } });`
`success`	`function`	-
Вызывается при успешном запросе. `$.ajax({ success: function (data, textStatus, xhr) { // data: данные ответа // textStatus: строка с кодом успеха // xhr: объект XMLHttpRequest } });`
`error`	`function`	-
Вызывается при ошибке запроса. `$.ajax({ error: function (xhr, textStatus) { // xhr: объект XMLHttpRequest // textStatus: строка с кодом ошибки } });`
`complete`	`function`	-
Вызывается по завершении запроса (успех или ошибка). `$.ajax({ complete: function (xhr, textStatus) { // xhr: объект XMLHttpRequest // textStatus: строка с кодом успеха или ошибки } });`

Предыдущая глава

TopAppBar Верхняя панель приложения

Следующая глава

dialog