interact.js 迁移指南：从 v1.2 升级到最新版本

interact.js 迁移指南：从 v1.2 升级到最新版本

interact.js JavaScript drag and drop, resizing and multi-touch gestures with inertia and snapping for modern browsers (and also IE9+) 项目地址: https://gitcode.com/gh_mirrors/in/interact.js

前言

interact.js 是一个强大的 JavaScript 库，用于处理拖放、调整大小和多点触控手势等交互操作。随着版本迭代，v1.2 之后的新版本引入了多项改进和新特性。本文将为开发者提供详细的迁移指南，帮助您顺利升级到最新版本。

主要变更概述

最新版本主要包含以下改进：

• 修复了多个已知问题
• 支持基于每个动作设置更多选项
• 为 pointerEvents 添加了新的配置选项
• 新增了多个方法和选项

核心变更详解

1. 基于动作的修饰器数组

新版本重构了修饰器（modifiers）的使用方式，使其更加模块化和可重用。

旧版 vs 新版实现对比

旧版实现：

interact(target)
  .draggable()
  .restrict({ restriction: 'parent' })
  .snap({ targets: [interact.snappers.grid({ x: 100, y: 100 })] });

新版实现：

const restrictToParent = interact.modifiers.restrict({
  restriction: 'parent',
  elementRect: { left: 0, right: 0, top: 1, bottom: 1 }
});

const snap100x100 = interact.modifiers.snap({
  targets: [interact.snappers.grid({ x: 100, y: 100 })],
  relativePoints: [{ x: 0.5, y: 0.5 }]
});

interact(target).draggable({
  modifiers: [restrictToParent, snap100x100]
});

优势分析

1. 更好的代码组织：修饰器配置可以独立定义和复用
2. 明确的执行顺序：数组顺序决定了修饰器的应用顺序
3. 更强的类型安全：每个修饰器都有明确的类型定义

2. 改进的调整大小（resize）功能

新版本为调整大小操作提供了更精细的控制选项。

限制类型增强

• restrict：基于指针坐标的限制
• restrictRect：基于元素矩形的限制
• restrictSize（仅调整大小）：基于元素尺寸的限制
• restrictEdges（仅调整大小）：基于元素边缘的限制

对齐功能增强

• snap：适合拖拽操作的指针坐标对齐
• snapSize（仅调整大小）：设置目标元素尺寸的对齐点
• snapEdges：设置目标元素边缘位置的对齐点

示例代码

interact(target).resize({
  edges: { bottom: true, right: true },
  snapSize: {
    targets: [interact.snappers.grid({ x: 25, y: 25, range: Infinity })]
  },
  restrictSize: {
    min: { width: 100, height: 50 }
  },
  restrictEdges: {
    outer: 'parent',
    endOnly: true
  }
});

3. 宽高比修饰器

新版将 preserveAspectRatio 和 square 选项整合为更灵活的 aspectRatio 修饰器。

基本用法

interact(target).resizable({
  edges: { left: true, bottom: true },
  modifiers: [
    interact.modifiers.aspectRatio({
      ratio: 'preserve',  // 保持初始宽高比
      modifiers: [interact.modifiers.restrictSize({ max: 'parent' })]
    })
  ]
});

正方形调整

interact(target).resizable({
  modifiers: [
    interact.modifiers.aspectRatio({
      equalDelta: true  // 替代旧版的 square 选项
    })
  ]
});

4. 已移除的方法

下表列出了已移除的方法及其替代方案：

| 已移除方法 | 替代方案 | |------------|----------| | interactable.squareResize(bool) | interact.modifiers.aspectRatio({ equalDelta: true }) | | interactable.snap({ actions: ['drag'], ... }) | interact.modifiers.snap(snapOptions) | | interactable.restrict(restrictOptions) | interact.modifiers.restrict(restrictOptions) | | interactable.inertia(true) | interactable.draggable({ inertia: true }) | | interactable.accept('.can-be-dropped') | interactable.dropzone({ accept: '.can-be-dropped' }) | | interact.margin(50) | interactable.resizable({ margin: 50 }) |

5. 动作结束事件的 dx/dy 变更

在 dragend、resizeend 和 gestureend 事件中，dx 和 dy 字段的含义发生了变化。

旧版行为：表示开始和结束坐标的差值
新版行为：始终为 0（表示最后移动事件与结束事件的差值）

正确获取总位移的方法：

interact(target).draggable({
  onend: function(event) {
    const totalDx = event.pageX - event.X0;
    const totalDy = event.pageY - event.Y0;
    console.log(totalDx, totalDy);
  }
});

6. 放置事件顺序变更

事件触发顺序调整：

1. 先触发 dragend 事件
2. 再触发 drop 事件

获取放置区域元素：

interact(target).on('dragend', function(event) {
  if (event.relatedTarget) {
    console.log('Will drop on:', event.relatedTarget);
  }
});

7. 鼠标按钮控制

默认情况下，只有左键可以触发交互动作。通过 mouseButtons 选项可以修改此行为。

示例：

interact(target).draggable({
  mouseButtons: ['left', 'middle']  // 允许左键和中键触发拖拽
});

迁移建议

1. 逐步替换：先替换已弃用的方法，再逐步采用新特性
2. 测试验证：特别注意事件顺序和坐标计算的变化
3. 性能优化：利用修饰器的可重用性减少重复代码
4. 文档参考：详细查阅新版本的API文档

结语

interact.js 的最新版本通过更模块化的设计和更精细的控制选项，为开发者提供了更强大的交互处理能力。本文介绍的迁移要点将帮助您顺利过渡到新版本，充分利用这些改进特性。在迁移过程中遇到任何问题，建议参考详细的变更日志和社区讨论。

interact.js JavaScript drag and drop, resizing and multi-touch gestures with inertia and snapping for modern browsers (and also IE9+) 项目地址: https://gitcode.com/gh_mirrors/in/interact.js