> ## 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.

# بلوك إضافة المنتج

> بلوك Product add-on في Aftersell Cart: اعرض منتجًا محددًا واحدًا كإضافة سريعة داخل الدرج.

> يعرض بلوك **Product add-on** منتجًا واحدًا محددًا تختاره كإضافة داخل السلة، للترويج لمنتج معروف واحد (ضمان، عيّنة، منتج الأكثر مبيعًا) كإضافة سريعة مباشرةً في السلة.

<Info>
  بخلاف بلوك [**Upsells**](/ar/aftersell/cart/upsells-block) الذي يعرض منتجات تختارها استراتيجية، يعرض Product add-on دائمًا المنتج المحدد الذي تختاره بالضبط.
</Info>

<Frame>
  <img src="https://mintcdn.com/aftersell/1Y3gBpUfxv16VGSW/images/aftersell/cart-product-add-on-block-additional-product.png?fit=max&auto=format&n=1Y3gBpUfxv16VGSW&q=85&s=29c7598c41c78f6503af7f9cd7ec084a" alt="بلوك إضافة المنتج يعرض منتجًا إضافيًا ليضمّه المتسوق إلى سلته" width="678" height="125" data-path="images/aftersell/cart-product-add-on-block-additional-product.png" />
</Frame>

<div id="behavior">
  ## السلوك
</div>

* **إذا لم يُحل أي متغير نشط** — المنتج غير معيّن أو مؤرشف أو نفد من المخزون — لا يعرض البلوك **أي شيء** بدلًا من زر معطّل.
* يعكس عنصر التحكم ما إذا كان بند الإضافة *الخاص بهذا البلوك نفسه* موجودًا في السلة، لذا فإن إيقافه يزيل البند الذي أضافه (ولن يؤثر على المنتج نفسه إذا أُضيف من مكان آخر).
* يُشطب سعر المقارنة عندما يكون هناك تخفيض حقيقي؛ وتُخفى تسمية "% off" إذا انخفض الخصم بعد التقريب عن 1%.
* تعود صورة الإضافة إلى الصورة المميزة للمنتج عندما لا تكون للمتغير المختار صورة.

<div id="settings">
  ## الإعدادات
</div>

| الإعداد          | ما الذي يتحكم فيه                                                                          | الافتراضي                             |
| ---------------- | ------------------------------------------------------------------------------------------ | ------------------------------------- |
| **Display type** | كيفية ظهور عنصر الإضافة: **Toggle** أو **Checkbox**.                                       | Toggle                                |
| **Product**      | متغير المنتج المراد عرضه — منتقٍ واحد يغطي الاثنين. تأتي الصورة والسعر من المتغير المختار. | لا شيء                                |
| **Title**        | عنوان منسّق.                                                                               | `<strong>{{product_title}}</strong>`  |
| **Price label**  | سطر السعر.                                                                                 | `{{price}}`                           |
| **Description**  | نص داعم.                                                                                   | `Add {{product_title}} to your order` |

تدعم **Title** و**Price label** و**Description** جميعها الرموز الأربعة نفسها: `{{product_title}}` و`{{price}}` و`{{compare_at_price}}` و`{{savings}}`.

<div id="placement-and-limits">
  ## الموضع والحدود
</div>

* **المنطقة:** الجسم أو الأسفل.
* **الحد الأقصى:** 3 لكل حالة سلة — للسلة الممتلئة والسلة الفارغة حصة مستقلة لكل منهما.
* **الحالة:** السلة الممتلئة والفارغة معًا.
* لا يُضاف افتراضيًا. غير مقفل — يمكنك إزالته أو إخفاؤه.

<div id="custom-template">
  ## القالب المخصص
</div>

يدعم [قالبًا مخصصًا](/ar/aftersell/cart/custom-templates) من تبويب Code الخاص به، والذي يستبدل الترميز المدمج لهذا البلوك بكود JSX الخاص بك. هذه هي الخصائص (props) التي يستقبلها.

<div id="content">
  ### المحتوى
</div>

| الخاصية                   | النوع            | الغرض منها                                                                                      |
| ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------- |
| `addonTitle`              | `string`         | العنوان كنص عادي. استخدمه للنص البديل و`aria-label`، وكقيمة احتياطية عندما لا يوجد عنوان منسّق. |
| `addonTitleHtml`          | `string`         | عنوان منسّق كـ HTML مُعقَّم. يكون فارغًا عند عدم وجوده.                                         |
| `descriptionHtml`         | `string`         | وصف منسّق كـ HTML مُعقَّم. يكون فارغًا عند عدم وجوده.                                           |
| `formattedPrice`          | `string`         | تسمية السعر منسّقة بالعملة. تكون فارغة عندما لا تُعرض.                                          |
| `formattedCompareAtPrice` | `string`         | سعر المقارنة (MSRP) للمتغير منسّقًا. يكون فارغًا عندما لا يوجد توفير حقيقي.                     |
| `savings`                 | `string`         | تسمية التوفير بنسبة مئوية صحيحة، مثل `25%`. تكون فارغة عندما لا يوجد توفير.                     |
| `priceHtml`               | `string \| null` | سعر منسّق كـ HTML مُعقَّم من حقل السعر المخصص. يكون `null` عند الفراغ.                          |
| `ctaText`                 | `string`         | نص الزر، لصيغة `button`.                                                                        |
| `imageUrl`                | `string`         | صورة المنتج. تكون فارغة عند عدم وجودها.                                                         |
| `productUrl`              | `string`         | رابط صفحة المنتج. يكون فارغًا عند عدم وجوده، وفي هذه الحالة لا تربط الصورة أو العنوان.          |

<div id="state-and-actions">
  ### الحالة والإجراءات
</div>

| الخاصية        | النوع                                | الغرض منها                                                                                     |
| -------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `variantId`    | `number \| null`                     | المتغير المُحلّل. يكون `null` عندما لا يوجد متغير نشط، لأن المنتج غير معيّن أو نفد من المخزون. |
| `format`       | `'button' \| 'checkbox' \| 'toggle'` | كيفية إضافة المشتري للإضافة. فرّع ترميزك بناءً عليها.                                          |
| `isEnabled`    | `boolean`                            | ما إذا كانت الإضافة موجودة حاليًا في السلة.                                                    |
| `isAdding`     | `boolean`                            | تكون `true` أثناء تنفيذ الإضافة أو الإزالة. عطّل عنصر التحكم بناءً عليها.                      |
| `handleAdd`    | `() => void`                         | يضيف الإضافة. لصيغة `button`.                                                                  |
| `handleToggle` | `() => void`                         | يبدّل الإضافة داخل السلة وخارجها. لصيغتي `checkbox` و`toggle`.                                 |
| `isLoading`    | `boolean`                            | تكون `true` بينما لا تزال السلة تنفّذ أول جلب لها.                                             |

<Warning>
  تحدد `format` المعالج المناسب: `handleAdd` لصيغة `button`، و`handleToggle` لصيغتي `checkbox` و`toggle`. إذا كانت `variantId` تساوي `null` فلا يوجد ما يُضاف، لذا اجعل عنصر التحكم مشروطًا بها بدلًا من استدعاء معالج لا يمكنه النجاح.
</Warning>

<div id="design">
  ## التصميم
</div>

نسّق هذا البلوك من قسم **Design** الخاص به في لوحة الإعدادات. هذه تجاوزات على مستوى البلوك تُطبَّق فوق تصميمك العام وتعود إليه عند تركها فارغة.

<div id="text">
  ### Text
</div>

يتيح لك قسم **Text** في Design التحكم في طباعة ثلاثة عناصر. استخدم منتقي **Text element** للتبديل بينها.

**Title** — اسم المنتج. يدعم أيضًا عائلة خط مخصصة. يُضبط الخط العريض ولون النص من محرر النص المنسّق أعلاه (في علامة تبويب Settings)، وليس هنا.

| الإعداد            | ما الذي يتحكم فيه   | القيمة الافتراضية |
| ------------------ | ------------------- | ----------------- |
| **Font**           | عائلة خط العنوان.   | يرث من القالب     |
| **Size**           | حجم الخط.           | `15px`            |
| **Line height**    | مضاعف ارتفاع السطر. | `1.33`            |
| **Letter spacing** | التباعد بين الأحرف. | Normal            |

**Price** — سطر السعر. يُضبط الخط العريض ولون النص من محرر النص المنسّق أعلاه.

| الإعداد            | ما الذي يتحكم فيه   | القيمة الافتراضية |
| ------------------ | ------------------- | ----------------- |
| **Size**           | حجم الخط.           | `15px`            |
| **Line height**    | مضاعف ارتفاع السطر. | `1.33`            |
| **Letter spacing** | التباعد بين الأحرف. | Normal            |

**Description** — النص الداعم. يُضبط الخط العريض ولون النص من محرر النص المنسّق أعلاه.

| الإعداد            | ما الذي يتحكم فيه   | القيمة الافتراضية |
| ------------------ | ------------------- | ----------------- |
| **Size**           | حجم الخط.           | `14px`            |
| **Line height**    | مضاعف ارتفاع السطر. | `1.29`            |
| **Letter spacing** | التباعد بين الأحرف. | Normal            |

<Tip>
  النقر على عنصر نصي مباشرة في معاينة السلة يُبرزه ويفتح عناصر تحكمه في اللوحة تلقائيًا.
</Tip>

ما هي إعدادات التصميم؟ اعرف المزيد هنا: [إعدادات التصميم](/ar/aftersell/cart/design-settings).