UI 이벤트

1. 소개

1.1. 개요

UI Events는 두 가지 주요 목표로 설계되었습니다. 첫 번째 목표는 event 시스템의 설계로, event listeners 등록을 허용하고 이벤트가 트리 구조를 통해 흐르는 방식을 설명합니다. 또한 이 명세서는 사용자 인터페이스 제어 및 문서 변이 알림을 위한 표준 이벤트 모듈과 각 이벤트 모듈에 대한 정의된 컨텍스트 정보를 제공합니다.

UI Events의 두 번째 목표는 기존 브라우저에서 사용되는 현재 이벤트 시스템의 공통 부분 집합을 제공하는 것입니다. 이는 기존 스크립트와 콘텐츠의 상호운용성을 촉진하기 위함입니다. 이 목표가 완전한 하위 호환성으로 달성될 것으로 기대되지는 않으나, 명세서는 가능할 때마다 이를 달성하려고 시도합니다.

1.2. 적합성

이 섹션은 규범적입니다.

이 명세서 내에서 MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, OPTIONAL 등의 핵심 용어는 [RFC2119]에서 설명된 대로 해석되어야 합니다.

이 명세서는 DOM Level 3 Core 명세의 맥락에서 이해되어야 하며 [DOM-Level-3-Core] 및 DOM 구현에 대한 일반적인 고려사항이 적용됩니다. 예를 들어, namespace URIs의 처리는 XML Namespaces에서 논의됩니다. 적합성에 대한 추가 정보는 DOM Level 3 Core 명세의 [DOM-Level-3-Core]에서 확인할 수 있습니다. user agent는 이 명세서에 적합하기 위해 반드시 다른 명세서 전체에 적합할 필요는 없으나, 이 명세서에서 언급된 특정 부분에는 반드시 적합해야 합니다 (예: 적합한 UI Events user agent는 DOMString 데이터 타입을 [WebIDL]에서 정의한 대로 지원해야 하지만, UI Events에 적합하기 위해 [WebIDL]에서 정의된 모든 메서드나 데이터 타입을 지원할 필요는 없습니다).

이 명세서는 다양한 user agent, 명세, 콘텐츠 작성자를 위한 여러 적합성 클래스를 정의합니다:

1.2.1. 웹 브라우저 및 기타 동적 또는 상호작용 user agent

동적 또는 상호작용 user agent는 여기서 브라우저로 언급되며 (웹 브라우저, AT(접근성 기술) 애플리케이션, 기타 유사한 프로그램 포함), 다음을 지원하는 경우 UI Events에 적합합니다:

• [DOM-Level-3-Core]에 정의된 Core 모듈

• 이 명세서에서 정의된 모든 인터페이스와 이벤트의 관련 메서드, 속성, 의미(단, deprecated로 표시된 항목은 제외, 적합한 user agent는 하위 호환성을 위해 deprecated 인터페이스, 이벤트, API를 구현할 수 있으나, 적합성을 위해 반드시 구현해야 하는 것은 아님)

• 플랫폼의 가용성에 따라 [UIEvents-Key] 및 [UIEvents-Code]에서 정의된 key 및 code 값 전체, 그리고

• 이 명세서에 정의된 그 밖의 모든 규범적 요구 사항.

적합한 브라우저는 dispatch 메커니즘을 이용하여 해당 EventTarget 에 대해 정의된 조건이 충족되었을 때 적절한 이벤트를 발생시켜야 합니다.

브라우저는 이 문서에서 명시된 인터페이스 및 관련 event types를 구현하는 경우 UI Events에 명확히 적합합니다.

적합한 브라우저는 스크립팅, 선언적 상호작용 또는 이 명세서에서 설명한 방식으로 이벤트를 감지하고 발생시킬 수 있는 다른 수단을 지원해야 하며, 해당 event type에 대해 명시된 API를 반드시 지원해야 합니다.

모든 적합성 기준을 충족하는 것 이외에도, 적합한 브라우저는 기존 콘텐츠의 하위 호환성을 위해 deprecated로 표시된 기능을 구현할 수 있으나, 이러한 구현은 권장되지 않습니다.

적합한 브라우저는 이 명세서에 없는 기능도 지원할 수 있으나, 인터페이스, 이벤트 또는 이 명세서에서 정의된 기타 기능을 사용할 수 있으며, 구현에 적합한 추가 인터페이스 및 event types도 구현할 수 있습니다. 이러한 기능은 향후 명세에서 표준화될 수 있습니다.

이 명세서의 필수 부분을 모두 준수하지 않은 브라우저는 UI Events에 대한 적합성을 주장해서는 안 됩니다. 이 명세서의 일부만 준수하는 구현은 해당 부분에 대해서만 적합성을 주장할 수 있습니다.

적합한 브라우저는 또한 Web IDL 명세서 [WebIDL]에 따라 이 명세서의 IDL 조각에 대한 적합한 구현이어야 합니다.

1.2.2. 저작 도구

콘텐츠 저작 도구는 event types를 이 명세서에서 정의된 방식과 일관되게 사용하는 콘텐츠를 생성하는 경우 UI Events에 적합합니다.

콘텐츠 저작 도구는 이 명세서에서 deprecated로 표시된 기능을 사용하는 콘텐츠에 대해 UI Events 적합성을 주장해서는 안 됩니다.

적합한 콘텐츠 저작 도구는 콘텐츠 작성자가 해당 콘텐츠 문서에 적합한 모든 event types 및 인터페이스를 사용할 수 있도록 해야 하며, 모든 host languages에 대해 적합한 기능을 제공해야 합니다.

1.2.3. 콘텐츠 작성자 및 콘텐츠

콘텐츠 author는 해당 콘텐츠가 이 명세서에서 정의된 방식과 일관되게 event types를 사용하는 경우 UI Events 적합 콘텐츠를 생성한 것입니다.

콘텐츠 작성자는 이 명세서에서 deprecated로 표시된 기능을 사용하지 않는 것이 좋으며, 대신 이 명세서 및 기타에서 정의된 대체 메커니즘을 사용하는 것이 바람직합니다.

적합한 콘텐츠는 이 명세서에서 설명하는 인터페이스 및 event types의 의미를 반드시 따라야 합니다.

콘텐츠 작성자는 접근성 및 국제화 가이드라인 명세에서 설명하는 모범 사례를 따르는 것이 좋습니다.

1.2.4. 명세 및 호스트 언어

명세 또는 host language는 [DOM]에서 정의된 이벤트 흐름 메커니즘, 인터페이스, 이벤트 또는 기타 기능을 참조하고 사용하며, 이러한 기능을 호환되지 않는 방식으로 확장하지 않는 경우 UI Events에 적합합니다.

명세 또는 host language는 이 문서에서 명시된 인터페이스 및 관련 event types를 참조하고 사용하는 경우 UI Events에 명확히 적합합니다. 적합한 명세는 그 명세에 맞는 추가 인터페이스와 event types를 정의하거나, UI Events 인터페이스 및 event types를 이 명세서에서 정의한 내용을 모순하거나 충돌하지 않는 방식으로 확장할 수 있습니다.

UI Events를 참조하는 명세 또는 host languages는 이 명세서에서 deprecated로 표시된 기능을 사용하거나 권장해서는 안 되며, 해당 기능에 대해 대체 기법(있는 경우)을 사용하거나 권장해야 합니다.

2. 스타일 관례

이 명세서는 제안된 W3C 명세 관례를 따르며, 다음과 같은 추가 사항이 있습니다:

• 키에 인쇄된 키 캡은 ↓, = 또는 Q로 표시됩니다. 이는 사용자의 관점에서 key 및 code 값과 관계없이 키를 참조할 때 사용됩니다. 이벤트가 생성된 KeyboardEvent 값과 상관없습니다.

• 문자를 나타내는 글리프는 다음과 같이 표시됩니다: "𣧂".

• 유니코드 문자 인코딩은 다음과 같이 표시됩니다: U+003d.

• 키 입력에 의해 생성된 키 값의 이름(즉, KeyboardEvent.key 값)은 다음과 같이 표시됩니다: "ArrowDown", "=", "q" 또는 "Q".

• 물리적 키에 해당하는 키 코드의 이름(즉, KeyboardEvent.code 값)은 다음과 같이 표시됩니다: "ArrowDown", "Equal" 또는 "KeyQ".

또한, 이 명세서에서 특정 용어는 특별한 의미로 사용됩니다. 구현(implementation)은 브라우저, 콘텐츠 저작 도구 또는 이 명세서를 구현하는 기타 user agent를 의미하며, 콘텐츠 작성자(content author)는 이 명세서에서 설명된 인터페이스, 메서드, 속성, 이벤트 및 기타 기능을 활용하여 웹 애플리케이션을 작성하는 사람입니다. 사용자는 해당 웹 애플리케이션을 구현(implementation)에서 사용하는 사람을 의미합니다.

마지막으로:

이것은 참고 사항입니다.

이것은 열린 이슈입니다.

이것은 경고입니다.

interface Example {
    // This is an IDL definition.
};

3. 기본 이벤트 인터페이스

[DOM]에서 정의된 기본 이벤트 인터페이스는 UI Events의 근간이 됩니다. 이러한 기본 이벤트 인터페이스는 구현에서 반드시 항상 지원되어야 합니다:

• Event 인터페이스와 다음 상수, 메서드 및 속성:

  • NONE 상수

  • CAPTURING_PHASE 상수

  • AT_TARGET 상수

  • BUBBLING_PHASE 상수

  • type 속성

  • target 속성

  • currentTarget 속성

  • eventPhase 속성

  • bubbles 속성

  • cancelable 속성

  • composed 속성

  • timeStamp 속성

  • defaultPrevented 속성

  • isTrusted 속성

  • stopPropagation() 메서드

  • stopImmediatePropagation() 메서드

  • preventDefault() 메서드

  • initEvent() 메서드

• CustomEvent 인터페이스와 다음 메서드 및 속성:

  • initCustomEvent() 메서드

  • detail 속성

• EventTarget 인터페이스와 다음 메서드들:

  • addEventListener() 메서드

  • removeEventListener() 메서드

  • dispatchEvent() 메서드

• EventListener 인터페이스와 handleEvent() 메서드

• Document 인터페이스의 createEvent() 메서드

이 명세서에서 정의된 이벤트 타입들은 이러한 기본 인터페이스에서 파생되며, 반드시 해당 인터페이스에서 파생된 모든 속성, 메서드, 상수를 상속받아야 합니다.

다음 도표는 이 명세서에서 설명된 인터페이스의 상속 구조를 나타냅니다.

3.1. 이벤트 타입 목록

각 이벤트는 이벤트 타입이라 불리는 타입과 연결되어야 하며, 이벤트 객체의 type 속성으로 제공됩니다. 이벤트 타입은 DOMString 타입이어야 합니다.

DOM 지원 수준이나 디스플레이(예: 화면) 또는 상호작용(예: 마우스, 키보드, 터치스크린, 음성)에 사용되는 장치에 따라 구현에서 이러한 이벤트 타입이 생성될 수 있습니다. [XML] 또는 [HTML5] 애플리케이션에서 사용할 때, 해당 언어의 명세가 이벤트 타입과 관련된 의미와 범위(특히 가능한 이벤트 타겟)를 제한할 수 있습니다. 사용 중인 언어를 정의하는 명세를 참조하여 이러한 제한 사항이나 이 문서에 정의되지 않은 이벤트 타입을 확인하세요.

다음 표는 이 명세서에서 설명된 이벤트 타입의 정보를 요약하여 제공합니다.

이 명세서에서 deprecated로 지정된 이벤트 목록은 문서 마지막의 레거시 이벤트 타입 부록을 참조하세요.

위 표를 해석하는 한 가지 방법: load 이벤트는 해당 이벤트에 대해 Element 노드에 연결된 이벤트 리스너를 캡처 및 타겟 단계에서 트리거합니다. 이 이벤트는 취소할 수 없습니다. 이벤트 리스너가 load 이벤트에 대해 Window, Document, 또는 Element 노드가 아닌 노드에 연결되어 있거나 버블링 단계에만 연결되어 있는 경우, 해당 이벤트 리스너는 트리거되지 않습니다.

위 표를 나열된 이벤트 타입에 대한 결정적인 것으로 해석하지 마세요. 예를 들어, load 이벤트는 다른 명세서(예: XMLHttpRequest)에서도 사용됩니다. 마찬가지로, dispatchEvent() 는 모든 EventTarget을 구현하는 객체의 리스너에 신뢰할 수 없는 이벤트도 발생시킬 수 있습니다.

위에서 설명한 이벤트 타입과 관련된 이벤트 객체에는 추가적인 컨텍스트 정보가 포함되어 있습니다. 자세한 내용은 DOM 인터페이스 설명을 참조하세요.

3.2. 사용자 인터페이스 이벤트

사용자 인터페이스 이벤트 모듈은 사용자 인터페이스 및 문서 조작과 관련된 기본 이벤트 타입을 포함합니다.

3.2.1. UIEvent 인터페이스

DOM Level 2에서 도입됨

UIEvent 인터페이스는 사용자 인터페이스 이벤트와 관련된 특정 컨텍스트 정보를 제공합니다.

UIEvent 인터페이스의 인스턴스를 생성하려면, 선택적으로 UIEventInit 딕셔너리를 UIEvent 생성자에 전달하세요.

새로 정의된 이벤트의 경우, 단순히 사용자 인터페이스와 관련이 있다고 해서 UIEvent 인터페이스를 상속할 필요는 없습니다. UIEventInit 멤버가 해당 이벤트에 유효할 때만 상속하세요.

3.2.1.1. UIEvent

[Exposed=Window]
interface UIEvent : Event {
  constructor(DOMString type, optional UIEventInit eventInitDict = {});
  readonly attribute Window? view;
  readonly attribute long detail;
};

UIEvent . view

view 속성은 이벤트가 생성된 Window를 식별합니다.

이 속성의 초기화되지 않은 값은 null이어야 합니다.

UIEvent . detail

이벤트 타입에 따라 Event 에 대한 상세 정보를 지정합니다.

이 속성의 초기화되지 않은 값은 0이어야 합니다.

3.2.1.2. UIEventInit

dictionary UIEventInit : EventInit {
  Window? view = null;
  long detail = 0;
};

UIEventInit . view

이 이벤트가 디스패치될 글로벌 환경의 Window 객체로 초기화되어야 합니다. 만약 이 이벤트가 요소에 디스패치될 경우, view 속성은 해당 요소의 ownerDocument를 포함하는 Window 객체로 설정되어야 합니다.

UIEventInit . detail

이 값은 애플리케이션마다 다르게 초기화되는 숫자값입니다.

3.2.2. UIEvent 알고리즘

3.2.3. UIEvent 타입

사용자 인터페이스 이벤트 타입들은 아래에 나열되어 있습니다. 이들 중 일부 이벤트는 사용자 인터페이스에서 생성된 경우 UIEvent 인터페이스를 사용하지만, 그렇지 않은 경우 각 이벤트 설명대로 Event 인터페이스를 사용합니다.

3.2.3.1. load

user agent는 DOM 구현이 리소스(예: 문서)와 종속 리소스(이미지, 스타일시트, 스크립트 등)를 모두 로드 완료했을 때 이 이벤트를 반드시 디스패치해야 합니다. 종속 리소스가 로드에 실패하더라도, 해당 리소스를 로드한 객체가 DOM에서 접근 가능하다면 이 이벤트가 발생되는 것을 막아서는 안 됩니다. 이 이벤트 타입이 디스패치될 경우, 구현체는 반드시 Document 노드에서 최소한 이 이벤트를 디스패치해야 합니다.

레거시 이유로, 문서 내부 리소스(예: 이미지)에 대한 load 이벤트는 HTML 구현에서 Window가 전파 경로에 포함되지 않습니다. 자세한 내용은 [HTML5]를 참조하세요.

3.2.3.2. unload

user agent는 DOM 구현이 환경에서 리소스(예: 문서) 또는 종속 리소스(이미지, 스타일시트, 스크립트 등)를 제거할 때 이 이벤트를 반드시 디스패치해야 합니다. 문서는 이 이벤트 타입이 디스패치된 후 반드시 언로드되어야 합니다. 이 이벤트 타입이 디스패치될 경우, 구현체는 반드시 Document 노드에서 최소한 이 이벤트를 디스패치해야 합니다.

3.2.3.3. abort

user agent는 리소스 로딩이 중단된 경우(예: 사용자가 로딩 중에 취소한 경우) 이 이벤트를 반드시 디스패치해야 합니다.

3.2.3.4. error

user agent는 리소스가 로드에 실패했거나, 로드되었지만 해당 의미에 따라 해석할 수 없는 경우(예: 잘못된 이미지, 스크립트 실행 오류, 비정형 XML 등) 이 이벤트를 반드시 디스패치해야 합니다.

3.2.3.5. select

user agent는 사용자가 텍스트를 선택할 때 반드시 이 이벤트를 디스패치해야 합니다. 이 이벤트는 선택이 완료된 다음에 디스패치됩니다.

이 명세서는 선택된 텍스트를 접근할 수 있는 컨텍스트 정보를 제공하지 않습니다. 해당되는 경우 호스트 언어는 사용자가 콘텐츠를 선택하는 방법(국제 언어 관례를 고려), select 이벤트가 언제 디스패치되는지, 콘텐츠 작성자가 선택된 콘텐츠에 어떻게 접근할 수 있는지에 대한 규칙을 정의해야 합니다.

콘텐츠 작성자는 사용자가 선택한 콘텐츠에 접근하기 위해 호스트 언어의 고유 기능(예: HTML Editing APIs의 Document.getSelection() 메서드 [Editing])을 사용할 수 있습니다.

select 이벤트는 모든 요소와 모든 언어에서 항상 사용 가능한 것은 아닙니다. 예를 들어, [HTML5]에서는 select 이벤트가 폼 input 및 textarea 요소에서만 디스패치될 수 있습니다. 구현체는 폼 컨트롤 외부의 텍스트 선택, 이미지 또는 SVG와 같은 마크업 선택 등 적절하다고 판단되는 모든 컨텍스트에서 select 이벤트를 디스패치할 수 있습니다.

3.3. 포커스 이벤트

이 인터페이스와 관련된 이벤트 타입 및 § 3.3.2 포커스 이벤트 순서는 User Agent Accessibility Guidelines 2.0 [UAAG20]의 개념과 지침에 따라 설계되었으며, 특히 포커스 메커니즘과 포커스에 대한 용어집 항목에 주목하였습니다.

3.3.1. FocusEvent 인터페이스

이 명세에서 도입됨

FocusEvent 인터페이스는 포커스 이벤트와 관련된 특정 컨텍스트 정보를 제공합니다.

FocusEvent 인터페이스의 인스턴스를 생성하려면, FocusEvent 생성자에 선택적으로 FocusEventInit 딕셔너리를 전달하세요.

3.3.1.1. FocusEvent

[Exposed=Window]
interface FocusEvent : UIEvent {
  constructor(DOMString type, optional FocusEventInit eventInitDict = {});
  readonly attribute EventTarget? relatedTarget;
};

FocusEvent . relatedTarget

Focus 이벤트와 관련된 두 번째 EventTarget 을 식별할 때 사용되며, 이벤트 타입에 따라 달라집니다.

중첩된 브라우징 컨텍스트에서 탭 이동 시 보안상의 이유로, 관련 EventTarget 은 null이어야 합니다.

이 속성의 초기화되지 않은 값은 null이어야 합니다.

3.3.1.2. FocusEventInit

dictionary FocusEventInit : UIEventInit {
  EventTarget? relatedTarget = null;
};

FocusEventInit . relatedTarget

relatedTarget 은 포커스가 사라지는 요소(focus나 focusin 이벤트의 경우) 또는 포커스가 생기는 요소(blur나 focusout 이벤트의 경우)로 초기화되어야 합니다.

3.3.2. 포커스 이벤트 순서

이 명세에서 정의된 포커스 이벤트는 서로 일정한 순서로 발생합니다. 포커스가 요소 간에 이동할 때(초기에는 포커스된 요소가 없는 것으로 가정), 일반적인 이벤트 순서는 다음과 같습니다:

이 명세서는 focus() 혹은 blur()와 같은 메서드로 상호작용할 때의 포커스 이벤트 동작을 정의하지 않습니다. 해당 메서드가 정의된 관련 명세를 참조하세요.

3.3.3. 문서 포커스와 포커스 컨텍스트

이 이벤트 모듈에는 문서 포커스 변경 알림을 위한 이벤트 타입이 포함되어 있습니다. 이와 관련하여 세 가지 구분되는 포커스 컨텍스트가 있습니다:

• 운영체제 포커스 컨텍스트: 현재 컴퓨터에서 실행 중인 여러 애플리케이션 중 하나에 포커스가 있을 수 있습니다. 이 중 포커스된 애플리케이션이 브라우저일 수 있습니다.

• 브라우저가 포커스를 가진 경우, 사용자는 탭 키 등으로 애플리케이션 포커스 컨텍스트를 브라우저의 다양한 UI 필드(예: 웹사이트 주소 입력창, 검색창 등)로 전환할 수 있습니다. 이 중 하나가 탭에서 보여지고 있는 문서일 수 있습니다.

• 문서 자체가 포커스를 가진 경우, 문서 포커스 컨텍스트는 문서 내부의 포커스 가능한 아무 요소로 설정될 수 있습니다.

이 명세에서 정의된 이벤트 타입은 오직 문서 포커스만 다루며, 이벤트 세부 정보에서 식별된 event target은 반드시 문서나 해당 창의 문서 내의 일부여야 하며, 브라우저나 운영체제의 일부가 되어서는 안 됩니다. 포커스 컨텍스트 간 전환 시에도 마찬가지입니다.

일반적으로 문서에는 항상 포커스된 요소(문서 요소 자체일 수도 있음)와 지속적인 포커스 링이 존재합니다. 포커스 컨텍스트를 전환해도 문서의 현재 포커스된 요소와 포커스 링은 보통 유지됩니다. 예를 들어, 문서에 포커스 가능한 요소가 3개 있고 두 번째 요소에 포커스가 있을 때, 사용자가 운영체제 포커스를 다른 애플리케이션으로 옮겼다가 다시 브라우저로 돌아오면, 두 번째 요소가 여전히 문서 내에서 포커스를 유지하며, 탭 키로 세 번째 요소로 포커스를 이동할 수 있습니다. 호스트 언어는 포커스를 받을 수 있는 요소, 포커스를 받을 수 있는 조건, 포커스를 변경하는 방법, 포커스 변경 순서 등을 구체적으로 정의할 수 있습니다. 예를 들어, 어떤 경우에는 포인터를 이동하여 포커스를 줄 수 있고, 다른 경우에는 마우스 클릭이 필요할 수 있습니다. 일부 요소는 포커스를 받을 수 없으며, 일부는 특정 방법(요소 클릭)으로만 포커스를 받을 수 있고, 탭 키로는 불가능할 수도 있습니다. 문서는 여러 개의 포커스 링을 가질 수 있습니다. 다른 명세에서는 이 명세보다 더 복잡한 포커스 모델(예: 여러 요소가 동시에 현재 포커스를 가질 수 있음)을 정의할 수 있습니다.

3.3.4. 포커스 이벤트 타입

포커스 이벤트 타입은 아래에 나열되어 있습니다.

3.3.4.1. blur

user agent는 event target이 포커스를 잃을 때 반드시 이 이벤트를 디스패치해야 합니다. 이 이벤트 타입이 디스패치되기 전에 해당 요소에서 포커스를 제거해야 합니다. 이 이벤트 타입은 focusout과 유사하지만 버블링되지 않습니다.

3.3.4.2. focus

user agent는 event target이 포커스를 받을 때 반드시 이 이벤트를 디스패치해야 합니다. 이 이벤트 타입이 디스패치되기 전에 해당 요소에 포커스를 부여해야 합니다. 이 이벤트 타입은 focusin과 유사하지만 버블링되지 않습니다.

3.3.4.3. focusin

user agent는 event target이 포커스를 받을 때 반드시 이 이벤트를 디스패치해야 합니다. event target은 포커스를 받은 요소여야 합니다. focus 이벤트가 이 이벤트 타입보다 먼저 발생해야 합니다. 이 이벤트 타입은 focus와 유사하지만 버블링됩니다.

3.3.4.4. focusout

user agent는 event target이 포커스를 잃을 때 반드시 이 이벤트를 디스패치해야 합니다. event target은 포커스를 잃은 요소여야 합니다. blur 이벤트가 이 이벤트 타입보다 먼저 발생해야 합니다. 이 이벤트 타입은 blur와 유사하지만 버블링됩니다.

3.4. 마우스 이벤트

마우스 이벤트 모듈은 [HTML401]의 onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseout 속성에서 기원합니다. 이 이벤트 모듈은 마우스나 트랙볼 같은 포인팅 입력 장치와 함께 사용하도록 특별히 설계되었습니다.

3.4.1. MouseEvent 인터페이스

DOM Level 2에서 도입, 이 명세에서 수정됨

MouseEvent 인터페이스는 마우스 이벤트와 관련된 특정 컨텍스트 정보를 제공합니다.

중첩된 요소의 경우, 마우스 이벤트는 항상 가장 깊이 중첩된 요소를 타겟으로 합니다.

타겟이 된 요소의 상위 요소들은 이벤트 버블링을 통해 그 하위 요소에서 발생한 마우스 이벤트 알림을 받을 수 있습니다.

MouseEvent 인터페이스의 인스턴스를 생성하려면, MouseEvent 생성자에 선택적으로 MouseEventInit 딕셔너리를 전달하세요.

MouseEvent 객체를 initMouseEvent로 초기화할 때, 구현체는 clientX 와 clientY 를 사용하여 다른 좌표(예: DOM Level 0 구현이나 기타 독점적 속성에서 노출하는 target 좌표, pageX 등)를 계산할 수 있습니다.

3.4.1.1. MouseEvent

[Exposed=Window]
interface MouseEvent : UIEvent {
  constructor(DOMString type, optional MouseEventInit eventInitDict = {});
  readonly attribute long screenX;
  readonly attribute long screenY;
  readonly attribute long clientX;
  readonly attribute long clientY;
  readonly attribute long layerX;
  readonly attribute long layerY;

  readonly attribute boolean ctrlKey;
  readonly attribute boolean shiftKey;
  readonly attribute boolean altKey;
  readonly attribute boolean metaKey;

  readonly attribute short button;
  readonly attribute unsigned short buttons;

  readonly attribute EventTarget? relatedTarget;

  boolean getModifierState(DOMString keyArg);
};

screenX, 타입 long, readonly

이벤트가 발생한 스크린 좌표 원점 기준의 수평 좌표입니다.

이 속성의 초기화되지 않은 값은 0이어야 합니다.

screenY, 타입 long, readonly

이벤트가 발생한 스크린 좌표 원점 기준의 수직 좌표입니다.

이 속성의 초기화되지 않은 값은 0이어야 합니다.

clientX, 타입 long, readonly

이벤트가 발생한 뷰포트 기준의 수평 좌표입니다.

이 속성의 초기화되지 않은 값은 0이어야 합니다.

clientY, 타입 long, readonly

이벤트가 발생한 뷰포트 기준의 수직 좌표입니다.

이 속성의 초기화되지 않은 값은 0이어야 합니다.

layerX, 타입 long, readonly

가장 가까운 조상 요소(예: 스태킹 컨텍스트, 포지셔닝된 박스, 스태킹 컨텍스트 페인팅 시 포지셔닝 단계에서 페인팅하는 요소) 기준의 수평 오프셋입니다.

이 속성의 초기화되지 않은 값은 0이어야 합니다.

layerY, 타입 long, readonly

가장 가까운 조상 요소(예: 스태킹 컨텍스트, 포지셔닝된 박스, 스태킹 컨텍스트 페인팅 시 포지셔닝 단계에서 페인팅하는 요소) 기준의 수직 오프셋입니다.

이 속성의 초기화되지 않은 값은 0이어야 합니다.

ctrlKey, 타입 boolean, readonly

KeyboardEvent의 ctrlKey 속성을 참고하세요.

이 속성의 초기화되지 않은 값은 false이어야 합니다.

shiftKey, 타입 boolean, readonly

KeyboardEvent의 shiftKey 속성을 참고하세요.

이 속성의 초기화되지 않은 값은 false이어야 합니다.

altKey, 타입 boolean, readonly

KeyboardEvent의 altKey 속성을 참고하세요.

이 속성의 초기화되지 않은 값은 false이어야 합니다.

metaKey, 타입 boolean, readonly

KeyboardEvent의 metaKey 속성을 참고하세요.

이 속성의 초기화되지 않은 값은 false이어야 합니다.

button, 타입 short, readonly

마우스 버튼의 눌림이나 해제에 의해 발생하는 마우스 이벤트 동안 button 은 어떤 포인터 장치의 버튼이 상태가 변경되었는지 나타내는 데 사용되어야 합니다.

button 속성의 값은 다음과 같아야 합니다:

• 0: 장치의 기본 버튼(일반적으로 왼쪽 버튼 또는 단일 버튼 장치의 유일한 버튼, UI 컨트롤 활성화 또는 텍스트 선택에 사용) 또는 초기화되지 않은 값

• 1: 보조 버튼(일반적으로 가운데 버튼, 종종 마우스 휠과 함께)

• 2: 보조 버튼(일반적으로 오른쪽 버튼, 컨텍스트 메뉴 표시에 사용)

• 3: X1(뒤로) 버튼

• 4: X2(앞으로) 버튼

일부 포인팅 장치는 더 많은 버튼 상태를 제공하거나 시뮬레이션하며, 2보다 큰 값 또는 0보다 작은 값이 해당 버튼을 나타내는 데 사용될 수 있습니다.

button 값은 마우스 버튼의 눌림/해제에 의해 발생하지 않은 이벤트에서는 갱신되지 않습니다. 이런 경우 0 값을 왼쪽 버튼으로 해석하지 말고 초기화되지 않은 값으로 해석해야 합니다.

mousedown 및 mouseup과 같은 이벤트의 기본 동작은 사용 중인 특정 마우스 버튼에 따라 달라집니다.

이 속성의 초기화되지 않은 값은 0이어야 합니다.

buttons, 타입 unsigned short, readonly

모든 마우스 이벤트 동안 buttons 는 현재 눌린 마우스 버튼 조합을 비트마스크로 나타내는 데 사용되어야 합니다.

buttons 속성의 값과 button 속성의 값은 매우 다릅니다. button 값은 mousedown / mouseup 이벤트 핸들러에서 유효하며, buttons 속성은 신뢰된 MouseEvent 객체가 디스패치되는 동안 마우스 버튼의 상태를 반영합니다(현재 활성 버튼 없음(0)도 나타낼 수 있음).

buttons 속성의 값은 다음과 같아야 합니다:

• 0: 현재 활성 버튼 없음

• 1: 장치의 기본 버튼(일반적으로 왼쪽 버튼 또는 단일 버튼 장치의 유일한 버튼, UI 컨트롤 활성화 또는 텍스트 선택에 사용)

• 2: 보조 버튼(일반적으로 오른쪽 버튼, 컨텍스트 메뉴 표시에 사용, 있을 경우)

• 4: 보조 버튼(일반적으로 가운데 버튼, 종종 마우스 휠과 함께)

일부 포인팅 장치는 더 많은 버튼을 제공하거나 시뮬레이션하며, 각 버튼마다 값은 2배씩 증가해야 합니다(8, 16, 32, ... 와 같이 이진수 시리즈).

버튼 값의 합은 항상 고유한 숫자이므로, 콘텐츠 작성자는 비트 연산으로 현재 몇 개의 버튼이 눌려 있는지와 어떤 버튼이 눌려 있는지 임의의 개수의 마우스 버튼에 대해 판별할 수 있습니다. 예를 들어, 3은 왼쪽과 오른쪽 버튼이 동시에 눌려 있음을, 5는 왼쪽과 가운데 버튼이 동시에 눌려 있음을 나타냅니다.

mousedown 및 mouseup과 같은 이벤트의 기본 동작은 사용 중인 특정 마우스 버튼에 따라 달라집니다.

이 속성의 초기화되지 않은 값은 0이어야 합니다.

relatedTarget, 타입 EventTarget, readonly, nullable

UI 이벤트와 관련된 두 번째 EventTarget 을 식별할 때 사용됩니다. 이벤트 타입에 따라 달라집니다.

이 속성의 초기화되지 않은 값은 null이어야 합니다.

getModifierState(keyArg)

이 명세에서 도입됨

키 값으로 modifier의 상태를 질의합니다.

modifier 키이고 modifier가 활성화된 경우 true를, 그렇지 않으면 false를 반환합니다.

DOMString keyArg

KeyboardEvent의 getModifierState() 메서드의 해당 파라미터 설명을 참고하세요.

3.4.1.2. MouseEventInit

dictionary MouseEventInit : EventModifierInit {
  long screenX = 0;
  long screenY = 0;
  long clientX = 0;
  long clientY = 0;

  short button = 0;
  unsigned short buttons = 0;
  EventTarget? relatedTarget = null;
};

screenX, 타입 long, 기본값 0

screenX 속성을 MouseEvent 객체의 마우스 포인터가 사용자의 화면에서 원하는 수평 상대 위치로 초기화합니다.

이벤트 객체를 지정한 마우스 위치로 초기화해도 사용자의 마우스 포인터가 그 위치로 이동되어서는 안 됩니다.

screenY, 타입 long, 기본값 0

screenY 속성을 MouseEvent 객체의 마우스 포인터가 사용자의 화면에서 원하는 수직 상대 위치로 초기화합니다.

이벤트 객체를 지정한 마우스 위치로 초기화해도 사용자의 마우스 포인터가 그 위치로 이동되어서는 안 됩니다.

clientX, 타입 long, 기본값 0

clientX 속성을 MouseEvent 객체의 마우스 포인터가 사용자의 브라우저 클라이언트 창 기준으로 원하는 수평 위치로 초기화합니다.

이벤트 객체를 지정한 마우스 위치로 초기화해도 사용자의 마우스 포인터가 그 위치로 이동되어서는 안 됩니다.

clientY, 타입 long, 기본값 0

clientY 속성을 MouseEvent 객체의 마우스 포인터가 사용자의 브라우저 클라이언트 창 기준으로 원하는 수직 위치로 초기화합니다.

이벤트 객체를 지정한 마우스 위치로 초기화해도 사용자의 마우스 포인터가 그 위치로 이동되어서는 안 됩니다.

button, 타입 short, 기본값 0

button 속성을 MouseEvent 객체의 마우스 버튼 상태를 나타내는 숫자로 초기화합니다.

값 0은 주 마우스 버튼, 1은 보조/가운데 마우스 버튼, 2는 오른쪽 마우스 버튼을 나타냅니다. 2보다 큰 숫자도 사용될 수 있지만, 이 문서에서는 명시되지 않습니다.

buttons, 타입 unsigned short, 기본값 0

buttons 속성을 MouseEvent 객체의 하나 이상의 마우스 버튼이 활성 상태임을 나타내는 숫자로 초기화합니다.

buttons 속성은 비트필드입니다. 마스크 값 1을 비트필드 값에 적용했을 때 true라면 주 마우스 버튼이 눌려 있는 것이고, 마스크 값 2가 true이면 오른쪽 마우스 버튼이 눌려 있는 것이며, 마스크 값 4가 true이면 보조/가운데 버튼이 눌려 있는 것입니다.

JavaScript에서 buttons 속성을 오른쪽(2)과 가운데(4) 버튼이 동시에 눌린 것처럼 초기화하려면, buttons 값을 다음과 같이 할당할 수 있습니다:
{ buttons: 2 | 4 }
또는:
{ buttons: 6 }

relatedTarget, 타입 EventTarget, nullable, 기본값 null

relatedTarget은 마우스 포인터가 막 벗어난 요소(mouseover 또는 mouseenter 이벤트의 경우) 또는 마우스 포인터가 막 진입하는 요소(mouseout, mouseleave, focusout 이벤트의 경우)로 초기화되어야 합니다. 다른 이벤트인 경우 이 값은 할당하지 않아도 되며 기본값은 null입니다.

구현체는 마우스 이벤트를 생성할 때 현재 클릭 횟수를 반드시 유지해야 합니다. 이는 특정 시간 내에 포인팅 장치 버튼이 연속으로 클릭된 횟수를 나타내는 0 이상의 정수여야 합니다. 클릭 횟수 리셋 딜레이는 환경 설정에 따라 다릅니다.

3.4.2. 이벤트 수정자 초기화자

MouseEvent 와 KeyboardEvent 인터페이스는 키보드 수정자 속성 집합을 공유하며, 추가 수정자 상태를 가져오는 메커니즘을 지원합니다. 다음 딕셔너리는 MouseEvent 및 KeyboardEvent 인터페이스의 키보드 수정자 속성을 초기화하고, getModifierState() 를 통해 질의되는 추가 수정자 상태도 초기화할 수 있게 해줍니다. 이 딕셔너리를 사용한 이벤트 생성 단계는 MouseEvent 생성자 섹션에 정의되어 있습니다.

dictionary EventModifierInit : UIEventInit {
  boolean ctrlKey = false;
  boolean shiftKey = false;
  boolean altKey = false;
  boolean metaKey = false;

  boolean modifierAltGraph = false;
  boolean modifierCapsLock = false;
  boolean modifierFn = false;
  boolean modifierFnLock = false;
  boolean modifierHyper = false;
  boolean modifierNumLock = false;
  boolean modifierScrollLock = false;
  boolean modifierSuper = false;
  boolean modifierSymbol = false;
  boolean modifierSymbolLock = false;
};

ctrlKey, 타입 boolean, 기본값 false

ctrlKey 속성을 MouseEvent 또는 KeyboardEvent 객체에 Control 키 수정자가 활성 상태일 때 true, 그렇지 않으면 false로 초기화합니다.

true인 경우, 구현체는 이벤트 객체의 키 수정자 상태도 getModifierState() 또는 getModifierState() 에 Control을 파라미터로 넘겼을 때 true를 반환하도록 초기화해야 합니다.

shiftKey, 타입 boolean, 기본값 false

shiftKey 속성을 MouseEvent 또는 KeyboardEvent 객체에 Shift 키 수정자가 활성 상태일 때 true, 그렇지 않으면 false로 초기화합니다.

true인 경우, 구현체는 이벤트 객체의 키 수정자 상태도 getModifierState() 또는 getModifierState() 에 Shift를 파라미터로 넘겼을 때 true를 반환하도록 초기화해야 합니다.

altKey, 타입 boolean, 기본값 false

altKey 속성을 MouseEvent 또는 KeyboardEvent 객체에 Alt(대체) 또는 Option 키 수정자가 활성 상태일 때 true, 그렇지 않으면 false로 초기화합니다.

true인 경우, 구현체는 이벤트 객체의 키 수정자 상태도 getModifierState() 또는 getModifierState() 에 Alt를 파라미터로 넘겼을 때 true를 반환하도록 초기화해야 합니다.

metaKey, 타입 boolean, 기본값 false

metaKey 속성을 MouseEvent 또는 KeyboardEvent 객체에 Meta 키 수정자가 활성 상태일 때 true, 그렇지 않으면 false로 초기화합니다.

true인 경우, 구현체는 이벤트 객체의 키 수정자 상태도 getModifierState() 또는 getModifierState() 에 Meta를 파라미터로 넘겼을 때 true를 반환하도록 초기화해야 합니다.

modifierAltGraph, 타입 boolean, 기본값 false

이벤트 객체의 키 수정자 상태를 getModifierState() 또는 getModifierState() 에 AltGraph를 파라미터로 넘겼을 때 true를 반환하도록 초기화합니다.

modifierCapsLock, 타입 boolean, 기본값 false

이벤트 객체의 키 수정자 상태를 getModifierState() 또는 getModifierState() 에 CapsLock를 파라미터로 넘겼을 때 true를 반환하도록 초기화합니다.

modifierFn, 타입 boolean, 기본값 false

이벤트 객체의 키 수정자 상태를 getModifierState() 또는 getModifierState() 에 Fn를 파라미터로 넘겼을 때 true를 반환하도록 초기화합니다.

modifierFnLock, 타입 boolean, 기본값 false

이벤트 객체의 키 수정자 상태를 getModifierState() 또는 getModifierState() 에 FnLock를 파라미터로 넘겼을 때 true를 반환하도록 초기화합니다.

modifierHyper, 타입 boolean, 기본값 false

이벤트 객체의 키 수정자 상태를 getModifierState() 또는 getModifierState() 에 Hyper를 파라미터로 넘겼을 때 true를 반환하도록 초기화합니다.

modifierNumLock, 타입 boolean, 기본값 false

이벤트 객체의 키 수정자 상태를 getModifierState() 또는 getModifierState() 에 NumLock를 파라미터로 넘겼을 때 true를 반환하도록 초기화합니다.

modifierScrollLock, 타입 boolean, 기본값 false

이벤트 객체의 키 수정자 상태를 getModifierState() 또는 getModifierState() 에 ScrollLock를 파라미터로 넘겼을 때 true를 반환하도록 초기화합니다.

modifierSuper, 타입 boolean, 기본값 false

이벤트 객체의 키 수정자 상태를 getModifierState() 또는 getModifierState() 에 Super를 파라미터로 넘겼을 때 true를 반환하도록 초기화합니다.

modifierSymbol, 타입 boolean, 기본값 false

이벤트 객체의 키 수정자 상태를 getModifierState() 또는 getModifierState() 에 Symbol를 파라미터로 넘겼을 때 true를 반환하도록 초기화합니다.

modifierSymbolLock, 타입 boolean, 기본값 false

이벤트 객체의 키 수정자 상태를 getModifierState() 또는 getModifierState() 에 SymbolLock를 파라미터로 넘겼을 때 true를 반환하도록 초기화합니다.

3.4.2.1. 마우스 이벤트 생성

일반적으로 Event 인터페이스 또는 Event 인터페이스에서 상속된 인터페이스의 생성자가 호출될 때, [DOM]에 설명된 절차를 따라야 합니다. 그러나 MouseEvent 인터페이스는 Event 객체의 키 수정자 내부 상태를 초기화하는 데 사용할 수 있는 추가 딕셔너리 멤버를 제공합니다. 즉, getModifierState() 메서드로 질의되는 내부 상태입니다. 이 섹션은 새로운 MouseEvent 객체를 초기화할 때 DOM4의 절차를 보완하여 이러한 선택적 수정자 상태를 포함합니다.

MouseEvent 또는 아래 알고리즘을 사용하여 이들 객체에서 파생된 객체를 생성할 때, 모든 MouseEvent 및 파생 객체는 내부 키 수정자 상태를 가지며, 키 수정자 이름을 사용해서 Modifier Keys 표([UIEvents-Key] 참조)에 따라 설정 및 조회할 수 있습니다.

다음 단계는 DOM4에서 이벤트를 생성하는 알고리즘을 보완합니다:

• 생성되는 Event 가 MouseEvent 객체 또는 그 파생 객체이고, 생성자에 EventModifierInit 인자가 제공된 경우, 다음 하위 단계를 실행합니다:

  • 각 EventModifierInit 인자에 대해, 딕셔너리 멤버가 "modifier"로 시작한다면 키 수정자 이름을 해당 멤버 이름에서 "modifier" 접두사를 제외한 이름으로 하고, Event 객체의 내부 키 수정자 상태 중 키 수정자 이름과 일치하는 값을 해당 값으로 설정합니다.

3.4.3. MouseEvent 알고리즘

3.4.3.1. 네이티브 OS 요구사항

이 섹션의 알고리즘은 네이티브 플랫폼 OS가 다음을 제공한다고 가정합니다:

• 마우스가 움직일 때의 이벤트(네이티브 마우스 이동 처리로 처리)

• 마우스 버튼이 눌릴 때의 이벤트(네이티브 마우스 다운 처리로 처리)

• 마우스 버튼이 해제될 때의 이벤트(네이티브 마우스 업 처리로 처리)

• 마우스 버튼 누름이 "클릭"으로 해석되어야 할 때를 식별하는 방법(네이티브 마우스 클릭 처리로 처리)

  • 예를 들어, 플래그나 별도의 이벤트로

  • 별도의 "클릭" 이벤트가 발생하는 경우, 네이티브 OS는 해당 "마우스 업" 이벤트 바로 뒤에, 그 사이에 다른 마우스 관련 이벤트 없이 "클릭" 이벤트를 발생시켜야 함

• 마우스 클릭이 "더블 클릭"인지 식별할 방법(네이티브 마우스 더블 클릭 처리로 처리)

이러한 이벤트에 대해 OS는 다음 정보를 제공할 수 있습니다:

• 네이티브 OS 데스크톱 기준 x, y 마우스 좌표

• UA의 윈도우 뷰포트 기준 x, y 마우스 좌표

• 현재 누르고 있는 키보드 수정자

3.4.3.2. MouseEvent의 전역 상태

3.4.3.2.1. User Agent 수준 상태

UA는 전체 User Agent에 대해 공유되는 다음 값을 유지해야 합니다.

마우스 버튼의 현재 상태를 추적하는 마우스 버튼 비트마스크가 있습니다.

3.4.3.2.2. Window 수준 상태

UA는 각 Window에 대해 공유되는 다음 값을 유지해야 합니다.

마지막으로 Element 에 마우스 이벤트를 전송한 기록을 담는 마지막 마우스 요소 값(초기값 undefined)이 있습니다.

가장 최근 마우스 이벤트가 전송된 시점의 마지막 마우스 요소의 조상 Element들을 스냅샷으로 담는 마지막 마우스 DOM 경로 값(초기값 빈 값)이 있습니다.

3.4.3.3. MouseEvent의 내부 상태

MouseEvent 는 다양한 수정자 키의 상태를 추적하기 위한 다음 내부 플래그를 가집니다: shift 플래그, control 플래그, alt 플래그, altgraph 플래그, 그리고 meta 플래그. 해당 마우스 이벤트 시점에 해당 수정자 키가 눌린 경우 이 플래그가 설정됩니다.

3.5. 휠 이벤트

휠은 하나 이상의 공간 차원에서 회전할 수 있는 장치이며 포인팅 장치와 연관될 수 있습니다. 좌표계는 환경 구성에 따라 달라집니다.

사용자의 환경은 수직 스크롤을 y축 회전에, 수평 스크롤을 x축 회전에, 그리고 줌을 z축 회전에 연관시키도록 구성될 수 있습니다.

WheelEvent 객체의 deltaX, deltaY, deltaZ 속성은 해당 축을 따라 픽셀, 줄 또는 페이지 단위의 측정값을 나타냅니다. 보고되는 측정값은 환경별 알고리즘에 의해 실제 휠 장치의 회전/이동을 적절한 값과 단위로 변환한 후 제공됩니다.

사용자의 환경 설정에 따라 실제 휠 장치의 회전/이동을 다르게 해석할 수 있습니다. 일반적인 덴트(dented) 마우스 휠의 한 번 움직임은 162픽셀 측정값을 만들 수 있습니다(162는 예시값이며 실제 값은 사용자 에이전트의 현재 화면 크기에 따라 달라집니다). 하지만 사용자는 기본 환경 설정을 변경해 마우스 휠 속도를 높여 이 숫자를 증가시킬 수 있습니다. 더 나아가 일부 마우스 휠 소프트웨어는 가속(휠을 더 빠르게 돌릴수록 각 측정의 delta가 커짐) 또는 서브픽셀 회전 측정을 지원할 수 있습니다. 따라서 작성자는 한 사용자 에이전트에서의 회전 양이 모든 사용자 에이전트에서 동일한 delta 값을 생성한다고 가정할 수 없습니다.

deltaX, deltaY, deltaZ 속성 값의 부호(양수/음수)는 실제 휠 장치가 동일 방향으로 회전/이동하는 동안 여러 번 wheel 이벤트가 발생해도 일관되어야 합니다. 만약 사용자 에이전트가 wheel 이벤트의 기본 동작으로 스크롤을 수행한다면, delta의 부호는 오른손 좌표계에 따라 X, Y, Z축의 양수 방향이 각각 문서의 가장 오른쪽, 가장 아래쪽, 그리고 가장 깊은(사용자와 멀어지는) 방향임을 나타내야 합니다.

개별 사용자 에이전트는(환경 및 하드웨어 구성에 따라) 동일한 휠 물리적 동작을 다르게 해석할 수 있습니다. 예를 들어 트랙패드의 가장자리에서 위에서 아래로 수직 스와이프하면 휠 동작으로 해석되어 페이지를 아래로 스크롤하거나 페이지를 위로 팬(즉, 각각 양수 또는 음수 deltaY 값)할 수 있습니다.

사용자 에이전트는 첫 번째 휠 이벤트가 발생하면 휠 이벤트 트랜잭션을 생성해야 하며, 이후 구현별 시간 내의 모든 휠 이벤트가 동일 요소에 대상으로 지정될 수 있습니다. 휠 이벤트 트랜잭션은 단일 사용자 제스처와 연관된 일련의 휠 이벤트입니다. 휠 이벤트 트랜잭션은 첫 번째 휠 이벤트가 발생한 시점의 최상위 이벤트 대상을 이벤트 대상으로 가져야 합니다.

스크롤 가능한 요소에서 시작된 일련의 휠 이벤트가 자식 요소 위에서 시작된다면, 동일 사용자 제스처의 이후 이벤트는 자식 요소 위에서 발생할 수 있습니다.

3.5.1. 인터페이스 WheelEvent

이 명세서에서 도입됨

WheelEvent 인터페이스는 wheel 이벤트와 연관된 구체적 컨텍스트 정보를 제공합니다.

WheelEvent 인터페이스의 인스턴스를 생성하려면, WheelEvent 생성자에 선택적 WheelEventInit 딕셔너리를 전달하세요.

3.5.1.1. WheelEvent

[Exposed=Window]
interface WheelEvent : MouseEvent {
  constructor(DOMString type, optional WheelEventInit eventInitDict = {});
  // DeltaModeCode
  const unsigned long DOM_DELTA_PIXEL = 0x00;
  const unsigned long DOM_DELTA_LINE  = 0x01;
  const unsigned long DOM_DELTA_PAGE  = 0x02;

  readonly attribute double deltaX;
  readonly attribute double deltaY;
  readonly attribute double deltaZ;
  readonly attribute unsigned long deltaMode;
};

DOM_DELTA_PIXEL

delta의 측정 단위는 반드시 픽셀이어야 합니다. 이는 대부분의 운영체제 및 구현 환경에서 가장 일반적인 경우입니다.

DOM_DELTA_LINE

delta의 측정 단위는 반드시 개별 텍스트 줄이어야 합니다. 이는 많은 폼 컨트롤에서 해당됩니다.

DOM_DELTA_PAGE

delta의 측정 단위는 반드시 페이지이어야 하며, 한 화면 또는 구분된 페이지로 정의될 수 있습니다.

deltaX, 타입 double, 읽기 전용

wheel 이벤트의 기본 동작이 스크롤인 사용자 에이전트에서는, 이 값은 이벤트가 취소되지 않은 경우 x축(픽셀, 줄, 페이지)의 스크롤 양이어야 합니다. 그렇지 않으면 휠 장치의 x축 이동(픽셀, 줄, 페이지)의 구현별 측정값입니다.

이 속성의 초기화되지 않은 값은 0.0이어야 합니다.

deltaY, 타입 double, 읽기 전용

wheel 이벤트의 기본 동작이 스크롤인 사용자 에이전트에서는, 이 값은 이벤트가 취소되지 않은 경우 y축(픽셀, 줄, 페이지)의 스크롤 양이어야 합니다. 그렇지 않으면 휠 장치의 y축 이동(픽셀, 줄, 페이지)의 구현별 측정값입니다.

이 속성의 초기화되지 않은 값은 0.0이어야 합니다.

deltaZ, 타입 double, 읽기 전용

wheel 이벤트의 기본 동작이 스크롤인 사용자 에이전트에서는, 이 값은 이벤트가 취소되지 않은 경우 z축(픽셀, 줄, 페이지)의 스크롤 양이어야 합니다. 그렇지 않으면 휠 장치의 z축 이동(픽셀, 줄, 페이지)의 구현별 측정값입니다.

이 속성의 초기화되지 않은 값은 0.0이어야 합니다.

deltaMode, 타입 unsigned long, 읽기 전용

deltaMode 속성은 delta 값의 측정 단위를 나타냅니다. 기본값은 DOM_DELTA_PIXEL (픽셀)입니다.

이 속성은 반드시 delta 값의 단위를 나타내는 DOM_DELTA 상수 중 하나로 설정되어야 합니다. 정확한 측정 단위는 장치, 운영체제, 애플리케이션 구성에 따라 다릅니다.

이 속성의 초기화되지 않은 값은 0이어야 합니다.

3.5.1.2. WheelEventInit

dictionary WheelEventInit : MouseEventInit {
  double deltaX = 0.0;
  double deltaY = 0.0;
  double deltaZ = 0.0;
  unsigned long deltaMode = 0;
};

deltaX, 타입 double, 기본값 0.0

deltaZ 속성 참조.

deltaY, 타입 double, 기본값 0.0

deltaZ 속성 참조.

deltaZ, 타입 double, 기본값 0.0

deltaZ 속성의 초기화에 사용됩니다. 이 속성(그리고 deltaX, deltaY 속성 포함)은 오른손 좌표계에서 X, Y, Z축이 각각 문서의 가장 오른쪽, 아래쪽, 가장 깊은(사용자와 멀어지는) 방향임을 기준으로 양수 값을 가집니다. 음수 값은 반대 방향입니다.

deltaMode, 타입 unsigned long, 기본값 0

deltaMode 속성을 0, 1, 2 중 하나의 열거값으로 초기화합니다. 각각은 휠의 회전이 스크롤을 야기한 경우 픽셀(DOM_DELTA_PIXEL), 줄(DOM_DELTA_LINE), 페이지(DOM_DELTA_PAGE) 단위의 스크롤 양을 나타냅니다.

3.5.2. 휠 이벤트 유형

3.5.2.1. wheel

사용자 에이전트는 마우스 휠이 어떤 축으로든 회전되었을 때, 또는 동등한 입력장치(마우스볼, 특정 태블릿 또는 터치패드 등)가 그러한 동작을 에뮬레이션한 경우 반드시 이 이벤트를 발생시켜야 합니다. 플랫폼 및 입력 장치에 따라, 대각선 휠 delta는 하나의 wheel 이벤트에 여러 축에 대해 모두 비영(0이 아닌) 값을 제공하거나, 각 축마다 별도의 wheel 이벤트로 전달될 수 있습니다.

일반적으로 wheel 이벤트 유형의 기본 동작은 문서를 지정된 양만큼 스크롤(또는 경우에 따라 줌)하는 것입니다. 이 이벤트가 취소되면 구현체는 문서를 스크롤하거나 줌하지 말아야 하며(또는 이 이벤트 유형에 연관된 기타 구현별 기본 동작 수행 금지),

일부 사용자 에이전트나 입력장치에서는 휠이 빨리 회전될수록 delta 값이 커질 수 있습니다.

3.5.2.2. 휠 이벤트의 취소 가능성

휠 이벤트에서 preventDefault를 호출하면 스크롤을 방지하거나 중단시킬 수 있습니다. 최대 스크롤 성능을 위해, 사용자 에이전트는 스크롤과 연관된 각 휠 이벤트가 취소될지 확인하기 위해 처리될 때까지 기다리지 않을 수 있습니다. 이런 경우 사용자 에이전트는 cancelable 속성이 false인 wheel 이벤트를 생성해야 하며, 이는 preventDefault로 스크롤을 방지하거나 중단할 수 없음을 의미합니다. 그렇지 않은 경우 cancelable은 true입니다.

특히, 사용자 에이전트는 비수동(non-passive) 리스너가 없는 것을 관찰하면 오직 취소 불가 wheel 이벤트만 생성해야 합니다.

3.6. 입력 이벤트

입력 이벤트는 사용자의 직접적인 동작(예: 편집 가능한 영역에서 키보드 입력, 텍스트 삭제 또는 서식 변경 등)으로 인해 DOM이 업데이트될 때(혹은 업데이트 직전) 알림으로 전송됩니다.

3.6.1. 인터페이스 InputEvent

3.6.1.1. InputEvent

DOM Level 3에서 도입됨

[Exposed=Window]
interface InputEvent : UIEvent {
  constructor(DOMString type, optional InputEventInit eventInitDict = {});
  readonly attribute USVString? data;
  readonly attribute boolean isComposing;
  readonly attribute DOMString inputType;
};

data, 타입 USVString, 읽기 전용, nullable

data는 입력 방법에 의해 생성된 문자의 값을 담고 있습니다. 이는 단일 유니코드 문자 또는 비어 있지 않은 유니코드 문자 시퀀스일 수 있습니다 [Unicode]. 문자는 [UAX15]에서 정의된 유니코드 정규화 형식 NFC로 정규화되어야 합니다. 이 속성은 빈 문자열을 포함할 수 있습니다.

이 속성의 초기화되지 않은 값은 null이어야 합니다.

isComposing, 타입 boolean, 읽기 전용

입력 이벤트가 합성 세션의 일부로 발생한 경우(즉, compositionstart 이벤트 이후, 해당 compositionend 이벤트 이전) true입니다.

이 속성의 초기화되지 않은 값은 false여야 합니다.

inputType, 타입 DOMString, 읽기 전용

inputType은 이벤트와 연관된 입력의 종류를 식별하는 문자열을 포함합니다.

이 속성의 올바른 값 목록은 [Input-Events] 명세를 참조하세요.

이 속성의 초기화되지 않은 값은 빈 문자열 ""이어야 합니다.

3.6.1.2. InputEventInit

dictionary InputEventInit : UIEventInit {
  DOMString? data = null;
  boolean isComposing = false;
  DOMString inputType = "";
};

data, 타입 DOMString, nullable, 기본값 null

InputEvent 객체의 data 속성을 초기화합니다.

isComposing, 타입 boolean, 기본값 false

InputEvent 객체의 isComposing 속성을 초기화합니다.

inputType, 타입 DOMString, 기본값 ""

InputEvent 객체의 inputType 속성을 초기화합니다.

3.6.2. 입력 이벤트 순서

이 명세에서 정의된 입력 이벤트는 서로에 대해 반드시 정해진 순서로 발생해야 합니다.

3.6.3. 입력 이벤트 유형

3.6.3.1. beforeinput

사용자 에이전트는 DOM이 곧 업데이트될 때 반드시 이 이벤트를 발생시켜야 합니다.

3.6.3.2. input

사용자 에이전트는 DOM이 업데이트된 직후 반드시 이 이벤트를 발생시켜야 합니다.

3.7. 키보드 이벤트

키보드 이벤트는 장치 의존적입니다. 즉, 입력 장치의 기능과 운영체제에서의 매핑 방식에 따라 달라집니다. 자세한 내용과 키보드 이벤트와 조합 이벤트의 사용 예시 등은 키보드 이벤트 및 키 값을 참고하세요. 문자 생성 장치에 따라 키보드 이벤트가 생성되지 않을 수도 있습니다.

키보드 이벤트는 텍스트 입력을 제공하는 방식 중 하나에 불과합니다. 편집 시나리오에서는 InputEvent를 키보드 이벤트의 대안 또는 보완으로 사용하는 것도 고려하세요.

3.7.1. 인터페이스 KeyboardEvent

이 명세서에서 도입됨

KeyboardEvent 인터페이스는 키보드 장치와 연관된 구체적 컨텍스트 정보를 제공합니다. 각 키보드 이벤트는 키 값을 참조합니다. 키보드 이벤트는 일반적으로 포커스를 가진 요소에 전달됩니다.

KeyboardEvent 인터페이스는 ctrlKey, shiftKey, altKey, metaKey와 같은 일반적인 수정키에 대한 편리한 속성을 제공합니다. 이들 속성은 getModifierState() 메서드에서 각각 Control, Shift, Alt, Meta 값을 사용하는 것과 같습니다.

KeyboardEvent 인터페이스의 인스턴스를 생성하려면, KeyboardEvent 생성자에 선택적 KeyboardEventInit 딕셔너리를 전달하세요.

3.7.1.1. KeyboardEvent

[Exposed=Window]
interface KeyboardEvent : UIEvent {
  constructor(DOMString type, optional KeyboardEventInit eventInitDict = {});
  // KeyLocationCode
  const unsigned long DOM_KEY_LOCATION_STANDARD = 0x00;
  const unsigned long DOM_KEY_LOCATION_LEFT = 0x01;
  const unsigned long DOM_KEY_LOCATION_RIGHT = 0x02;
  const unsigned long DOM_KEY_LOCATION_NUMPAD = 0x03;

  readonly attribute DOMString key;
  readonly attribute DOMString code;
  readonly attribute unsigned long location;

  readonly attribute boolean ctrlKey;
  readonly attribute boolean shiftKey;
  readonly attribute boolean altKey;
  readonly attribute boolean metaKey;

  readonly attribute boolean repeat;
  readonly attribute boolean isComposing;

  boolean getModifierState(DOMString keyArg);
};

DOM_KEY_LOCATION_STANDARD

키 활성화가 왼쪽 또는 오른쪽 키 버전으로 구분되지 않으며(NumLock 키를 제외), 숫자 키패드에서 비롯되지 않았거나(혹은 숫자 키패드에 대응하는 가상 키에서 비롯되지 않음) 합니다.

PC 101키 US 키보드의 Q 키.
PC 101키 US 키보드의 NumLock 키.
키보드 본체에 위치한 1 키.

DOM_KEY_LOCATION_LEFT

키 활성화가 해당 키의 여러 위치 중 왼쪽 위치에서 발생함을 나타냅니다.

PC 101키 US 키보드의 왼쪽 Control 키.

DOM_KEY_LOCATION_RIGHT

키 활성화가 해당 키의 여러 위치 중 오른쪽 위치에서 발생함을 나타냅니다.

PC 101키 US 키보드의 오른쪽 Shift 키.

DOM_KEY_LOCATION_NUMPAD

키 활성화가 숫자 키패드 또는 숫자 키패드에 대응하는 가상 키에서 발생함을 나타냅니다(해당 키에 여러 위치가 있을 때). NumLock 키는 항상 location 값으로 DOM_KEY_LOCATION_STANDARD을 사용해야 합니다.

PC 101키 US 키보드의 숫자 키패드에 위치한 1 키.

key, 타입 DOMString, 읽기 전용

key는 눌린 키에 해당하는 key attribute value를 담습니다.

key 속성은 레거시 keyCode 속성과 관련이 없으며 동일한 값 집합을 가지지 않습니다.

이 속성의 초기화되지 않은 값은 ""(빈 문자열)이어야 합니다.

code, 타입 DOMString, 읽기 전용

code는 눌리고 있는 실제 물리적 키를 식별하는 문자열입니다. 이 값은 현재 키보드 레이아웃이나 수정키 상태에 영향을 받지 않으므로 특정 키는 항상 동일한 값을 반환합니다.

이 속성의 초기화되지 않은 값은 ""(빈 문자열)이어야 합니다.

location, 타입 unsigned long, 읽기 전용

location 속성은 장치에서 키의 논리적 위치를 나타냅니다.

이 속성은 반드시 DOM_KEY_LOCATION 상수 중 하나로 설정되어 키의 장치 내 위치를 나타내야 합니다.

만약 사용자 에이전트가 키를 재매핑할 수 있다면, 재매핑된 키의 location 값은 새로운 키에 적합한 값으로 설정해야 합니다. 예를 들어, "ControlLeft" 키가 "KeyQ" 키로 매핑되면 location 속성은 DOM_KEY_LOCATION_STANDARD이어야 합니다. 반대로 "KeyQ" 키가 Control 키 중 하나로 매핑된다면, location 속성은 DOM_KEY_LOCATION_LEFT 또는 DOM_KEY_LOCATION_RIGHT이어야 합니다.

이 속성의 초기화되지 않은 값은 0입니다.

ctrlKey, 타입 boolean, 읽기 전용

true일 때 Control(컨트롤) 키 수정자가 활성화됨.

이 속성의 초기화되지 않은 값은 false입니다.

shiftKey, 타입 boolean, 읽기 전용

true일 때 Shift(쉬프트) 키 수정자가 활성화됨.

이 속성의 초기화되지 않은 값은 false입니다.

altKey, 타입 boolean, 읽기 전용

true일 때 Alt(대체) 키 수정자("Option" 포함)가 활성화됨.

이 속성의 초기화되지 않은 값은 false입니다.

metaKey, 타입 boolean, 읽기 전용

true일 때 Meta(메타) 키 수정자가 활성화됨.

맥 시스템에서는 "Command"("⌘") 키가 이 수정자로 표현됩니다.

이 속성의 초기화되지 않은 값은 false입니다.

repeat, 타입 boolean, 읽기 전용

true일 때 키가 지속적으로 눌려진 상태임을 나타냅니다. 키를 계속 누르면 keydown, beforeinput, input 이벤트가 이 순서대로 시스템 설정에 따라 반복적으로 발생해야 합니다. 모바일 장치에서 장기 키 누름(long-key-press)이 있다면, repeat 값이 true인 첫 번째 키 이벤트가 장기 키 누름의 신호가 됩니다. 반복을 시작하는 데 필요한 키 누름 시간은 환경에 따라 다릅니다.

이 속성의 초기화되지 않은 값은 false입니다.

isComposing, 타입 boolean, 읽기 전용

키 이벤트가 합성 세션의 일부로 발생한 경우(즉, compositionstart 이벤트 이후, 해당 compositionend 이벤트 이전) true입니다.

이 속성의 초기화되지 않은 값은 false입니다.

getModifierState(keyArg)

키 값으로 수정키의 상태를 질의합니다.

수정키이면서 활성화되어 있으면 true, 그렇지 않으면 false를 반환합니다.

DOMString keyArg

수정키 값입니다. 올바른 수정키는 Modifier Keys table([UIEvents-Key])에서 정의되어 있습니다.

애플리케이션이 오른쪽/왼쪽 수정키를 구분하고 싶다면, 키보드 이벤트와 location을 통해 추론할 수 있습니다.

3.7.1.2. KeyboardEventInit

dictionary KeyboardEventInit : EventModifierInit {
  DOMString key = "";
  DOMString code = "";
  unsigned long location = 0;
  boolean repeat = false;
  boolean isComposing = false;
};

key, 타입 DOMString, 기본값 ""

KeyboardEvent 객체의 key 속성을 키의 의미를 나타내는 유니코드 문자열로 초기화합니다. 이 값은 모든 키보드 수정키(쉬프트 상태 등)를 고려한 최종 효과 값입니다. 만약 키가 출력 가능한 문자가 아니라면, [UIEvents-Key]에 정의된 키 값 중 하나여야 합니다.

code, 타입 DOMString, 기본값 ""

KeyboardEvent 객체의 code 속성을 눌린 키를 나타내는 유니코드 문자열로 초기화합니다. 키보드 레이아웃 등 수정사항은 무시하고 실제 물리적 키를 나타냅니다. 이 값은 [UIEvents-Code]에 정의된 코드 값 중 하나여야 합니다.

location, 타입 unsigned long, 기본값 0

KeyboardEvent 객체의 location 속성을 다음의 위치 상수 중 하나로 초기화합니다:

• DOM_KEY_LOCATION_STANDARD (숫자 값 0)

• DOM_KEY_LOCATION_LEFT (숫자 값 1)

• DOM_KEY_LOCATION_RIGHT (숫자 값 2)

• DOM_KEY_LOCATION_NUMPAD (숫자 값 3)

repeat, 타입 boolean, 기본값 false

KeyboardEvent 객체의 repeat 속성을 초기화합니다. 이 속성은 현재 KeyboardEvent가 하나의 키가 길게 눌려 반복적으로 발생한 이벤트 시퀀스의 일부일 때 true로, 아니면 false로 설정해야 합니다.

isComposing, 타입 boolean, 기본값 false

KeyboardEvent 객체의 isComposing 속성을 초기화합니다. 이 속성은 생성되는 이벤트가 조합 입력 시퀀스의 일부일 때 true, 그렇지 않으면 false로 설정해야 합니다.

기존 콘텐츠와의 호환성을 위해, 소프트웨어 키보드와 같은 가상 키보드는 실제 키가 없더라도 일반적인 키보드 이벤트를 생성해야 합니다.

일부 구현이나 시스템 설정에서는 사용 중인 IME에 의해 일부 키 이벤트 또는 값이 억제될 수 있습니다.

3.7.2. 키보드 이벤트 키 위치

location 속성은 키보드의 서로 다른 물리적 키(예: 왼쪽/오른쪽 Shift 키, 물리적 화살표 키와 숫자패드 화살표 키(NumLock이 꺼진 경우 등))에서 생성되는 key 값을 구분하는 데 사용할 수 있습니다.

아래 표는 키보드에서 위치가 둘 이상인 특수키에 대해 location 속성의 유효 값을 정의합니다:

위 표에 없는 모든 키에 대해서는 location 속성은 항상 DOM_KEY_LOCATION_STANDARD로 설정되어야 합니다.

3.7.3. KeyboardEvent 알고리즘

3.7.3.1. KeyboardEvent의 전역 상태

3.7.3.1.1. User Agent 수준 상태

UA는 전체 User Agent에서 공유되는 다음 값을 유지해야 합니다.

시스템에서 사용 가능한 각 수정키의 현재 상태를 추적하는 키 수정자 상태(초기값은 비어 있음)을 유지해야 합니다.

3.7.4. 키보드 이벤트 순서

이 명세에서 정의된 키보드 이벤트는 특정 키에 대해 반드시 서로 정해진 순서대로 발생합니다:

키가 일정 시간 이상 눌려지면, 다음 이벤트들이 환경에 따라 반복적으로 발생할 수 있습니다:

일반적으로 특정 키와 연관된 기본 동작은 keyup 이벤트가 디스패치되기 전에 완료됩니다. 이로 인해 keyup 이벤트가 약간 지연될 수 있지만(감지할 정도는 아님)

키 이벤트의 이벤트 대상은 현재 키보드 입력을 처리하는 포커스된 요소입니다. 이는 보통 HTML input 요소나 편집 가능한 텍스트 요소이지만, 호스트 언어가 텍스트 이외의 목적으로 키보드 입력을 받을 수 있도록 정의한 요소(예: 단축키, 기타 동작 트리거)일 수 있습니다. 적합한 요소가 포커스되지 않았다면, 이벤트 대상은 가능하면 HTML body 요소, 그렇지 않으면 루트 요소입니다.

이벤트 대상은 키 이벤트마다 달라질 수 있습니다. 예를 들어 Tab 키의 keydown 이벤트와 같은 키 입력에서의 keyup 이벤트는 서로 다른 이벤트 대상을 가질 수 있습니다.

3.7.5. 키보드 이벤트 유형

3.7.5.1. keydown

사용자 에이전트는 키가 눌렸을 때 반드시 이 이벤트를 발생시켜야 합니다. keydown 이벤트 유형은 장치 의존적이며 입력 장치의 기능과 운영체제에서의 매핑 방식에 따라 달라집니다. 이 이벤트 유형은 키 매핑 이후에 반드시 생성되어야 하며, 동일 키에 대한 beforeinput, input, keyup 이벤트보다 먼저 디스패치되어야 합니다.

keydown 이벤트의 기본 동작은 키에 따라 다릅니다:

• 키가 문자와 연관된 경우, 반드시 beforeinput 이벤트 후 input 이벤트를 디스패치해야 합니다. 매크로나 죽은 키 시퀀스 등 여러 문자를 생성하는 키의 경우, 각 문자마다 beforeinput / input 이벤트 세트를 디스패치해야 합니다.

• 키가 텍스트 조합 시스템과 연관된 경우, 반드시 해당 시스템을 실행해야 합니다.

• 키가 Tab 키일 경우, 현재 포커스된 요소(있다면)에서 새롭게 포커스된 요소로 문서 포커스를 이동해야 하며, 자세한 내용은 포커스 이벤트 유형에서 설명합니다.

• 키가 Enter 또는 (Space) 키이고, 현재 포커스가 상태 변경 요소에 있다면, 반드시 click 이벤트와, DOMActivate 이벤트(지원되는 경우)를 디스패치해야 합니다.

이 이벤트가 취소되면, 연관된 이벤트 유형은 디스패치되지 말아야 하며, 연관된 동작도 수행되어서는 안 됩니다.

keydown와 keyup 이벤트는 전통적으로 문자 값을 생성하는 키뿐 아니라 모든 키 감지에 사용됩니다.

3.7.5.2. keyup

사용자 에이전트는 키가 해제될 때 반드시 이 이벤트를 발생시켜야 합니다. keyup 이벤트 유형은 장치 의존적이며 입력 장치의 기능과 운영체제에서의 매핑 방식에 따라 달라집니다. 이 이벤트 유형은 키 매핑 이후에 반드시 생성되어야 하며, 동일 키에 대한 keydown, beforeinput, input 이벤트 이후에 디스패치되어야 합니다.

keydown와 keyup 이벤트는 문자 값을 생성하는 키뿐 아니라 모든 키 감지에 전통적으로 사용됩니다.

3.8. 조합 이벤트

조합 이벤트는 키보드 이벤트와는 보완적이거나 대체적인 방식으로 텍스트를 입력할 수 있게 하여, 키보드에 일반적으로 없는 문자를 사용할 수 있도록 합니다. 예를 들어, 조합 이벤트는 표준 미국 키보드에 없는 악센트를 문자에 추가하거나, 많은 아시아 언어의 한자를 기본 구성 요소나 범주에서 조합하여 만들거나, 모바일 기기 키보드에서 여러 키 조합으로 단어 선택을 하거나, 음성 인식 프로세서를 사용해 음성 명령을 텍스트로 변환하는 데 사용할 수 있습니다. 조합 이벤트와 키보드 이벤트의 조합 사용 예시는 § 4 키보드 이벤트 및 키 값을 참고하세요.

개념적으로, 조합 세션은 하나의 compositionstart 이벤트, 하나 이상의 compositionupdate 이벤트, 그리고 하나의 compositionend 이벤트로 이루어지며, 각 세션 동안 이 이벤트 체인의 각 단계에서는 data 속성의 값이 유지됩니다.

참고: 조합 세션이 활성화된 동안 키보드가 조합 세션의 입력 장치로 사용된다면 키보드 이벤트가 DOM으로 디스패치될 수 있습니다. 관련 이벤트 순서에 대해서는 compositionstart 이벤트 상세와 IME 섹션을 참고하세요.

모든 IME 시스템이나 장치가 DOM에 필요한 데이터를 노출하는 것은 아니므로, 활성 조합 문자열(예: 읽기 창 또는 후보 선택 메뉴 옵션)이 이 인터페이스를 통해 제공되지 않을 수 있으며, 이 경우 선택은 빈 문자열로 표현될 수 있습니다.

3.8.1. 인터페이스 CompositionEvent

현행 표준에서 도입됨

CompositionEvent 인터페이스는 조합 이벤트와 관련된 구체적 컨텍스트 정보를 제공합니다.

CompositionEvent 인터페이스의 인스턴스를 생성하려면, CompositionEvent 생성자에 선택적 CompositionEventInit 딕셔너리를 전달하세요.

3.8.1.1. CompositionEvent

[Exposed=Window]
interface CompositionEvent : UIEvent {
  constructor(DOMString type, optional CompositionEventInit eventInitDict = {});
  readonly attribute USVString data;
};

data, 타입 USVString, 읽기 전용

data는 입력 방법에 의해 생성된 문자의 값을 담고 있습니다. 이는 단일 유니코드 문자 또는 비어 있지 않은 유니코드 문자 시퀀스일 수 있습니다 [Unicode]. 문자는 [UAX15]에서 정의된 유니코드 정규화 형식 NFC로 정규화해야 합니다. 이 속성은 빈 문자열일 수 있습니다.

이 속성의 초기화되지 않은 값은 ""(빈 문자열)이어야 합니다.

3.8.1.2. CompositionEventInit

dictionary CompositionEventInit : UIEventInit {
  DOMString data = "";
};

data, 타입 DOMString, 기본값 ""

IME 조합에 의해 생성된 문자를 CompositionEvent 객체의 data 속성에 초기화합니다.

3.8.2. 조합 이벤트 순서

이 명세에서 정의된 조합 이벤트는 반드시 다음의 순서대로 서로 발생해야 합니다:

3.8.3. 필기 인식 시스템

다음 예시는 펜 태블릿과 같은 필기 인식 시스템에서 text라는 텍스트를 작성할 때의 조합 이벤트 시퀀스를 설명합니다.

3.8.4. 조합 이벤트 취소

keydown 이벤트가 취소되면 해당 keydown에서 발생할 조합 이벤트는 디스패치되지 않아야 합니다:

최초 compositionstart 이벤트가 취소되면 텍스트 조합 세션은 종료되어야 합니다. 세션이 종료되든 아니든 compositionend 이벤트는 반드시 전송되어야 합니다.

3.8.5. 조합 중 키 이벤트

조합 세션 중에는 keydown과 keyup 이벤트가 반드시 전송되어야 하며, 이 이벤트의 isComposing 속성은 true로 설정되어야 합니다.

3.8.6. 조합 중 입력 이벤트

조합 세션 중에는 compositionupdate가 반드시 beforeinput이 전송된 후, input 이벤트가 전송되기 전에 디스패치되어야 합니다.