npm package: @hadss/web_uni_input
Description: Interactive Event Normalization Library of the HTML5 framework.
Latest version: 1.0.0-rc.0

# web_uni_input

## 介绍
H5框架多设备适配交互归一库核心代码。

## 目录结构

```
├─web_uni_input // 项目名称
│  ├─src
│  │  ├─hooks // API库文件
│  │  │  └─{pointerGestureManager/index.ts}
│  │  ├─types // 类型定义文件
│  │  │  └─{pointerGestureManager/index.ts}
│  │  └─index.ts // 组件库入口文件
│  ├─LICENSE
│  ├─vite.config.ts // 打包配置文件
│  ├─tsconfig.json // typeScript配置文件
```

## 交互归一库能力介绍
### PointerGestureManager交互归一管理库接收的核心参数集合
|参数  |说明 |类型 |必填  |
| ------------ | ------------ | ------------ | ------------ |
|element |事件绑定的dom元素  |HTMLElement |是   |
|handlers |事件回调集合  |GestureHandlers |是 |
|configs |事件触发可选配置 |PointerOptions  |否 |
#### API
|  属性 | 说明  |
| ------------ | ------------ |
|destroy   |destroy销毁实例，实例销毁以后交互归一事件不再触发   |

### GestureHandlers：统一暴露所有交互事件，通过回调函数传递标准化数据
|  属性   |说明|
| ------------ |  ------------ |
|onClick: (state: PointerState)=>{} |点击事件触发回调  |
|onDoubleClick: (state: PointerState)=>{} |双击事件触发回调  |
|onLongPressStart: (state: PointerState)=>{} |长按事件初始触发回调 |
|onLongPressEnd: (state: PointerState)=>{}  |长按事件结束触发回调 |
|onLongPressCancel: (state: PointerEvent)=>{}  |长按事件取消触发回调 |
|onDragStart: (state: DragEvent)=>{}  |绑定A组件，触控屏长按/鼠标左键按下后移动触发<br>说明：需要设置元素属性 draggable="true" 启用拖拽（链接和图片默认支持拖拽）  |
|onDragEnter: (state: DragEvent)=>{}  |绑定B组件，触控屏手指、鼠标移动进入B组件瞬间触发  |
|onDragMove: (state: DragEvent)=>{} |绑定B组件，触控屏手指、鼠标在B组件内移动触发  |
|onDragLeave: (state: DragEvent)=>{}  |绑定B组件，触控屏手指、鼠标移动退出B组件瞬间触发   |
|onDrop: (state: DragEvent)=>{}  |绑定B组件，在B组件内，触控屏手指抬起、鼠标左键松开时触发<br>说明：需要在onDragMove事件设置state.preventDefault()来触发   |
|onSwipe: (state: PointerState)=>{} |轻扫事件触发回调   |
|onScroll: (state: PointerState)=>{} |滚动/平移事件触发回调   |
|onPinchStart: (state: PointerState)=>{}  |缩放事件初始触发回调   |
|onPinchMove: (state: PointerState)=>{} |缩放过程中触发回调   |
|onPinchEnd: (state: PointerState)=>{} |缩放事件结束触发回调   |
|onHover: (state: PointerState)=>{} |悬浮事件进入或退出元素触发回调（不支持触控屏）   |
|onHoverMove: (state: PointerState)=>{} |悬浮事件悬浮于元素上方触发回调（不支持触控屏）   |
|onContextMenu: (state: MouseEvent \| TouchEvent)=>{} |上下文菜单打开时触发回调   |
|onRotateStart: (state: PointerState)=>{} |旋转事件开始触发回调（不支持PC、触控板）   |
|onRotateMove: (state: PointerState)=>{} |旋转事件过程中触发回调（不支持PC、触控板）   |
|onRotateEnd: (state: PointerState)=>{} |旋转事件结束触发回调（不支持PC、触控板）   |
### PointerOptions：定义全局指针参数，支持用户自定义阈值和时间限制
|属性   |类型   |默认值  |说明    |
| ------------ | ------------ | ------------ | ------------ |
|distanceThreshold   |number   |2^31-1   |点击事件移动阈值。当设置的值小于等于0时，会被转化为默认值。<br>说明：当手指的移动距离超出开发者预设的移动阈值时，点击识别失败。如果初始化为默认阈值时，手指移动超过组件热区范围，点击识别失败。 |
|enableClick   |boolean   |false   |单击功能开关控制   |
|doubleTapThreshold   |number   |300ms   |双击超时时间间隔   |
|enableDoubleClick   |boolean   |false   |双击功能开关控制   |
|longPressThreshold   |number   |500ms   |触发长按的最短时间，单位为毫秒（ms）取值范围：[0, +∞)，设置小于等于0时，按照默认值500处理。   |
|enableLongPress   |boolean   |false   |长按功能开关控制   |
|enableDrag   |boolean   |false   |拖拽功能开关控制   |
|direction  |string   |All   |触发轻扫的滑动方向。<br>说明：<br>All：所有方向<br>Horizontal：水平方向，手指滑动方向与x轴夹角小于45度时触发<br>Vertical：竖直方向，手指滑动方向与y轴夹角小于45度时触发<br>None：任何方向均不可触发  |
|speed   |number   |0.1px/ms   |识别轻扫的最小速度   |
|enableSwipe |boolean   |false |轻扫功能开关控制|
|scrollDirection   |string   |All|触发滚动的滑动方向，支持逻辑与（&）或逻辑或（l）运算，方向没有角度限制<br>说明：<br>（1）All：所有方向<br>（2）Horizontal：水平方向<br>（3）Vertical：竖直方向<br>（4）Left：向左滑动<br>（5）Right：向右滑动<br>（6）Up：向上滑动<br>（7）Down：向下滑动<br>（8）None：任何方向均不可触发 |
|scrollDistance   |number   |5px   |指定触发滑动手势事件的最小滑动距离   |
|enableScroll   |boolean   |false   |滚动功能开关控制   |
|scaleDistance   |number   |5px|最小识别距离   |
|enableScale   |boolean   |false|缩放功能开关控制 |
|enableHover   |boolean   |false|悬浮功能开关控制 |
|enableContextMenu   |boolean   |false|上下文菜单功能开关控制 |
|angle   |number   |1deg|触发旋转手势的最小改变度数，单位为deg。当改变度数的值小于等于0或大于360时，会被转化为默认值。 |
|enableRotate   |boolean   |false|旋转功能开关控制 |
### PointerState接口：定义事件回调接收到的事件对象，包含了与触发事件相关的各种信息，方便开发者在回调函数中进行相应的处理。
#### PointerInfo：定义指针事件接口属性，用于记录指针相关的状态信息。
|属性   |类型   |说明   |
| ------------ | ------------ | ------------ |
|id   |number   |指针的索引编号   |
|globalX   |number   |相对于应用窗口左上角的x轴坐标   |
|globalY   |number   |相对于应用窗口左上角的y轴坐标   |
|localX   |number   |相对于当前元素原始区域左上角的x轴坐标   |
|localY   |number   |相对于当前元素原始区域左上角的y轴坐标   |
|displayX   |number   |相对于屏幕左上角的x轴坐标   |
|displayY   |number   |相对于屏幕左上角的y轴坐标   |
|hand   |NONE：未知<br>LEFT：左键<br>RIGHT：右键   |表示事件是由左键点击还是右键点击触发   |
#### 基础事件：包含与触发事件相关的基础信息
|属性   |类型   |说明   |
| ------------ | ------------ | ------------ |
|target   |EventTarget   |触发事件的元素对象显示区域   |
|source   |unknown：未知设备<br>mouse：鼠标<br>touchScreen：触摸屏   |事件输入设备   |
|sourceTool   |unknown：未知输入源<br>finger：手指输入<br>mouse：鼠标输入   |事件输入源   |
|pressure   |number   |按压的压力大小   |
|axisHorizontal   |number   |水平轴值，仅在由鼠标滚轮或者触控板双指滑动场景下触发的滚动及平移手势中可以获取   |
|axisVertical   |number   |垂直轴值，仅在由鼠标滚轮或者触控板双指滑动场景下触发的滚动及平移手势中可以获取   |
|fingerList   |FingerInfo[]   |输入源为触屏产生的手势，fingerList中会包含触发事件的所有触点信息，鼠标和触摸板事件只会携带一条记录   |
#### 点击事件（继承基础事件）
|属性   |类型   |说明   |
| ------------ | ------------ | ------------ |
|x   |number   |点击位置相对于被点击元素左边缘的X坐标   |
|y   |number   |点击位置相对于被点击元素原始区域左上角的Y坐标   |
|windowX   |number   |点击位置相对于应用窗口左上角的X坐标   |
|windowY   |number   |点击位置相对于应用窗口左上角的Y坐标   |
|displayX   |number   |点击位置相对于应用屏幕左上角的X坐标   |
|displayY   |number   |点击位置相对于应用屏幕左上角的Y坐标   |
|hand   |NONE：未知<br>LEFT：左键<br>RIGHT：右键   |表示事件是由左键点击还是右键点击触发   |
#### 双击事件、长按事件、轻扫事件、滚动及平移事件、缩放事件、旋转事件（继承基础事件）
|属性   |类型   |说明   |
| ------------ | ------------ | ------------ |
|repeat   |boolean   |是否为重复触发事件，用于长按手势触发场景   |
|offsetX   |number   |手势事件偏移量X，用于滚动及平移手势触发场景从左向右滑动offsetX为正，反之为负。   |
|offsetY   |number   |手势事件偏移量Y，用于滚动及平移手势触发场景从上向下滑动offsetY为正，反之为负。   |
|scale   |number   |缩放比例   |
|pinchCenterX   |number   |捏合手势中心点的x轴坐标，用于缩放手势触发场景   |
|pinchCenterY   |number   |捏合手势中心点的y轴坐标，用于缩放手势触发场景   |
|speed   |number   |滑动手势速度，用于轻扫手势触发场景   |
|velocityX   |number   |用于滚动及平移手势中，获取当前手势的x轴方向速度   |
|velocityY   |number   |用于滚动及平移手势中，获取当前手势的y轴方向速度   |
|velocity   |number   |用于滚动及平移手势中，获取当前手势的主方向速度   |
|angle   |number   |旋转角度   |
#### 悬浮事件（继承基础事件）
|属性   |类型   |说明   |
| ------------ | ------------ | ------------ |
|x   |number   |悬浮位置相对于当前元素左上角的X轴坐标   |
|y   |number   |悬浮位置相对于当前元素左上角的Y轴坐标  |
|stopPropagation   |() => void   |阻塞事件冒泡   |
|windowX   |number   |悬浮位置相对于应用窗口左上角的X轴坐标  |
|windowY   |number   |悬浮位置相对于应用窗口左上角的Y轴坐标   |
|displayX   |number   |悬浮位置相对于应用屏幕左上角的X轴坐标  |
|displayY   |number   |悬浮位置相对于应用屏幕左上角的Y轴坐标  |
#### 拖拽事件
|参数   |类型   |说明   |
| ------------ | ------------ | ------------ |
|state   |DragEvent   |原生事件的event对象   |
#### 上下文菜单事件
|参数   |类型   |说明   |
| ------------ | ------------ | ------------ |
|state   |MouseEvent\|TouchEvent   |原生事件的event对象   |
### PointerGestureManager交互归一库使用说明
#### **import引用交互**
  ```typescript
  import { PointerGestureManager, PointerOptions, GestureHandlers, PointerState } from '@hadss/web_uni_input';
  ```
#### PointerGestureManager交互归一库使用示例(Vue3)

```
<template>
  <div ref="testDom" id="testId"></div>
</template>

<script lang="ts" setup>
import { onMounted, onUnmounted, ref } from "vue";
import {
  PointerGestureManager,
  PointerOptions,
  GestureHandlers,
  PointerState,
} from "web_uni_input";
const handleClick = (state: PointerState) => {
  // 代码编辑
};
const testDom = ref<HTMLElement | null>(null);
const instance = ref(null);
onMounted(() => {
  // 如果要获取DOM元素，请在DOM元素挂载之后获取，比如VUE3生命周期的onMounted中获取DOM元素
  const handlers: GestureHandlers = {
    onClick: handleClick,
  };
  const configs: PointerOptions = {
    enableClick: true,
  };

  if (testDom.value) {
    instance.value = PointerGestureManager(testDom.value, handlers, configs);
  }
});
onUnmounted(() => {
  //destroy销毁实例，实例销毁以后交互归一事件不再触发
  if (instance.value) {
    instance.value.destroy();
  }
});
</script>

<style scoped>
#testId {
  width: 200px;
  height: 200px;
  background-color: aquamarine;
}
</style>
```