터치 이벤트 - 레벨 2

비규범적으로 표시된 절 외에도, 이 명세서의 모든 작성 지침, 다이어그램, 예제 및 참고는 비규범적입니다. 이 명세서의 나머지 모든 내용은 규범적입니다.

이 문서에서 핵심 단어 MUST는 여기와 같이 모두 대문자로 표시될 때에 한해 BCP 14 [RFC2119] [RFC8174] 에 설명된 대로 해석됩니다.

이 명세서는 포함된 인터페이스를 구현하는 단일 제품, 즉 해당 인터페이스를 구현하는 사용자 에이전트에 적용되는 적합성 기준을 정의합니다.

WindowProxy는 [HTML5]에 정의되어 있습니다.

이 인터페이스는 터치 이벤트의 개별 터치 포인트를 설명합니다. Touch 객체는 불변이며; 생성된 이후에는 그 속성이 변경되어서는 안 됩니다.

WebIDLenum TouchType {
    "direct",
    "stylus"
};

dictionary TouchInit {
    required long        identifier;
    required EventTarget target;
             double      clientX = 0;
             double      clientY = 0;
             double      screenX = 0;
             double      screenY = 0;
             double      pageX = 0;
             double      pageY = 0;
             float       radiusX = 0;
             float       radiusY = 0;
             float       rotationAngle = 0;
             float       force = 0;
             double      altitudeAngle = 0;
             double      azimuthAngle = 0;
             TouchType   touchType = "direct";
};

[Exposed=Window]
interface Touch {
    constructor(TouchInit touchInitDict);
    readonly        attribute long        identifier;
    readonly        attribute EventTarget target;
    readonly        attribute double      screenX;
    readonly        attribute double      screenY;
    readonly        attribute double      clientX;
    readonly        attribute double      clientY;
    readonly        attribute double      pageX;
    readonly        attribute double      pageY;
    readonly        attribute float       radiusX;
    readonly        attribute float       radiusY;
    readonly        attribute float       rotationAngle;
    readonly        attribute float       force;
    readonly        attribute float       altitudeAngle;
    readonly        attribute float       azimuthAngle;
    readonly        attribute TouchType   touchType;
};

identifier

각 터치 포인트에 대한 식별 번호입니다.

터치 포인트가 활성화되면, 활성 상태인 다른 모든 터치 포인트와 구별되는 identifier가 할당되어야 합니다. 터치 포인트가 활성 상태인 동안, 해당 터치 포인트를 참조하는 모든 이벤트는 동일한 identifier를 할당해야 합니다.

target

터치 포인트가 표면에 처음 놓였을 때 시작된 EventTarget입니다. 이후 해당 터치 포인트가 그 요소의 상호작용 영역 밖으로 이동했더라도 이 값은 처음 시작된 요소를 가리킵니다.

참고

일부 구현은 조잡한 입력(coarse input)의 부정확성을 보정하기 위해 대상 요소를 변경합니다. 따라서 대상 요소가 이벤트 좌표에 직접 있는 요소가 아닐 수도 있습니다. 조잡한 입력을 타깃팅/구분하는 데 사용되는 방법들은 이 명세서의 범위를 벗어납니다.

screenX

화면에 대한 점의 수평 좌표(픽셀 단위)

screenY

화면에 대한 점의 수직 좌표(픽셀 단위)

clientX

스크롤 오프셋을 제외한 뷰포트에 대한 점의 수평 좌표(픽셀 단위)

clientY

스크롤 오프셋을 제외한 뷰포트에 대한 점의 수직 좌표(픽셀 단위)

pageX

스크롤 오프셋을 포함한 뷰포트에 대한 점의 수평 좌표(픽셀 단위)

pageY

스크롤 오프셋을 포함한 뷰포트에 대한 점의 수직 좌표(픽셀 단위)

radiusX

rotationAngle로 표시된 축을 따라 접촉 영역(예: 손가락, 스타일러스)을 가장 가깝게 둘러싸는 타원의 반지름입니다. 단위는 screenX와 동일한 스케일의 CSS 픽셀([CSS-VALUES])입니다. 알려진 값이 없으면 0입니다. 값은 음수가 될 수 없습니다.

radiusY

rotationAngle로 표시된 축에 수직인 축을 따라 접촉 영역(예: 손가락, 스타일러스)을 가장 가깝게 둘러싸는 타원의 반지름입니다. 단위는 screenY와 동일한 스케일의 CSS 픽셀([CSS-VALUES])입니다. 알려진 값이 없으면 0입니다. 값은 음수가 될 수 없습니다.

rotationAngle

radiusX와 radiusY로 기술된 타원이 중심을 기준으로 시계 방향으로 회전한 각도(도 단위); 알려진 값이 없으면 0입니다. 값은 0 이상이고 90 미만이어야 합니다.

만약 radiusX와 radiusY로 기술된 타원이 원형이라면 rotationAngle은 영향을 주지 않습니다. 이 경우 사용자 에이전트는 0을 사용할 수 있으며, 또는 허용 범위 내의 다른 값을 사용할 수 있습니다. (예: 갑작스러운 변화를 피하기 위해 이전 터치 이벤트의 rotationAngle 값을 사용할 수 있습니다.)

force

적용된 압력의 상대 값으로, 범위는 0에서 1까지입니다. 여기서 0은 압력 없음, 1은 터치 장치가 감지할 수 있는 가장 높은 압력을 의미합니다. 알려진 값이 없으면 0입니다. force가 알려진 환경에서는 force 속성이 나타내는 절대 압력과 압력 민감도의 단계는 달라질 수 있습니다.

altitudeAngle

트랜스듀서(예: 펜/스타일러스)의 고도(라디안 단위)로, 범위는 [0,π/2]입니다 — 여기서 0은 표면(X-Y 평면)과 평행함을, π/2는 표면에 수직임을 뜻합니다. 기울기나 각도를 보고하지 않는 하드웨어나 플랫폼의 경우 값은 MUST 0이어야 합니다.

참고

여기서 정의한 altitudeAngle의 기본값은 0입니다. 이는 Pointer Events - Level 3 [POINTEREVENTS] 명세의 altitudeAngle 속성의 기본값(π/2, 트랜스듀서를 표면에 수직으로 위치시키는 값)과 다릅니다.

azimuthAngle

트랜스듀서(예: 펜/스타일러스)의 방위각(라디안 단위)으로, 범위는 [0, 2π]입니다 — 여기서 0은 X 값이 증가하는 방향(정면에서 보았을 때 "3시 방향")을 가리키는 트랜스듀서를 나타내며, 값은 시계 방향으로 증가합니다(π/2는 "6시", π는 "9시", 3π/2는 "12시"). 트랜스듀서가 표면에 완전히 수직인 경우(altitudeAngle이 π/2) 값은 MUST 0이어야 합니다. 기울기나 각도를 보고하지 않는 하드웨어나 플랫폼의 경우 값은 MUST 0이어야 합니다.

touchType

터치를 유발한 장치의 유형입니다.

TouchType

가능한 터치 입력의 서로 다른 유형을 나타내는 열거형입니다.

direct

화면에 직접 닿는 손가락의 터치입니다.

stylus

스타일러스나 펜 장치의 터치입니다.

이 인터페이스는 터치 이벤트를 위한 개별 접촉 지점의 목록을 정의합니다. TouchList 객체는 불변이며; 생성된 이후에는 그 내용이 변경되어서는 안 됩니다.

TouchList 객체의 지원되는 속성 인덱스([WEBIDL])는 목록의 길이보다 1 작은 값에서 0까지의 범위에 있는 숫자들입니다.

WebIDL[Exposed=Window]
interface TouchList {
    readonly        attribute unsigned long length;
    getter Touch? item (unsigned long index);
};

length

목록에 있는 Touch 객체의 수를 반환합니다.

item

목록에서 지정된 인덱스의 Touch를 반환하며, 인덱스가 목록의 길이보다 크거나 같으면 null을 반환합니다.

이 인터페이스는 touchstart, touchend, touchmove, 및 touchcancel 이벤트 유형을 정의합니다. TouchEvent 객체는 불변이며; 생성 및 초기화된 이후에는 그 속성이 변경되어서는 안 됩니다. TouchEvent는 [DOM-LEVEL-3-EVENTS]에 정의된 UIEvent 인터페이스를 상속합니다.

TouchEventInit 딕셔너리는 TouchEvent 인터페이스의 생성자가 신뢰되지 않은(합성된) 터치 이벤트를 생성하기 위한 메커니즘을 제공하는 데 사용됩니다. 이 딕셔너리는 [DOM-LEVEL-3-EVENTS]에 정의된 EventModifierInit 딕셔너리를 상속합니다. 이벤트 생성 절차는 [DOM4]에 정의되어 있습니다. 신뢰되지 않은 터치 이벤트를 발생시키는 방법을 보여주는 샘플 코드는 예제를 참조하세요.

WebIDLdictionary TouchEventInit : EventModifierInit {
            sequence<Touch> touches = [];
            sequence<Touch> targetTouches = [];
            sequence<Touch> changedTouches = [];
};

[Exposed=Window]
interface TouchEvent : UIEvent {
    constructor(DOMString type, optional TouchEventInit eventInitDict = {});
    readonly        attribute TouchList touches;
    readonly        attribute TouchList targetTouches;
    readonly        attribute TouchList changedTouches;
    readonly        attribute boolean   altKey;
    readonly        attribute boolean   metaKey;
    readonly        attribute boolean   ctrlKey;
    readonly        attribute boolean   shiftKey;
    getter boolean getModifierState (DOMString keyArg);
};

touches

현재 표면에 접촉되어 있는 모든 접촉 지점에 대한 Touch 객체의 목록입니다.

targetTouches

현재 표면에 접촉되어 있고 그리고 현재 이벤트의 대상이 되는 요소에서 시작된 모든 접촉 지점에 대한 Touch 객체의 목록입니다.

changedTouches

이 이벤트에 기여한 모든 접촉 지점에 대한 Touch 객체의 목록입니다.

touchstart 이벤트의 경우, 이는 현재 이벤트로 활성화된 터치 포인트들의 목록이어야 합니다. touchmove 이벤트의 경우, 이는 마지막 이벤트 이후로 이동한 터치 포인트들의 목록이어야 합니다. touchend 및 touchcancel 이벤트의 경우, 이는 표면에서 제거된 터치 포인트들의 목록이어야 하며, 제거되기 전의 마지막 알려진 좌표를 포함해야 합니다.

altKey

alt(Alternate) 키 수정자가 활성화되어 있으면 true, 그렇지 않으면 false

metaKey

meta(Meta) 키 수정자가 활성화되어 있으면 true, 그렇지 않으면 false. 일부 플랫폼에서는 이 속성이 이름이 다른 키 수정자에 매핑될 수 있습니다.

ctrlKey

ctrl(Control) 키 수정자가 활성화되어 있으면 true, 그렇지 않으면 false

shiftKey

shift(Shift) 키 수정자가 활성화되어 있으면 true, 그렇지 않으면 false

getModifierState(keyArg)

키 값을 사용하여 수정자의 상태를 조회합니다. 해당 키가 수정자 키이고 그 수정자가 활성화되어 있으면 true, 그렇지 않으면 false를 반환합니다.

<div id="touchable">This element is touchable.</div>

<script>
document.getElementById('touchable').addEventListener('touchstart', function(ev) {

    if (ev.touches.item(0) == ev.targetTouches.item(0))
    {
        /**
         * If the first touch on the surface is also targeting the
         * "touchable" element, the code below should execute.
         * Since targetTouches is a subset of touches which covers the
         * entire surface, TouchEvent.touches >= TouchEvents.targetTouches
         * is always true.
         */

        document.write('Hello Touch Events!');
    }

    if (ev.touches.length == ev.targetTouches.length)
    {
        /**
         * If all of the active touch points are on the "touchable"
         * element, the length properties should be the same.
         */

        document.write('All points are on target element')
    }

    if (ev.touches.length > 1)
    {
        /**
         * On a single touch input device, there can only be one point
         * of contact on the surface, so the following code can only
         * execute when the terminal supports multiple touches.
         */

        document.write('Hello Multiple Touch!');
    }

}, false);
</script>

<div id="touchable">This element is touchable.</div>

<script>
document.getElementById('touchable').addEventListener('touchend', function(ev) {

    /**
     * Example output when three touch points are on the surface,
     * two of them being on the "touchable" element and one point
     * in the "touchable" element is lifted from the surface:
     *
     * Touch points removed: 1
     * Touch points left on element: 1
     * Touch points left on document: 2
     */

    document.write('Touch points removed: ' + ev.changedTouches.length);
    document.write('Touch points left on element: ' + ev.targetTouches.length);
    document.write('Touch points left on document: ' + ev.touches.length);

}, false);
</script>

if (Touch.length < 1 || TouchEvent.length < 1)
  throw "TouchEvent constructors not supported";

var touch = new Touch({
    identifier: 42,
    target: document.body,
    clientX: 200,
    clientY: 200,
    screenX: 300,
    screenY: 300,
    pageX: 200,
    pageY: 200,
    radiusX: 5,
    radiusY: 5
});

var touchEvent = new TouchEvent("touchstart", {
    cancelable: true,
    bubbles: true,
    composed: true,
    touches: [touch],
    targetTouches: [touch],
    changedTouches: [touch]
});

document.body.dispatchEvent(touchEvent);

다음 절은 [WHATWG-DOM]에 정의된 재타겟팅 단계를 설명합니다.

Touch 객체에는 연관된 unadjustedTarget(null 또는 EventTarget)이 있습니다. 달리 명시되지 않는 한 이것은 null입니다.

TouchEvent의 재타겟팅 단계는, touchEvent가 주어졌을 때, 다음 단계를 실행해야 합니다:

1. touchEvent의 touches, targetTouches, 및 changedTouches 멤버에 있는 각 Touch touch에 대해:

   1. 만약 touch의 unadjustedTarget이 null이면, touch의 unadjustedTarget을 touch의 target으로 설정합니다.
   2. touch의 target을, 재타겟팅을 호출하여 touch의 unadjustedTarget을 touchEvent의 target에 대해 재타겟팅한 결과로 설정합니다.

사용자 에이전트에는 불리언 값인 expose legacy touch event APIs가 연결되어 있으며, 그 값은 구현 정의적(implementation-defined)입니다.

다음 절은 이벤트 핸들러 등록을 용이하게 하기 위해 [HTML5]에 정의된 기존 GlobalEventHandlers 믹스인에 대한 확장을 설명합니다. expose legacy touch event APIs가 false인 사용자 에이전트에서는 이 믹스인을 구현해서는 안 됩니다.

WebIDLpartial interface mixin GlobalEventHandlers {
                    attribute EventHandler ontouchstart;
                    attribute EventHandler ontouchend;
                    attribute EventHandler ontouchmove;
                    attribute EventHandler ontouchcancel;
};

ontouchstart

touchstart 이벤트 유형에 대한 이벤트 핸들러 IDL 속성입니다(자세한 내용은 [HTML5] 참조).

ontouchend

touchend 이벤트 유형에 대한 이벤트 핸들러 IDL 속성입니다(자세한 내용은 [HTML5] 참조).

ontouchmove

touchmove 이벤트 유형에 대한 이벤트 핸들러 IDL 속성입니다(자세한 내용은 [HTML5] 참조).

ontouchcancel

touchcancel 이벤트 유형에 대한 이벤트 핸들러 IDL 속성입니다(자세한 내용은 [HTML5] 참조).

사용자 에이전트는 동일한 사용자 입력에 대해 터치 이벤트와(터치용으로 설계되지 않은 웹 콘텐츠와의 호환성을 위해) 마우스 이벤트 [DOM-LEVEL-2-EVENTS]를 모두 디스패치할 수 있습니다. 만약 사용자 에이전트가 단일 사용자 동작에 대해 터치 이벤트와 마우스 이벤트를 모두 디스패치한다면, 그 동작에 대한 어떤 마우스 이벤트보다 먼저 touchstart 이벤트 유형이 디스패치되어야 합니다. 또한 touchstart, touchmove 또는 touchend가 취소된 경우, 사용자 에이전트는 그 취소된 터치 이벤트로 인해 발생할 수 있는 결과적인 어떤 마우스 이벤트도 디스패치해서는 안 됩니다.

만약 사용자 에이전트가 터치 이벤트 시퀀스를 탭 제스처로 해석한다면, 해당 터치 입력과 대응하는 touchend 이벤트 위치에서 mousemove, mousedown, mouseup, 및 click 이벤트(이 순서대로)를 디스패치해야 합니다. 터치 이벤트 처리 중 문서의 내용이 변경된 경우, 사용자 에이전트는 마우스 이벤트를 터치 이벤트와 다른 대상에 디스패치할 수 있습니다.

추가적인 터치 및 마우스 이벤트의 기본 동작과 순서는 다른 곳에 명시된 경우를 제외하고는 구현 정의적입니다.

// conditional "touch OR mouse/keyboard" event binding
// DON'T DO THIS, as it makes interactions touch-exclusive
// on devices that have both touch and mouse/keyboard

if ('ontouchstart' in window) {
  // set up event listeners for touch
  target.addEventListener('touchend', ...);
  ...
} else {
  // set up event listeners for mouse/keyboard
  target.addEventListener('click', ...);
  ...
}

// concurrent "touch AND mouse/keyboard" event binding

// set up event listeners for touch
target.addEventListener('touchend', function(e) {
  // prevent compatibility mouse events and click
  e.preventDefault();
  ...
});
...

// set up event listeners for mouse/keyboard
target.addEventListener('click', ...);
...

활성 터치 포인트

현재 화면에 있으며 사용자 에이전트가 추적하고 있는 터치 포인트입니다. 터치 포인트는 사용자 에이전트가 그 출현을 나타내는 touchstart 이벤트를 처음 디스패치할 때 활성화됩니다. 터치 포인트는 사용자 에이전트가 표면에서 제거되었거나 더 이상 추적되지 않음을 나타내는 touchend 또는 touchcancel 이벤트를 디스패치한 후 활성 상태가 해제됩니다.

터치 포인트

포인터(예: 손가락 또는 스타일러스)가 인터페이스의 대상 표면과 교차하는 좌표 지점입니다. 이는 터치스크린에 손가락이 닿는 경우나 디지털 펜이 종이에 글을 쓸 때에 해당할 수 있습니다.

취소된 이벤트

기본 동작이 preventDefault()로 방지되었거나, 이벤트 핸들러에서 false를 반환했거나, [DOM-LEVEL-3-EVENTS] 및 [HTML5]에서 정의된 다른 수단으로 방지된 이벤트입니다.