触摸事件 - 第二级

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

文档中关键词 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，即使该触控点此后已移出该元素的交互区域，target 仍为最初的那个元素。

注意

某些实现会更改目标元素以纠正粗糙输入的不精确性。因此，目标元素不一定是事件坐标处直接的元素。用于定位/消歧义粗糙输入的方法超出本规范的范围。

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 所表示的绝对压力值及压力灵敏度等级可能有所不同。

altitudeAngle

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

注意

此处为 altitudeAngle 定义的默认值为 0。该默认值不同于 Pointer Events - Level 3 规范 [POINTEREVENTS] 对 altitudeAngle 属性的定义，该规范将默认值定义为 π/2，即将传感器位置视为垂直于表面。

azimuthAngle

传感器（例如笔/手写笔）在 X-Y 平面上的方位角（以弧度计），范围为 [0, 2π] —— 其中 0 表示笔帽指向 X 轴增大的方向（如果从上方俯视，则相当于“3 点钟”方向），数值在顺时针方向上递增（π/2 在“6 点钟”，π 在“9 点钟”，3π/2 在“12 点钟”）。当传感器与表面完全垂直（即 altitudeAngle 为 π/2）时，该值 MUST 为 0。对于不报告倾斜或角度的硬件和平台，该值 MUST 为 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（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 的 target。
   2. 将 touch 的 target 设置为对 touch 的 unadjustedTarget 针对 touchEvent 的 target 执行 retargeting 后的结果。

用户代理具有一个关联的布尔值 expose legacy touch event APIs，其值为 implementation-defined。

下面的部分描述了对定义于 [HTML5] 的现有 GlobalEventHandlers mixin 的扩展，以便于事件处理器的注册。对于 expose legacy touch event APIs 为 false 的用户代理，不得实现此 mixin。

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]）。

用户代理可能会针对同一用户输入同时分派触摸事件和（为与未针对触摸设计的 Web 内容兼容）鼠标事件 [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] 定义的其他方法阻止其默认操作的事件。