> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upcart V2.0 移行ガイド

> この記事は、Upcart V1.0 モジュールから V2.0 モジュールへアップグレードするための移行ガイドです。破壊的変更、CSS クラスのマッピング、JavaScript セレクターの更新、トラブルシューティング、段階的な移行プロセスを扱います。

<div id="overview">
  ## 概要
</div>

Upcart V2.0 モジュールは、カートシステムのアーキテクチャを完全に再設計したものです。この更新は、パフォーマンスの向上、カスタマイズ性の強化、保守性の改善に重点を置いています。

このガイドは、V1.0 モジュールから V2.0 モジュールへの移行で何が変わるのか、どのような互換性の問題が発生する可能性があるのか、既存のカスタマイズを安全に更新する方法を理解するのに役立ちます。

***

<div id="breaking-changes---css-classname-changes">
  ## 破壊的変更 - CSS クラス名の変更
</div>

<div id="v1-classes-deprecated">
  ### V1 クラス(非推奨)
</div>

🚨 次の V1.0 クラス名は V2.0 ではサポートされなくなりました:

```
.styles_Header__  
.styles_ProductRow__  
.styles_Rewards__  
.styles_TieredRewards__  
...
```

<Note>
  在庫切れ警告のクラス `upcart-quantity-warning` と `upcart-quantity-warning-text` も**変更されていません**。これらはバージョン管理されたモジュールではなくカートイニシャライザーから生成されるため、モジュールが V1 でも V2 でも同一のものが出力されます。
</Note>

<Note>
  **`.styles_CartPreview__card__` はこのリストに含まれていません** — これはバージョンに関係なくすべてのモジュールの周囲にレンダリングされる共有のカートシェルラッパーであるため、これを対象とするルールは V2 でも機能し続けます。リワードのクラスは `.styles_Rewards__`(シンプルバー)と `.styles_TieredRewards__`(階層バー)です。`.styles_RewardsModule__` は存在しません。
</Note>

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

<div id="v20-classes-new-system">
  ### V2.0 クラス(新システム)
</div>

V2.0 では、**internal** と **public** のクラスプレフィックスによる構造化された命名システムが導入されています。

<div id="internal-classnames">
  #### Internal クラス名
</div>

これらは内部使用のために予約されており、予告なく変更される可能性があります。

これらのクラスを上書きした場合、将来の互換性は保証されません。

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

<div id="public-classnames">
  #### Public クラス名
</div>

🚨 利用可能な 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  
...
```

###

<div id="dos">
  ### ✅ 推奨事項
</div>

スタイリングには `upcart-public-` クラス名のみを使用してください。

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

<div id="donts">
  ### ❌ 非推奨事項
</div>

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;   
}
```

***

<div id="data-attribute-system">
  ## データ属性システム
</div>

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

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

これらの属性により、コードの明快さを維持しながら、柔軟でデータ駆動型のテンプレートを簡単に作成できます。

***

<div id="template-variable-changes">
  ## テンプレート変数の変更
</div>

V2 モジュールは、二重波括弧 `{{ }}` を使用する**新しいテンプレート変数構文**を使用します。

<div id="announcement-module">
  ## アナウンスメントモジュール
</div>

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

<div id="tiered-rewards-module">
  ## 階層型リワードモジュール
</div>

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

***

<div id="migration-process">
  ## 移行プロセス
</div>

<div id="1-backup-current-configuration">
  #### 1. 現在の構成をバックアップする
</div>

変更を行う前に、既存の**カスタム CSS** ファイルと **HTML** ファイルをバックアップしてください。

<div id="2-test-in-sandbox-mode">
  #### 2. サンドボックスモードでテストする
</div>

本番公開前に新しいモジュールを安全にテストするため、**サンドボックスモード**を使用して更新後のカートをセットアップしてください。

***

<div id="advanced-customization-with-v20">
  ## V2.0 での高度なカスタマイズ
</div>

<div id="custom-templates">
  ### カスタムテンプレート
</div>

V2.0 モジュールは、レイアウトと構造を完全に制御したいマーチャント向けに、完全な**カスタムテンプレート**をサポートしています。

カスタムテンプレートを有効にするには:

1. **Settings > Cart settings** に移動し、**Advanced Settings** を展開して **Access custom templates** にチェックを入れます。このチェックボックスは折りたたまれたセクションの中にあり、Cart settings タブ自体にはありません。
2. 機能トグルを有効にします。
3. 構文と例については、Upcart の開発者向けドキュメントを参照してください。

<img src="https://mintcdn.com/aftersell/uVGuDiyXpd6WOLO4/images/upcart/v2-migration-enabled-access-custom-templates.png?fit=max&auto=format&n=uVGuDiyXpd6WOLO4&q=85&s=43b637828ba38b90360f58fb3c6c5a37" alt="Upcart のカート設定で有効化された Access custom templates チェックボックスとその説明" width="1612" height="164" data-path="images/upcart/v2-migration-enabled-access-custom-templates.png" />

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

***

<div id="best-practices">
  ## ベストプラクティス
</div>

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

***

<div id="future-considerations">
  ## 今後の展望
</div>

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

##

##