VGToast

Уведомления, стек, перетаскивание, AJAX и жизненный цикл.

API, события и оформление

Ручное управление, отмена скрытия и справочник публичного контракта.

Каждый пример независим. Кнопка «Показать код» раскрывает HTML, JavaScript и CSS, которые используются в самом примере. Стили оболочки и кнопок предоставляет OKAUX 1.0.2.

Жизненный цикл

show, hide, toggle, dispose и повторный init. Для очистки сначала скройте тост. Флажок запрещает скрытие через отменяемое событие.

Журнал событий
Управление экземпляром. Esc и кнопка закрытия вызывают hide().
HTML
<div class="d-flex flex-wrap gap-2">
<button type="button" id="toast-api-show" class="btn btn-primary btn-sm">show</button>
<button type="button" id="toast-api-hide" class="btn btn-primary btn-sm">hide</button>
<button type="button" id="toast-api-toggle" class="btn btn-primary btn-sm">toggle</button>
<button type="button" id="toast-api-dispose" class="btn btn-primary btn-sm">dispose</button>
<button type="button" id="toast-api-init" class="btn btn-primary btn-sm">init</button>
</div>
<label class="d-block mt-3"><input type="checkbox" id="toast-prevent"> Запретить скрытие через preventDefault()</label>
<pre id="toast-api-log" class="toast-demo-log" role="log" aria-live="polite">Журнал событий</pre>
<div id="toast-api" class="vg-toast bottom center" role="status" aria-live="polite" >
  <div class="vg-toast-wrapper">
    <div class="vg-toast-content"><div class="vg-toast-body">Управление экземпляром. Esc и кнопка закрытия вызывают hide().</div></div>
    <div class="vg-toast-button"><button type="button" class="vg-btn-close" data-vg-dismiss="toast" aria-label="Закрыть уведомление"></button></div>
  </div>
</div>
JavaScript
/**
 * Описание: жизненный цикл и отмена скрытия.
 * Возможности: рабочий пример публичного API VGToast.
 */
import { VGToast } from 'vgapp';

function initToastDemo() {
  const element = document.querySelector('#toast-api');
  if (!element) return;
  const log = document.querySelector('#toast-api-log');
  const write = text => { log.textContent = (log.textContent + '\n' + text).split('\n').slice(-12).join('\n'); };
  let instance;
  const init = () => {
    instance = VGToast.getOrCreateInstance(element, {static: true, enableClickToast: false, animation: {enable: false, delay: 0}});
    write('Экземпляр готов');
  };
  ['show', 'shown', 'hide', 'hidden'].forEach(name => {
    element.addEventListener('vg.toast.' + name, event => {
      if (name === 'hide' && document.querySelector('#toast-prevent').checked) {
        event.preventDefault();
        write('hide отменён');
      } else write(name);
    });
  });
  init();
  ['show', 'hide', 'toggle'].forEach(method => {
    document.querySelector('#toast-api-' + method).addEventListener('click', () => {
      if (instance) instance[method]();
      else write('Сначала нажмите init');
    });
  });
  document.querySelector('#toast-api-dispose').addEventListener('click', () => {
    if (!instance) return;
    if (element.classList.contains('show')) { write('Сначала hide, затем dispose'); return; }
    instance.dispose();
    instance = null;
    write('dispose: статический DOM сохранён');
  });
  document.querySelector('#toast-api-init').addEventListener('click', init);
}

initToastDemo();
CSS
/* Композиция демо и публичные переменные VGToast. Тему переключает OKAUX. */
.page-module-toast .vg-toast {
  --vg-toast-width: min(28rem, 100%);
  --vg-toast-border-radius: var(--vg-radius-lg);
  --vg-toast-background-color: var(--vg-bg-secondary);
  --vg-toast-color: var(--vg-text-primary);
  --vg-toast-border-color: var(--vg-border-default);
}
.page-module-toast .vg-toast-content { min-width: 0; overflow-wrap: anywhere; }
.module-toast-content { min-width: 0; }
.toast-demo-log { white-space: pre-wrap; overflow-wrap: anywhere; padding: 1rem; background: var(--vg-bg-secondary); border: 1px solid var(--vg-border-default); border-radius: var(--vg-radius-lg); }
.toast-demo-reference { overflow-wrap: anywhere; }
.toast-demo-reference dt { margin-top: 1rem; font-family: monospace; }
.toast-demo-reference dd { margin: .25rem 0 0; }

Публичный контракт

Значения проверены по исходникам VGToast; особенности build и статической разметки различаются.

Подключение
import { VGToast } from 'vgapp'; стили — @use "vgapp/scss" либо публичный entrypoint vgapp/toast. На этом сайте кнопки и поля предоставляет OKAUX 1.0.2. Для переноса CSS примеров добавьте класс page-module-toast на body. Состояние темы хранит OKAUX; адаптер vgapp/theme привязывает переменные VGApp к data-theme.
run(text, params, callback) / build(text, params, callback)
Создают и сразу показывают тост; возвращают экземпляр. Текст — строка HTML или массив [заголовок, тело]. Callback получает экземпляр до вызова show(). Не передавайте недоверенный HTML без очистки.
getOrCreateInstance(element, params) / getInstance(element)
Получение экземпляра для существующей разметки. Повторный getOrCreateInstance возвращает существующий экземпляр, не меняя его настройки.
static / autohide / delay
Для разметки: true / false / 3000 мс. Для run и build: false / true / 3000 мс. При static: true в build автоскрытие по умолчанию выключается. Таймер стартует после shown. Нажатие указателя приостанавливает таймер, отпускание внутри тоста запускает его заново.
placement / stack
По умолчанию bottom center. top или bottom плюс left, center или right, разделённые пробелом. stack: {enable: true, max: 5}. Лимит и смещения общие для вертикальной группы top / bottom. stack.enable: false заменяет уведомления своей группы.
enableClickToast / enableButtonClose / keyboard
true / false / true. Для тоста с интерактивным содержимым отключайте закрытие по клику. enableButtonClose добавляет кнопку только в build; в статическом HTML кнопку с data-vg-dismiss="toast" добавляют вручную. Esc закрывает все показанные экземпляры с keyboard: true.
theme / type
theme: 'dark' добавляет класс при build. Пустая строка оставляет базовые переменные темы. type: null; success, error, warning, info добавляют иконку при build. Тип не назначает цвет автоматически.
animation
enable: true, in: animate__backInUp, out: animate__backOutDown, delay: 300. Для этих классов нужен Animate.css. effect: none, fade, zoom, blur, slide-up, slide-down, массив эффектов или собственный CSS-класс. Встроенные эффекты работают и при enable: false.
drag / resize
Оба по умолчанию выключены. drag: {enable, selector: '.vg-toast-wrapper', threshold: 4, resizeEdgeSize: 8, debug: false}. resize: {enable, edgeSize: 8, minWidth: 220, minHeight: 64, debug: false}. Явно указывайте enable: true; boolean true также поддерживается.
ajax
route: '', target: '', method: 'get', loader: false, once: false, output: true. target обязателен для вывода HTML, автоматической подстановки тела тоста нет. output: false позволяет обработать ответ самостоятельно через loaded. once кэширует завершение, включая ошибку; для повторных попыток используйте once: false.
Data API
data-vg-toggle="toast" + data-vg-target="#id"; закрытие — data-vg-dismiss="toast". Вложенные параметры: data-stack-max="3", data-ajax-route="/api/toast/demo". camelCase-настройки передавайте через JSON data-params, например {"enableClickToast": false}.
show / hide / toggle / dispose
show(relatedTarget?) читает параметры триггера. Повторный show видимого тоста не запускает новый цикл. hide асинхронный; завершение — hidden. dispose освобождает экземпляр; при static: true сохраняет DOM. Сначала скройте тост, затем вызывайте dispose.
События
vg.toast.show и vg.toast.hide отменяются через preventDefault(); vg.toast.shown и vg.toast.hidden сообщают о завершении. show/shown содержат detail.relatedTarget. vg.toast.loaded содержит detail.stats ('success' / 'error') и detail.data. hidePrevented.vg.toast объявлено в старом README, но реализация его не отправляет.
CSS: размеры и размещение
--vg-toast-width, --vg-toast-height, --vg-toast-indent, --vg-toast-padding, --vg-toast-z-index, --vg-toast-transition.
CSS: поверхность
--vg-toast-background-color, --vg-toast-color, --vg-toast-border-width, --vg-toast-border-style, --vg-toast-border-color, --vg-toast-border-radius, --vg-toast-box-shadow.
CSS: типографика
--vg-toast-header-font-size, --vg-toast-header-font-weight, --vg-toast-body-font-size, --vg-toast-body-font-weight. Объявленная --vg-toast-font-size непосредственно шаблоном не используется.