К содержимому
API

Notification API

Обновлено

Описание

Единый API уведомлений для всех модулей темы. Использует Toastify и предоставляет унифицированный интерфейс для отображения toast-уведомлений о товарах и простых текстовых сообщений.

Доступ к API

API входит в состав минифицированного бандла темы assets/js/site.theme.min.js и доступен глобально:

window.waTheme.notificationAPI

Алиас для обратной совместимости: window.waTheme.notificationService

Уведомления из DOM-элементов (атрибут data-toastify) инициализируются автоматически; при необходимости можно вызвать вручную:

window.waTheme.notificationAPI.initFromDOM();

Настройки темы

Настройки для каждого типа события

Уведомления настраиваются отдельно для каждого типа события (корзина, избранное, сравнение) с возможностью выбора устройств:

Настройка Название в настройках темы
apps__shop_common_notification_cart_type_buttons Уведомления корзины
apps__shop_common_notification_wishlist_type_buttons Уведомления избранного
apps__shop_common_notification_compare_type_buttons Уведомления сравнения

Опции для каждой настройки:

  • everywhere — «Везде» (по умолчанию)

  • desktop — «Только на десктопе»

  • mobile — «Только на мобильном»

  • disabled — «Нигде»

Позиция уведомлений

  • Десктоп: настройка «Позиция уведомления (десктоп)» — apps__shop_common_product_added_notification_position_type_buttons (значения: bottom-right, bottom-left, top-right, top-left, top-center, bottom-center; по умолчанию top-right — «Верх справа»)

  • Мобильные: всегда top-center (фиксированная позиция)

Все значения доступны в window.waTheme.themesettings.settings[<key>].value.

Пример чтения настроек

// Проверка, нужно ли показывать уведомления корзины
const cartNotification = window.waTheme?.themesettings?.settings?.['apps__shop_common_notification_cart_type_buttons']?.value || 'everywhere';

// Получение позиции для десктопа
const position = window.waTheme?.themesettings?.settings?.['apps__shop_common_product_added_notification_position_type_buttons']?.value || 'top-right';

// Проверка типа устройства
const isMobile = window.waTheme?.is_mobile === '1' || window.waTheme?.is_mobile_checking_by_wa === '1';

// Определение, показывать ли уведомление
const shouldShow =
  cartNotification === 'everywhere' ||
  (cartNotification === 'desktop' && !isMobile) ||
  (cartNotification === 'mobile' && isMobile);

if (shouldShow && window.waTheme?.notificationAPI) {
  window.waTheme.notificationAPI.cart.added('123', 2);
}

API автоматически проверяет настройки перед показом уведомлений, поэтому в большинстве случаев достаточно просто вызывать методы cart.added(), wishlist.added() и т.д.

Настройки по умолчанию

{
  duration: 4,              // Длительность показа в секундах
  position: 'bottom-right', // Резервная позиция — используется, только если настройка темы недоступна
  close: true,              // Показывать кнопку закрытия
  width: 'w-80'             // Фиксированная ширина 320px (Tailwind)
}

Фактическая позиция уведомления определяется автоматически: на мобильных — top-center, на десктопе — из настройки темы «Позиция уведомления (десктоп)» (по умолчанию top-right).

Публичные методы

showProductNotification(options)

Показывает уведомление о товаре с изображением, названием и дополнительной информацией.

Если передан параметр type (cart, wishlist, compare), метод автоматически проверяет настройки темы и может не показывать уведомление, если оно отключено для данного типа или устройства.

Параметры:

Параметр Тип Описание
productId string/number ID товара (обязательный)
message string Текст сообщения (обязательный)
productName string Название товара
productImage string URL изображения
additionalInfo string Дополнительная информация
showLink boolean Показывать ссылку
linkUrl string URL ссылки
linkText string Текст ссылки
duration number Длительность показа в секундах
type string Тип уведомления: cart, wishlist, compare, default
position string Позиция уведомления (по умолчанию определяется автоматически)
close boolean Показывать кнопку закрытия

Примеры использования:

Базовое уведомление:

notificationAPI.showProductNotification({
  productId: '123',
  message: 'Товар добавлен в корзину'
});

Уведомление со ссылкой:

notificationAPI.showProductNotification({
  productId: '123',
  message: 'Товар добавлен в корзину',
  productName: 'Джемпер флисовый',
  productImage: '/path/to/image.jpg',
  showLink: true,
  linkUrl: '/cart/',
  linkText: 'Перейти в корзину',
  duration: 5
});

Уведомление с проверкой настроек:

notificationAPI.showProductNotification({
  productId: '123',
  message: 'Товар добавлен',
  additionalInfo: '(2 шт.)',
  type: 'cart' // API проверит настройки корзины перед показом
});

Уведомление без проверки настроек:

notificationAPI.showProductNotification({
  productId: '123',
  message: 'Специальное уведомление',
  type: 'default' // Или не передавать type — уведомление будет показано всегда
});

showSimpleNotification(message, duration, extraOptions)

Показывает простое текстовое уведомление без изображения товара.

Параметры:

  • message (string) — текст сообщения

  • duration (number) — длительность показа в секундах (по умолчанию 4)

  • extraOptions (Object) — дополнительные опции (position, close)

Примеры использования:

// Простое сообщение
notificationAPI.showSimpleNotification('Операция выполнена успешно');

// С настройкой длительности
notificationAPI.showSimpleNotification('Товар удален', 3);

// С дополнительными опциями
notificationAPI.showSimpleNotification(
  'Изменения сохранены',
  5,
  { position: 'top-right', close: true }
);

initFromDOM()

Инициализирует уведомления из DOM-элементов с атрибутом data-toastify.

Пример HTML:

<!-- Уведомление с задержкой -->
<div data-toastify='{"html": "<div>Успешно сохранено</div>", "delay": 1, "remove": true}'>
</div>

<!-- Уведомление с контентом из элемента -->
<div data-toastify='{"duration": 5, "position": "top-right"}'>
  <div class="p-4">Ваше сообщение здесь</div>
</div>

Параметры data-toastify (JSON):

Параметр Тип Описание
html string HTML-контент (если не передан, берется innerHTML элемента)
duration number Длительность показа в секундах
delay number Задержка перед показом в секундах
position string Позиция уведомления
close boolean Показывать кнопку закрытия
remove boolean Удалить элемент после показа 
// Вызывается автоматически при инициализации темы
// Или можно вызвать вручную для динамически добавленных элементов
notificationAPI.initFromDOM();

Специализированные методы

Уведомления для корзины (cart)

cart.added(productId, quantity, productName, productImage)

Товар добавлен в корзину.

Параметры:

  • productId (string|number) — ID товара

  • quantity (number) — количество (по умолчанию 1)

  • productName (string) — название товара

  • productImage (string) — URL изображения

notificationAPI.cart.added('123', 2);
// Показывает: "В корзине (2 шт.)" со ссылкой "Перейти в корзину"

cart.removed(itemInfo)

Товар удален из корзины.

Параметры:

  • itemInfo (Object) — информация о товаре:

  • product_id (string) — ID товара

  • name (string) — название

  • image_url (string) — URL изображения

  • quantity (number) — количество

notificationAPI.cart.removed({
  product_id: '123',
  name: 'Джемпер флисовый',
  image_url: '/path/to/image.jpg',
  quantity: 2
});
// Показывается 3 секунды

cart.updated(itemInfo, newQuantity)

Количество товара в корзине обновлено.

Параметры:

  • itemInfo (Object) — информация о товаре (см. cart.removed)

  • newQuantity (number) — новое количество

notificationAPI.cart.updated(itemInfo, 5);
// Показывает: "Количество обновлено (5 шт.)" со ссылкой "Перейти в корзину"

cart.maxQuantity(productId, maxQuantity)

Достигнуто максимальное количество товара.

Параметры:

  • productId (string|number) — ID товара

  • maxQuantity (number) — максимальное количество

notificationAPI.cart.maxQuantity('123', 10);
// Показывает: "Достигнуто максимальное количество (макс. 10 шт.)"

Уведомления для избранного (wishlist)

wishlist.added(productId, productName, productImage)

Товар добавлен в избранное.

notificationAPI.wishlist.added('123');
// Показывает: "В избранном" со ссылкой "Перейти к избранному"

wishlist.removed(productId, productName, productImage)

Товар удален из избранного.

notificationAPI.wishlist.removed('123');
// Показывает: "Удален из избранного" (3 секунды)

Уведомления для сравнения (compare)

compare.added(productId, productName, productImage)

Товар добавлен к сравнению.

notificationAPI.compare.added('123');
// Показывает: "В сравнении" со ссылкой "Перейти к сравнению"

compare.removed(productId, productName, productImage)

Товар удален из сравнения.

notificationAPI.compare.removed('123');
// Показывает: "Удален из сравнения" (3 секунды)

Автоматическое получение данных товара

Если название или изображение товара не переданы явно, API автоматически пытается найти их.

Источники данных (в порядке приоритета):

  1. Из data-атрибутов кнопки: <button data-product-id="123" data-product-name="Джемпер" data-product-image="/path/to/image.jpg">

  2. Из данных корзины — поиск в window.waTheme.cart.items по полю product_id (ключом в items служит идентификатор позиции корзины, а не ID товара): items.find(i => i.product_id === String(productId))

  3. Из карточки товара на странице: <div data-product="123"> <img src="/path/to/image.jpg" alt="Товар"> </div>

  4. Значения по умолчанию: название — window.waTheme?.locale?.product || 'Товар', изображение — window.waTheme?.theme?.url + 'assets/img/svg/empty_photo.svg'

Локализация

API использует глобальные переменные локализации из window.waTheme.locale:

{
  in_cart: 'В корзине',
  go_to_cart: 'Перейти в корзину',
  removed_from_cart: 'Удален из корзины',
  quantity_updated: 'Количество обновлено',
  maximum_quantity_reached: 'Достигнуто максимальное количество',
  in_wishlist: 'В избранном',
  go_to_wishlist: 'Перейти к избранному',
  removed_from_wishlist: 'Удален из избранного',
  in_comparison: 'В сравнении',
  go_to_comparison: 'Перейти к сравнению',
  removed_from_comparison: 'Удален из сравнения',
  product: 'Товар'
}

Структура HTML уведомления

Уведомление о товаре

<div class="w-80 flex items-start gap-3 p-4 pr-10 bg-white border border-gray-200 rounded-theme shadow-theme dark:bg-neutral-800 dark:border-neutral-700">
  <div class="flex-shrink-0">
    <img src="..." alt="..." class="aspect-square size-12 min-w-12 rounded-theme object-cover">
  </div>
  <div class="flex-1">
    <div class="text-sm text-inverse font-semibold">
      В корзине
    </div>
    <div class="text-sm text-inverse">
      Джемпер флисовый (2 шт.)
    </div>
    <a href="/cart/" class="text-sm mt-2 text-blue-600 hover:text-blue-800 dark:text-blue-400 dark:hover:text-blue-300">
      Перейти в корзину
    </a>
  </div>
</div>

Простое уведомление

<div class="w-80 flex items-center gap-3 p-4 pr-10 bg-white border border-gray-200 rounded-theme shadow-theme dark:bg-neutral-800 dark:border-neutral-700">
  <div class="flex-1">
    <div class="text-sm text-inverse font-semibold">
      Операция выполнена успешно
    </div>
  </div>
</div>

Отступ pr-10 в обеих обёртках оставляет место под кнопку закрытия уведомления.

Обратите внимание: классы text-blue-* в CSS темы не генерируются — в палитре Tailwind темы нет цвета blue, поэтому в собранном site.theme.min.css таких правил нет и ссылка просто наследует цвет текста. В собственной разметке уведомлений используйте классы темы, например link-theme или text-theme-500:

<a href="/cart/" class="text-sm mt-2 link-theme">
  Перейти в корзину
</a>

Интеграция с другими API

Cart API

// Cart API автоматически использует Notification API
await cartAPI.add({ product_id: '123', sku_id: '456' });
// Notification API автоматически покажет уведомление

Wishlist API

// Wishlist API автоматически использует Notification API
wishlistAPI.addToWishlist(productId);
// Автоматическое уведомление о добавлении

Compare API

// Compare API автоматически использует Notification API
compareAPI.addToCompare(productId);
// Автоматическое уведомление о добавлении

Примеры использования

Базовая интеграция

const { cartAPI, notificationAPI } = window.waTheme;

// При добавлении товара в корзину
document.querySelector('.js-add-to-cart').addEventListener('click', async (e) => {
  const productId = e.target.dataset.productId;

  try {
    await cartAPI.add({ product_id: productId, quantity: 2 });
    // Уведомление показывается автоматически через Cart API
  } catch (error) {
    notificationAPI.showSimpleNotification('Ошибка добавления товара', 3);
  }
});

Кастомное уведомление

// Уведомление о специальной акции
notificationAPI.showProductNotification({
  productId: '999',
  message: 'Специальная цена!',
  additionalInfo: '(скидка 50%)',
  showLink: true,
  linkUrl: '/promo/',
  linkText: 'Узнать больше',
  duration: 6,
  position: 'top-center'
});

Динамические уведомления из бэкенда

<!-- В Smarty-шаблоне -->
{if $success_message}
  <div data-toastify='{"duration": 5, "remove": true}'>
    <div class="w-80 p-4 bg-green-100 border border-green-200 rounded-theme">
      <div class="text-sm font-semibold text-green-800">
        {$success_message}
      </div>
    </div>
  </div>
{/if}

<script>
  // Инициализация после загрузки DOM
  document.addEventListener('DOMContentLoaded', () => {
    window.waTheme.notificationAPI.initFromDOM();
  });
</script>

Рекомендации

  1. Используйте специализированные методы (cart.added, wishlist.added) вместо прямого вызова showProductNotification

  2. Передавайте данные явно, если они доступны, чтобы избежать поиска в DOM

  3. Настраивайте duration в зависимости от важности сообщения: успешные действия — 4 секунды (по умолчанию), удаления — 3 секунды, важные сообщения — 5–6 секунд

  4. Используйте data-toastify для серверных уведомлений

  5. Используйте локализацию из window.waTheme.locale

Примечания

  • Все методы cart, wishlist и compare автоматически используют локализацию

  • При отсутствии данных товара используются значения по умолчанию

  • Уведомления адаптированы под темную тему (dark mode)

  • Ширина уведомлений фиксирована (320px) для консистентности

  • API экспортируется как singleton instance для использования во всех модулях