API

Cart API

Описание

Централизованный API для работы с корзиной. Обеспечивает операции добавления, удаления товаров и автоматическое обновление интерфейса всплывающих корзин.

Доступ к API

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

window.waTheme.cartAPI

Обработчики всплывающих корзин инициализируются темой автоматически. При необходимости их можно переинициализировать вручную:

window.waTheme.cartAPI.initCartDropdowns();

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

add(data)

Добавляет товар в корзину.

Параметры:

  • data (FormData|string|Object) — данные формы товара: объект FormData, строка запроса (product_id=123&sku_id=456) или обычный объект

Возвращает: Promise<Object> — ответ сервера

Структура данных товара:

Обязательные поля:

  • product_id — ID товара

Один из вариантов:

  • sku_id — ID SKU (для товаров с фиксированными комплектациями)

  • features[] — характеристики товара (для товаров с динамическим выбором опций)

Дополнительные поля:

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

  • service_variant[] — варианты услуг к товару

  • services[] — услуги к товару

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

Товар с SKU (данные из формы):

const formData = new FormData(form);
const result = await cartAPI.add(formData);

Товар с features (программно):

const result = await cartAPI.add({
  product_id: '1049',
  quantity: 1,
  'features[6]': '93',        // характеристика 6 = значение 93
  'features[115]': '874',     // характеристика 115 = значение 874
  'service_variant[1]': '1',  // услуга 1 = вариант 1
  'service_variant[5]': '9'   // услуга 5 = вариант 9
});

Минимальный набор:

const result = await cartAPI.add({
  product_id: '123',
  sku_id: '456'
});

delete(itemId)

Удаляет товар из корзины.

Параметры:

  • itemId (string|number) — ID товара в корзине

Возвращает: Promise<Object> — ответ сервера

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

const result = await cartAPI.delete('1175');

save(data)

Сохраняет изменения в корзине (например, новое количество товара).

Параметры:

  • data (FormData|string|Object) — данные для сохранения; ID позиции в корзине передается в поле id

Возвращает: Promise<Object> — ответ сервера

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

const result = await cartAPI.save({ id: '1175', quantity: 3 });

Поле item_id распознается только локально — по нему API ищет товар для текста уведомления. В запрос данные уходят как есть, поэтому item_id не заменяет id: если передать только его, сервер не получит идентификатор позиции и количество не сохранится.

clearCart()

Очищает всю корзину (удаляет все товары).

Возвращает: Promise<Object>

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

await cartAPI.clearCart();

getCartItems()

Возвращает актуальный список товаров корзины из window.waTheme.cart.items.

Возвращает: Array — массив товаров корзины

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

const items = cartAPI.getCartItems();
console.log('Товаров в корзине:', items.length);

showMaxQuantityNotification(productId, maxQuantity)

Показывает уведомление о достижении максимального количества товара (через Notification API — notificationAPI.cart.maxQuantity).

Параметры:

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

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

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

cartAPI.showMaxQuantityNotification('123', 10);

initCartDropdowns()

Инициализирует обработчики событий для всплывающих корзин.

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

cartAPI.initCartDropdowns();

Событие cart:changed

При любом изменении корзины Cart API генерирует на document событие CustomEvent с именем cart:changed:

document.addEventListener('cart:changed', (event) => {
  const { action, itemInfo, quantity, count } = event.detail;
  console.log(`Действие: ${action}, всего в корзине: ${count}`);
});

Структура event.detail:

ПолеТипОписание
actionstringТип изменения: added, removed, updated, cleared
itemInfoObject|nullИнформация о товаре (при добавлении — объект с product_id)
quantitynumber|nullКоличество (для added и updated)
countnumberОбщее количество товаров в корзине после изменения

Автоматические обновления

Cart API автоматически обновляет:

  1. Данные в window.waTheme.cart: count — количество товаров, total — общая сумма, items — массив товаров

  2. DOM-элементы: .js-cart-count — счетчики корзины (скрываются при count = 0), .js-cart-dropdown-total — общая сумма (скрывается при count = 0)

  3. Состояние всплывающих корзин: переключение между пустым состоянием и списком товаров, автоматический рендеринг актуальных товаров

  4. Синхронизацию с товарами на странице: обновление видимости блоков quantity/submit для связанных товаров при удалении из корзины

Структура ответов сервера

Ответ метода add()

{
  "status": "ok",
  "data": {
    "item_id": 1175,
    "total": "23 190 <span class=\"ruble\">₽</span>",
    "discount": "0 <span class=\"ruble\">₽</span>",
    "discount_numeric": 0,
    "discount_coupon": "0 <span class=\"ruble\">₽</span>",
    "count": 5,
    "items": [
      {
        "id": "1166",
        "product_id": "11",
        "name": "Джемпер флисовый мужской Termit (синий, M-L 52 (RU))",
        "quantity": 1,
        "sku_id": "18",
        "sku_code": "354002",
        "sku_name": "синий, M-L 52 (RU)",
        "product_name": "Джемпер флисовый мужской Termit",
        "image_url": "/wa-data/public/shop/products/11/00/11/images/47/47.96x96.webp",
        "frontend_url": "/shop/dzhemper-flisovyy-muzhskoy-termit/",
        "price": "1 800 <span class=\"ruble\">₽</span>",
        "services": [],
        "full_price": "1 800 <span class=\"ruble\">₽</span>"
      }
    ]
  }
}

Ответ метода delete()

{
  "status": "ok",
  "data": {
    "total": "0 <span class=\"ruble\">₽</span>",
    "discount": "0 <span class=\"ruble\">₽</span>",
    "discount_numeric": 0,
    "discount_coupon": "0 <span class=\"ruble\">₽</span>",
    "count": 0,
    "add_affiliate_bonus": "Этот заказ добавит <strong>+0 бонусных баллов</strong>",
    "affiliate_discount": "0 <span class=\"ruble\">₽</span>"
  }
}

Ответ метода save()

{
  "status": "ok",
  "data": {
    "item_total": "7 590 <span class=\"ruble\">₽</span>",
    "total": "23 190 <span class=\"ruble\">₽</span>",
    "discount": "0 <span class=\"ruble\">₽</span>",
    "discount_numeric": 0,
    "discount_coupon": "0 <span class=\"ruble\">₽</span>",
    "count": 5
  }
}

Селекторы DOM-элементов

Константы селекторов, используемых Cart API:

СелекторОписание
.js-cart-countСчетчики товаров в корзине
.js-cart-dropdown-totalОбщая сумма в выпадающих корзинах
.js-cart-dropdownКонтейнеры выпадающих корзин
.js-cart-dropdown-itemЭлементы товаров в выпадающих корзинах
.js-cart-dropdown-removeКнопки удаления товара
.js-cart-dropdown-clearКнопки очистки корзины
.js-cart-dropdown-headerЗаголовок корзины
.js-cart-dropdown-itemsКонтейнер списка товаров
.js-cart-dropdown-emptyБлок пустой корзины
.js-cart-dropdown-checkoutБлок оформления заказа

Обработка ошибок

Все методы возвращают Promise. При ошибках генерируется исключение:

try {
  await cartAPI.add(formData);
} catch (error) {
  console.error('Ошибка добавления в корзину:', error);
}

Интеграция с товарами на странице

Cart API синхронизирует состояние товаров на странице при изменениях корзины.

Синхронизация при удалении товара

При удалении товара из всплывающей корзины Cart API:

  1. Определяет связанные товары на странице по data-product-id

  2. Находит экземпляры товаров через element._productInstance

  3. Вызывает метод toggleSubmitQuantityBlocks() для обновления видимости блоков

// Автоматически происходит при клике на js-cart-dropdown-remove
await cartAPI.delete(itemId); // Удаляет товар из корзины

// Cart API автоматически вызывает для всех товаров с таким product_id:
productElement._productInstance.toggleSubmitQuantityBlocks();

Требования для интеграции

  1. Товар должен иметь атрибут data-product-id и класс js-product

  2. Экземпляр товара должен быть привязан к элементу через _productInstance (тема делает это автоматически)

Пример HTML-разметки

<div class="js-product"
     data-product-id="123"
     data-product-name="Товар"
     data-product-price="1000"
     data-product-compare-price="1200"
     data-product-image="/path/to/image.jpg">
  <!-- содержимое товара -->
</div>

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

Для базовой цели «добавление в корзину» писать код не обязательно: в настройках темы есть группа «Цели Яндекс.Метрики» — достаточно указать «Номер счётчика Яндекс.Метрики» и идентификатор цели в поле «Добавление товара в корзину», и тема отправит цель сама.

Для своей логики подпишитесь на событие cart:changed. Разместите код в блоке site.{имя_темы}_js (Сайт — Блоки):

{literal}
<script>
document.addEventListener('cart:changed', (event) => {
    if (event.detail.action === 'added') {
        // Цель Яндекс.Метрики
        ym(00000000, 'reachGoal', 'addToCart');
    }
});
</script>
{/literal}