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 と public のクラスプレフィックスによる構造化された命名システムが導入されています。

Internal クラス名

これらは内部使用のために予約されており、予告なく変更される可能性があります。これらのクラスを上書きした場合、将来の互換性は保証されません。

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

Public クラス名

🚨 利用可能な public クラス名の一覧

/*******************  
***** 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'

これらは public スタイリング 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;   
}

❌ 非推奨事項

internal クラス名の上書きは避けてください

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

深い階層のセレクターやカスタムセレクターで特定のノードを対象にするのは避けてください。

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

データ属性システム

V2.0 では、ターゲティングの改善と高度なカスタマイズのために、構造化されたデータ属性システムが導入されています。

<!-- 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 の開発者向けドキュメントを参照してください。

Upcart のカート設定で有効化された Access custom templates チェックボックスとその説明

注: Upcart のサポートチームは、カスタムテンプレートの開発、デバッグ、トラブルシューティングをお手伝いできません。

ベストプラクティス

更新は必ず最初にサンドボックスモードでテストしてください。
カスタマイズの移行と更新は段階的に行ってください。
スタイリングには internal クラスではなく public クラスを使用してください。
本番設定を更新する前に、以前のバージョンをすべてバックアップしてください。

今後の展望

V2 モジュールは、今後も新機能、最適化、更新が提供され続けます。
V1 モジュールは現在メンテナンスモードにあり、サポートは限定的で新機能は追加されません。
完全な互換性のため、できるだけ早く V2 への移行をおすすめします。

カート機能リファレンス

CSSリファレンス

スタイリングレシピ

機能レシピ

カスタムテンプレート

Upcart公開API

概要

破壊的変更 - CSS クラス名の変更

V1 クラス(非推奨)

V2.0 クラス(新システム)

Internal クラス名

Public クラス名

✅ 推奨事項

❌ 非推奨事項

データ属性システム

テンプレート変数の変更

アナウンスメントモジュール

階層型リワードモジュール

移行プロセス

1. 現在の構成をバックアップする

2. サンドボックスモードでテストする

V2.0 での高度なカスタマイズ

カスタムテンプレート

ベストプラクティス

今後の展望

​概要

​破壊的変更 - CSS クラス名の変更

​V1 クラス(非推奨)

​V2.0 クラス(新システム)

​Internal クラス名

​Public クラス名

​

​✅ 推奨事項

​❌ 非推奨事項

​データ属性システム

​テンプレート変数の変更

​アナウンスメントモジュール

​階層型リワードモジュール

​移行プロセス

​1. 現在の構成をバックアップする

​2. サンドボックスモードでテストする

​V2.0 での高度なカスタマイズ

​カスタムテンプレート

​ベストプラクティス

​今後の展望

​

​

概要

破壊的変更 - CSS クラス名の変更

V1 クラス(非推奨)

V2.0 クラス(新システム)

Internal クラス名

Public クラス名

✅ 推奨事項

❌ 非推奨事項

データ属性システム

テンプレート変数の変更

アナウンスメントモジュール

階層型リワードモジュール

移行プロセス

1. 現在の構成をバックアップする

2. サンドボックスモードでテストする

V2.0 での高度なカスタマイズ

カスタムテンプレート

ベストプラクティス

今後の展望