Кастомные события в 1С-Битрикс: BX.addCustomEvent — руководство с живыми примерами

В этой статье мы рассмотрим, как можно использовать BX.addCustomEvent для улучшения взаимодействия между различными компонентами системы, что позволяет создавать более модульные и гибкие решения.

Зачем нужны кастомные события

JavaScript-ядро Битрикса генерирует собственные события и позволяет «подписываться» на них. Это снимает жёсткое связывание модулей: логика разносится по обработчикам, а не прячется в глубине компонентов.

Сигнатуры BX.addCustomEvent

handler — функция, внутри которой this содержит объект, переданный через BX.proxy, BX.delegate или bind.

Как вывести все события без правки ядра

Править /bitrix/js/main/core/core.js рискованно: обновление затрёт правки. Используйте обёртку-патч:

if (!window.__BX_EVENTS_DUMPED) {
  window.__BX_EVENTS_DUMPED = true;
  const original = BX.onCustomEvent;
  BX.onCustomEvent = function (target, name, params, secure) {
    const realName = typeof target === 'string' ? target : name;
    console.info('%c[EVENT]', 'color:#0af', realName, params);
    return original.apply(this, arguments);
  };
}

Удалите патч после диагностики, чтобы консоль не «шумела».

Где хранить и как подключать скрипт

1. Создайте собственное расширение ядра

   /local/js/mytools/custom_events
   ├─ dist/
   │   └─ index.js      // итоговый бандл
   └─ config.php        // описание
   

2. config.php

   <?php
   return [
       'js'  => 'dist/index.js',
       'rel' => ['main.core', 'pull.client'],
   ];

3. Подключение

   \CJSCore::Init(['mytools.custom_events']);

Расширения устойчивы к композитному кешу и единообразно подключаются в любом шаблоне.

Практические рецепты

Расширяем список шрифтов визуального редактора

import { ready } from 'main.core';
ready(() => {
  BX.addCustomEvent('GetFontFamilyList', fonts => {
    ['Inter','Rubik','Manrope'].forEach(f => fonts.push({ value: f, name: f }));
    (window.APP_FONTS || []).forEach(f => fonts.push({ value: f, name: f }));
  });
});

Что получить: новые шрифты появляются в выпадающем списке редактора (bitrix:main.post.form, e-mail-шаблоны, письма CRM).

Обновляем пользовательский счётчик в реальном времени через PULL

Сервер (пример)

\Bitrix\Pull\Event::add($userId, [
  'module_id' => 'main',
  'command'   => 'user_counter',
  'expiry'    => 3600,
  'params'    => [SITE_ID => ['MY_COUNTER' => 7]],
]);

Клиент

BX.addCustomEvent('onPullEvent-main', (cmd, params) => {
  if (cmd === 'user_counter') {
    const value = params[BX.message('SITE_ID')]?.MY_COUNTER;
    if (value !== undefined) {
      BX('my-counter').textContent = value;
      BX.ajax.runAction('my:module.Hit', { data:{v:value} });
    }
  }
});

«Живая» корзина на странице оформления заказа

BX.addCustomEvent('OnBasketChange', () => {
  const cmp = window.BX?.Sale?.OrderAjaxComponent;
  if (cmp) cmp.sendRequest('refreshOrderAjax');
});

Любое изменение в компоненте корзины мгновенно перерисует блок sale.order.ajax.

Отладка PULL-команд своего модуля

const dump = ({ command, params }) =>
  console.dir({ MODULE: 'my_module', command, params });
BX.addCustomEvent('onPullEvent-my_module', dump);   // desktop
BX.addCustomEvent('onPull-my_module', dump);        // mobile

Хук после успешной загрузки файла (bitrix:main.file.input)

BX.addCustomEvent('FileInput:afterUpload', res => {
  if (res?.success) {
    BX.UI.Notification.Center.notify({ content: 'Файл загружен!' });
  }
});

Кастомное оформление чекбоксов после Ajax-перерисовки

BX.addCustomEvent('onAjaxSuccess', () => {
  document.querySelectorAll('.checkbox, .radio').forEach(el => {
    if (!el.dataset.rendered) {
      el.dataset.rendered = 1;
      el.insertAdjacentHTML('afterend',
        ``);
    }
  });
});

Снятие подписок (SPA, Vue, React)

export default {
  mounted() {
    this.onGridReady = this.onGridReady.bind(this);
    BX.addCustomEvent('Grid::ready', this.onGridReady);
  },
  beforeUnmount() {
    BX.removeCustomEvent('Grid::ready', this.onGridReady);
  },
  methods: {
    onGridReady(grid) { /* … */ },
  },
};

Чек-лист внедрения

1. Не править ядро — используйте расширения.
2. Именовать события через namespace: CRM.Stage:change, Grid::ready.
3. Следить за this: BX.proxy, BX.delegate, bind.
4. Собирать фронт (Webpack/Vite) в /local/js.
5. Отписываться в SPA для предотвращения утечек памяти.

Итог

BX.addCustomEvent — универсальный механизм, который:

• расширяет стандартный функционал без форка ядра;
• делает возможной реакцию на PULL-события в реальном времени;
• связывает кастомные модули на одной странице.

Используйте его осознанно, держите код модульным — и ваш фронтенд в 1С-Битрикс станет гибче и отзывчивее. Успехов в продакшене!