Руководство по миграции на Upcart V2.0

Обзор

Модули Upcart V2.0 представляют собой полностью переработанную архитектуру системы корзины. Обновление сосредоточено на повышении производительности, расширенной настройке и улучшенной сопровождаемости. Это руководство поможет вам понять, что меняется при миграции с модулей V1.0 на V2.0, с какими проблемами совместимости вы можете столкнуться и как безопасно обновить существующие настройки.

Критические изменения — изменения имён CSS-классов

Классы V1 (устаревшие)

🚨 Следующие имена классов V1.0 больше не поддерживаются в V2.0:

.styles_Header__  
.styles_ProductRow__  
.styles_Rewards__  
.styles_TieredRewards__  
...

Классы предупреждения об отсутствии товара на складе upcart-quantity-warning и upcart-quantity-warning-text также не изменились. Они поступают из инициализатора корзины, а не из версионируемого модуля, поэтому выводятся одинаково независимо от того, работают ли ваши модули на V1 или V2.

.styles_CartPreview__card__ отсутствует в этом списке — это общая обёртка оболочки корзины, отображаемая вокруг каждого модуля независимо от версии, поэтому правила, нацеленные на неё, продолжают работать в V2. Классы вознаграждений — это .styles_Rewards__ (простая полоса) и .styles_TieredRewards__ (многоуровневая полоса); класса .styles_RewardsModule__ не существует.

/*******************  
*** Cart Header ***  
*******************/  
'upcart-header',  
'upcart-header-text',  
'upcart-header-logo',  
'upcart-header-close-button',  
'upcart-header-close-button-icon',  
  
/******************  
*** Line Items ***  
******************/  
'upcart-products-section',  
'upcart-product-item',  
/** > Title */  
'upcart-product-title',  
'upcart-product-title-link',  
/** > Prices */  
'upcart-item-prices-row',  
'upcart-item-price',  
'upcart-item-compare-price',  
'upcart-product-savings',  
/** > Options/Variants */  
'upcart-item-option',  
'upcart-item-option-category',  
'upcart-item-option-value',  
/** > Bundle Item Components */  
'upcart-bundle-item-image-wrapper',  
'upcart-bundle-item-product-title',  
'upcart-bundle-item-variant-title',  
'upcart-bundle-detail-toggle',  
/** > Properties */  
'upcart-item-properties',  
'upcart-item-property',  
'upcart-item-property-subscription',  
/** > Quantity Selector */  
'upcart-product-quantity-input',  
'upcart-product-quantity-minus',  
'upcart-product-quantity-plus',  
/** > Image */  
'upcart-product-image-wrapper',  
  
/*********************  
*** Announcements ***  
*********************/  
'upcart-announcement',  
  
/***************  
*** Rewards ***  
***************/  
'upcart-rewards',  
'upcart-rewards-message',  
'upcart-rewards-bar-background',  
'upcart-rewards-bar-foreground',  
'upcart-rewards-tier',  
'upcart-rewards-tier-circle',  
'upcart-rewards-tier-icon',  
'upcart-rewards-tier-description',  
  
/***************  
*** Upsells & Recommendations ***  
***************/  
'upcart-upsells-module',  
'upcart-upsells-title',  
'upcart-upsells-button',  
'upcart-upsell-item-title',  
'upcart-upsell-item-card',  
'upcart-upsell-item-image-wrapper',  
'upcart-upsell-item-image',  
'upcart-upsell-item-price',  
'upcart-upsell-item-price-row',  
'upcart-upsell-item-compare-price',  
'upcart-upsell-item-variant-selector',  
'upcart-upsells', // deprecated  
'upcart-recommendation-module',  
'upcart-recommendations-title',  
'upcart-recommendations-shop-now-button',  
  
/***************  
*** Add-ons ***  
***************/  
'upcart-addons',  
'upcart-addons-title',  
'upcart-addons-product-description',  
'upcart-addons-price',  
'upcart-addons-compare-price',  
'upcart-addons-toggle',  
'upcart-addons-image-wrapper',  
  
/**********************  
*** Discount Codes ***  
**********************/  
'upcart-discount-code-row',  
'upcart-discount-code-module',  
'upcart-discount-code-button',  
'upcart-discount-code-input',  
'upcart-discount-code-badge',  
'upcart-discount-code-icon',  
'upcart-discount-code-text',  
'upcart-discount-code-input-wrapper',  
  
/*****************************  
*** Subscription Upgrades ***  
*****************************/  
'upcart-subscription-upgrade-section',  
'upcart-subscription-upgrade-button',  
'upcart-subscription-upgrade-dropdown',  
  
/***************************  
*** Express Pay Buttons ***  
***************************/  
'upcart-express-pay-buttons-container',  
'upcart-express-pay-buttons-row',  
'upcart-express-pay-button',  
'upcart-express-pay-button-shop-pay',  
'upcart-express-pay-button-google-pay',  
'upcart-express-pay-button-paypal',  
'upcart-express-pay-button-apple-pay',  
'upcart-express-pay-button-amazon-pay',  
'upcart-express-pay-button-meta-pay',  
  
/********************  
*** Trust Badges ***  
********************/  
'upcart-trust-badge',  
'upcart-trust-badge-image',  
  
/********************  
*** Integrations ***  
********************/  
'upcart-integration-zapiet-pickup',  
  
/*****************  
*** Skeletons ***  
*****************/  
'upcart-skeleton',  
'upcart-product-item-skeleton',  
'upcart-product-image-skeleton',  
'upcart-product-title-skeleton',  
'upcart-item-option-skeleton',  
'upcart-product-quantity-skeleton',  
'upcart-product-price-container-skeleton',  
'upcart-announcement-skeleton',  
'upcart-rewards-skeleton',  
'upcart-rewards-message-skeleton',  
'upcart-rewards-bar-skeleton',  
'upcart-upsells-module-skeleton',  
'upcart-upsells-title-skeleton',  
'upcart-upsell-item-image-skeleton',  
'upcart-upsell-item-title-skeleton',  
'upcart-upsell-item-price-skeleton',  
'upcart-upsells-button-skeleton',  
'upcart-trust-badge-skeleton',  
'upcart-trust-badge-image-skeleton',  
'upcart-checkout-button-container-skeleton',  
'upcart-checkout-button-skeleton',  
'upcart-addons-skeleton',  
'upcart-addons-image-wrapper-skeleton',  
'upcart-addons-skeleton-text-container',  
'upcart-discount-code-module-skeleton',  
'upcart-discount-code-input-skeleton',  
'upcart-discount-code-button-skeleton',  
'upcart-express-pay-buttons-container-skeleton',  
'upcart-express-pay-button-skeleton'

Классы V2.0 (новая система)

V2.0 вводит структурированную систему именования с префиксами внутренних и публичных классов.

Внутренние имена классов

Они зарезервированы для внутреннего использования и могут измениться без предупреждения. Если вы переопределяете эти классы, совместимость в будущем не гарантируется.

/* Internal classes - for Upcart's internal styling */   
.upcart-internal-header  
.upcart-internal-header__close-button  
.upcart-internal-cart-items  
.upcart-internal-rewards  
...

Публичные имена классов

🚨 Список доступных публичных имён классов

/*******************  
***** Skeleton *****  
*******************/  
'upcart-public-skeleton'  
  
/*******************  
****** Header ******  
*******************/  
'upcart-public-header'  
'upcart-public-header__close-button'  
'upcart-public-header__close-button-icon'  
  
/*******************  
*** Announcement ***  
*******************/  
'upcart-public-announcement'  
  
/*******************  
** Recommendation **  
****** Upsell ******  
*******************/  
'upcart-public-component-upsell-tile'  
'upcart-public-component-upsell-tile__image-container'  
'upcart-public-component-upsell-tile__image'  
'upcart-public-component-upsell-tile__info'  
'upcart-public-component-upsell-tile__title-link'  
'upcart-public-component-upsell-tile__title'  
'upcart-public-component-upsell-tile__rating-row'  
'upcart-public-component-upsell-tile__stars'  
'upcart-public-component-upsell-tile__star--partial'  
'upcart-public-component-upsell-tile__reviews'  
'upcart-public-component-upsell-tile__price-row'  
'upcart-public-component-upsell-tile__price-compare-at'  
'upcart-public-component-upsell-tile__price'  
'upcart-public-component-upsell-tile__variant-row'  
'upcart-public-component__button'  
'upcart-public-component-loader'  
'upcart-public-upsell__skeleton'  
'upcart-public-upsell__skeleton-title'  
'upcart-public-upsell__skeleton-image'  
'upcart-public-upsell__skeleton-product-title'  
'upcart-public-upsell__skeleton-product-price'  
  
/*******************  
****** Notes *******  
*******************/  
'upcart-public-notes'  
'upcart-public-component-collapse__dropdown-container'  
'upcart-public-component-collapse__expand-icon'  
'upcart-public-notes__text-container'  
'upcart-public-notes__textarea'  
  
/*******************  
** Discount Code ***  
*******************/  
'upcart-public-discount-code'  
'upcart-public-discount-code__form'  
'upcart-public-discount-code__input-wrapper'  
'upcart-public-discount-code__input'  
'upcart-public-discount-code__suffix'  
'upcart-public-discount-code__error'  
'upcart-public-discount-code__button'  
'upcart-public-component__button'  
'upcart-public-skeleton'  
'upcart-public-discount-code__skeleton'  
'upcart-public-discount-code__skeleton-input'  
'upcart-public-discount-code__skeleton-button'  
  
/*******************  
** Trust Badges ****  
*******************/  
'upcart-public-trust-badges'  
'upcart-public-trust-badges__image'  
  
/*******************  
** Tiered Rewards **  
*******************/  
'upcart-public-rewards'  
'upcart-public-rewards__message'  
'upcart-public-rewards__bar'  
'upcart-public-component-segmented-progress-bar'  
'upcart-public-component-segmented-progress-bar__segments-container'  
'upcart-public-component-segmented-progress-bar__segment'  
'upcart-public-component-segmented-progress-bar__segment-fill'  
'upcart-public-component-segmented-progress-bar__milestone'  
'upcart-public-component-segmented-progress-bar__milestone--bottom'  
'upcart-public-component-segmented-progress-bar__milestone--top'  
'upcart-public-component-segmented-progress-bar__milestone--middle'  
'upcart-public-component-segmented-progress-bar__milestone-icon'  
'upcart-public-component-segmented-progress-bar__milestone-label'  
'upcart-public-component-segmented-progress-bar__milestone-label--align-right'  
'upcart-public-component-segmented-progress-bar__milestone-label--align-center'  
'upcart-public-rewards__skeleton',  
'upcart-public-rewards__skeleton-message',  
'upcart-public-rewards__skeleton-bar',  
  
/*******************  
**** Cart Items ****  
*******************/  
'upcart-public-component-product-tile'  
'upcart-public-component-product-tile__content'  
'upcart-public-component-product-tile__image-wrapper'  
'upcart-public-component-product-tile__image'  
'upcart-public-component-product-tile__info'  
'upcart-public-component-product-tile__header'  
'upcart-public-component-product-tile__product-title'  
'upcart-public-component-product-tile__title-link'  
'upcart-public-component-product-tile__remove-button'  
'upcart-public-component-loader'  
'upcart-public-component-product-tile__variant'  
'upcart-public-component-product-tile__properties'  
'upcart-public-component-product-tile__bundle'  
'upcart-public-component-product-tile__product-pricing'  
'upcart-public-component-product-tile__price-compare-at'  
'upcart-public-component-product-tile__price'  
'upcart-public-component-product-tile__savings'  
'upcart-public-component-product-tile__controls'  
'upcart-public-component-product-tile__quantity-selector'  
'upcart-public-component-product-tile__quantity-minus'  
'upcart-public-component-product-tile__quantity-plus'  
'upcart-public-component-product-tile__discount-codes'  
'upcart-public-component-tag'  
'upcart-public-component-tag__icon'  
'upcart-public-component-tag__text'  
'upcart-public-component-product-tile__subscription-upgrade'  
'upcart-public-component__button'  
'upcart-public-component-product-tile__select-wrapper'  
'upcart-public-component-product-tile__select'  
'upcart-public-product-properties__subscription'  
'upcart-public-product-properties__item'  
'upcart-public-product-properties__link'  
'upcart-public-cart-items__key-value-pair'  
'upcart-public-bundle-properties'  
'upcart-public-bundle-properties__variant-title'  
'upcart-public-component-collapse__dropdown-container'  
'upcart-public-bundle-properties__header'  
'upcart-public-component-collapse__expand-icon'  
'upcart-public-notes__text-container'  
'upcart-public-bundle-properties__item-components'  
'upcart-public-bundle-properties__item-component-row'  
'upcart-public-bundle-properties__image-wrapper'  
'upcart-public-bundle-properties__content'  
'upcart-public-bundle-properties__product-title'  
'upcart-public-upsell__skeleton'  
'upcart-public-upsell__skeleton-title'  
'upcart-public-upsell__skeleton-image'  
'upcart-public-upsell__skeleton-product-title'  
'upcart-public-upsell__skeleton-product-price'  
  
/*******************  
***** Add-ons ******  
*******************/  
'upcart-public-addons'  
'upcart-public-addons__image-wrapper'  
'upcart-public-addons__content-wrapper'  
'upcart-public-addons__content-title-wrapper'  
'upcart-public-addons__content-title'  
'upcart-public-addons__content-price'  
'upcart-public-addons__compare-at-price'  
'upcart-public-addons__price'  
'upcart-public-addons__content-description'  
'upcart-public-addons__toggle-wrapper'  
'upcart-public-addons__toggle'  
'upcart-public-addons__toggle-switch'  
'upcart-public-addons__toggle-slider'  
'upcart-public-skeleton'  
'upcart-public-addons__skeleton'  
'upcart-public-addons__skeleton-image'  
'upcart-public-addons__skeleton-text'  
  
/*******************  
*** Cart summary ***  
*******************/  
'upcart-public-cart-summary'  
'upcart-public-cart-summary__discount-codes'  
'upcart-public-cart-summary__discount-label'  
'upcart-public-cart-summary__slide-codes'  
'upcart-public-cart-summary__total-discount'

Они являются частью публичного API стилизации (upcart-public-), и их можно безопасно переопределять для создания собственного дизайна.

.upcart-public-header  
.upcart-public-header__close-button  
.upcart-public-rewards  
...

✅ Что НУЖНО делать

Используйте только имена классов upcart-public- для стилизации.

/* ✅ Correct usage */  
.upcart-public-header {     
  font-size: 18px;  
  font-weight: bold;   
}

❌ Чего НЕ нужно делать

Избегайте переопределения внутренних имён классов

/* ❌ Avoid this */  
.upcart-internal-header {     
  font-size: 18px;  
  font-weight: bold;   
}

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

/* ❌ Avoid this */  
.upcart-public-upsell div a {     
  font-size: 18px;  
  font-weight: bold;   
}

Система data-атрибутов

V2.0 вводит структурированную систему data-атрибутов для улучшенного таргетинга и расширенной настройки.

<!-- V2 data attributes for targeting -->   
<div data-upcart-chunk="header-title-content" />     
<div data-internal-properties="hasNonDefaultTitleAlignment=true" />       
<div data-placement="topOfFooter" />

Эти атрибуты упрощают создание гибких шаблонов, управляемых данными, сохраняя при этом ясность кода.

Изменения переменных шаблонов

Модули V2 используют новый синтаксис переменных шаблонов с двойными фигурными скобками {{ }}.

Модуль объявлений

V1.0: `{TIMER}`
V2.0: `{{timer}}`

Модуль многоуровневых вознаграждений

V1.0: `{AMOUNT}` → V2: `{{amount}}`
V1.0: `{COUNT}` → V2: `{{count}}`

Процесс миграции

1. Сделайте резервную копию текущей конфигурации

Прежде чем вносить какие-либо изменения, сделайте резервную копию существующих файлов пользовательского CSS и HTML.

2. Протестируйте в режиме песочницы

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

Расширенная настройка с V2.0

Пользовательские шаблоны

Модули V2.0 поддерживают полностью пользовательские шаблоны для продавцов, которым нужен полный контроль над макетом и структурой. Чтобы включить пользовательские шаблоны:

Перейдите в Settings > Cart settings, разверните раздел Advanced Settings и установите флажок Access custom templates. Флажок находится внутри этого свёрнутого раздела, а не на самой вкладке Cart settings.
Включите переключатель функции.
Обратитесь к документации для разработчиков Upcart за синтаксисом и примерами.

Включённый флажок Access custom templates с его описанием в настройках корзины Upcart

Примечание: служба поддержки Upcart не может помогать с разработкой, отладкой или устранением неполадок пользовательских шаблонов.

Планы на будущее

Модули V2 будут и дальше получать новые функции, оптимизации и обновления.
Модули V1 теперь находятся в режиме сопровождения с ограниченной поддержкой и без новых функций.
Продавцам рекомендуется как можно скорее перейти на V2 для полной совместимости.

Начало работы

Модули корзины

Настройки корзины

Закреплённая кнопка корзины

Multicart

Кастомизации

Аналитика

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

Оплата и аккаунт

Устранение неполадок

Руководство по миграции на Upcart V2.0

Обзор

Критические изменения — изменения имён CSS-классов

Классы V1 (устаревшие)

Классы V2.0 (новая система)

Внутренние имена классов

Публичные имена классов

✅ Что НУЖНО делать

❌ Чего НЕ нужно делать

Система data-атрибутов

Изменения переменных шаблонов

Модуль объявлений

Модуль многоуровневых вознаграждений

Процесс миграции

1. Сделайте резервную копию текущей конфигурации

2. Протестируйте в режиме песочницы

Расширенная настройка с V2.0

Пользовательские шаблоны

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

Планы на будущее

​Обзор

​Критические изменения — изменения имён CSS-классов

​Классы V1 (устаревшие)

​Классы V2.0 (новая система)

​Внутренние имена классов

​Публичные имена классов

​

​✅ Что НУЖНО делать

​❌ Чего НЕ нужно делать

​Система data-атрибутов

​Изменения переменных шаблонов

​Модуль объявлений

​Модуль многоуровневых вознаграждений

​Процесс миграции

​1. Сделайте резервную копию текущей конфигурации

​2. Протестируйте в режиме песочницы

​Расширенная настройка с V2.0

​Пользовательские шаблоны

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

​Планы на будущее

​

​

Обзор

Критические изменения — изменения имён CSS-классов

Классы V1 (устаревшие)

Классы V2.0 (новая система)

Внутренние имена классов

Публичные имена классов

✅ Что НУЖНО делать

❌ Чего НЕ нужно делать

Система data-атрибутов

Изменения переменных шаблонов

Модуль объявлений

Модуль многоуровневых вознаграждений

Процесс миграции

1. Сделайте резервную копию текущей конфигурации

2. Протестируйте в режиме песочницы

Расширенная настройка с V2.0

Пользовательские шаблоны

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

Планы на будущее