處理事件

對於互動，選擇允許監聽和發送事件。

selection.on(typenames, listener, options)

原始碼 · 為每個選取的元素新增或移除一個listener，以監聽指定的事件typenames。

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。

當在選取的元素上發送指定的事件時，指定的listener 將會針對該元素進行評估，並傳遞目前的事件 (event) 和目前的資料 (d)，其中 this 為目前的 DOM 元素 (event.currentTarget)。監聽器總是會看到其元素的最新資料。注意：雖然你可以直接使用 event.pageX 和 event.pageY，但通常會很方便使用 d3.pointer 將事件位置轉換為接收事件的元素的本地座標系統。

如果先前已為選取的元素的相同typename 註冊事件監聽器，則會在新增新的監聽器之前移除舊的監聽器。若要移除監聽器，請將 listener 傳遞為 null。若要移除具有特定名稱的所有監聽器，請將 listener 傳遞為 null，並將 typename 傳遞為 .foo，其中 foo 是名稱；若要移除所有沒有名稱的監聽器，請將 typename 指定為 .。

一個可選的 選項 物件可以指定事件監聽器的特性，例如它是捕獲還是被動的；請參閱 element.addEventListener。

如果未指定 監聽器，則傳回在第一個（非空值）選取元素（如果有的話）上指定事件 類型名稱 的當前已指派監聽器。如果指定多個類型名稱，則傳回第一個匹配的監聽器。

selection.dispatch(type, parameters)

來源 · 依序將指定 類型 的 自訂事件 分派到每個選取的元素。

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

可以指定一個可選的 參數 物件來設定事件的其他屬性。它可能包含以下欄位

• bubbles - 如果為 true，則事件會依逆向樹狀順序分派到祖先。
• cancelable - 如果為 true，則允許 event.preventDefault。
• detail - 與事件相關的任何自訂資料。

如果 參數 是函式，則會依序針對每個選取的元素評估它，傳遞目前的資料（d）、目前的索引（i）和目前的群組（節點），其中 this 為目前的 DOM 元素（節點[i]）。它必須傳回目前元素的參數。

pointer(event, target)

來源 · 傳回一個由兩個數字 [x, y] 組成的陣列，表示指定 事件 相對於指定 目標 的座標。

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

事件 可以是 MouseEvent、PointerEvent、觸控，或是一個自訂事件，其中包含 UIEvent 作為 event.sourceEvent。

如果未指定 target，則預設為來源事件的 currentTarget 屬性（如果可用）。如果 target 是 SVG 元素，則事件的座標會使用 反函數 轉換 畫面座標轉換矩陣。如果 target 是 HTML 元素，則事件的座標會相對於 target 的 邊界客戶端矩形 的左上角進行轉換。（因此，座標系統只能相對於客戶端座標進行轉換。另請參閱 GeometryUtils。）否則，會傳回 [event.pageX, event.pageY]。

pointers(event, target)

來源 · 傳回指定的 event 指標位置的座標陣列 [[x0, y0], [x1, y1]…]，相對於指定的 target。

const points = d3.pointers(event);

對於觸控事件，傳回的位置陣列會對應到 event.touches 陣列；對於其他事件，則傳回單一元素陣列。

如果未指定 target，則預設為來源事件的 currentTarget 屬性（如果有的話）。