> ## 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/Universal%20Variant%20Picker.png)

مكون محدد متغيرات متصل بـ Shopify لـ Framer يعرض أزرار خيارات قابلة للنقر (الحجم، اللون، نمط الإطار، إلخ) مع فحص التوافر في الوقت الفعلي.

***

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

يعرض **محدد المتغيرات الشامل** الخيارات القابلة للتحديد لمنتج Shopify — مثل الحجم أو اللون أو نمط الإطار — كصف أو عمود من الأزرار. صُمِّم ليوضع مرة لكل نوع خيار، لذا فإن منتجًا يحتوي على خياري الحجم واللون يستخدم نسختين منفصلتين من هذا المكون.

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

* **يعرض مجموعة خيار واحدة** — تتعامل كل نسخة مع نوع خيار واحد (مثال: محدد للحجم، وآخر للون). يُعيَّن اسم الخيار عبر ضابط **Variant Name**.
* **التوافر المباشر من Shopify** — عند التحميل، يستعلم المكون عن Shopify Storefront API لجلب حالة `availableForSale` الحديثة لكل متغير، متجاوزًا بيانات CMS القديمة.
* **منطق اختيار ذكي** — عند اختيار قيمة (مثل "XL")، يجد المكون المتغير الذي يطابق القيمة الجديدة وجميع الخيارات المحددة الأخرى، مما يُبقي التحديدات متسقة عبر المحددات.
* **الخيارات غير المتاحة** — تُعرض المتغيرات النافدة بشفافية مخفضة مع خط مائل قطري ولا يمكن النقر عليها.
* **الحالة مدفوعة بـ URL** — يُحفظ المتغير النشط في معامل URL ‏`?variant=`. جميع المحددات في الصفحة تقرأ وتكتب في نفس هذا المعامل، لذا تبقى متزامنة مع بعضها ومع مكونات المعرض.
* **الاختيار التلقائي للأول المتاح** — إذا لم يكن هناك متغير صالح في URL، يختار المكون تلقائيًا أول متغير متاح ويعيّنه.
* **تسمية اختيارية** — يمكن عرض تسمية نصية (مثل "الحجم") فوق أو بجانب الخيارات مع التحكم الكامل في الطباعة واللون.

***

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

جميع الضوابط متاحة في لوحة Framer اليمنى عند تحديد المكون. تُجمَّع في أربعة أقسام: **المتغيرات**، **اسم المتغير**، **التسمية**، و**الخيارات**.

### المتغيرات *(CMS)*

| الخاصية      | النوع     | الوصف                                                                                                                                                                                     |
| :----------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Variants** | نص (JSON) | مصفوفة JSON من جميع كائنات متغيرات المنتج من Shopify، يحتوي كل منها على `id` و`title` و`price` و`availableForSale` و`image` و`selectedOptions`. اربط هذا بمتغير `Variants` من Framer CMS. |

### اسم المتغير

| الخاصية          | النوع | الافتراضي | الوصف                                                                                                                                                      |
| :--------------- | :---- | :-------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Variant Name** | نص    | `Size`    | الاسم الدقيق لخيار Shopify الذي يتحكم فيه هذا المحدد. يجب أن يطابق اسم الخيار في Shopify تمامًا (مثال: `Color`، `Size`، `Frame Style`). حساس لحالة الأحرف. |

### التسمية

يتحكم في التسمية المعروضة بجانب أزرار الخيارات.

| الخاصية       | النوع | الافتراضي | الوصف                                                                                            |
| :------------ | :---- | :-------- | :----------------------------------------------------------------------------------------------- |
| **Show**      | قائمة | `Show`    | إظهار أو إخفاء التسمية. الخيارات: `Show`، `Hide`.                                                |
| **Font**      | خط    | —         | إعدادات الطباعة لنص التسمية (العائلة، الحجم، الوزن، إلخ).                                        |
| **Color**     | لون   | —         | لون نص التسمية.                                                                                  |
| **Direction** | قائمة | `Column`  | اتجاه تخطيط التسمية نسبة إلى الخيارات. `Row` يضع التسمية بجانب الخيارات؛ `Column` يضعها فوقها.   |
| **Gap**       | مسافة | `8px`     | المسافة بين التسمية ومجموعة الخيارات.                                                            |
| **Alignment** | قائمة | `Center`  | المحاذاة الرأسية للتسمية والخيارات في اتجاه `Row`. الخيارات: `Center`، `Flex Start`، `Flex End`. |

### الخيارات

يتحكم في مظهر وتخطيط أزرار الخيارات الفردية.

#### التخطيط

| الخاصية           | النوع     | الافتراضي                   | الوصف                                                      |
| :---------------- | :-------- | :-------------------------- | :--------------------------------------------------------- |
| **Layout**        | قائمة     | `Row`                       | ترتيب أزرار الخيارات أفقيًا (`Row`) أو عموديًا (`Column`). |
| **Gap**           | مسافة     | `8px`                       | المسافة بين أزرار الخيارات الفردية.                        |
| **Padding**       | حشو       | `12px`                      | المسافة الداخلية لكل زر خيار.                              |
| **Border Radius** | نصف القطر | `8px`                       | يجعل زوايا كل زر خيار مستديرة.                             |
| **Border**        | حدود      | `1px solid rgba(0,0,0,0.5)` | نمط الحدود المطبق على جميع أزرار الخيارات.                 |
| **Box Shadow**    | ظل        | —                           | ظل مطبق على أزرار الخيارات.                                |
| **Font**          | خط        | —                           | الطباعة للنص داخل أزرار الخيارات.                          |

#### الحالات

تمتلك أزرار الخيارات ثلاث حالات بصرية — **محدد**، **غير محدد**، و**معطّل** — لكل منها ضوابط ألوان مستقلة.

**محدد** *(الخيار النشط حاليًا)*

| الخاصية        | النوع | الافتراضي | الوصف                       |
| :------------- | :---- | :-------- | :-------------------------- |
| **Color**      | لون   | `#fff`    | لون نص زر الخيار المحدد.    |
| **Background** | لون   | `#000`    | لون خلفية زر الخيار المحدد. |

**غير محدد** *(متاح لكن غير نشط)*

| الخاصية        | النوع | الافتراضي | الوصف                                 |
| :------------- | :---- | :-------- | :------------------------------------ |
| **Color**      | لون   | `#000`    | لون نص أزرار الخيارات غير المحددة.    |
| **Background** | لون   | `#fff`    | لون خلفية أزرار الخيارات غير المحددة. |

**معطّل** *(نافد من المخزون)*

| الخاصية   | النوع | الافتراضي | الوصف                                                                  |
| :-------- | :---- | :-------- | :--------------------------------------------------------------------- |
| **Color** | لون   | `#999`    | لون نص أزرار الخيارات غير المتاحة. تُعرض أيضًا بشفافية 50% مع خط قطري. |

## ملاحظات

* يتطلب هذا المكون تعيين `window.DOMAIN` و`window.ACCESSTOKEN` عالميًا على الصفحة لجلب التوافر المباشر من Shopify. بدونها، يعود المكون إلى بيانات التوافر من CMS.
* ضع نسخة واحدة من هذا المكون لكل نوع خيار. منتج يحتوي على خياري الحجم واللون يحتاج إلى نسختين منفصلتين من **محدد المتغيرات الشامل**، لكل منهما **Variant Name** مختلف.
* يجب أن يطابق **Variant Name** اسم الخيار كما هو محدد في Shopify تمامًا (مثال: `Frame Style` وليس `frame style` أو `FrameStyle`).
* جميع المحددات ومكونات المعرض في نفس الصفحة تتشارك الحالة تلقائيًا عبر معامل URL ‏`?variant=` — لا حاجة لتوصيلات إضافية.