D3 拖拽行为实战指南：深入 d3-drag 的坐标系统、事件生命周期与自定义交互设计

d3-drag 是 D3 交互体系的基石之一，它用一套统一的行为（behavior）抽象封装了“按下、拖动、释放”的完整手势，屏蔽了鼠标与触摸输入的差异以及浏览器怪癖。本文基于当前仓库的 d3-drag 官方文档 展开，覆盖从行为创建、应用、坐标系统设定，到 subject 判定、事件字段解析与原生事件映射的全部 API 细节，并结合仓库中的依赖与构建结构说明 d3-drag 在 D3 全家桶中的位置，帮助读者在力导向图、画板绘图、Canvas 交互等场景中写出可复制、可运行的拖拽代码。

什么是 d3-drag：一个与 DOM 无关的手势抽象

拖放（drag-and-drop）是最常见的空间交互方式：将指针移到某个对象上，按住抓起，把对象“拖”到新位置，再松开“放下”。d3-drag 提供的拖拽行为正是对这种交互的灵活抽象，典型用法包括：

• 拖拽力导向图中的节点；
• 拖拽碰撞模拟（colliding circles）中的圆；
• 在散点图中套索（lasso）选取元素，或在画布上绘制线条；
• 与 d3-zoom 等其它行为组合使用，实现拖拽与缩放并存。

从文档的定位看，d3-drag 有两个关键设计特点：

1. DOM 无关性：行为本身不假设你操作的是 SVG 元素，它可以用于 SVG、HTML，甚至 Canvas 绘图。你还可以叠加高级选取技术，例如 Voronoi 覆盖层或最近目标搜索，来扩大“可拖拽热区”。
2. 输入统一性：行为内部同时处理鼠标与触摸事件，规避浏览器的不一致行为。文档同时指出，该行为未来还将支持 Pointer Events。

理解了这两点，就能理解 d3-drag 全部 API 的设计动机：container 定义“在哪套坐标系里测量”、subject 定义“被拖的是什么”、filter 定义“哪些事件才算开始拖拽”。

创建并应用拖拽行为：drag() 与 selection.call

d3.drag() 创建一个新的拖拽行为。返回的对象既是一个对象又是一个函数，通常通过 selection.call 应用到选中的元素上：

const drag = d3.drag();

drag(selection) 将该行为应用到指定 selection。通常不直接调用它，而是经由 selection.call。例如，实例化拖拽行为并应用到选区：

d3.selectAll(".node").call(d3.drag().on("start", started));

这里有两个值得注意的实现细节：

• 监听器命名空间为 .drag。行为内部使用 selection.on 绑定拖拽所需的监听器，且监听器统一使用 .drag 名称。因此，可以通过 selection.on(".drag", null) 解除拖拽行为：

selection.on(".drag", null);

• iOS 点击高亮的处理。应用拖拽行为时，行为会把 -webkit-tap-highlight-color 样式设置为 transparent，以禁用 iOS 上的 tap 高亮。如果你希望使用别的 tap 高亮颜色，需要在应用行为之后移除或重新设置该样式。

坐标系统：drag.container()

拖拽事件的 event.x 与 event.y 并不是屏幕坐标，而是相对于**容器（container）**坐标系的坐标。container 决定了手势坐标系的参照物：容器访问器返回的元素随后会传给 pointer 来计算指针的局部坐标。

默认容器访问器返回“发起输入事件的那个元素”的父节点：

function container() {
  return this.parentNode;
}

对于通常相对父元素定位的 SVG 或 HTML 元素，这个默认值是合适的。但如果你要拖拽的是 Canvas 中的图形，更常见的做法是把容器重新定义为发起元素本身：

function container() {
  return this;
}

容器也可以直接传元素对象，例如 drag.container(canvas)。

实践含义：当你的绘制坐标系（比如经过缩放/平移的 SVG viewBox、或 Canvas 逻辑坐标）与 DOM 结构不同时，一定要显式设置 container，否则 event.x/y 的参照系会和你预期的位置不一致。

哪些事件能触发拖拽：drag.filter()

drag.filter(filter) 设置事件过滤器；不传参时返回当前过滤器，默认为：

function filter(event) {
  return !event.ctrlKey && !event.button;
}

如果过滤器返回假值，发起事件将被忽略，不会开始任何拖拽手势。默认过滤器忽略了辅助鼠标按键的 mousedown 事件——因为这些按键通常用于其它用途（例如触发右键上下文菜单）。当你需要让拖拽只响应特定按键、中键、特定修饰键，或只响应某个图形内部的指针位置时，就通过 filter 自定义这一判定。

判定被拖对象：drag.subject()

subject（被拖主体）代表“正在被拖的东西”，它在收到发起输入事件（mousedown / touchstart）时立即计算，随后暴露为每次拖拽事件的 event.subject。默认访问器为：

function subject(event, d) {
  return d == null ? {x: event.x, y: event.y} : d;
}

也就是说：

• 被拖元素的 datum 存在时，默认 subject 就是该 datum（拖 SVG 圆时就是那个圆的数据）；
• datum 为 undefined 时，会创建一个表示指针坐标的对象 {x: event.x, y: event.y}；
• 对 Canvas 而言，无论点在哪里，默认 subject 都是整个 canvas 元素的 datum——这种场景下自定义 subject 访问器才更合适。

一个经典的 Canvas 用例：从一组圆中挑出鼠标给定搜索半径内最近的那个作为被拖对象：

function subject(event) {
  let n = circles.length,
      i,
      dx,
      dy,
      d2,
      s2 = radius * radius,
      circle,
      subject;

  for (i = 0; i < n; ++i) {
    circle = circles[i];
    dx = event.x - circle.x;
    dy = event.y - circle.y;
    d2 = dx * dx + dy * dy;
    if (d2 < s2) subject = circle, s2 = d2;
  }

  return subject;
}

当元素数量很大时，上述线性查找可以用 quadtree.find、simulation.find 或 delaunay.find 加速，避免每帧拖拽都遍历全部元素。

使用 subject 时有几条硬性约定：

• 返回的 subject 必须暴露 x 和 y 属性，这样拖拽过程中才能保持 subject 与指针之间的相对位置（即“抓在圆上哪一点就保持哪个偏移”）。
• subject 为 null 或 undefined 时，该指针不会开始拖拽手势；但同一时刻其它触点仍可能各自发起手势。
• 手势一旦开始，subject 不可再更改。
• subject 访问器以与 selection.on 监听器相同的上下文和参数被调用：当前事件（event）、datum（d），this 为当前 DOM 元素。在访问器求值期间，event 是一个 beforestart 拖拽事件，可以通过 event.sourceEvent 访问发起的原始输入事件，通过 event.identifier 访问触摸标识符；event.x 与 event.y 相对于 container 计算，且经由 pointer 求得。

抑制误触发点击：drag.clickDistance()

drag.clickDistance(distance) 设置 mousedown 与 mouseup 之间鼠标允许移动的最大距离：一旦移动距离大于或等于该阈值，mouseup 之后跟随的 click 事件就会被抑制。不传参时返回当前阈值，默认为 0。该距离以 client 坐标（event.clientX / event.clientY）度量。

它的价值在于区分“拖拽”和“点击”：当拖拽结束时不希望再触发一次点击事件（例如误触发选中、切换类名），可调大该阈值让微小的抖动不产生 click，同时保留真正的点击交互。

注册事件：drag.on() 与临时监听器 event.on()

drag.on(typenames, listener) 为指定的类型注册监听器。typenames 是由空白符分隔的一个或多个 typename；每个 typename 由 type 组成，可附加 . 和 name（如 drag.foo 与 drag.bar），name 允许为同一 type 注册多个监听器。合法的 type 只有三种：

• start - 新的指针变为活动状态后（mousedown 或 touchstart）；
• drag - 活动指针移动后（mousemove 或 touchmove）；
• end - 活动指针变为非活动状态后（mouseup、touchend 或 touchcancel）。

类型注册与回调管理的更多规则详见 dispatch.on。每个 listener 被调用时的上下文与 selection.on 监听器一致：参数为当前事件（event）和 datum d，this 为当前 DOM 元素。

这里有两个高频陷阱，文档中特别强调：

1. 拖拽过程中用 drag.on 修改的监听器不会影响正在进行的手势。要修改当前手势的监听行为，必须使用 event.on——它还能帮你为当前手势注册“临时”监听器。
2. 拖拽期间每个活动指针单独派发事件。比如两根手指同时拖两个对象时，即使两个手指同时落下，start 事件也会各派发一次。

event.on(typenames, listener) 等价于 drag.on，但只作用于当前拖拽手势：手势开始前，当前拖拽监听器的一份副本会被创建并绑定到该手势，event.on 修改的是这份副本。一个惯用模式是在 start 监听器里用闭包注册临时的 drag / end 监听器：

function started(event) {
  const circle = d3.select(this).classed("dragging", true);
  const dragged = (event, d) => circle.raise().attr("cx", d.x = event.x).attr("cy", d.y = event.y);
  const ended = () => circle.classed("dragging", false);
  event.on("drag", dragged).on("end", ended);
}

这个例子里，dragged 把 datum 的 x、y 直接更新为 event.x、event.y，并顺带用 raise() 把被拖的圆置顶，是“移动 SVG 元素”最紧凑的写法。

原生拖拽的抑制与恢复：dragDisable / dragEnable

拖拽期间浏览器可能触发原生拖放或文本选中，干扰自定义交互。d3-drag 提供成对工具函数：

• dragDisable(window)：阻止指定窗口上的原生拖放和文本选中。在不阻止 mousedown 默认行为的场景下，它通过在受支持浏览器中捕获 dragstart 与 selectstart 事件、阻止其默认行为并立即停止冒泡来工作；在不支持 selection 事件的浏览器中，则把 document 元素的 user-select CSS 属性设为 none。
• dragEnable(window, noclick)：恢复原生拖放和文本选中，即撤销 dragDisable 的效果。若 noclick 为 true，还会临时抑制 click 事件——这种抑制在一个 0 毫秒超时后过期，因此只会抑制紧跟当前 mouseup 之后的那次 click（如果有的话）。

使用约定是：在 mousedown 时调用 dragDisable，在 mouseup 时调用 dragEnable。

拖拽事件对象与原生事件映射表

拖拽事件监听器被调用时，第一个参数是当前拖拽事件对象 event，其字段如下：

字段	含义
target	关联的拖拽行为对象
type	字符串 "start"、"drag" 或 "end"
subject	被拖主体，由 drag.subject 定义
x / y	subject 的新 x / y 坐标（相对于 container）
dx / dy	自上一次拖拽事件以来 x / y 坐标的增量
identifier	字符串 "mouse"，或数字形式的触摸 identifier
active	当前活动拖拽手势的数量（start/end 时均不含本次事件自身）
sourceEvent	底层输入事件，如 mousemove 或 touchmove

其中 event.active 在多手势并发场景下尤其有用：第一个手势开始、以及最后一个手势结束时它都等于 0，可据此做“初始化/收尾”逻辑（例如显示或隐藏辅助 UI）。

下面是拖拽行为如何解释原生事件的完整映射表：

Event	Listening Element	Drag Event	Default Prevented?
mousedown⁵	selection	start	no¹
mousemove²	window¹	drag	yes
mouseup²	window¹	end	yes
dragstart²	window	-	yes
selectstart²	window	-	yes
click³	window	-	yes
touchstart	selection	start	no⁴
touchmove	selection	drag	yes
touchend	selection	end	no⁴
touchcancel	selection	end	no⁴

脚注说明（对应原文档注释编号）：

1. ¹ 必须在 window 上监听才能捕获 iframe 外部的指针移动事件。
2. ² 仅适用于活动中的鼠标手势期间。
3. ³ 仅适用于某些鼠标手势结束之后立即发生的 click；受 drag.clickDistance 控制。
4. ⁴ touch 事件不阻止默认行为，是为了允许触摸输入上的 click 模拟（click emulation）。
5. ⁵ mousedown 若发生在一次触摸手势结束后的 500ms 内会被忽略（假设存在 click 模拟）。

所有被消费的（consumed）事件传播都会被立即停止（stopImmediatePropagation）。如果想让某些事件不发起拖拽手势，应使用 drag.filter 而不是修改事件传播。

仓库视角：d3-drag 在 D3 主仓库中的组织方式

从当前仓库的源码结构看，d3-drag 以独立 npm 包的形式集成进 D3 主包，而非内联在主仓库中：

• package.json 的 dependencies 中声明了 "d3-drag": "^3.0.0"（与 d3-selection、d3-zoom、d3-dispatch 等同为 v3 主线的模块），主包版本为 7.9.0；
• src/index.js 通过 export * from "d3-drag"; 一行将其全部 API 汇入 D3 命名空间，因此文档中所有 d3.drag()、d3.dragDisable() 等调用来自该统一出口；
• bundle.js 进一步把 src/index.js 与版本号重新导出，rollup.config.js 则将其打包为 dist/d3.js（UMD）、dist/d3.mjs（ESM）与 dist/d3.min.js（压缩版）三种产物。

这一结构意味着：文档中每个 API 标注的 “Source”（d3-drag 仓库的 src/drag.js、src/nodrag.js、src/event.js）对应独立模块内部的实现文件；而当前主仓库提供的是文档站与聚合构建。阅读 d3-drag 文档 时，可以结合 d3-selection 事件文档（pointer、selection.on）、d3-dispatch 文档 中引用的派发机制，以及 d3-force、d3-zoom 等交互模块，形成完整的 D3 交互知识图谱。

小结

d3-drag 的 API 数量不多，但每个方法都对应拖拽交互中一个明确的决策点：container 决定坐标系、subject 决定被拖对象、filter 决定手势是否开始、clickDistance 决定拖拽后是否吞掉 click、event.on 决定当前手势内的临时行为。掌握这些默认值（父节点容器、datum 主体、!ctrlKey && !button 过滤、0 像素点击阈值）及其修改方式，就能覆盖从 SVG 节点拖拽到 Canvas 最近目标选取、再到多点触摸并发手势的绝大多数交互需求。