Всплытие и погружение

Когда вы кликаете по кнопке внутри карточки, браузер не зовёт обработчик кнопки напрямую. Сначала он строит путь от window вниз до самой кнопки и проходит его дважды: вниз — это фаза погружения (capturing), затем отмечает цель (target), затем возвращается наверх — фаза всплытия (bubbling).

Обычный addEventListener слушает всплытие. Чтобы попасть в погружение, третьим аргументом передают true или { capture: true }. Проще один раз увидеть порядок, чем запомнить его.

const outer = document.getElementById("outer");
const btn = document.getElementById("btn");

// третий аргумент true — слушатель работает на погружении
outer.addEventListener("click", () => console.log("outer, погружение"), true);
btn.addEventListener("click", () => console.log("btn, цель"));
outer.addEventListener("click", () => console.log("outer, всплытие"));

btn.click();

Всплытие — вторая половина пути, от цели наверх. Внутри обработчика есть два разных элемента: event.target — тот, на котором событие возникло, и event.currentTarget — тот, на котором висит этот самый обработчик. В обычной (не стрелочной) функции второе значение лежит ещё и в this.

const panel = document.getElementById("panel");

panel.addEventListener("click", (event) => {
  console.log(event.target.id);
  console.log(event.currentTarget.id);
  console.log(event.target === event.currentTarget);
});

document.getElementById("save").click();

Всплытие не заканчивается на ближайшем предке: событие поднимается до document и window, задевая по дороге всех, у кого есть подходящий обработчик. target при этом остаётся неизменным, а currentTarget меняется на каждом шаге.

const path = [];

for (const id of ["a", "b", "c"]) {
  document.getElementById(id).addEventListener("click", (event) => {
    path.push(event.currentTarget.id);
  });
}

document.getElementById("c").click();
console.log(path.join(" -> "));

Слушатель с capture: true срабатывает на предке до того, как событие доберётся до цели. Это способ перехватить событие раньше всех: залогировать, отменить, подменить поведение — пока дочерние обработчики ещё не отработали.

Погружение придумал Netscape, всплытие — Internet Explorer. W3C не стал выбирать победителя и склеил обе модели в один маршрут. Отсюда и странный третий аргумент, который годами был просто голым булевым флагом.

const wrap = document.getElementById("wrap");
const go = document.getElementById("go");
const log = [];

wrap.addEventListener("click", (event) => {
  log.push("capture");
  event.stopPropagation();
}, { capture: true });

go.addEventListener("click", () => log.push("target"));

go.click();
console.log(log.join(","));

И важная бытовая деталь: removeEventListener ищет слушатель по трём вещам — тип события, та же самая функция и то же значение capture. Повесили с true, снимаете без него — браузер молча ничего не найдёт.

const ping = document.getElementById("ping");
let count = 0;

ping.addEventListener("click", () => { count += 1; }, { once: true });

ping.click();
ping.click();
console.log(count);

У каждого события есть флаг bubbles. Если он false, обратного подъёма просто не будет: обработчик на предке, повешенный обычным способом, не сработает никогда — и это одна из самых частых причин тихо не работающего кода.

Но есть выход поизящнее списка замен: погружение работает всегда. Флаг bubbles отменяет только подъём — вниз событие проходит в любом случае. Значит, невсплывающее событие всё равно ловится на предке через capture: true.

const box = document.getElementById("box");
const field = document.getElementById("field");
const seen = [];

box.addEventListener("focus", () => seen.push("bubble"));
box.addEventListener("focus", () => seen.push("capture"), true);

console.log(new Event("focus").bubbles);
field.dispatchEvent(new Event("focus"));

console.log(seen.join(","));

Если непонятно, кто и в каком порядке получит событие, спросите у самого события. composedPath() возвращает массив узлов от цели до window — это и есть весь маршрут. eventPhase говорит, в какой фазе сейчас работает обработчик: 1 — погружение, 2 — цель, 3 — всплытие.

document.getElementById("root").addEventListener("click", (event) => {
  const ids = event.composedPath()
    .filter((node) => node.id)
    .map((node) => node.id);

  console.log(ids.join(" -> "));
  console.log(event.eventPhase === Event.BUBBLING_PHASE);
});

document.getElementById("bold").click();

stopPropagation() обрывает маршрут: элементы дальше по пути события не увидят. Пользуйтесь осторожно — обработчик, глушащий всплытие, ломает чужой код на предках, включая делегирование и сторонние виджеты. Отлаживать такое неприятно: код просто не вызывается, ошибок нет. Чем остановка оборачивается на живой странице и чем её заменить, разбирает статья «stopPropagation и когда он вреден».

const one = document.getElementById("one");
const host = document.getElementById("host");
const log = [];

one.addEventListener("click", (event) => {
  log.push("первый");
  event.stopImmediatePropagation();
});
one.addEventListener("click", () => log.push("второй"));
host.addEventListener("click", () => log.push("родитель"));

one.click();
console.log(log.join(","));