处理事件

¥Handling events

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

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

selection.on(typenames, listener, options) {#selection_on}

源代码 · 为每个选定元素添加或移除指定事件类型名的监听器。

¥Source · Adds or removes a listener to each selected element for the specified event typenames.

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

typenames 是一个字符串事件类型，例如 click、mouseover 或 submit；可以使用浏览器支持的任何 DOM 事件类型。类型后面可以可选地跟一个句点 (.) 和一个名称；可选名称允许注册多个回调以接收相同类型的事件，例如 click.foo 和 click.bar。要指定多个类型名称，请使用空格分隔类型名称，例如 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.

当在选定元素上调度指定事件时，将为该元素评估指定的监听器，并传递当前事件 (event) 和当前数据 (d)，并将其作为当前 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.

如果先前已在选定元素上为相同类型名称注册了事件监听器，则在添加新监听器之前，会先移除旧监听器。要删除监听器，请将监听器设置为 null。要删除给定名称的所有监听器，请将 null 作为监听器传递，并将 .foo 作为类型名称传递，其中 foo 是名称；要移除所有没有名称的监听器，请指定 . 作为类型名称。

¥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.

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

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

如果未指定监听器，则返回当前已分配的监听器，该监听器针对第一个（非空）选定元素（如果有）。如果指定了多个 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) {#selection_dispatch}

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

¥Source · Dispatches a custom event of the specified type to each selected element, in order.

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

可以指定一个可选的参数对象，用于设置事件的其他属性。它可能包含以下字段：

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

• bubbles - 如果为 true，则事件将按树的反向顺序发送给祖级节点。

  ¥bubbles - if true, the event is dispatched to ancestors in reverse tree order.

• cancelable - 如果为 true，则允许使用 event.preventDefault。

  ¥cancelable - if true, event.preventDefault is allowed.

• detail - 与事件关联的任何自定义数据。

  ¥detail - any custom data associated with the event.

如果参数是一个函数，则按顺序为每个选定元素计算该函数的值，传递当前数据 (d)、当前索引 (i) 和当前组 (nodes)，并将此作为当前 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] 的双元素数组，表示指定事件相对于指定目标的坐标。

¥Source · Returns a two-element array of numbers [x, y] representing the coordinates of the specified event relative to the specified target.

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

事件可以是 MouseEvent、PointerEvent、接触，也可以是将 UIEvent 作为 event.sourceEvent 的自定义事件。

¥event can be a MouseEvent, a PointerEvent, a Touch, or a custom event holding a UIEvent as event.sourceEvent.

如果未指定目标，则默认为源事件的 currentTarget 属性（如果有）。如果目标是 SVG 元素，则事件坐标将使用 屏幕坐标变换矩阵 的 inverse 进行转换。如果目标是 HTML 元素，则事件坐标将相对于目标 边界客户矩形 的左上角进行平移。（因此，坐标系只能相对于客户端坐标进行平移。另请参阅 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.

pointers(event, target)

源代码 · 返回一个 [[x0, y0], [x1, y1]…] 数组，其中包含指定事件指针位置相对于指定目标的坐标。

¥Source · Returns an array [[x0, y0], [x1, y1]…] of coordinates of the specified event’s pointer locations relative to the specified target.

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.

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

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