触摸事件 - 第2级

除了标记为非规范性的章节，本规范中的所有创作指南、图表、示例和注释均为非规范性。规范中的其他内容均为规范性。

本文档中的关键词 必须 应按 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 是触摸点开始的对象，即使触摸点已移动到该元素的交互区域之外。

注意

某些实现会修改目标元素，以纠正粗略输入的不准确性。因此，目标元素不一定是事件坐标直接对应的元素。用于针对粗略输入的目标/去除模糊的技术超出了本规范的范围。

screenX

相对于屏幕的水平坐标，以像素为单位

screenY

相对于屏幕的垂直坐标，以像素为单位

clientX

相对于视口的水平坐标，不包括任何滚动偏移，以像素为单位

clientY

相对于视口的垂直坐标，不包括任何滚动偏移，以像素为单位

pageX

相对于视口的水平坐标，包括任何滚动偏移，以像素为单位

pageY

相对于视口的垂直坐标，包括任何滚动偏移，以像素为单位

radiusX

沿着由 rotationAngle 指示的轴的触摸区域（例如手指、触控笔）所围绕的椭圆的半径，以CSS像素为单位（如 [CSS-VALUES] 中定义），与 screenX 的比例相同；如果未知值则为 0。该值不能为负。

radiusY

沿垂直于由 rotationAngle 指示的轴的触摸区域（例如手指、触控笔）所围绕的椭圆的半径，以CSS像素为单位（如 [CSS-VALUES] 中定义），与 screenY 的比例相同；如果未知值则为 0。该值不能为负。

rotationAngle

椭圆（由 radiusX 和 radiusY 描述）绕其中心顺时针旋转的角度（以度为单位）；如果未知值则为 0。该值必须大于或等于 0 且小于 90。

如果椭圆（由 radiusX 和 radiusY 描述）是圆形的，则 rotationAngle 无效。在这种情况下，用户代理可以使用 0 作为值，或者使用允许范围内的任何其他值。（例如，用户代理可以使用前一个触摸事件的 rotationAngle 值，以避免突然的变化。）

force

施加压力的相对值，范围为 0 到 1，其中 0 表示无压力，1 表示触摸设备能够感知的最大压力；如果未知值则为 0。在知道压力的环境中，由 force 属性表示的绝对压力以及压力的灵敏度级别可能会有所不同。

altitudeAngle

传感器（例如触控笔/笔）的仰角（以弧度为单位），范围为 [0,π/2]——其中0表示与表面平行（X-Y平面），π/2表示垂直于表面。对于不报告倾斜或角度的硬件和平台，值 必须 为0。

注意

altitudeAngle 在此处定义的默认值为 0。这与 指针事件 - 第3级 [POINTEREVENTS] 规范中 altitudeAngle 属性的定义不同，后者的默认值为 π/2，将传感器位置为垂直于表面。

azimuthAngle

传感器（例如触控笔/笔）的方位角（以弧度为单位），范围为 [0, 2π]——其中0表示传感器的盖子指向X-Y平面上X值增大的方向（从正上方看，指向“3点钟”），顺时针旋转时值逐渐增加（π/2为“6点钟”，π为“9点钟”，3π/2为“12点钟”）。当传感器完全垂直于表面时（altitudeAngle 为 π/2），值 必须 为0。对于不报告倾斜或角度的硬件和平台，值 必须 为0。

touchType

触发触摸的设备类型。

TouchType

枚举表示不同类型的可能触摸输入。

direct

来自屏幕上的手指的直接触摸。

stylus

来自触控笔或笔设备的触摸。

该接口定义了触摸事件中多个单个接触点的列表。TouchList 对象是不可变的；一旦创建，其内容不得更改。

TouchList 对象的 支持的属性索引 ([WEBIDL]) 为从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（备用）键修饰符，则为 true；否则为 false

metaKey

如果激活了 meta（Meta）键修饰符，则为 true；否则为 false。在某些平台上，此属性可能映射到一个不同名称的键修饰符。

ctrlKey

如果激活了 ctrl（Control）键修饰符，则为 true；否则为 false

shiftKey

如果激活了 shift（Shift）键修饰符，则为 true；否则为 false

getModifierState(keyArg)

使用键值查询修饰符的状态。如果它是修饰符键并且该修饰符已激活，则返回 true，否则返回 false。

<div id="touchable">此元素是可触摸的。</div>
    
    <script>
    document.getElementById('touchable').addEventListener('touchstart', function(ev) {
    
        if (ev.touches.item(0) == ev.targetTouches.item(0))
        {
            /**
             * 如果表面上的第一个触摸点也定位在
             * "touchable" 元素上，则下面的代码应该执行。
             * 由于 targetTouches 是覆盖整个表面的 touches 的子集，
             * TouchEvent.touches >= TouchEvents.targetTouches
             * 始终为真。
             */
    
            document.write('Hello Touch Events!');
        }
    
        if (ev.touches.length == ev.targetTouches.length)
        {
            /**
             * 如果所有活动的触摸点都在 "touchable" 元素上，
             * 则长度属性应该相同。
             */
    
            document.write('所有触摸点都在目标元素上')
        }
    
        if (ev.touches.length > 1)
        {
            /**
             * 在单触摸输入设备上，表面上只能有一个触摸点，
             * 因此以下代码只能在支持多点触摸的设备上执行。
             */
    
            document.write('你好，多点触摸！');
        }
    
    }, false);
    </script>

<div id="touchable">此元素是可触摸的。</div>
    
    <script>
    document.getElementById('touchable').addEventListener('touchend', function(ev) {
    
        /**
         * 当表面上有三个触摸点时的示例输出，
         * 其中两个在 "touchable" 元素上，
         * 并且一个点从 "touchable" 元素上被移除：
         *
         * 移除的触摸点：1
         * 元素上剩余的触摸点：1
         * 文档上剩余的触摸点：2
         */
    
        document.write('移除的触摸点：' + ev.changedTouches.length);
        document.write('元素上剩余的触摸点：' + ev.targetTouches.length);
        document.write('文档上剩余的触摸点：' + ev.touches.length);
    
    }, false);
    </script>

if (Touch.length < 1 || TouchEvent.length < 1)
      throw "TouchEvent 构造函数不支持";
    
    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对象有一个关联的未调整目标（null或EventTarget）。除非另有说明，默认为null。

在给定touchEvent的情况下，TouchEvent的重定向步骤必须执行以下步骤：

1. 对于touchEvent的touches、targetTouches和changedTouches成员中的每个Touch touch：

   1. 如果touch的未调整目标为null，则将touch的target设置为touch的未调整目标。
   2. 将touch的target设置为对touchEvent的target调用重定向步骤的结果。

用户代理有一个关联的布尔值暴露旧的触摸事件 API，其值为实现定义。

以下部分描述了[HTML5]中定义的现有GlobalEventHandlers混入的扩展，以便于事件处理程序的注册。对于暴露旧的触摸事件 API为false的用户代理，不得实现此混入。

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

ontouchstart

事件处理程序IDL属性（参见[HTML5]）用于touchstart事件类型。

ontouchend

事件处理程序IDL属性（参见[HTML5]）用于touchend事件类型。

ontouchmove

事件处理程序IDL属性（参见[HTML5]）用于touchmove事件类型。

ontouchcancel

事件处理程序IDL属性（参见[HTML5]）用于touchcancel事件类型。

用户代理可以同时分派触摸事件和鼠标事件（为兼容非触摸设计的网页内容）[DOM-LEVEL-2-EVENTS]，以响应同一个用户输入。如果用户代理在单个用户操作响应中同时分派了触摸事件和鼠标事件，那么在任何鼠标事件类型之前，必须首先分派touchstart事件类型。如果touchstart、touchmove或touchend被取消，用户代理不应分派与阻止的触摸事件相应的任何鼠标事件。

如果用户代理将一系列触摸事件解释为点击手势，则应按照mousemove、mousedown、mouseup和click的顺序在对应的touchend事件位置处分派这些事件。如果文档内容在处理触摸事件期间发生了变化，则用户代理可能会将鼠标事件分派到与触摸事件不同的目标。

任何进一步的触摸和鼠标事件的默认行为和顺序是实现定义的，除非在其他地方另有规定。

    // 条件的“触摸或鼠标/键盘”事件绑定
    // 不要这样做，因为这会使交互仅限于触摸
    // 在同时具有触摸和鼠标/键盘的设备上
    
    if ('ontouchstart' in window) {
      // 设置触摸事件监听器
      target.addEventListener('touchend', ...);
      ...
    } else {
      // 设置鼠标/键盘事件监听器
      target.addEventListener('click', ...);
      ...
    }
    

    // 同时绑定“触摸和鼠标/键盘”事件
    
    // 设置触摸事件监听器
    target.addEventListener('touchend', function(e) {
      // 阻止兼容的鼠标事件和点击
      e.preventDefault();
      ...
    });
    ...
    
    // 设置鼠标/键盘事件监听器
    target.addEventListener('click', ...);
    ...
    

活跃触点

一个触点，当前位于屏幕上并由用户代理跟踪。用户代理首次分派touchstart事件来指示它的出现时，触点变为活跃。当用户代理分派touchend或touchcancel事件来指示触点从表面移除或不再跟踪时，它不再活跃。

触点

指针（例如手指或触笔）与界面目标表面相交的坐标点。可以指手指接触触摸屏，或数字笔在纸上书写。

取消的事件

其默认操作已通过preventDefault()、在事件处理程序中返回false，或其他由[DOM-LEVEL-3-EVENTS]和[HTML5]定义的手段阻止的事件。