jQuery события
Событие сообщает программе о действии пользователя или изменении на странице: например, о нажатии кнопки, вводе текста или завершении загрузки. Методы событий jQuery позволяют назначать функции-обработчики, которые выполняются при наступлении события, снимать их и программно вызывать события.
Основной способ подписки —
.on(), снятия обработчика —
.off(). Делегирование через селектор позволяет обрабатывать события потомков, добавленных после подписки.
.one()
назначает обработчик на одно срабатывание каждого указанного типа события у каждого элемента.
Событие и сокращённый метод — разные вещи. Например, событие click используется и сейчас, а форма
.click(handler) устарела: пишите .on("click", handler). Для программного вызова предназначен
.trigger(). Назначение обработчика не воспроизводит действие пользователя.
Примеры используют jQuery 4.0.0. Устаревшие сокращения сохранены для чтения существующего кода и отмечены в таблицах. Готовность DOM и диагностические функции вынесены в отдельную группу ниже.
Назначение и вызов обработчиков
| Метод | Описание |
|---|---|
| .on() | Присоединяет для выбранных элементов функцию обработчика для одного или нескольких событий. |
| .off() | Позволяет удалить обработчик, или обработчики событий, присоединенные методом .on(). |
| .one() | Присоединяет для выбранных элементов функцию обработчика, которая будет выполнена не более одного раза к каждому элементу по каждому типу событий. |
| .trigger() | Вызывает обработчики события у выбранных элементов с имитацией всплытия. В зависимости от события может запустить стандартное действие; это не полная замена реальному действию пользователя. |
| .triggerHandler() | Вызывает обработчики только у первого элемента, без всплытия и стандартного действия браузера. Возвращает результат последнего обработчика, а не коллекцию. |
| $.proxy() Устарело | Принимает функцию и возвращает новую, которая всегда будет иметь определенный контекст выполнения. Устарело с jQuery 3.3. |
События клавиатуры
| Метод | Описание |
|---|---|
| .keydown() Устарело |
Привязывает JavaScript обработчик событий "keydown" (нажатие на любую клавишу клавиатуры),
или запускает это событие на выбранный элемент. Устарело с jQuery 3.3.
|
| .keypress() Устарело |
Сокращение для исторического события ввода символа. Метод устарел с 3.3; для клавиш используйте
keydown/keyup, для изменения значения поля — input.
|
| .keyup() Устарело |
Привязывает JavaScript обработчик событий "keyup" (нажатая клавиша была отпущена), или
запускает это событие на выбранный элемент. Устарело с jQuery 3.3.
|
События мыши
| Метод | Описание |
|---|---|
| .click() Устарело |
Назначает обработчик click или вызывает это событие. Активация возможна мышью, клавиатурой и
другими способами. Сокращение устарело с 3.3; используйте .on("click", handler) или
.trigger("click").
|
| .contextmenu() Устарело |
Назначает обработчик вызова контекстного меню или вызывает событие. Меню может открываться мышью или
клавиатурой. Сокращение устарело с 3.3; используйте .on("contextmenu", handler).
|
| .dblclick() Устарело |
Привязывает JavaScript обработчик событий "dblclick" (двойной клик левой кнопкой мыши),
или запускает это событие на выбранный элемент. Устарело с jQuery 3.3.
|
| .hover() Устарело | Связывает один или два обработчика событий для элемента, которые будут выполнены, когда указатель мыши находится на элементе и при его отведении. Устарело с jQuery 3.3. |
| .mousedown() Устарело |
Привязывает JavaScript обработчик событий "mousedown" (нажатие кнопки мыши на элементе),
или запускает это событие на выбранный элемент. Устарело с jQuery 3.3.
|
| .mouseenter() Устарело |
Привязывает JavaScript обработчик событий "mouseenter" (срабатывает, когда указатель мыши
заходит на элемент), или запускает это событие на выбранный элемент. Устарело с jQuery 3.3.
|
| .mouseleave() Устарело |
Привязывает JavaScript обработчик событий "mouseleave" (срабатывает, когда указатель мыши
выходит из элемента), или запускает это событие на выбранный элемент. Устарело с jQuery 3.3.
|
| .mousemove() Устарело |
Привязывает JavaScript обработчик событий "mousemove" (срабатывает, когда указатель мыши
перемещается внутри элемента), или запускает это событие на выбранный элемент. Устарело с jQuery 3.3.
|
| .mouseout() Устарело |
Привязывает JavaScript обработчик событий "mouseout" (срабатывает, когда указатель мыши
покидает элемент), или запускает это событие на выбранный элемент. Устарело с jQuery 3.3.
|
| .mouseover() Устарело |
Привязывает JavaScript обработчик событий "mouseover" (срабатывает, когда указатель мыши
входит в элемент), или запускает это событие на выбранный элемент. Устарело с jQuery 3.3.
|
| .mouseup() Устарело |
Привязывает JavaScript обработчик событий "mouseup" (срабатывает, когда указатель мыши
находится над элементом и кнопка мыши отпущена), или запускает это событие на выбранный элемент. Устарело с
jQuery 3.3.
|
События браузера
| Метод | Описание |
|---|---|
| .resize() Устарело |
Привязывает JavaScript обработчик событий "resize" (срабатывает при изменении размеров
окна браузера), или запускает это событие на выбранный элемент. Устарело с jQuery 3.3.
|
| .scroll() Устарело |
Привязывает JavaScript обработчик событий "scroll" (срабатывает при прокрутке элементов),
или запускает это событие на выбранный элемент. Устарело с jQuery 3.3.
|
События формы
| Метод | Описание |
|---|---|
| .blur() Устарело |
Привязывает JavaScript обработчик событий "blur" (потеря фокуса элементом), или запускает
это событие на выбранный элемент. Устарело с jQuery 3.3.
|
| .change() Устарело |
Привязывает JavaScript обработчик событий "change" (изменение элемента), или запускает это
событие на выбранный элемент. Метод используется с элементами HTML формы. Устарело с jQuery 3.3.
|
| .focus() Устарело |
Привязывает JavaScript обработчик событий "focus" (получение фокуса элементом), или
запускает это событие на выбранный элемент. Устарело с jQuery 3.3.
|
| .focusin() Устарело |
Привязывает JavaScript обработчик событий "focusin" (получение фокуса элементом, или любым
вложенным элементом), или запускает это событие на выбранный элемент. Метод поддерживает всплывающие события
(event bubbling). Устарело с jQuery 3.3.
|
| .focusout() Устарело |
Привязывает JavaScript обработчик событий "focusout" (потеря фокуса элементом, или любым
вложенным элементом), или запускает это событие на выбранный элемент. Метод поддерживает всплывающие события
(event bubbling). Устарело с jQuery 3.3.
|
| .select() Устарело |
Привязывает JavaScript обработчик событий "select" (срабатывает при выделении текста), или
запускает это событие на выбранный элемент. Метод используется с элементом
<input>
(с текстовым типом type = "text") и элементом
<textarea>. Устарело с jQuery 3.3.
|
| .submit() Устарело |
Привязывает JavaScript обработчик событий "submit" (обработчик отправки формы), или
запускает это событие на выбранный элемент. Устарело с jQuery 3.3.
|
Свойства и методы объекта Event
jQuery скрывает различия реализации между браузерами, определяя свой собственный объект события. Большинство свойств исходного события копируются и нормализуются в новый объект события. Ниже представлены свойства и методы этого объекта:
| Свойство / Метод | Описание |
|---|---|
| event.currentTarget | Определяет текущий элемент DOM, в котором в настоящий момент обрабатывается событие. |
| event.data | Необязательный объект данных, передаваемый методу события, когда текущий обработчик события привязывается. |
| event.delegateTarget | Возвращает элемент, к которому был прикреплен вызванный в данный момент обработчик события. Это свойство будет отличаться от свойства event.currentTarget только в том случае, если обработчик события делегирован, а не на прямую привязан к элементу. |
| event.isDefaultPrevented() |
Метод возвращает логическое значение true, если для этого объекта событий вызывался метод
event.preventDefault()
и false в обратном случае.
|
| event.isImmediatePropagationStopped() |
Метод возвращает логическое значение true, если для этого объекта событий вызывался метод
event.stopImmediatePropagation()
и false в обратном случае.
|
| event.isPropagationStopped() |
Метод возвращает логическое значение true, если для этого объекта событий вызывался метод
event.stopPropagation()
и false в обратном случае.
|
| event.metaKey | Содержит логическое значение, которое указывает на то, была ли нажата, или нет мета клавиша Cmd (Mac) / Windows (Windows), когда событие сработало. |
| event.namespace | Соответствует пользовательскому пространству имён, определенному при срабатывании события (строковое значение). |
| event.pageX | Координата указателя по горизонтали относительно документа. |
| event.pageY | Координата указателя по вертикали относительно документа. |
| event.preventDefault() | Если этот метод вызывается, то действие события по умолчанию не будет срабатывать (отменяет действие события по умолчанию). Событие продолжает распространяться как обычно, только с тем исключением, что событие ничего не делает. |
| event.relatedTarget | Соответствует другому элементу DOM, который участвует в событии, если таковой имеется. |
| event.result |
Содержит последнее значение, возвращаемое обработчиком события, которое было вызвано этим событием (если
значение не было равно undefined).
|
| event.stopImmediatePropagation() | Прекращает дальнейшую передачу текущего события (предотвращает всплытие по дереву DOM) и останавливает цепочку вызова событий для текущего элемента. |
| event.stopPropagation() | Прекращает дальнейшую передачу текущего события (предотвращает всплытие по дереву DOM). |
| event.target | DOM элемент, который инициировал событие. |
| event.timeStamp | Метка времени создания события в миллисекундах. Начало отсчёта зависит от происхождения события; не следует считать её всегда Unix-временем. |
| event.type | Описывает тип события, которое было вызвано. |
| event.which | В зависимости от типа события свойство указывает на определенную клавишу клавиатуры или кнопку мыши, которая была нажата пользователем. |
Готовность DOM и прежние способы подписки
| API | Описание |
|---|---|
.ready()
|
Запускает обработчик после готовности DOM, включая позднюю подписку. Для jQuery 4.0 используйте краткую форму
$(handler).
|
$.ready
|
Объект с методом then, завершающийся при готовности DOM. Его можно передать в
$.when() вместе с другими асинхронными задачами.
Документация.
|
$.holdReady()
Устарело
|
При значении true задерживает выполнение обработчиков готовности DOM, при
false снимает одну установленную задержку. Вызывать нужно до готовности.
Документация. Устарело с jQuery
3.2.
|
.bind()
Устарело
|
Назначает прямые обработчики событий существующим элементам. Устарел с jQuery 3.0; используйте
.on(events, handler).
Документация.
|
.unbind()
Устарело
|
Удаляет прямые обработчики событий. Устарел с jQuery 3.0; используйте .off(events, handler).
Документация.
|
.delegate()
Устарело
|
Назначает делегированные обработчики потомкам через родительский элемент. Устарел с jQuery 3.0; используйте
.on(events, selector, handler).
Документация.
|
.undelegate()
Устарело
|
Удаляет делегированные обработчики. Устарел с jQuery 3.0; используйте
.off(events, selector, handler).
Документация.
|
$.readyException()
|
Обрабатывает исключения из функций готовности DOM, позволяя остальным обработчикам выполниться. |