# 触控功能

JsView中的触控功能，设计思路是js定规则后尽最大可能减少触控处理过程中和js的交互，以提升触控处理中drag/fling的性能。 (TBD: 当前版本PC浏览器模拟环境上的click/drag/fling暂时未实现)

# 1. 普通div元素上追加点击支持

在div元素上追加 @click="回调函数" 即可

例如:

  <script setup>
  /* 声明click的回调函数 */
  const click_callback = ()=>{
    console.log("on clicked");
  }
  <script/>

  <template>
    <div 
      :style="{
        width:100, 
        height:100, 
        backgroundColor: '#FF00FF'}"
      @click="click_callback"/>
  </template>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 2. 普通元素中追加长按的响应

通过element的ref句柄，调用 jsvSetTapListener 函数来设置，具体参考

Element的jsvSetTapListener

# 3. MetroWidget支撑的列表触控处理(drag/fling/click)

根节点追加触控总管模块(尺寸为全屏), 整个界面作为此节点的子

import {
  JsvTouchModeSwitcher,
} from "jsview";

<jsv-touch-mode-switcher
      :width="1920"
      :height="1080"
    >
    <!-- 整个界面 -->
</jsv-touch-mode-switcher>

1
2
3
4
5
6
7
8
9
10

打开MetroWidget的props中的touchFlag即可：

// props
//   touchFlag {int} 触控的开关, 
//       0:关闭, 1:打开. 打开后支持drag, fling; 
//       另外，item要支持点击(click)时，要在measure回调函数中，对measuresObject的追加enableTap:true
//   mouseFlag {int} 支持鼠标滚轮的开关, 0:关闭, 1:打开, 打开后可以用鼠标滚轮来对mw进行scroll

1
2
3
4
5

# 4. 长文本滚动

使用JsvScrollBox和JsvScrollFollow组件来完成。可以参考“功能实例->长文字”的样例(如下)

node_modules/@shijiu/jsview-vue-samples/LongText/LongTextScroll.vue

因为是整篇文字是一部分可见，所以用JsvScrollBox的抽屉模式(drawer)

这两个组件的参数说明见:
node_modules/@shijiu/jsview-vue/utils/JsViewVueWidget/JsvScrollBox/JsvScrollBox.vue
node_modules/@shijiu/jsview-vue/utils/JsViewVueWidget/JsvScrollBox/JsvScrollFollow.vue

# 5. 进度条拖动(视频进度条)

使用JsvScrollBox和JsvScrollFollow组件来完成。可以参考“触控->可拖拽进度条”的样例(如下)

node_modules/@shijiu/jsview-vue-samples/ScrollBoxTest/SizeDivBar.vue
node_modules/@shijiu/jsview-vue-samples/ScrollBoxTest/ClipBar.vue
node_modules/@shijiu/jsview-vue-samples/ScrollBoxTest/NinePatchBar.vue

因为是进度条游标在滚动区域中滑动，所以用JsvScrollBox的Pin模式

# 6. div拖动和对齐检测

使用JsvDragBox组件来完成此功能，可参考"触控->DragBox"的样例(如下)

node_modules/@shijiu/jsview-vue-samples/DragBox/App.vue

使用此组件时，注意 setSensor 的敏感度设置，越小性能开销越大(js是单线程，过于频繁的消息和回调会导致其他任务无法执行)

此组件的参数说明见:
node_modules/@shijiu/jsview-vue/utils/JsViewVueWidget/JsvDragBox/JsvDragBox.vue

# 7. 鼠标的hover进出检测

在div元素上追加 @mouseenter="回调函数" 和 @mouseleave="回调函数" 即可

例如:

  <script setup>
  /* 声明click的回调函数 */
  const click_callback = ()=>{
    console.log("on clicked");
  }
  <script/>

  <template>
    <div 
      :style="{
        width:100, 
        height:100, 
        backgroundColor: '#FF00FF'}"
      @mouseenter="mouseenter_callback"
      @mouseleave="mouseleave_callback"
      />
  </template>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 8. 使用蒙层屏蔽下层元素的触控与鼠标事件

在需要临时禁止用户操作（例如弹窗、加载中、全屏遮罩）时，可在界面上方叠一层全屏或局部的 蒙层 div，使其盖住下层可交互元素。蒙层本身通过 jsvSetTapListener 与 jsvConsumeMouseEvent 吞掉触控与鼠标事件，下层元素便不会收到 click、长按、hover、滚轮等响应。

实现要点：

蒙层需覆盖待屏蔽区域，并设置合适DOM层级，使其位于下层元素之上。
触控：对蒙层调用 jsvSetTapListener，为各触控回调注册空实现，避免事件继续下发。
鼠标：对蒙层调用 jsvConsumeMouseEvent({ hover: true, scroll: true })，屏蔽 hover 与滚轮；蒙层挡住区域内的 MetroWidget 等下层控件的鼠标事件同样会被挡住。

API 说明见：
Element 的 jsvSetTapListener / jsvConsumeMouseEvent

例如（Vue 3，使用 ref 拿到蒙层 div 句柄 overlay）：

<script setup>
import { ref, onMounted } from "vue";

const overlay = ref(null);

// 空回调，用于吞掉触控事件
const emptyListener = () => {};

onMounted(() => {
  if (!overlay.value) return;

  let emptyListener = ()=>{};
  // 屏蔽所有触控事件
  overlay.value.jsvSetTapListener({
    onClick: emptyListener,
    onTouchStart: emptyListener,
    onTouchEnd: emptyListener,
    onLongPress: emptyListener,
    onLongPressRelease: emptyListener,
    onCancel: emptyListener,
  });

  // 屏蔽所有鼠标 hover 与滚轮事件
  overlay.value.jsvConsumeMouseEvent({ hover: true, scroll: true });
});
</script>

<template>
  <!-- 下层：正常可点击、可 hover 的内容 -->
  <div :style="{ width: 1920, height: 1080 }">
    <!-- ... -->
  </div>

  <!-- 蒙层：盖住下层，屏蔽触控与鼠标事件 -->
  <div
    ref="overlay"
    :style="{
      width: 1920,
      height: 1080,
      backgroundColor: 'rgba(0,0,0,0.5)',
    }"
  />
</template>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

需要恢复交互时，移除或隐藏蒙层即可；若蒙层长期存在，可在显示/隐藏时分别调用上述 API 与对应清理逻辑（按业务需要处理）。

← WebSocket (Vue)JsvFocusBlock →