Блок: HTML-код и JavaScript

Для чего нужен HTML-блок

HTML-блок позволяет добавить на страницу собственную разметку, стили CSS и интерактивное поведение на JavaScript. Он подходит для небольших виджетов, нестандартных карточек, калькуляторов, переключателей и других элементов, которых нет в каталоге готовых блоков.

Используйте HTML-блок только тогда, когда стандартных блоков недостаточно. Ошибка в пользовательском коде может повлиять на внешний вид или работу опубликованной страницы.

Вкладки блока

HTML и CSS

Во вкладке «HTML и CSS» размещается разметка элемента. CSS можно добавить внутрь тега <style>. Чтобы стили не затронули остальные части сайта, используйте уникальный класс-обёртку и начинайте каждый CSS-селектор с этого класса.

Теги <script>, вставленные в HTML, не выполняются. JavaScript необходимо размещать в отдельной вкладке «JavaScript».

JavaScript

Код из вкладки «JavaScript» запускается только на опубликованном сайте после того, как HTML текущего блока появился в DOM. В редакторе страницы, предпросмотре каталога блоков и окне настройки блока код не запускается.

При загрузке скрипту доступны три переменные:

• root — корневой DOM-элемент текущего HTML-блока. Используйте root.querySelector(...), чтобы работать с элементами именно этого блока.
• block — данные текущего блока, включая id и options.
• site — данные текущего сайта, доступные публичному приложению.

Обычные браузерные объекты window и document также доступны. Переменная root помогает локализовать код, но не является песочницей и технически не ограничивает доступ к остальной странице.

Рабочий пример

Добавьте во вкладку «HTML и CSS»:

<div class="my-click-demo">
  <button type="button" data-demo-button>Показать сообщение</button>
  <p data-demo-result hidden>JavaScript работает!</p>
</div>

Добавьте во вкладку «JavaScript»:

const button = root.querySelector("[data-demo-button]");
const result = root.querySelector("[data-demo-result]");

if (!button || !result) return;

const handleClick = () => {
    result.hidden = false;
    button.textContent = "Готово";
};

button.addEventListener("click", handleClick);

return () => {
    button.removeEventListener("click", handleClick);
};

Сохраните блок и откройте опубликованную страницу. После нажатия на кнопку появится сообщение.

Очистка обработчиков и таймеров

Mobitsa может повторно использовать Vue-компонент при переходе между страницами или заново запускать код после изменения блока. Поэтому скрипт может вернуть функцию очистки. Она вызывается перед повторным запуском и при удалении блока со страницы.

В функции очистки удаляйте всё, что было создано скриптом:

• обработчики событий через removeEventListener;
• таймеры через clearTimeout и clearInterval;
• MutationObserver, ResizeObserver и другие наблюдатели через disconnect();
• добавленные скриптом глобальные DOM-элементы или подписки.

Если скрипт возвращает Promise, Mobitsa дождётся его результата. Promise также может вернуть функцию очистки. Ошибки запуска и очистки перехватываются и записываются в консоль браузера, чтобы пользовательский код не прерывал монтирование Vue-страницы.

Предупреждение о безопасности

JavaScript в HTML-блоке является доверенным кодом владельца сайта, а не изолированным виджетом.

Код имеет доступ к публичной странице, DOM, браузерному хранилищу и сетевым запросам, разрешённым браузером. Ненадёжный сторонний скрипт может прочитать введённые посетителем данные, изменить страницу, перенаправить пользователя, загрузить дополнительный код или замедлить сайт.

• Вставляйте код только из доверенного и проверенного источника.
• Не размещайте в клиентском коде пароли, приватные API-ключи и другие секреты: посетитель может увидеть их в браузере.
• Проверяйте адреса внешних запросов и подключаемых файлов.
• Не используйте бесконечные циклы и тяжёлые синхронные вычисления.
• Не изменяйте глобальные стили и элементы страницы без необходимости.

Cookies и внешние счётчики

JavaScript HTML-блока запускается сразу при показе опубликованного блока и сам по себе не ожидает согласия посетителя на аналитические или маркетинговые cookies. Для счётчиков и глобальных интеграций, которым требуется согласие, используйте предназначенные для всего сайта настройки HEAD/footer и настройте механизм согласия на cookies.

Как проверить код

1. Сохраните или добавьте HTML-блок.
2. Откройте опубликованную страницу: в редакторе JavaScript намеренно не выполняется.
3. Проверьте сценарий на компьютере и мобильном устройстве.
4. Перейдите на другую страницу и вернитесь, чтобы убедиться, что обработчики не дублируются.
5. Если элемент не работает, откройте консоль разработчика браузера и найдите сообщение «HTML block JavaScript error».

Старые HTML-блоки без JavaScript продолжают работать как раньше. Существующие глобальные поля HEAD и footer не изменяются новым механизмом.