@kyfe/ks-query-table 0.0.21 → 0.0.22

package/src/view/home/query-table/components/pe-table/utils/touch-scroll.js

@@ -0,0 +1,417 @@
+import isFunction from 'lodash/isFunction';
+import isNaN from 'lodash/isNaN';
+
+/**
+ * 触摸滚动处理类
+ * 实现移动端触摸滚动及惯性滚动效果
+ */
+export class TouchScrolling {
+  /**
+   * 构造函数
+   * @param {HTMLElement} el - 需要绑定滚动效果的目标元素
+   * @param {Object} options - 配置选项
+   * @param {boolean} options.unScrollX - 是否禁用X轴滚动
+   * @param {boolean} options.unScrollY - 是否禁用Y轴滚动
+   * @param {boolean} options.isShowHorizontal - 是否显示水平滚动条
+   * @param {Function} options.handlerTouchend - 触摸结束回调函数
+   * @param {Function} options.handlerScrollEnd - 滚动结束回调函数
+   */
+  constructor(el, options = {}) {
+    // 参数校验
+    if (!el) throw new Error('必须提供目标元素');
+    this.timer = null
+    this.isScrolling = null
+
+    // 初始化属性
+    this.el = el;                      // 目标DOM元素
+    this.decelerationId = null;       // 减速动画ID
+    this.touchScrollState = null;      // 触摸滚动状态
+    this.lastMoveTime = 0;             // 上次移动时间戳
+    this.moveThrottle = 2;            // 移动事件节流时间(毫秒)
+    this.touchPosition = null;
+
+    // 配置选项处理
+    this.unScrollX = !!options.unScrollX;          // X轴滚动禁用状态
+    this.unScrollY = !!options.unScrollY;          // Y轴滚动禁用状态
+    this.isShowHorizontal = !!options.isShowHorizontal; // 水平滚动条显示状态
+
+    // 回调函数绑定
+    this.handlerTouchStar = isFunction(options.handlerTouchStar) ? options.handlerTouchStar : null;
+    this.handlerTouchend = isFunction(options.handlerTouchend) ? options.handlerTouchend : null;
+    this.handlerTouchmove = isFunction(options.handlerTouchmove) ? options.handlerTouchmove : null;
+    this.onScrollEnd = isFunction(options.handlerScrollEnd) ? options.handlerScrollEnd : null;
+    this.handlerBeforeAnimation = isFunction(options.handlerBeforeAnimation) ? options.handlerBeforeAnimation : null;
+
+    // 绑定事件处理函数(仅绑定一次)
+    this.boundHandlers = {
+      touchstart: this.onTouchStart.bind(this),
+      touchend: this.onTouchEnd.bind(this),
+      touchmove: this.onTouchMove.bind(this),
+      touchcancel: this.onTouchCancel.bind(this),
+      pointermove: this.onPointermove.bind(this),
+    };
+
+    // 添加事件监听
+    this.addEventListeners();
+  }
+
+  /**
+   * 添加事件监听器
+   */
+  addEventListeners() {
+    const { touchstart, touchend, touchmove, touchcancel, pointermove } = this.boundHandlers;
+    this.el.addEventListener('touchstart', touchstart);
+    this.el.addEventListener('touchend', touchend);
+    this.el.addEventListener('touchmove', touchmove);
+    this.el.addEventListener('touchcancel', touchcancel);
+    this.el.addEventListener('pointermove', pointermove);
+  }
+
+  /**
+   * 移除事件监听器
+   */
+  removeEventListeners() {
+    const { touchstart, touchend, touchmove } = this.boundHandlers;
+    this.el.removeEventListener('touchstart', touchstart);
+    this.el.removeEventListener('touchend', touchend);
+    this.el.removeEventListener('touchmove', touchmove);
+    this.el.removeEventListener('pointermove', pointermove);
+  }
+
+  /**
+   * 确保值为有效数字
+   * @param {*} value - 需要转换的值
+   * @returns {number} - 转换后的数字
+   */
+  ensureNumeric(value) {
+    const numericValue = Number(value);
+    return isNaN(numericValue) ? 0 : numericValue;
+  }
+
+  /**
+   * 派发滚轮事件
+   * @param {number} deltaY - Y轴滚动量
+   * @param {number} deltaX - X轴滚动量
+   */
+  dispatchWheelEvent(deltaY, deltaX) {
+    deltaY = this.ensureNumeric(deltaY);
+    deltaX = this.ensureNumeric(deltaX);
+
+    // 无滚动量时不派发事件
+    if (!deltaY && !deltaX) {
+      // this.handlerBeforeAnimation?.(true)
+      return
+    }
+
+    const wheelEvent = new WheelEvent('wheel', {
+      deltaY,
+      deltaX,
+      deltaMode: 0,  // 像素模式
+      bubbles: true  // 允许事件冒泡
+    })
+
+    this.el.dispatchEvent(wheelEvent);
+  }
+
+  /**
+   * 设置滚动属性
+   * @param {string} key - 属性名
+   * @param {*} val - 属性值
+   */
+  setScroll(key, val) {
+    if (Object.prototype.hasOwnProperty.call(this, key)) {
+      this[key] = !!val;
+    }
+  }
+
+  /**
+   * 模拟惯性减速滚动效果
+   * @param {number} decelerationId - 当前减速动画ID
+   * @param {Boolean} isYAndDownToTop - Y轴并且从下至上滚动
+   */
+  simulateDeceleratedScrolling(decelerationId, isYAndDownToTop) {
+    // 检查是否应该继续执行
+    if (!this.touchScrollState || decelerationId !== this.decelerationId) return;
+
+    // 减速效果配置常量
+    const DECELERATION_FACTOR = 0.92;  // 减速因子
+    const MIN_SPEED = 0.005;           // 最小速度阈值
+    const MAX_DURATION = 1000;         // 最大持续时间(毫秒)
+    const Y_BOOST = 4;                 // Y轴初始速度增强倍数
+    const X_BOOST = 3.5;               // X轴初始速度增强倍数
+
+    // 获取当前滚动量
+    let {
+      lastDeltaY: currentDeltaY,
+      lastDeltaX: currentDeltaX
+    } = this.touchScrollState;
+
+    // 无滚动量时直接触发结束
+    if (!currentDeltaY && !currentDeltaX) {
+      // 这里是为了处理没有滚动量的情况，兜底橡皮筋回弹效果。
+      // 场景：上拉到表格外部时，有概率出现 currentDeltaY = 0 && currentDeltaX = 0 的情况。
+      this.handlerBeforeAnimation?.(true)
+      return;
+    }
+
+    // 增强初始速度
+    currentDeltaY *= Y_BOOST;
+    currentDeltaX *= X_BOOST;
+
+    // 记录初始滚动方向
+    const initialDirection = {
+      y: Math.sign(currentDeltaY),
+      x: Math.sign(currentDeltaX)
+    };
+
+    let lastTime = performance.now();  // 上次动画帧时间
+    let elapsedTime = 0;               // 已过去的时间
+
+    /**
+     * 动画帧回调函数
+     * @param {number} timestamp - 当前时间戳
+     */
+    const step = (timestamp) => {
+      // 检查是否应该继续执行
+      if (decelerationId !== this.decelerationId) return;
+
+      // 计算时间差(限制最大帧时间)
+      const deltaTime = Math.min(timestamp - lastTime, 32);
+      lastTime = timestamp;
+      elapsedTime += deltaTime;
+
+      // 计算当前减速因子
+      const progress = Math.min(1, elapsedTime / MAX_DURATION);
+      const currentFactor = DECELERATION_FACTOR * (1 - progress * 0.3);
+      const frameFactor = Math.pow(currentFactor, deltaTime / 16);
+
+      // 应用减速效果
+      currentDeltaY *= frameFactor;
+      currentDeltaX *= frameFactor;
+
+      // 确保滚动方向一致性
+      if (Math.sign(currentDeltaY) !== 0 && Math.sign(currentDeltaY) !== initialDirection.y) {
+        currentDeltaY = 0;
+      }
+      if (Math.sign(currentDeltaX) !== 0 && Math.sign(currentDeltaX) !== initialDirection.x) {
+        currentDeltaX = 0;
+      }
+
+      // 检查停止条件
+      const shouldStop =
+        (Math.abs(currentDeltaY) < MIN_SPEED && Math.abs(currentDeltaX) < MIN_SPEED * 2) ||
+        elapsedTime >= MAX_DURATION;
+
+      if (shouldStop) {
+        this.triggerScrollEnd(initialDirection);
+        return;
+      }
+
+      const isBottom = this.handlerBeforeAnimation?.(isYAndDownToTop)
+
+      if (isBottom) return
+
+      // 派发滚轮事件并继续动画
+      this.dispatchWheelEvent(currentDeltaY, currentDeltaX);
+      requestAnimationFrame(step);
+    };
+
+    // 启动动画
+    requestAnimationFrame(step);
+  }
+
+  /**
+   * 触发滚动结束回调
+   * @param {Object|null} direction - 滚动方向对象
+   */
+  triggerScrollEnd(direction = null) {
+    // 如果没有提供方向，则从状态中获取
+    if (!direction && this.touchScrollState) {
+      direction = {
+        y: Math.sign(this.touchScrollState.lastDeltaY),
+        x: Math.sign(this.touchScrollState.lastDeltaX)
+      };
+    }
+    // 调用滚动结束回调(如果存在)
+    this.onScrollEnd?.(direction);
+  }
+
+  /**
+   * 触摸开始事件处理
+   * @param {TouchEvent} event - 触摸事件对象
+   */
+  onTouchStart(event) {
+    // 只处理单指触摸
+    if (event.touches.length !== 1) return;
+    this.touchPosition = this.el.getBoundingClientRect()
+
+    const touch = event.touches[0];
+    const now = performance.now();
+
+    // 初始化触摸状态
+    this.touchScrollState = {
+      startY: touch.clientY,    // 起始Y坐标
+      lastY: touch.clientY,     // 上次Y坐标
+      lastDeltaY: 0,           // 上次Y轴变化量
+      startX: touch.clientX,    // 起始X坐标
+      lastX: touch.clientX,     // 上次X坐标
+      lastDeltaX: 0,           // 上次X轴变化量
+      startTime: now,          // 触摸开始时间
+    };
+
+    // 使用时间戳作为减速动画ID
+    this.decelerationId = now;
+    this.lastMoveTime = now;
+    this.handlerTouchStar?.(event)
+  }
+
+  /**
+   * 触摸取消事件处理
+   */
+  onTouchCancel() {
+  }
+
+  /**
+   * 触摸结束事件处理
+   */
+  onTouchEnd() {
+    // 检查是否有有效的触摸状态
+    if (!this.touchScrollState || !this.decelerationId) {
+      this.touchScrollState = null;
+      return;
+    }
+
+    // 获取触摸状态数据
+    const {
+      startY, lastY,
+      startX, lastX,
+      startTime
+    } = this.touchScrollState;
+
+    // 计算触摸持续时间和距离
+    const touchDuration = performance.now() - startTime;
+    const totalDeltaY = Math.abs(startY - lastY);
+    const totalDeltaX = Math.abs(startX - lastX);
+    const totalDistance = Math.max(totalDeltaY, totalDeltaX);
+    const speed = touchDuration > 0 ? totalDistance / touchDuration : 0;
+
+    // 处理触摸结束回调
+    const finalOffsetY = this.touchScrollState.lastDeltaY / 0.05;
+    this.handlerTouchend?.(finalOffsetY);
+
+    // 判断Y轴并且从下至上滚动
+    const isY = Math.sign(this.touchScrollState.lastDeltaX) === 0
+    const isDownToTop = lastY < startY
+    const isYAndDownToTop = isY && isDownToTop
+    // 根据速度决定是否应用惯性效果
+    const SPEED_THRESHOLD = 0.5;  // 速度阈值
+    if (speed >= SPEED_THRESHOLD) {
+      this.simulateDeceleratedScrolling(this.decelerationId, isYAndDownToTop);
+    } else {
+      this.triggerScrollEnd();
+      this.handlerBeforeAnimation?.(isYAndDownToTop)
+    }
+
+    // 清除触摸状态
+    this.touchScrollState = null;
+    clearTimeout(this.timer);
+    this.timer = null;
+    if (this.isScrolling) {
+      this.handlerBeforeAnimation?.(true)
+    }
+  }
+
+  onPointermove() {
+
+  }
+
+  /**
+   * 触摸移动事件处理
+   * @param {TouchEvent} event - 触摸事件对象
+   */
+  onTouchMove(event) {
+    // 只处理单指触摸且有触摸状态的情况
+    if (!this.touchScrollState || event.touches.length !== 1) return;
+
+    // 节流处理
+    const now = performance.now();
+    if (now - this.lastMoveTime < this.moveThrottle) return;
+    this.lastMoveTime = now;
+
+    // 获取当前触摸点坐标
+    const touch = event.touches[0];
+    const currentY = touch.clientY;
+    const currentX = touch.clientX;
+
+    // 计算滚动量
+    let deltaY = this.touchScrollState.lastY - currentY;
+    let deltaX = this.touchScrollState.lastX - currentX;
+
+    // 确定主要滚动方向
+    const diffY = Math.abs(this.touchScrollState.startY - currentY);
+    const diffX = Math.abs(this.touchScrollState.startX - currentX);
+    const isVerticalScroll = (diffX - diffY) <= 0;
+
+    // 应用滚动限制
+    if (isVerticalScroll) {
+      // 判断Y轴并且从下至上滚动
+      // const isY = Math.sign(this.touchScrollState.lastDeltaX) === 0
+      // const isDownToTop = this.touchScrollState.lastY < this.touchScrollState.startY
+      // const isYAndDownToTop = isY && isDownToTop
+      // this.handlerBeforeAnimation?.(true)
+      // 垂直滚动处理
+      if (this.unScrollY && !this.isShowHorizontal) {
+        this.updateTouchState(currentY, currentX, 0, 0);
+        return;
+      }
+      deltaX = 0;  // 垂直滚动时忽略水平移动
+    } else {
+      // 水平滚动处理
+      deltaY = 0;  // 水平滚动时忽略垂直移动
+    }
+
+    // 阻止默认行为并派发滚轮事件
+    event.preventDefault();
+    this.dispatchWheelEvent(deltaY, deltaX);
+    this.updateTouchState(currentY, currentX, deltaY, deltaX);
+
+    // 清除之前的定时器
+    clearTimeout(this.timer);
+    this.timer = null;
+    // 标记为正在滑动
+    this.isScrolling = true;
+    // 设置新的定时器
+    this.timer = setTimeout(() => {
+      this.isScrolling = false;
+      this.touchScrollState = null;
+      this.handlerBeforeAnimation?.(true);
+    }, 150); // 150ms 内没有新的 touchmove 事件则认为停止
+  }
+
+  /**
+   * 更新触摸状态
+   * @param {number} y - 当前Y坐标
+   * @param {number} x - 当前X坐标
+   * @param {number} deltaY - Y轴滚动量
+   * @param {number} deltaX - X轴滚动量
+   */
+  updateTouchState(y, x, deltaY, deltaX) {
+    if (!this.touchScrollState) return;
+
+    // 更新触摸状态
+    this.touchScrollState.lastY = y;
+    this.touchScrollState.lastDeltaY = deltaY;
+    this.touchScrollState.lastX = x;
+    this.touchScrollState.lastDeltaX = deltaX;
+  }
+
+  /**
+   * 销毁方法，清理资源
+   */
+  destroy() {
+    this.removeEventListeners();  // 移除事件监听
+    this.touchScrollState = null; // 清除触摸状态
+    cancelAnimationFrame(this.decelerationId); // 取消动画帧
+    this.decelerationId = null;   // 清除动画ID
+  }
+}