Книга: JavaScript. Подробное руководство, 6-е издание

Event

Event

информация о стандартных событиях, события IE и jQuery

Когда вызывается обработчик события, ему передается объект Event, чьи свойства содержат дополнительную информацию о событии, такую как тип события и элемент, в котором оно возникло. С помощью методов этого объекта Event можно управлять распространением события. Все современные броузеры реализуют стандартную модель событий, кроме ІE, который в версии 8 и ниже определяет свою собственную, не совместимую с другими броузерами модель. Эта справочная статья описывает стандартные свойства и методы объекта события, альтернативные им свойства и методы, поддерживаемые в ІE, а также охватывает объект события, реализованный в библиотеке jQuery, который имитирует стандартный объект события в IE. Более подробно о событиях рассказывается в главе 17, а о поддержке событий в библиотеке jQuery -в разделе 19.4.

В стандартной модели событий для различных типов событий определены различные типы объектов событий, связанных с ними: по событиям мыши, например, обработчикам передается объект MouseEvent со свойствами, имеющими отношение к мыши, а по событиям клавиатуры передается объект KeyEvent со свойствами, имеющими отношение к клавиатуре. Оба типа, MouseEvent и KeyEvent, наследуют общий суперкласс Event. Однако в моделях событий IE и jQuery по всем событиям, возникающим в объектах Element, передаются объекты единого типа Event. Свойства объекта Event, имеющие отношение к клавиатуре, не будут иметь сколько-нибудь осмысленные значения в обработчике события мыши, но сами свойства будут определены в объекте. Для простоты в этой справочной статье не рассматривается иерархия событий и описываются свойства всех событий, которые могут получить объекты Element (и затем всплыть до объектов Document и Window).

Первоначально практически все события в клиентских сценариях генерировались в элементах документа, поэтому такое смешивание свойств, имеющих отношение к документу, в одном объекте выглядит вполне естественным. Однако HTML5 и связанные с ним стандарты определяют множество новых типов событий, которые генерируются в объектах, не являющихся элементами документа. Для этих типов событий часто определяются собственные объекты событий, и этим объектам посвящены собственные справочные статьи. См. статьи BeforeUnloadEvent, CloseEvent, ErrorEvent, HashChangeEvent, MessageEvent, PageTransitionEvent, PopStateEvent, ProgressEvent и StorageEvent. Большинство из этих типов объектов событий расширяют тип Event. Для других новых типов событий, появившихся в стандарте HTML5, их отдельные типы объектов событий не определяются - обработчикам этих событий передается обычный объект Event. Данная справочная статья описывает этот «обычный» объект Event, плюс некоторые из его подтипов. Свойства в списке ниже, помеченные звездочкой, определяются непосредственно типом Event. Эти свойства наследуются такими объектами событий, как MessageEvent, и используются при работе с простыми событиями, такими как событие «load» объекта Window и событие «playing» объекта MediaElement.

Константы

Следующие константы определяют значения свойства eventPhase. Это свойство и эти константы не поддерживаются моделью событий, реализованной в ІE.

unsigned short CAPTURING.PHASE = 1

Событие посылается перехватывающим обработчикам событий в предках целевого объекта.

unsigned short ATTARGET = 2

Событие посылается обработчикам целевого объекта

unsigned short BUBBLING.PHASE = З

Событие всплывает и посылается обработчикам событий в предках целевого объекта.

Свойства

Следующие свойства определяются стандартной моделью для объекта Event событий, а также для объектов событий, связанных с событиями мыши и клавиатуры. В этот список также включены свойства, определяемые моделями событий ІE и jQuery. Свойства, помеченные звездочкой, определены непосредственно в объекте Event и доступны в любых стандартных объектах событий, независимо от типов событий, с которыми они связаны.

readonly boolean altKey

Указывает, удерживалась ли нажатой клавиша Alt в момент события. Определено для событий мыши и клавиатуры, а также в модели событий IE.

readonly boolean bubbles*

Значение true, если тип события поддерживает «всплытие» (и если не вызван метод stopPropagation()), и false - в противном случае. Отсутствует в модели событий IE.

readonly unsigned short button

Указывает, изменение состояния какой кнопки мыши вызвало событие «mousedown», «mouseup» или «click». Значение 0 соответствует левой кнопке, значение 2 -правой и значение 1 - средней кнопке мыши. Обратите внимание, что значение этого свойства определено только для событий, связанных с изменением состояния кнопки мыши - оно не используется, например, чтобы сообщить, какая кнопка удерживалась при возникновении события «mousemove». Кроме того, это свойство не является битовой маской: оно не позволяет сообщить обработчику об изменении состояния более чем одной кнопки. Наконец, некоторые броузеры генерируют события только для левой кнопки.

Модель событий IE определяет несовместимое свойство button. В этом броузере данное свойство является битовой маской: бит 1 устанавливается, когда была нажата левая кнопка, бит 2 - когда была нажата правая кнопка и бит 4 - когда была нажата средняя кнопка (трехкнопочной) мыши. Библиотека jQuery не имитирует стандартное свойство button в IE, вместо этого она реализует свойство which.

readonly boolean cancelable*

Значение true, если действие, предлагаемое по умолчанию и связанное с событием, может быть отменено с помощью метода preventDefault(), и false - в противном случае. Определено во всех стандартных объектах событий и отсутствует в модели событий IE.

boolean cancelBubble

В модели событий IE, чтобы в обработчике события остановить дальнейшее распространение события вверх по дереву вмещающих объектов, в это свойство нужно записать значение true. В стандартной модели событий для этой цели следует использовать метод stopPropagation().
readonly integer charCode

Для событий «keypress» это свойство содержит код Юникода сгенерированного печатного символа. Данное свойство равно нулю в случае нажатия функциональной клавиши. Оно не используется событиями «keydown» и «кеуир». Преобразовать это число в строку можно с помощью метода String.fromCharCode(). Для событий «keypress» то же самое значение большинство броузеров записывают в свойство keyCode. Однако в Firefox свойство keyCode не определено для события «keypress», поэтому следует использовать свойство charCode. Данное свойство является нестандартным, отсутствует в модели событий IE и не имитируется в модели событий jQuery.

readonly long clientX
readonly long clientY

Координаты X и Y указателя мыши относительно клиентской области или окна броузера. Обратите внимание: эти координаты не учитывают величину прокрутки документа; если событие происходит на верхнем краю окна, свойство clientY будет равно 0 независимо от того, как далеко выполнена прокрутка документа. Эти свойства определены для всех типов событий мыши, и в модели событий IE, и в стандартной модели. См. также раgеХ и раgеУ.

readonly boolean ctrlKey

Указывает, удерживалась ли нажатой клавиша Ctrl в момент события. Определено для событий мыши и клавиатуры, а также в модели событий IE.

readonly EventTarget currentTarget*

Объект Element, Document или Window, обрабатывающий событие в данный момент. Во время фазы перехвата и всплытия значение свойства отличается от target. Отсутствует в модели событий IE, но имитируется в модели событий jQuery.

readonly DataTransfer dataTransfer

Для событий буксировки (drag-and-drop) это свойство определяет объект DataTransfer, полностью координирующий выполнение операции буксировки. События буксировки относятся к событиям мыши; любое событие, имеющее это свойство, также будет иметь свойства clientX, clientY и другие, свойственные событиям мыши. События буксировки «dragstart», «drag» и «dragend» возбуждаются в объекте-источнике; а события «dragenter», «dragover», «dragleave» и «drop» - в объекте-приемнике. Дополнительные сведения об операциях буксировки приводятся в справочной статье DataTransfer и в разделе 17.7.

readonly boolean defaultPrevented*

Значение true, если обработчик этого события вызвал defaultPrevented(), и false -в противном случае. Это новое расширение стандартной модели событий, и потому может быть реализовано не всеми броузерами. (Модель событий jQuery определяет метод isDefaultPrevented(), действующий подобно этому свойству.)

readonly long detail

Сведения о событии (число). Для событий «click», «mousedown» и «mouseup» это свойство показывает количество щелчков: 1 - одинарный щелчок, 2 - двойной щелчок, 3 - тройной щелчок и т. д. В Firefox это свойство используется событиями «DOMMouseScroll», чтобы сообщить величину прокрутки колесика мыши.

readonly unsigned short eventPhase*

Текущая фаза распространения события. Значение свойства - одна из трех констант, описанных выше. Не поддерживается в модели событий ІE.

readonly boolean isTrusted*

Значение true, если это событие было создано и послано броузером, и false - если это искусственное событие, созданное и посланное сценарием на языке JavaScript. Это относительно новое расширение стандартной модели событий, и потому может быть реализовано не всеми броузерами.

readonly Element fromElement

Для событий «mouseover» и «mouseout» в модели IE свойство fromElement содержит ссылку на объект, с которого двигался указатель мыши. В стандартной модели событий следует использовать свойство relatedTarget.

readonly integer keyCode

Виртуальный код нажатой клавиши. Это свойство используется всеми типами событий клавиатуры. Код клавиши может зависеть от броузера, операционной системы, самой клавиатуры. Обычно, если на клавише изображен печатный символ, виртуальный код этой клавиши совпадает с кодом символа. Коды функциональных клавиш, не соответствующих печатным символам, могут существенно отличаться, тем не менее множество наиболее часто используемых кодов клавиш можно увидеть в примере 17.8. Это свойство не было стандартизовано, но определяется всеми броузерами, включая IE.

readonly boolean metaKey

Признак, показывающий, удерживалась ли клавиша Meta, когда произошло событие. Свойство определено для всех типов событий мыши и клавиатуры, а также в модели событий IE.

readonly integer offsetX, offsetY

В модели событий IE эти свойства определяют координаты, в которых возникло событие, в координатной системе элемента-источника события (см. описание свойства srcElement). Стандартная модель событий не имеет эквивалентных свойств.

readonly integer pageX, pageY

Эти нестандартные, но широко поддерживаемые свойства подобны свойствам clientX и clientY, но вместо системы координат окна используют систему координат документа. Эти свойства отсутствуют в модели событий IE, но библиотека jQuery имитирует их во всех броузерах.

readonly EventTarget relatedTarget*

Ссылается на элемент (обычно элемент документа), который имеет отношение к целевому элементу события. Для событий «mouseover» это элемент, который покинул указатель мыши при наведении на целевой элемент. Для событий «mouseout» это элемент, на который наводится указатель мыши, когда он покидает целевой элемент. Это свойство отсутствует в модели событий IE, но оно имитируется в модели событий jQuery. См. также свойства fromElement и toElement, определяемые в модели событий IE.

boolean returnValue

Чтобы в модели событий IE предотвратить выполнение действия, предусмотренного по умолчанию элементом-источником, в котором возникло событие, данное свойство следует установить в значение false. В стандартной модели событий следует использовать метод preventDefault().
readonly long screenX, screenY

Для событий мыши эти свойства определяют координаты указателя мыши относительно верхнего левого угла экрана. Сами по себе эти свойства не используются, но они определены во всех типах событий мыши и поддерживаются обеими моделями событий, стандартной и ІБ.

readonly boolean shiftKey

Указывает, удерживалась ли нажатой клавиша Shift в момент события. Определено для событий мыши и клавиатуры, а также в модели событий IE.

readonly EventTarget srcElement

В модели событий IE это свойство определяет объект, в котором было сгенерировано событие. В стандартной модели событий вместо этого свойства следует использовать свойство target.

readonly EventTarget target*

Целевой объект события, т. е. объект, в котором было сгенерировано событие. (Все объекты, которые могут быть целевыми объектами событий, реализуют методы интерфейса EventTarget.) Это свойство отсутствует в модели событий IE, но имитируется в модели событий jQuery. См. также srcElement.

readonly unsigned long timestamp*

Число, определяющее дату и время, когда произошло событие, или которое можно использовать для определения очередности событий. Многие броузеры возвращают значение времени в секундах, которое можно передать конструктору Date(). Однако в Firefox версии 4 и ниже это свойство содержит количество миллисекунд, прошедших с момента включения компьютера. Это свойство не поддерживается в модели событий ІБ. Модель событий jQuery записывает в это свойство значение в формате, возвращаемом методом Date.getTime().
Element toElement

Для событий «mouseover» и «mouseout» в модели событий IE содержит ссылку на объект, в пределы которого был перемещен указатель мыши. В стандартной модели событий вместо этого свойства следует использовать свойство relatedTarget.

readonly string type*

Тип события, которое представляет данный объект Event. Это имя, под которым был зарегистрирован обработчик события, или имя свойства обработчика события, без префикса «оn». Например, «click», «load» или «submit». Это свойство поддерживаются обеими моделями событий, стандартной и IE.

readonly Window view

Окно (исторически называется «представлением» («view»)), в котором было сгенерировано событие. Это свойство определено для всех стандартных событий пользовательского интерфейса, таких как события мыши и клавиатуры. Не поддерживается в модели событий ІE.

readonly integer wheelDelta

Для событий колесика мыши это свойство определяет величину прокрутки по оси Y. Различные броузеры записывают в это свойство разные значения; подробнее об этом рассказывается в разделе 17.6. Это нестандартное свойство, но оно поддерживается всеми броузерами, включая IE версии 8 и ниже.

readonly integer wheelDeltaX
readonly integer wheelDeltaY

В броузерах, поддерживающих мыши с двумя колесиками, эти события определяют величину прокрутки по осям X и Y. Описание, как следует интерпретировать

эти свойства, приводится в разделе 17.6. Если определено свойство wheelDeltaY, оно будет содержать то же значение, что и свойство wheelDelta.

readonly integer which

Это нестандартное, устаревшее свойство поддерживается всеми броузерами, кроме IE, и имитируется в библиотеке jQuery. Для событий мыши это еще одно свойство, аналогичное свойству button: значение 1 соответствует левой кнопке, 2 -средней кнопке и 3 - правой. Для событий клавиатуры оно получает то же значение, что и свойство keyCode.

Методы

Все следующие методы определены непосредственно в классе Event, поэтому все они доступны в любом стандартном объекте Event.

void initEvent(string type, boolean bubbles, boolean cancelable)

Инициализирует свойства type, bubbles и cancelable объекта Event. Создать новый объект события можно вызовом createEvent() объекта Document, передав ему строку «Event». После инициализации объекта события вызовом этого метода его можно послать любому объекту, поддерживающему интерфейс EventTarget, вызвав метод dispatchEvent() этого объекта. Другие стандартные свойства объекта события (помимо type, bubbles и cancelable) будут инициализированы во время отправки. Если потребуется создать, инициализировать и послать более сложное искусственное событие, необходимо передать методу createEvent() другой аргумент (такой как «MouseEvent») и затем инициализировать полученный объект события с помощью специализированной функции, такой как initMouseEvent() (не описывается в этой книге).

void preventDefault()

Сообщает веб-броузеру, чтобы он не выполнял действие по умолчанию для этого события, если таковое предусмотрено. Если событие относится к категории неотменяемых, вызов этого метода не оказывает никакого влияния. Этот метод отсутствует в модели событий IE, но имитируется библиотекой jQuery. В модели событий IE вместо вызова этого метода следует присваивать значение false свойству returnValue.

void stopImmediatePropagation()

Действует подобно методу stopPropagation(), но, кроме того, предотвращает вызов остальных обработчиков, зарегистрированных в этом же элементе документа. Этот метод является новым расширением стандартной модели событий, и потому может быть реализован не во всех броузерах. Не поддерживается моделью событий IE, но имитируется библиотекой jQuery.

void stopPropagation()

Останавливает распространение события по фазам захвата или всплытия и передачу его целевому элементу. Этот метод не отменяет вызов других обработчиков событий того же узла документа, но предотвращает передачу событий любым другим узлам. Не поддерживается моделью событий IE, но имитируется библиотекой jQuery. В IE вместо вызова метода stopPropagation() следует присваивать значение true свойству cancelBubble.

Предлагаемые к реализации свойства

Свойства, перечисленные ниже, предлагаются проектом спецификации «DOM Level 3 Events». Они должны решить основные проблемы несовместимости между броузерами, но пока (на момент написания этих слов) не реализованы ни в одном из броузеров. Если они будут реализованы совместимым способом, это существенно упростит создание переносимого программного кода для обработки событий ввода текста, нажатий клавиш и событий мыши.

readonly unsigned short buttons

Напоминает свойство button, поддерживаемое в модели событий ІE и описанное выше.

readonly string char

Для событий клавиатуры это свойство хранит строку символов (т. е. может содержать более одного символа), сгенерированную событием.

readonly string data

Для событий «textinput» определяет введенный текст.

readonly unsigned long deltaMode

Для событий колесика мыши это свойство определяет соответствующую интерпретацию свойств deltaX, deltaY и deltaZ. Значением этого свойства может быть одна из констант: DOM_DELTA_PIXEL, DOM_DELTA_LINE, DOM_DELTA_PAGE. Конкретное значение определяется платформой и может зависеть от настроек системы или от факта удерживания нажатыми клавиш-модификаторов во время возникновения события колесика мыши.

readonly long deltaX, deltaY, deltaZ

Для событий колесика мыши эти свойства определяют величину прокрутки по каждой из трех осей.

readonly unsigned long inputMethod

Для событий «textinput» это свойство определяет способ ввода текста. Значением этого свойства может быть одна из констант: DOM_INPUT_METHOD_UNKNOWN, D0M_INPUT_ METHOD_KEYBOARD, DOM_INPUT_METHOD_PASTE, D0M_INPUT_METH0D_DR0P, DOM_INPUT_METHOD_IME, D0M_INPUT_METH0D_0PTI0N, DOM_INPUT_METHOD_HANDWRITING, DOM_INPUT_METHOD_VOICE, D0M_ INPUT_METHOD_MULTIMODAL, DOM_INPUT_METHOD_SCRIPT.

readonly string key

Для событий клавиатуры, генерирующих символы, это свойство получает то же значение, что и свойство char. Для событий клавиатуры, не генерирующих символы, это свойство содержит имя нажатой клавиши (такое как, «Tab» или «Down»).

readonly string locale

Для событий клавиатуры и событий «textinput» это свойство определяет код языка (например, «еn-GB»), идентифицирующий выбранную раскладку клавиатуры, если эта информация доступна.

readonly unsigned long location

Для событий клавиатуры это свойство определяет местоположение нажатой клавиши. Значением этого свойства может быть одна из констант: D0M_KEY_LOCATION_ STANDARD, D0M_KEY_LOATION_LEFT, DOM_KEY_LOCATION_RIGHT, DOM_KEY_LOCATION_NUMPAD, D0M_ KEY_LOCATION_M0BILE, D0M_KEY_LOCATION_JOYSTICK.

readonly boolean repeat

Для событий клавиатуры это свойство будет иметь значение true, если событие вызвано длительным удержанием клавиши в нажатом состоянии, вызвавшем автоповтор ввода.

Предлагаемые к реализации методы

Подобно предлагаемым к реализации свойствам, перечисленным выше, проектом стандарта предлагаются к реализации следующие методы, которые пока не реализованы ни в одном из броузеров.

boolean getModifierState(string modifier)

Для событий мыши и клавиатуры этот метод возвращает true, если в момент возбуждения события удерживалась нажатой указанная клавиша-модификатор modifier, и false - в противном случае. Значением аргумента modifier может быть одна из строк: «Alt», «AltGraph», «CapsLock», «Control», «Fn», «Meta», «NumLock», «Scroll», «Shift», «SymbolLock» и «Win».

Оглавление книги