Начало работы
Установка через CDN
jQuery UI зависит от ядра jQuery — всегда подключайте jQuery до jquery-ui.js. CSS даёт тему по умолчанию и необходим виджетам вроде Datepicker и Dialog для корректного отображения. Версия 1.13.x поддерживает jQuery 1.8+.
<!-- jQuery UI requires jQuery core first -->
<link rel="stylesheet"
href="https://code.jquery.com/ui/1.13.2/themes/base/jquery-ui.css">
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://code.jquery.com/ui/1.13.2/jquery-ui.min.js"></script>Установка через npm
Установка через npm позволяет tree-shaking, если импортировать только нужные виджеты (например, jquery-ui/ui/widgets/datepicker). Импорт всего пакета 'jquery-ui' включает каждый виджет и эффект. CSS-тему нужно импортировать отдельно.
# Install via npm
npm install jquery jquery-ui
# Import in your bundle
import $ from "jquery";
import "jquery-ui/ui/widgets/datepicker";
import "jquery-ui/themes/base/all.css";
// Or import the full bundle
import "jquery-ui";Базовая инициализация виджета
Все виджеты jQuery UI следуют одному плагинному шаблону: $(selector).widgetName(options). Передайте объект о пций для настройки, вызывайте методы строковым синтаксисом ('methodName', args...). Всегда оборачивайте инициализацию в $(function(){}) или ставьте скрипт в конец body.
$(function () {
// Initialize a widget on a selector
$("#datepicker").datepicker();
$("#dialog").dialog();
// Pass options as an object
$("#accordion").accordion({
active: false,
collapsible: true,
});
// Get or set an option after init
$("#accordion").accordion("option", "active", 1);
});Паттерн методов виджета
Строковый API единообразен для всех виджетов. 'option' (геттер/сеттер), 'enable'/'disable', 'widget' (возвращает внешний элемент) и 'destroy' (восстанавливает исходную разметку) поддерживаются каждым виджетом. Используйте destroy при удалении элементов, чтобы избежать утечек памяти.
// All widgets share the same API conventions
$("#dialog").dialog("open"); // call a method
$("#dialog").dialog("option", "title"); // get an option
$("#dialog").dialog("option", "modal", true); // set an option
$("#dialog").dialog("disable"); // disable widget
$("#dialog").dialog("enable"); // enable widget
$("#dialog").dialog("widget"); // get the wrapper element
$("#dialog").dialog("destroy"); // remove widget entirelyНастройка темы
jQuery UI поставляется с ~24 готовыми темами. Тема 'base' — по умолчанию. ThemeRoller (themeRoller.jqueryui.com) генерирует свои темы. Загружайте свой CSS после базового, чтобы переопределить конкретные классы вроде .ui-widget-header или .ui-state-default.
<!-- Default base theme -->
<link rel="stylesheet"
href="https://code.jquery.com/ui/1.13.2/themes/base/jquery-ui.css">
<!-- Other bundled themes: ui-lightness, ui-darkness, smoothness, redmond, ... -->
<link rel="stylesheet"
href="https://code.jquery.com/ui/1.13.2/themes/smoothness/jquery-ui.css">
<!-- Override theme with your own CSS -->
<link rel="stylesheet" href="jquery-ui.css">
<link rel="stylesheet" href="my-theme-overrides.css">Соглашение об именовании классов
CSS-фреймворк использует единое именование ui-*. Состояния взаимодействия (default, hover, active, focus) применяются виджетами автоматически. Эти классы можно использовать прямо в своей разметке, чтобы соответствовать стилю jQuery UI.
/* jQuery UI CSS classes are namespaced with ui- */
.ui-widget /* base widget class */
.ui-widget-header /* header bar (accordion, datepicker) */
.ui-widget-content /* content area */
.ui-state-default /* default interactive state */
.ui-state-hover /* mouse-over state */
.ui-state-active /* active/selected state */
.ui-state-focus /* keyboard focus state */
.ui-state-disabled /* disabled state */
.ui-corner-all /* rounded corners (themable) */
.ui-icon /* base icon class */Draggable
Базовый Draggable
Сделать элемент перетаскиваемым — один вызов. Затем элемент можно двигать мышью. Класс ui-widget-content применяет стиль темы по умолчанию. Draggable управляет позиционированием: relative/absolute применяется по необходимости.
<!-- HTML -->
<div id="box" class="ui-widget-content" style="width:100px;height:100px;">
Drag me
</div>
<!-- JS -->
<script>
$(function () {
$("#box").draggable();
});
</script>Опции Draggable
Опции управляют перетаскиванием. 'axis' ограничивает движение одной осью, 'containment' ограничивает область, 'grid' привязывает к шагу, 'revert' возвращает элемент в исходную позицию. 'helper: clone' тащит копию вместо оригинала.
$("#box").draggable({
axis: "x", // constrain to x or y axis
containment: "parent", // or "window", "document", or selector
cursor: "move", // cursor while dragging
cursorAt: { left: 5 }, // offset cursor from drag handle
grid: [20, 20], // snap to grid
delay: 100, // ms delay before drag starts
distance: 5, // px before drag starts
revert: true, // snap back to start
revertDuration: 200, // revert animation duration
scroll: false, // prevent auto-scroll
helper: "clone", // "original", "clone", or function
opacity: 0.6, // opacity while dragging
zIndex: 1000, // z-index while dragging
});События перетаскивания
Во время перетаскивания срабатывают три события: 'start' (один раз в начале), 'drag' (непрерывно при движении) и 'stop' (один раз в конце). Объект ui даёт position (относительно родителя) и offset (относительно страницы). Тяжёлая работа в 'drag' может снизить производительность.
$("#box").draggable({
start: function (event, ui) {
console.log("Drag started", ui.position);
},
drag: function (event, ui) {
// Fires continuously during drag
console.log(ui.position.left, ui.position.top);
},
stop: function (event, ui) {
console.log("Drag stopped at", ui.position);
console.log("Offset:", ui.offset);
},
});Handle и cancel
'handle' ограничивает начало перетаскивания конкретным дочерним элементом — полезно, когда двигать нужно весь блок, но только за заголовок. 'cancel' запрещает перетаскивание с отдельных элементов вроде input и textarea, где мышь нужна для редактирования.
<!-- Only the header acts as the drag handle -->
<div id="box" class="ui-widget-content">
<div class="drag-handle">Drag from here</div>
<div class="content">Some content here</div>
<textarea>Editable content</textarea>
</div>
<script>
$("#box").draggable({
handle: ".drag-handle", // only this starts the drag
cancel: "textarea", // these elements never start a drag
});
</script>Ограничение движения
Containment ограничивает, куда можно перетащить элемент. Работают 'parent', 'window', 'document', селектор или явный массив [x1,y1,x2,y2]. Вместе с 'grid' можно получить точное позиционирование по сетке для редакторов вёрстки или дашбордов.
// Constrain within a parent element
$("#box").draggable({ containment: "parent" });
// Constrain within the window
$("#box").draggable({ containment: "window" });
// Constrain within a specific selector
$("#box").draggable({ containment: "#drag-area" });
// Constrain to an explicit bounding box [x1, y1, x2, y2]
$("#box").draggable({ containment: [0, 0, 500, 300] });
// Snap to a 50px grid
$("#box").draggable({ grid: [50, 50] });Привязка к элементам
'snap' заставляет перетаскиваемый элемент выравниваться по целевым элементам, когда тот достаточно близко. 'snapMode' управляет выравниванием: 'inner' (внутри цели), 'outer' (снаружи цели) или 'both'. Полезно для инструментов построения диаграмм и раскладок дашбордов, где элементы должны выравниваться.
$(".card").draggable({
snap: ".snap-target", // selector of elements to snap to
snapMode: "inner", // "inner", "outer", or "both"
snapTolerance: 30, // px distance to trigger snap
});
// Snap to all siblings of the same class
$(".card").draggable({
snap: ".card",
snapTolerance: 20,
});Droppable
Базовый Droppable
Droppable задаёт область, принимающую перетаскиваемые элементы. Колбэк 'drop' срабатывает, когда draggable отпускают над ней. Свойство ui.draggable даёт ссылку на перетаскиваемый элемент, чтобы переместить или обработать его.
<div id="draggable" class="ui-widget-content">Drag me</div>
<div id="droppable" class="ui-widget-header">Drop here</div>
<script>
$(function () {
$("#draggable").draggable();
$("#droppable").droppable({
drop: function (event, ui) {
$(this).addClass("ui-state-highlight")
.html("Dropped!");
},
});
});
</script>Опции Droppable
'accept' фильтрует допустимые draggable: селектор или функция. 'activeClass' и 'hoverClass' дают визуальную обратную связь. 'greedy: true' не даёт вложенным droppable одновременно получать событие drop — полезно для вложенных зон.
$("#droppable").droppable({
accept: ".special", // only accept matching draggables
activeClass: "ui-state-default", // class while a drag is active
hoverClass: "ui-state-hover", // class while draggable is over
tolerance: "fit", // drop detection mode
greedy: true, // stop event propagation
disabled: false, // disable the droppable
});События drop
Пять событий покрывают весь жизненный цикл drop. 'activate'/'deactivate' срабатывают при начале и конце подходящего перетаскивания. 'over'/'out' — при входе и выходе draggable в зону. 'drop' — только при успешном отпускании. Используйте их для пошаговой визуальной обратной связи.
$("#droppable").droppable({
activate: function (event, ui) {
// Fires when an accepted draggable starts moving
$(this).addClass("ui-state-default");
},
deactivate: function (event, ui) {
// Fires when the drag ends (drop or cancel)
$(this).removeClass("ui-state-default");
},
over: function (event, ui) {
// Draggable entered the drop zone
$(this).addClass("ui-state-hover");
},
out: function (event, ui) {
// Draggable left the drop zone
$(this).removeClass("ui-state-hover");
},
drop: function (event, ui) {
// Draggable was released here
console.log("Dropped:", ui.draggable);
},
});Селектор accept
'accept' может быть строкой-селектором или функцией, возвращающей булево. Функция получает перетаскиваемый элемент и выполняется для каждого кандидата, позволяя применять логику времени выполнения: атрибуты данных, вычисленные состояния. Непринятые draggable не вызывают события drop.
<!-- HTML: red and blue boxes -->
<div class="red draggable">Red</div>
<div class="blue draggable">Blue</div>
<div id="red-bin" class="bin">Red bin</div>
<div id="blue-bin" class="bin">Blue bin</div>
<script>
// Only accept elements matching the selector
$("#red-bin").droppable({ accept: ".red" });
$("#blue-bin").droppable({ accept: ".blue" });
// Or use a function for dynamic logic
$("#any-bin").droppable({
accept: function (drag) {
return $(drag).data("category") === "recyclable";
},
});
</script>Режимы tolerance
Tolerance определяет, какое перекрытие нужно для регистрации drop. 'fit' самый строгий (весь элемент внутри). 'pointer' основан на курсоре мыши. 'intersect' (перекрытие 50%) — хороший баланс для большинства интерфейсов. 'touch' самый мягкий.
$("#droppable").droppable({
// "fit": draggable must be fully inside (default)
tolerance: "fit",
// "intersect": at least 50% overlap
tolerance: "intersect",
// "pointer": mouse pointer must be inside
tolerance: "pointer",
// "touch": any edge touching counts
tolerance: "touch",
});Визуальная обратная связь классами
Сочетайте activeClass (показывается, пока идёт допустимое перетаскивание) и hoverClass (показывается, когда draggable над зоной), чтобы дать пользователю ясную обратную связь. В обработчике drop обычно добавляют draggable в зону, меняя его родителя.
<!-- CSS -->
<style>
.drop-active { border: 2px dashed #ccc; }
.drop-hover { border: 2px solid #0a0; background: #efe; }
</style>
<!-- JS -->
$("#zone").droppable({
accept: ".item",
activeClass: "drop-active",
hoverClass: "drop-hover",
drop: function (event, ui) {
$(this).append(ui.draggable);
ui.draggable.css({ top: 0, left: 0 });
},
});Resizable
Базовый Resizable
Resizable добавляет элементу ручки изменения размера. По умолчанию ручка появляется в правом нижнем углу (se). Элемент должен иметь позиционирование (relative/absolute), чтобы ручки крепились правильно.
<div id="box" class="ui-widget-content">
Resize me from the corner
</div>
<script>
$(function () {
$("#box").resizable();
});
</script>Ручки изменения размера
'handles' управляет тем, у каких краёв и углов есть ручки. Используйте стороны света: n, e, s, w, ne, se, sw, nw. По умолчанию 'e, s, se'. Можно задать свои элементы-ручки селектором для полного контроля над стилями.
$("#box").resizable({
handles: "n, e, s, w, ne, se, sw, nw", // all eight handles
});
// Or specify handle elements
$("#box").resizable({
handles: {
n: ".n-handle",
se: ".se-handle",
},
});Опции Resizable
Опции ограничивают и настраивают изменение размера. 'aspectRatio' сохраняет пропорции (отлично для изображений и видео). 'alsoResize' синхронизирует другой элемент. 'ghost' показывает призрачный предпросмотр при изменении, а реальный размер применяется при отпускании. min/max задают границы.
$("#box").resizable({
alsoResize: "#other", // resize another element in sync
animate: true, // animate to final size
animateDuration: 200, // ms
aspectRatio: 16 / 9, // preserve width:height ratio
autoHide: true, // hide handles until hover
containment: "parent", // restrict resize within parent
grid: [10, 10], // snap to grid
maxHeight: 400,
maxWidth: 600,
minHeight: 100,
minWidth: 100,
ghost: true, // show a ghost outline while resizing
});События изменения размера
Как и у draggable, resize генерирует start/resize/stop. Объект ui имеет 'size' (width, height) и 'position' (left, top). При изменении с северного или западного края меняются и размер, и позиция. Используйте resize для обновления зависимого UI, например живого предпросмотра.
$("#box").resizable({
start: function (event, ui) {
console.log("Resize start", ui.size, ui.position);
},
resize: function (event, ui) {
// Fires continuously during resize
ui.size.width; // new width
ui.size.height; // new height
ui.position.left; // new position (may change for n/w handles)
},
stop: function (event, ui) {
console.log("Final size:", ui.size);
},
});Пропорции и ограничения
Используйте aspectRatio (число или true, чтобы зафиксировать текущее соотношение) для изображений и медиа. Вместе с ограничениями min/max это предотвращает неудобные размеры. Привязка к сетке выравнивает по шагу — полезно для редакторов и инструментов вёрстки.
// Keep a 4:3 ratio
$("#photo").resizable({ aspectRatio: 4 / 3 });
// Keep ratio and stay within bounds
$("#photo").resizable({
aspectRatio: 4 / 3,
maxWidth: 800,
maxHeight: 600,
minWidth: 100,
minHeight: 75,
});
// Snap to a grid of 20px
$("#grid-box").resizable({ grid: [20, 20] });Режимы animate и ghost
'animate' плавно переходит к новому размеру после отпускания мыши. 'ghost' показывает полупрозрачный предпросмотр при перетаскивании, применяя реальное изменение только при отпускании. Вместе они дают аккуратное изменение размера без рывков.
// Animate to the final size after release
$("#box").resizable({
animate: true,
animateDuration: "slow", // or ms number
animateEasing: "swing",
});
// Show a ghost outline while dragging, apply on release
$("#box").resizable({
ghost: true,
helper: "ui-resizable-helper", // class for the ghost
});
// Combine both
$("#box").resizable({ ghost: true, animate: true });Selectable
Базовый Selectable
Selectable превращает список детей в группу с возможностью выбора. Клик выбирает, перетаскивание рамкой — несколько. Удерживайте Ctrl/Cmd, чтобы добавить к выбору, Shift — чтобы выбрать диапазон. Выбранные элементы автоматически получают класс ui-selected.
<ol id="selectable">
<li class="ui-widget-content">Item 1</li>
<li class="ui-widget-content">Item 2</li>
<li class="ui-widget-content">Item 3</li>
</ol>
<script>
$(function () {
$("#selectable").selectable();
});
</script>Опции Selectable
'filter' ограничивает, какие дети участвуют. 'tolerance' управляет поведением рамки: 'touch' выбирает при любом перекрытии (по умолчанию), 'fit' требует полного включения. Для больших списков задайте 'autoRefresh: false' для производительности — вызывайте $(...).selectable('refresh') вручную после изменений раскладки.
$("#selectable").selectable({
filter: "li", // which children can be selected
tolerance: "touch", // "touch" or "fit" for lasso overlap
distance: 0, // px before lasso starts
delay: 0, // ms delay before lasso starts
autoRefresh: true, // recompute positions on each drag
disabled: false,
cancel: "a, .no-select", // elements that never start selection
});События выбора
События покрывают жизненный цикл выбора: 'selecting'/'unselecting' при перетаскивании, 'selected'/'unselected' после подтверждения, 'start'/'stop' для операции целиком. В каждом объекте ui есть соответствующий элемент (selecting, selected и т. д.).
$("#selectable").selectable({
selecting: function (event, ui) {
// ui.selecting: element being lassoed
$(ui.selecting).addClass("highlight");
},
selected: function (event, ui) {
// ui.selected: element just confirmed selected
console.log("Selected:", $(ui.selected).text());
},
unselecting: function (event, ui) {
$(ui.unselecting).removeClass("highlight");
},
unselected: function (event, ui) {
console.log("Unselected:", $(ui.unselected).text());
},
start: function (event, ui) { /* lasso started */ },
stop: function (event, ui) { /* lasso released */ },
});Фильтрация элементов
Используйте 'filter', чтобы разрешить выбор только определённых детей, и 'cancel', чтобы исключить остальные. Это полезно для галерей, где некоторые элементы (заблокированные, только для чтения) не должны участвовать. Рамка просто игнорирует неподходящие элементы.
<ul id="gallery">
<li class="selectable-item">Photo 1</li>
<li class="locked">Locked</li>
<li class="selectable-item">Photo 2</li>
</ul>
<script>
$("#gallery").selectable({
filter: ".selectable-item", // only these can be selected
cancel: ".locked", // locked items never select
});
</script>Стилизация выбранных
jQuery UI автоматически применяет классы ui-selecting (при перетаскивании) и ui-selected (после отпускания). Стилизуйте их для обратной связи. Текущий выбор можно прочитать в любой момент через $('.ui-selected') внутри контейнера — удобно для панелей инструментов и массовых действий.
/* CSS */
#selectable .ui-selecting {
background: #feca40; /* while dragging */
}
#selectable .ui-selected {
background: #f39814; /* confirmed selection */
color: white;
}
#selectable li {
margin: 3px; padding: 6px;
border: 1px solid #ccc;
}
/* selected count badge */
function updateCount() {
var n = $("#selectable .ui-selected").length;
$("#count").text(n + " selected");
}
$("#selectable").on("selectablestop", updateCount);Программный выбор
Вызывайте 'refresh' после добавления или удаления элементов, чтобы проверка попадания рамкой оставалась точной. Встроенного метода 'select' нет, но класс ui-selected можно переключать вручную. Очищайте, убирая этот класс со всех элементов.
// Refresh positions after DOM changes
$("#selectable").selectable("refresh");
// Disable / enable
$("#selectable").selectable("disable");
$("#selectable").selectable("enable");
// Remove the widget
$("#selectable").selectable("destroy");
// Manually select an item (set the class)
$("#selectable li").eq(2).addClass("ui-selected");
// Clear all selections
$("#selectable .ui-selected").removeClass("ui-selected");Sortable
Базовый Sortable
Sortable делает элементы списка переупорядочиваемыми перетаскиванием. Во время перетаскивания элементы визуально двигаются, а порядок в DOM обновляется при отпускании. Полезно для списков задач, фотогалерей и любого содержимого с приоритетом.
<ul id="sortable">
<li class="ui-widget-content">Item 1</li>
<li class="ui-widget-content">Item 2</li>
<li class="ui-widget-content">Item 3</li>
</ul>
<script>
$(function () {
$("#sortable").sortable();
});
</script>Опции Sortable
Опции уточняют поведение сортировки. 'placeholder' стилизует оставляемый промежуток; forcePlaceholderSize гарантирует с овпадение с размерами элемента. 'axis' ограничивает горизонталью или вертикалью. 'handle' задаёт ручку перетаскивания — идеально, когда у элемента есть интерактивные дети.
$("#sortable").sortable({
axis: "y", // constrain to vertical
cursor: "move",
handle: ".handle", // drag from this element only
placeholder: "sortable-placeholder", // class for the drop preview
forcePlaceholderSize: true, // match placeholder to item size
helper: "clone", // "original" or "clone"
opacity: 0.7,
revert: true, // animate item into place
tolerance: "pointer", // "intersect" or "pointer"
scroll: true, // auto-scroll the page
containment: "parent", // restrict within parent
});События сортировки
Ключевые события: 'start'/'stop' обрамляют сортировку. 'change' срабатывает при изменении позиции элемента во время перетаскивания. 'update' срабатывает, только если итоговый порядок отличается от начального — здесь сохраняют новый порядок, часто через toArray(), возвращающий ID элементов по порядку.
$("#sortable").sortable({
start: function (event, ui) {
ui.item; // the dragged element
ui.placeholder; // the placeholder element
ui.helper; // the helper being dragged
},
change: function (event, ui) {
// Position in list changed during drag
},
sort: function (event, ui) {
// Fires continuously while sorting
},
beforeStop: function (event, ui) {
// Just before the item is placed
},
stop: function (event, ui) {
console.log("Sort ended");
},
update: function (event, ui) {
// Order actually changed — persist it here
var order = $(this).sortable("toArray");
saveOrder(order);
},
});Связанные списки
'connectWith' связывает несколько sortable, чтобы элементы можно было перетаскивать между ними, — отлично для канбан-досок и менеджеров пайплайнов. Каждый список по-прежнему хранит свой порядок через toArray(). События receive/remove позволяют реагировать на переносы между списками.
<ul id="list-a" class="connected">
<li>Task A1</li><li>Task A2</li>
</ul>
<ul id="list-b" class="connected">
<li>Task B1</li>
</ul>
<script>
$(".connected").sortable({
connectWith: ".connected", // allow moving between lists
placeholder: "ui-state-highlight",
}).disableSelection();
</script>Placeholder и helper
Placeholder — пустое место, показываемое там, куда попадёт элемент; стилизуйте его для ясной обратной связи. forcePlaceholderSize важен, когда элементы разной высоты. Своя функция helper позволяет показывать упрощённый предпросмотр при перетаскивании.
$("#sortable").sortable({
placeholder: "ui-state-highlight", // class for the gap
forcePlaceholderSize: true,
helper: function (event, el) {
// Return a custom helper element
return $("<div class='custom-helper'>Moving...</div>");
},
cursorAt: { top: 10, left: 10 },
});
// Use a clone as the helper instead of moving the original
$("#sortable").sortable({ helper: "clone" });Методы Sortable
toArray() возвращает ID в текущем порядке — самое полезное для сохранения. serialize() строит query-строку, ко гда ID следуют соглашению 'name_number'. cancel() отменяет последнюю сортировку. Вызывайте refresh() после программного добавления элементов.
// Get current order as an array of IDs
var order = $("#sortable").sortable("toArray");
// ["item-1", "item-3", "item-2"]
// Get option values
var placeholder = $("#sortable").sortable("option", "placeholder");
// Serialize items as a query string (uses id="name_number")
var data = $("#sortable").sortable("serialize");
// "item[]=1&item[]=2&item[]=3"
// Cancel the current sort (revert)
$("#sortable").sortable("cancel");
// Refresh positions after DOM changes
$("#sortable").sortable("refresh");
// Disable / enable / destroy
$("#sortable").sortable("disable");
$("#sortable").sortable("enable");
$("#sortable").sortable("destroy");Accordion
Базовый Accordion
Accordion ожидает пары элементов-заголовков и содержимого (заголовок должен идти первым). По умолчанию открыта только одна секция. Заголовок по умолчанию — h3, но меняется опцией header. Панели содержимого следуют за каждым заголовком.
<div id="accordion">
<h3>Section 1</h3>
<div>Content for section 1</div>
<h3>Section 2</h3>
<div>Content for section 2</div>
<h3>Section 3</h3>
<div>Content for section 3</div>
</div>
<script>
$(function () {
$("#accordion").accordion();
});
</script>Опции Accordion
'collapsible: true' позволяет закрыть все панели (по умолчанию одна всегда открыта). 'heightStyle: content' подгоняет каждую панель под её содержимое; 'fill' делает все панели одной высоты с контейнером; 'auto' берёт высоту самой высокой панели.
$("#accordion").accordion({
active: 0, // index of open panel (false = all closed)
collapsible: true, // allow closing all panels
disabled: false,
animate: 200, // ms or "ease name" or false
heightStyle: "content", // "auto", "fill", or "content"
header: "h3", // header selector
icons: {
header: "ui-icon-triangle-1-e",
activeHeader: "ui-icon-triangle-1-s",
},
event: "click", // event that toggles panels
});События Accordion
beforeActivate позволяет отменить смену панели, вернув false, — удобно для предупреждений о несохранённых изменениях. activate срабатывает после завершения анимации. Объект ui даёт старые и новые элементы заголовка и панели для обоих событий.
$("#accordion").accordion({
beforeActivate: function (event, ui) {
// ui.oldHeader, ui.oldPanel (closing)
// ui.newHeader, ui.newPanel (opening)
// Return false to cancel
if ($(ui.newHeader).data("locked")) return false;
},
activate: function (event, ui) {
// Fires after a panel finishes opening
console.log("Opened:", ui.newHeader.text());
},
create: function (event, ui) {
// Fires on initialization
console.log("Accordion created, open:", ui.header.text());
},
});Свои иконки
icons сопоставляет классы иконок закрытого (header) и открытого (activeHeader) состояния. Передайте false, чтобы отключить иконки. Можно использовать любую библиотеку иконок (FontAwesome, Material Icons), указав подходящие классы: span-иконка создаётся автоматически.
$("#accordion").accordion({
icons: {
header: "ui-icon-circle-arrow-e",
activeHeader: "ui-icon-circle-arrow-s",
},
});
// Disable icons entirely
$("#accordion").accordion({ icons: false });
// Use your own icon classes (e.g. with FontAwesome)
$("#accordion").accordion({
icons: {
header: "fa fa-plus",
activeHeader: "fa fa-minus",
},
});Collapsible и несколько секций
Для аккордеона с несколькими одновременно открытыми секциями аккордеон jQuery UI не подходит напрямую: инициализируйте отдельные сворачиваемые аккордеоны для каждой секции или используйте вкладки. Опция 'collapsible: true' позволяет лишь закрыть текущую открытую панель.
// Allow all panels to be closed
$("#accordion").accordion({
collapsible: true,
active: false, // start with all closed
});
// Make every section independently toggleable
// (a true multi-open accordion = separate collapsibles)
$(".section").each(function () {
$(this).accordion({
collapsible: true,
active: false,
header: ".section-header",
});
});Динамический Accordion
Вызывайте refresh() после добавления или удаления панелей, чтобы виджет перепривязался. Опция active позволяет программно открыть панель по индексу. Паттерн beforeActivate — чистый способ лениво подгружать содержимое панели через AJAX только при первом открытии.
// Refresh after adding content
$("#accordion").append("<h3>New</h3><div>Content</div>");
$("#accordion").accordion("refresh");
// Switch the open panel
$("#accordion").accordion("option", "active", 2);
// Disable / enable
$("#accordion").accordion("disable");
$("#accordion").accordion("enable");
// Destroy
$("#accordion").accordion("destroy");
// Load content on demand (AJAX-style)
$("#accordion").accordion({
beforeActivate: function (event, ui) {
var panel = ui.newPanel;
if (panel.is(":empty")) {
panel.load("/api/section/" + ui.newHeader.data("id"));
}
},
});Autocomplete
Базовый Autocomplete
Передайте простой массив строк в 'source' для статических подсказок. Виджет фильтрует по подстроке по мере ввода. Подсказки появляются в выпадающем списке; выбор заполняет поле. Список может содержать объекты {label, value} для более богатого отображения.
<label for="city">City:</label>
<input id="city" type="text">
<script>
$(function () {
var cities = ["London", "Paris", "Berlin", "Madrid", "Rome"];
$("#city").autocomplete({ source: cities });
});
</script>Удалённый источник данных
Когда source — URL, autocomplete отправляет GET с ?term= введённого текста и ожидает JSON-массив. minLength откладывает запрос до ввода достаточного числа символов, снижая нагрузку на сервер. Опция delay дебаунсит быстрый ввод.
$("#city").autocomplete({
source: "/api/cities", // server endpoint
minLength: 2, // start suggesting after 2 chars
delay: 300, // ms between keystroke and request
});
// The server should return JSON like:
// ["London", "Paris", "Berlin"]
// or [{ "label": "London, UK", "value": "London" }]Опции Autocomplete
autoFocus: true подсвечивает первую подсказку, чтобы Enter сразу её выбр ал. position настраивает размещение меню относительно поля через jQuery UI Position. appendTo полезен, когда поле находится в контейнере с абсолютным позиционированием и проблемами overflow.
$("#city").autocomplete({
source: cities, // array, URL, or function
minLength: 1, // chars before suggestions appear
delay: 300, // ms between keystroke and request
autoFocus: true, // focus first item automatically
appendTo: "#container", // where to render the menu
position: { my: "left top", at: "left bottom" },
disabled: false,
});Своя функция source
Функция source даёт полный контроль: кеширование, своя фильтрация, объединение нескольких endpoint. Вы ОБЯЗАНЫ вызвать response(results) с массивом, даже пустым. Каждый элемент может иметь произвольные поля помимо label/value, доступные в обработчике select.
$("#city").autocomplete({
source: function (request, response) {
// request.term is the typed text
// response() must be called with the results array
$.getJSON("/api/cities", { q: request.term })
.done(function (data) {
response(data);
})
.fail(function () {
response([]); // always call response, even on error
});
},
select: function (event, ui) {
// ui.item.label, ui.item.value
$("#city-id").val(ui.item.id);
},
});События Autocomplete
focus срабатывает при перемещении по подсказкам (клавиатурой или мышью). select — при выборе элемента. change срабатывает на blur и подходит для проверки, что итоговое значение есть в источнике. Возврат false предотвращает стандартное заполнение поля.
$("#city").autocomplete({
source: cities,
focus: function (event, ui) {
// Fires when an item is highlighted (not selected)
$("#preview").text(ui.item.label);
return false; // prevent setting the input value on focus
},
select: function (event, ui) {
// Fires when an item is chosen
$("#city").val(ui.item.label);
$("#city-id").val(ui.item.value);
return false; // prevent default behavior
},
change: function (event, ui) {
// Fires when input loses focus
if (!ui.item) {
// User typed something not in the list
console.log("No match:", this.value);
}
},
});Категории и своё отображение
Переопределите _renderMenu или _renderItem, чтобы настроить раскладку выпадающего списка. Этот пример группирует подсказки по категориям с заголовками. Паттерн $.widget расширяет базовый autocomplete, поэтому все исходные опции и события продолжают работать. Часто для поисковых интерфейсов.
$.widget("custom.catcomplete", $.ui.autocomplete, {
_renderMenu: function (ul, items) {
var that = this, currentCategory = "";
$.each(items, function (index, item) {
if (item.category !== currentCategory) {
ul.append("<li class='ui-autocomplete-category'>"
+ item.category + "</li>");
currentCategory = item.category;
}
that._renderItemData(ul, item);
});
},
});
// Use the new widget
$("#search").catcomplete({
source: [
{ label: "Java", category: "Languages" },
{ label: "JavaScript", category: "Languages" },
{ label: "React", category: "Frameworks" },
],
});Datepicker
Базовый Datepicker
Клик или фокус в поле открывает всплывающий календарь. Выбранная дата заполняет поле текстом. Календарь показывает текущий месяц со стрелками для предыдущего и следующего месяца. По умолчанию даты в формате США (mm/dd/yy).
<label for="date">Pick a date:</label>
<input type="text" id="date">
<script>
$(function () {
$("#date").datepicker();
});
</script>Опции Datepicker
minDate/maxDate принимают объект Date, число (дни от сегодня) или строку ('+1M +1W'). numberOfMonths показывает несколько месяцев — полезно для выбора диапазона дат. changeMonth/changeYear добавляют выпадающие списки для быстрого перехода к далёким годам.
$("#date").datepicker({
dateFormat: "yy-mm-dd", // ISO format
defaultDate: "+1", // tomorrow when calendar opens
minDate: 0, // no past dates (today+)
maxDate: "+1Y", // up to one year ahead
numberOfMonths: 2, // show 2 months side by side
showButtonPanel: true, // Today/Done buttons
changeMonth: true, // dropdown for month
changeYear: true, // dropdown for year
showAnim: "fadeIn", // open animation
duration: "fast",
firstDay: 1, // start week on Monday
showWeek: true, // show week numbers
});Формат даты
Опция dateFormat использует токены в стиле PHP. 'yy' означает четырёхзначный год (лишняя y намеренна). Метод formatDate() переводит Date в строку с теми же токенами, а parseDate() выполняет обратное преобразование.
$("#date").datepicker({
dateFormat: "yy-mm-dd", // 2026-07-04
});
// Format tokens:
// d - day of month, no leading zero (1)
// dd - day, two digits (01)
// D - short day name (Mon)
// DD - full day name (Monday)
// m - month, no leading zero (1)
// mm - month, two digits (01)
// M - short month name (Jan)
// MM - full month name (January)
// y - two-digit year (26)
// yy - four-digit year (2026)
// @ - Unix timestamp
// ! - Windows ticks
// Common formats:
// "mm/dd/yy" -> 07/04/2026
// "yy-mm-dd" -> 2026-07-04
// "DD, MM d, yy" -> Friday, July 4, 2026Min/max и диапазоны
Для выбора диапазона свяжите два datepicker: при выборе начала задайте minDate конца; при выборе конца задайте maxDate начала. beforeShowDay позволяет отключать или стилизовать отдельные дни: noWeekends — встроенная функция, блокирующая субботу и воскресенье.
// Restrict to a date range
$("#start").datepicker({
minDate: 0,
maxDate: "+6M",
onSelect: function (dateText) {
// Set the end date's minimum to the start date
$("#end").datepicker("option", "minDate", dateText);
},
});
$("#end").datepicker({
minDate: 0,
maxDate: "+6M",
onSelect: function (dateText) {
$("#start").datepicker("option", "maxDate", dateText);
},
});
// Disable weekends
$("#date").datepicker({
beforeShowDay: $.datepicker.noWeekends,
});Локализация
jQuery UI поставляется с региональными файлами в папке i18n для ~40 локалей. Загрузите файл и примените через $.datepicker.regional['fr']. Отдельные строки можно переопределить inline. Региональный файл сразу задаёт названия месяцев, дней, firstDay и dateFormat.
// Set the regionalization
$("#date").datepicker($.datepicker.regional["fr"]);
// Override specific strings
$("#date").datepicker({
monthNames: ["janvier","février","mars","avril","mai","juin",
"juillet","août","septembre","octobre","novembre","décembre"],
dayNamesMin: ["Di","Lu","Ma","Me","Je","Ve","Sa"],
firstDay: 1,
dateFormat: "dd/mm/yy",
prevText: "Précédent",
nextText: "Suivant",
closeText: "Fermer",
currentText: "Aujourd'hui",
});
// Include the regional file for built-in locales:
// <script src="jquery-ui/i18n/datepicker-fr.js"></script>Inline Datepicker и события
Примените datepicker к div вместо input, чтобы получить всегда видимый встроенный календарь — отлично для интерфейсов бронирования. onSelect срабатывает при выборе даты, onChangeMonthYear — при переключении месяцев. getDate/setDate работают с объектами Date для программного управления.
<!-- Inline (always visible) calendar -->
<div id="inline-calendar"></div>
<script>
$("#inline-calendar").datepicker({
onSelect: function (dateText, inst) {
console.log("Selected:", dateText);
},
onChangeMonthYear: function (year, month, inst) {
console.log("Viewing:", month + "/" + year);
},
beforeShow: function (input, inst) {
// Fires before the popup opens
return { /* override options */ };
},
onClose: function (dateText, inst) {
// Fires when the popup closes
},
});
// Methods
$("#date").datepicker("setDate", "+7"); // set to a week from today
$("#date").datepicker("getDate"); // returns a Date object
$("#date").datepicker("option", "minDate", new Date(2026, 0, 1));
</script>Dialog
Базовый Dialog
Атрибут title элемента становится заголовком диалога. По умолчанию диалог открывается автоматически и его можно перетаскивать и изменять размер. Элемент перемещается в обёртку jQuery UI с правильным z-index. Закрытие по кнопке X или Escape.
<div id="dialog" title="Basic dialog">
<p>This is a simple dialog window.</p>
</div>
<script>
$(function () {
$("#dialog").dialog();
});
</script>Опции Dialog
autoOpen: false создаёт скрытый диалог, а затем вызывается dialog('open') по необходимости — стандартный паттерн для диалогов по требованию. modal добавляет подложку, блокирующую взаимодействие со страницей. position использует утилиту jQuery UI Position для точного размещения.
$("#dialog").dialog({
autoOpen: false, // don't open on init
modal: true, // dim the page behind
width: 400,
height: "auto",
minWidth: 200,
maxWidth: 600,
resizable: true,
draggable: true,
closeOnEscape: true,
position: { my: "center", at: "center", of: window },
title: "Custom Title", // override the title attr
show: { effect: "fade", duration: 200 },
hide: { effect: "fade", duration: 200 },
});Кнопки Dialog
buttons принимает массив (предпочтительно: иконки и опции на кнопк у) или объект (текст: обработчик). Внутри обработчика 'this' — элемент диалога: вызовите $(this).dialog('close') для закрытия. Кнопки автоматически оформляются и выравниваются вправо.
$("#dialog").dialog({
buttons: [
{
text: "Save",
icon: "ui-icon-disk",
click: function () {
saveForm();
$(this).dialog("close");
},
},
{
text: "Cancel",
click: function () {
$(this).dialog("close");
},
},
],
});
// Shortcut object form (1.12+)
$("#dialog").dialog({
buttons: {
"Save": function () { saveForm(); $(this).dialog("close"); },
"Cancel": function () { $(this).dialog("close"); },
},
});События Dialog
beforeClose — «привратник»: верните false, чтобы оставить диалог открытым (полезно для предупреждений о несохранённых изменениях). close срабатывает после закрытия — правильное место для сброса формы и освобождения ресурсов. События drag/resize повторяют события соответствующих взаимодействий.
$("#dialog").dialog({
beforeClose: function (event, ui) {
// Return false to prevent closing
if (!confirm("Discard changes?")) return false;
},
open: function (event, ui) {
console.log("Dialog opened");
},
close: function (event, ui) {
console.log("Dialog closed");
// Clean up form state
$(this).find("form")[0].reset();
},
focus: function (event, ui) {
// Dialog gained focus
},
dragStart: function (event, ui) { /* dragging started */ },
dragStop: function (event, ui) { /* dragging ended */ },
resizeStart: function (event, ui) { /* resizing started */ },
resizeStop: function (event, ui) { /* resizing ended */ },
});Модальное окно и подтверждение
Создайте диалог из динамически построенного элемента для разовых подтверждений. Модальная подложка блокирует взаимодействие с остальной страницей. Всегда вызывайте destroy и удаляйте элемент в обработчике close, чтобы не копить узлы DOM при закрытии.
function confirmDialog(message, onConfirm) {
$("<div>" + message + "</div>").dialog({
modal: true,
title: "Confirm",
buttons: {
"OK": function () {
onConfirm();
$(this).dialog("close");
},
"Cancel": function () {
$(this).dialog("close");
},
},
close: function () {
$(this).dialog("destroy").remove(); // clean up
},
});
}
// Usage
confirmDialog("Delete this item?", function () {
deleteItem();
});AJAX-содержимое и методы
Используйте событие open, чтобы загрузить содержимое через AJAX и инициализировать вложенные виджеты. Всегда очищайте содержимое при закрытии, чтобы следующее открытие было чистым. moveToTop поднимает диалог выше других по z-index — удобно для стопки диалогов. isOpen — булев геттер для условий.
// Load content from a URL when opening
function openEditDialog(id) {
var $dlg = $("#edit-dialog");
$dlg.dialog({
autoOpen: false,
modal: true,
open: function () {
$dlg.load("/api/edit/" + id, function () {
// Initialize widgets in loaded content
$dlg.find(".datepicker").datepicker();
});
},
close: function () {
$dlg.empty(); // clear for next open
},
});
$dlg.dialog("open");
}
// Common methods
$("#dialog").dialog("open");
$("#dialog").dialog("close");
$("#dialog").dialog("isOpen"); // returns boolean
$("#dialog").dialog("moveToTop"); // bring to front
$("#dialog").dialog("option", "title", "New Title");Progressbar
Базовая Progressbar
Progressbar показывает горизонтальную полосу, заполненную до процента (0-100). Опция value задаёт текущий прогресс. Полоса автоматически оформляется в стиле jQuery UI. Ширина контейнера определяет общую ширину полосы — задавайте её через CSS.
<div id="progress"></div>
<script>
$(function () {
$("#progress").progressbar({ value: 37 });
});
</script>Неопределённый режим
Значение value равное false переводит полосу в неопределённый режим: анимированная полоса показывает, что «что-то происходит», без конкретного процента. Используйте, когда общий объём неизвестен (например, ожидание сервера). Переключитесь обратно на число, когда прогресс станет отслеживаемым.
<div id="progress"></div>
<script>
// Set value to false for an indeterminate (animated) bar
$("#progress").progressbar({ value: false });
// Switch to determinate later when you know the percent
$("#progress").progressbar("option", "value", 50);
</script>Опции Progressbar
Опция 'max' позволяет использовать шкалу не до 100 (например, max: 1000 для загрузки в КБ). value интерпретируется как доля от max. Опция classes (1.12+) позволяет добавить свои классы к конкретным внутренним элементам для тонкой темизации.
$("#progress").progressbar({
value: 0, // 0-100, or false for indeterminate
max: 100, // upper bound (default 100)
disabled: false,
// 1.12+ supports a 'classes' option for theming
classes: {
"ui-progressbar": "highlight",
"ui-progressbar-value": "animated",
},
});Обновление значения
Обновляйте полосу, задавая опцию value. Цикл setInterval имитирует прогресс для загрузок или долгих задач. Для реальных загрузок используйте событие прогресса XHR upload, чтобы обновлять value по числу переданных байт. Всегда очищайте таймер по завершении.
// Simulate a file upload
var progress = 0;
$("#progress").progressbar({ value: 0 });
var timer = setInterval(function () {
progress += 5;
$("#progress").progressbar("option", "value", progress);
if (progress >= 100) {
clearInterval(timer);
console.log("Complete!");
}
}, 200);
// Get current value
var current = $("#progress").progressbar("option", "value");Событие change и свои подписи
change срабатывает при каждом обновлении значения, complete — на 100%; оба полезны для динамических стилей и подписей. Чтобы показать процент, добавьте абсолютно позиционированную подпись поверх полосы. Обновляйте её в обработчике change, чтобы она оставалась синхронной.
$("#progress").progressbar({
value: 0,
change: function () {
var v = $("#progress").progressbar("value");
$("#progress .ui-progressbar-value")
.css("background", v < 50 ? "#fa0" : "#0a0");
},
complete: function () {
$("#progress .ui-progressbar-value").css("background", "#0a0");
$("#progress-label").text("Done!");
},
});
// Overlay a text label
$("#progress").append(
'<div id="progress-label" style="position:absolute;left:50%;top:0;">Loading...</div>'
);Slider
Базовый Slider
Slider создаёт перетаскиваемый ползунок на горизонтальной дорожке. Диапазон по умолчанию 0-100, ползунок начинается с 0. Дорожка полностью в теме. Размеры задавайте через CSS контейнера: width для горизонтального, height для вертикального.
<div id="slider"></div>
<script>
$(function () {
$("#slider").slider();
});
</script>Опции Slider
Используйте 'values' (массив) вместо 'value' для слайдера с двумя ползунками. 'range: true' закрашивает область между ползунками; 'range: min' — от ползунка до минимума; 'range: max' — от ползунка до максимума. 'step' должен делить (max - min) без остатка.
$("#slider").slider({
min: 0,
max: 100,
step: 1, // increment size
value: 50, // single value
values: [25, 75], // two-handle range (omit 'value')
orientation: "horizontal", // or "vertical"
range: true, // or "min", "max"
disabled: false,
animate: "fast", // or ms, or false
});События Slider
slide срабатывает непрерывно при перетаскивании — идеально для живого обновления подписи. Возврат false в slide отменяет движение, что полезно для динамического ограничения значений. change срабатывает после отпускания и при программном изменении опций; используйте его для сохранения значения.
$("#slider").slider({
start: function (event, ui) {
// User started dragging a handle
console.log("Start:", ui.value || ui.values);
},
slide: function (event, ui) {
// Fires continuously during drag
// Return false to prevent the handle from moving
$("#label").text(ui.value);
},
change: function (event, ui) {
// Fires after the handle is released (and on programmatic change)
saveValue(ui.value);
},
stop: function (event, ui) {
// User released the handle
},
});Слайдер диапазона
Слайдер диапазона с двумя ползунками строится установкой range: true и передачей массива values. ui.values[0] — нижний ползунок, ui.values[1] — верхний. Ползунки не могут пересечься. Это классический паттерн для фильтров по цене или диапазону дат.
<div id="range-slider"></div>
<p>Price: $<span id="min-price"></span> - $<span id="max-price"></span></p>
<script>
$("#range-slider").slider({
range: true,
min: 0,
max: 500,
values: [75, 300],
slide: function (event, ui) {
$("#min-price").text(ui.values[0]);
$("#max-price").text(ui.values[1]);
},
});
</script>Вертикальные и ориентация
Вертикальным слайдерам нужна явная высота через CSS: width относится к поперечной оси. Ползунок двигается вверх и вниз вместо влево и вправо. Закраска диапазона работает так же. Полезно для аудиомикшеров, эквалайзеров и любого UI, где вертикальная ориентация естественнее.
// Vertical slider
$("#vertical").slider({
orientation: "vertical",
min: 0,
max: 100,
value: 60,
});
// Vertical range
$("#vertical-range").slider({
orientation: "vertical",
range: true,
min: 0,
max: 100,
values: [20, 80],
});
/* CSS: vertical sliders need a height */
/* #vertical { height: 200px; } */
</script>Методы Slider
Для слайдеров диапазона используйте values() (без аргументов) для получения массива, values(index, value) для установки одного ползунка или values(array) для обоих. Установка опций вроде min/max/step во время работы автоматически перепозиционирует ползунки в новых границах.
// Get or set the value
$("#slider").slider("value");
$("#slider").slider("value", 75);
// Get or set both handles of a range slider
var vals = $("#slider").slider("values"); // [25, 75]
$("#slider").slider("values", 0, 30); // set lower handle
$("#slider").slider("values", [30, 90]); // set both
// Get or set options
$("#slider").slider("option", "max", 200);
$("#slider").slider("option", "disabled", true);
// Disable / enable / destroy
$("#slider").slider("disable");
$("#slider").slider("enable");
$("#slider").slider("destroy");Spinner
Базовый Spinner
Spinner добавляет кнопки вверх и вниз к текстовому полю для числового ввода. Пользователь может вводить напрямую, нажимать кнопки или использовать стрелки. Удержание кнопки ускоряет приращение. Значение поля разбирается как число при каждом изменении.