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

# زر إضافة إلى عربة التسوق

![معاينة زر إضافة إلى عربة التسوق](https://raw.githubusercontent.com/thedesignmvp/framerfy-assets/refs/heads/main/docs/Add%20to%20Cart%20Button.png)

زر إضافة إلى عربة التسوق متصل بـ Shopify لـ Framer يقرأ المتغير المحدد حاليًا من URL، ويضيفه إلى عربة التسوق في `localStorage`، ويعرض اختياريًا إشعار تنبيه يؤكد الإجراء.

***

## ما الذي يفعله

**زر إضافة إلى عربة التسوق** هو زر منسق ومتحرك يتعامل مع عملية إضافة المنتج إلى عربة التسوق بالكامل. يقرأ المتغير النشط من URL، ويجد تفاصيله من بيانات المتغيرات، ويكتب العنصر في عربة التسوق بـ `localStorage` — مع زيادة الكمية إذا كان العنصر موجودًا بالفعل في العربة.

السلوكيات الرئيسية:

* **يقرأ المتغير النشط من URL** — عند النقر، يقرأ معامل URL ‏`?variant=` لتحديد المتغير المراد إضافته. يتحدث تلقائيًا عند تغيير URL (مثل عند تبديل المستخدم للمتغيرات).
* **يضيف أو يزيد** — إذا كان المتغير موجودًا بالفعل في العربة، تزيد كميته بمقدار `1`. إذا كان جديدًا، يُضاف كإدخال جديد في العربة بكمية `1`.
* **يكتب في** `localStorage` — يحفظ العربة المحدَّثة في `localStorage` تحت المفتاح `cart` ويطلق حدث `cartUpdated` لإبقاء جميع مكونات عربة التسوق الأخرى متزامنة.
* **إشعار التنبيه** — يعرض اختياريًا تنبيهًا عائمًا مع صورة المنتج والعنوان واسم المتغير بعد الإضافة الناجحة. موضع التنبيه والإزاحة قابلان للتخصيص بالكامل.
* **حالة التحميل** — أثناء إضافة العنصر، يعرض الزر نص تحميل قابل للتخصيص ويُعطَّل مؤقتًا لمنع النقر المزدوج.
* **زر متحرك** — يتضمن تصغيرًا خفيفًا عند اللمس وانتقال نصف قطر الحدود عند التحويم عبر Framer Motion.

***

## ضوابط الخصائص

جميع الضوابط متاحة في لوحة Framer اليمنى عند تحديد المكون. تُجمَّع في سبعة أقسام: **Store ID**، **Product ID**، **Product Title**، **Variants**، **Image URLs**، **Texts**، **Styles**، و**Toast Layout**.

### Store ID

| الخاصية      | النوع | الوصف                                                                                       |
| :----------- | :---- | :------------------------------------------------------------------------------------------ |
| **Store ID** | نص    | معرّف متجر Shopify. اربط هذا بمتغير `Store ID` من Framer CMS. يُستخدم لحساب السعر الإجمالي. |

### Product ID

| الخاصية        | النوع | الوصف                                                                                                    |
| :------------- | :---- | :------------------------------------------------------------------------------------------------------- |
| **Product ID** | نص    | معرّف منتج Shopify. اربط هذا بمتغير `Product ID` من Framer CMS. مطلوب لتعريف عنصر عربة التسوق بشكل صحيح. |

### Product Title

| الخاصية           | النوع | الوصف                                                                                                 |
| :---------------- | :---- | :---------------------------------------------------------------------------------------------------- |
| **Product Title** | نص    | اسم المنتج. اربط هذا بمتغير `Title` من Framer CMS. يُستخدم كعنوان عنصر عربة التسوق وفي إشعار التنبيه. |

### Variants *(CMS)*

| الخاصية      | النوع     | الوصف                                                                                                                                                                |
| :----------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Variants** | نص (JSON) | مصفوفة JSON من جميع كائنات المتغيرات لهذا المنتج. اربط هذا بمتغير `Variants` من Framer CMS. يُستخدم للبحث عن السعر والعنوان والخيارات المحددة والصورة للمتغير النشط. |

### Image URLs *(CMS)*

| الخاصية        | النوع     | الوصف                                                                                                                                                 |
| :------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Image URLs** | نص (JSON) | مصفوفة JSON من كائنات روابط صور المنتج. اربط هذا بمتغير `Image URLs` من Framer CMS. يُستخدم كصورة احتياطية عندما لا يكون للمتغير المحدد صورة خاصة به. |

### Texts

| الخاصية          | النوع | الافتراضي     | الوصف                                                         |
| :--------------- | :---- | :------------ | :------------------------------------------------------------ |
| **Button Text**  | نص    | `Add to cart` | التسمية المعروضة على الزر في حالته الافتراضية.                |
| **Loading Text** | نص    | `Adding`      | التسمية المعروضة على الزر أثناء إضافة العنصر إلى عربة التسوق. |

### Styles

يتحكم في المظهر البصري للزر.

| الخاصية              | النوع     | الافتراضي                          | الوصف                  |
| :------------------- | :-------- | :--------------------------------- | :--------------------- |
| **Font**             | خط        | `16px`                             | الطباعة لتسمية الزر.   |
| **Padding**          | حشو       | `12px`                             | المسافة الداخلية للزر. |
| **Background Color** | لون       | `#000000`                          | لون خلفية الزر.        |
| **Text Color**       | لون       | `#ffffff`                          | لون نص تسمية الزر.     |
| **Border Radius**    | نصف القطر | `12px`                             | استدارة زوايا الزر.    |
| **Border**           | حدود      | `1px solid rgba(0,0,0,0.5)`        | نمط حدود الزر.         |
| **Box Shadow**       | ظل        | `0px 1px 2px 0px rgba(0,0,0,0.25)` | الظل المطبق على الزر.  |

### Toast Layout

يتحكم في إشعار التأكيد المعروض بعد إضافة عنصر إلى عربة التسوق.

| الخاصية            | النوع | الافتراضي    | الوصف                                                                                                                          |
| :----------------- | :---- | :----------- | :----------------------------------------------------------------------------------------------------------------------------- |
| **Enable Toast**   | منطقي | `true`       | تفعيل أو تعطيل إشعار التنبيه.                                                                                                  |
| **Toast Position** | قائمة | `Top Center` | موضع ظهور التنبيه على الشاشة. الخيارات: `Top Center`، `Top Left`، `Top Right`، `Bottom Left`، `Bottom Center`، `Bottom Right`. |

**Offset** — ضبط دقيق لموضع التنبيه نسبة إلى حواف الشاشة:

| الخاصية    | النوع      | الافتراضي | الوصف                   |
| :--------- | :--------- | :-------- | :---------------------- |
| **Top**    | رقم (بكسل) | `64`      | المسافة من أعلى الشاشة. |
| **Right**  | رقم (بكسل) | `64`      | المسافة من يمين الشاشة. |
| **Bottom** | رقم (بكسل) | `64`      | المسافة من أسفل الشاشة. |
| **Left**   | رقم (بكسل) | `64`      | المسافة من يسار الشاشة. |

## ملاحظات

* لا يفعل الزر شيئًا إذا لم يُعيَّن **Product ID** — احرص دائمًا على ربطه من CMS.
* يُقرأ المتغير النشط من معامل URL ‏`?variant=`. إذا لم يكن هناك متغير محدد عند النقر على الزر، فسيكون `selectedVariant` فارغًا وسيفشل البحث عن المتغير بصمت. تأكد من وجود محدد متغير في نفس الصفحة.
* عنصر عربة التسوق المكتوب في `localStorage` يتضمن: `productId`، `variantId`، `title`، `variantTitle`، `price`، `quantity`، `selectedOptions`، و`image`.
* بعد كل إضافة، يُطلَق حدث `cartUpdated` على `window`، مما يُبقي عداد عناصر عربة التسوق ومتحكم حالة عربة التسوق وقائمة منتجات عربة التسوق والسعر الإجمالي لعربة التسوق متزامنة تلقائيًا.
* يُعرض إشعار التنبيه باستخدام مكتبة [Sonner](https://sonner.emilkowal.ski/) ويُظهر صورة المنتج والعنوان واسم المتغير.