addEventListener 是標準 DOM 事件註冊方法,支援捕獲/冒泡兩階段、多處理器、選項物件。取代舊式 onclick 屬性與 attachEvent (IE)。
target.addEventListener(type, listener[, options]);
target.addEventListener(type, listener[, useCapture]); // 舊版第三參數
| 參數 | 型別 | 說明 |
|---|---|---|
| type | String | 事件名稱,如 'click', 'keydown', 'customEvent' |
| listener | Function / EventListener | 事件處理函式,接收 Event 物件 |
| options (現代) | Object | { capture: Boolean, once: Boolean, passive: Boolean, signal: AbortSignal } |
| useCapture (舊) | Boolean | true=捕獲階段觸發,false=冒泡階段觸發 (預設) |
true 在捕獲階段 (由外而內) 呼叫,false 在冒泡階段 (由內而外)。true 執行一次後自動移除監聽器 (等同 one)。true 宣告處理器不會呼叫 preventDefault(),瀏覽器可優化滾動效能 (觸控/滾輪事件預設 true)。AbortSignal,配合 AbortController 統一移除多個監聽器。捕獲階段:window → document → html → body → ... → 目標父層 目標階段:目標元素 (捕獲與冒泡皆會執行目標元素監聽器) 冒泡階段:目標父層 → ... → body → html → document → window
var btn = document.getElementById('btn');
document.addEventListener('click', () => console.log('document 捕獲'), true); // 1
document.addEventListener('click', () => console.log('document 冒泡'), false); // 4
btn.addEventListener('click', () => console.log('btn 捕獲'), true); // 2
btn.addEventListener('click', () => console.log('btn 冒泡'), false); // 3
// 點擊 btn 輸出順序:1 → 2 → 3 → 4
// 基本綁定
btn.addEventListener('click', handleClick);
// 單次執行
btn.addEventListener('click', handleClick, { once: true });
// 捕獲階段攔截 (如全域快捷鍵)
document.addEventListener('keydown', handleShortcut, { capture: true });
// 被動監聽器 (滾動效能優化)
window.addEventListener('touchmove', onScroll, { passive: true });
// AbortController 批次移除
const controller = new AbortController();
btn.addEventListener('click', handler, { signal: controller.signal });
window.addEventListener('resize', handler, { signal: controller.signal });
controller.abort(); // 一次移除所有
btn.removeEventListener('click', handleClick); // 必須傳入相同函式參考
// 匿名函式無法移除,需保存參考
function addEvent(el, type, fn) {
if (el.addEventListener) {
el.addEventListener(type, fn, false);
} else if (el.attachEvent) {
el.attachEvent('on' + type, fn); // this 指向 window,需用 call
} else {
el['on' + type] = fn;
}
}