D3

处理事件 ​

🌐 Handling events

对于交互，选择允许监听和调度事件。

🌐 For interaction, selections allow listening for and dispatching of events.

selection.on(typenames, listener, options) ​

来源 · 为每个选定元素添加或移除指定事件 typenames 的监听器。

js
d3.selectAll("p").on("click", (event) => console.log(event))

typenames 是一个字符串事件类型，例如 click、mouseover 或 submit；可以使用浏览器支持的任何 DOM 事件类型。类型后可以可选地跟一个句点（.）（.）和一个名称；可选名称允许为同一类型的事件注册多个回调，例如 click.foo 和 click.bar。要指定多个 typenames，请用空格分隔 typenames，例如 input change 或 click.foo click.bar。

🌐 The typenames is a string event type, such as click, mouseover, or submit; any DOM event type supported by your browser may be used. The type may be optionally followed by a period (.) and a name; the optional name allows multiple callbacks to be registered to receive events of the same type, such as click.foo and click.bar. To specify multiple typenames, separate typenames with spaces, such as input change or click.foo click.bar.

当在选定元素上派发指定事件时，指定的 listener 将被对该元素进行评估，传入当前事件 (event) 和当前数据 (d)，并且 this 为当前 DOM 元素 (event.currentTarget)。监听器总是看到其元素的最新数据。注意：虽然你可以直接使用 event.pageX 和 event.pageY，但通常将事件位置转换到接收事件的元素的本地坐标系中使用 d3.pointer 会更加方便。

🌐 When a specified event is dispatched on a selected element, the specified listener will be evaluated for the element, being passed the current event (event) and the current datum (d), with this as the current DOM element (event.currentTarget). Listeners always see the latest datum for their element. Note: while you can use event.pageX and event.pageY directly, it is often convenient to transform the event position to the local coordinate system of the element that received the event using d3.pointer.

如果在所选元素上之前已经为同一个 typename 注册了事件监听器，则在添加新监听器之前会先移除旧监听器。要移除监听器，请将 listener 传递为 null。要移除给定名称的所有监听器，请将 listener 传递为 null，并将 .foo 作为 typename，其中 foo 是名称；要移除所有未命名的监听器，请将 . 指定为 typename。

🌐 If an event listener was previously registered for the same typename on a selected element, the old listener is removed before the new listener is added. To remove a listener, pass null as the listener. To remove all listeners for a given name, pass null as the listener and .foo as the typename, where foo is the name; to remove all listeners with no name, specify . as the typename.

可选的 options 对象可以指定事件监听器的特性，例如它是捕获还是被动；参见 element.addEventListener。

🌐 An optional options object may specify characteristics about the event listener, such as whether it is capturing or passive; see element.addEventListener.

如果未指定listener，则返回在第一个（非空）选定元素上为指定事件typename分配的当前监听器（如果有）。如果指定了多个类型名，则返回第一个匹配的监听器。

🌐 If a listener is not specified, returns the currently-assigned listener for the specified event typename on the first (non-null) selected element, if any. If multiple typenames are specified, the first matching listener is returned.

selection.dispatch(type, parameters) ​

来源 · 按顺序向每个选定的元素分发指定 类型 的自定义事件。

js
d3.select("p").dispatch("click")

可以指定一个可选的 parameters 对象来设置事件的附加属性。它可能包含以下字段：

🌐 An optional parameters object may be specified to set additional properties of the event. It may contain the following fields:

  • bubbles - 如果为真，事件将按树的反向顺序分发给祖级。
  • cancelable - 如果为真，event.preventDefault 是允许的。
  • detail - 与该事件相关的任何自定义数据。

如果 parameters 是一个函数，它会对每个被选中的元素依次进行求值，并传入当前数据 (d)、当前索引 (i) 和当前组 (nodes)，其中 this 为当前 DOM 元素 (nodes[i])。它必须返回当前元素的参数。

🌐 If parameters is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). It must return the parameters for the current element.

pointer(event, target) ​

来源 · 返回一个包含两个元素的数字数组 [x, y]，表示相对于指定 target 的指定 event 的坐标。

js
const [x, y] = d3.pointer(event);

event 可以是 MouseEvent、PointerEvent、Touch，或者包含 UIEvent 作为 event.sourceEvent 的自定义事件。

如果未指定 target，则默认为源事件的 currentTarget 属性（如果可用）。如果 target 是 SVG 元素，则使用 屏幕坐标变换矩阵 的 逆 转换事件的坐标。如果 target 是 HTML 元素，则事件的坐标相对于 target 的 边界客户端矩形 的左上角进行平移。（因此，坐标系统只能相对于客户端坐标进行平移。另见 GeometryUtils。）否则，返回 [event.pageX, event.pageY]。

🌐 If target is not specified, it defaults to the source event’s currentTarget property, if available. If the target is an SVG element, the event’s coordinates are transformed using the inverse of the screen coordinate transformation matrix. If the target is an HTML element, the event’s coordinates are translated relative to the top-left corner of the target’s bounding client rectangle. (As such, the coordinate system can only be translated relative to the client coordinates. See also GeometryUtils.) Otherwise, [event.pageX, event.pageY] is returned.

指针(event, target) ​

🌐 pointers(event, target)

来源 · 返回一个数组 [[x0, y0], [x1, y1]…]，包含指定 event 的指针相对于指定 target 的位置坐标。

js
const points = d3.pointers(event);

对于触摸事件，返回的位置数组对应于 event.touches 数组；对于其他事件，则返回一个单元素数组。

🌐 For touch events, the returned array of positions corresponds to the event.touches array; for other events, returns a single-element array.

如果未指定 target，则默认为源事件的 currentTarget 属性（如果有的话）。

🌐 If target is not specified, it defaults to the source event’s currentTarget property, if any.