> ## 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">
  #### أسماء الفئات الداخلية
</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">
  #### أسماء الفئات العامة
</div>

🚨 قائمة أسماء الفئات العامة المتاحة

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

###

<div id="dos">
  ### ✅ ما يجب فعله
</div>

استخدم فقط أسماء فئات `upcart-public-` للتنسيق.

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

<div id="donts">
  ### ❌ ما يجب تجنبه
</div>

تجنّب تجاوز أسماء الفئات الداخلية

```
/* ❌ 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 **نظام سمات بيانات (data attributes)** منظمًا لتحسين الاستهداف والتخصيص المتقدم.

```
<!-- 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. اختبر في وضع Sandbox
</div>

أعدّ سلتك المحدّثة باستخدام **وضع sandbox** لاختبار الوحدات الجديدة بأمان قبل الإطلاق.

***

<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="مربع اختيار Access custom templates مفعّل مع وصفه في إعدادات سلة Upcart" width="1612" height="164" data-path="images/upcart/v2-migration-enabled-access-custom-templates.png" />

**ملاحظة:** لا يمكن لفريق دعم Upcart المساعدة في تطوير القوالب المخصصة أو تصحيح أخطائها أو استكشاف مشاكلها وإصلاحها.

***

<div id="best-practices">
  ## أفضل الممارسات
</div>

* اختبر التحديثات دائمًا في **وضع sandbox** أولاً.
* رقِّ التخصيصات وحدّثها تدريجيًا.
* استخدم **الفئات العامة** للتنسيق بدلاً من الفئات الداخلية.
* احتفظ بنسخ احتياطية من جميع الإصدارات السابقة قبل تحديث الإعدادات المباشرة.

***

<div id="future-considerations">
  ## اعتبارات مستقبلية
</div>

* ستستمر وحدات V2 في تلقي ميزات جديدة وتحسينات وتحديثات.
* وحدات V1 الآن في **وضع الصيانة** بدعم محدود ودون ميزات جديدة.
* نشجع التجار على الترقية إلى V2 في أقرب وقت ممكن لتحقيق التوافق الكامل.

##

##