> For the complete documentation index, see [llms.txt](https://docs.chamilo.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chamilo.org/3.x/ar/dlyl-almtw-r/developer-guide/frontend/vue-components.md).

# مكونات Vue

يمتلك Chamilo مجموعة كبيرة من مكونات Vue منظَّمة حسب مجال الميزة في `assets/vue/components/`.

## المكونات الأساسية

تغلف عائلة `Base*` في `assets/vue/components/basecomponents/` عناصر PrimeVue الأولية بقيم افتراضية خاصة بـ Chamilo (تخطيط FloatLabel، وأيقونات MDI عبر `chamiloIconToClass`، ورسائل تحقق متسقة، وأحجام Tailwind). استخدم دائمًا مكوّنًا من عائلة `Base*` قبل استيراد مكوّن PrimeVue الأساسي — فهكذا تبقى واجهة المستخدم متسقة عبر تطبيق الصفحة الواحدة، وهكذا يمكن طرح تغييرات التصميم من مكان واحد.

المكوّنات **غير** مسجَّلة عالميًا (العنصر الأولي الوحيد المسجَّل عالميًا من PrimeVue هو `Column`، ويُستخدم داخل `BaseTable`). استورد كل مكوّن صراحةً:

```js
import BaseButton from "@/components/basecomponents/BaseButton.vue"
import BaseDialog from "@/components/basecomponents/BaseDialog.vue"
```

### حقول النماذج

تقبل معظمها القيمة عبر `v-model`، وتعرّض خاصيتي `id` + `label` لإمكانية الوصول وربط التسمية العائمة، وتعرض التحقق عبر زوج `isInvalid` / `errorText` (أو `messageText`).

| المكوّن                          | يغلّف                                              | الغرض                                                                                                                                                                      |
| -------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BaseInputText.vue`              | `InputText` + `FloatLabel`                         | حقل نصي أحادي السطر. ينتقل إلى تسمية ثابتة لمدخلات `date`/`time`/`datetime-local` (حيث تتداخل التسمية العائمة مع العنصر النائب الأصلي).                                    |
| `BaseInputTextWithVuelidate.vue` | `BaseInputText`                                    | محوّل Vuelidate رقيق: يمرّر `$error` إلى `isInvalid` ويعرض `$errors[].$message` في فتحة `errors`. يُقرَن بكائن حقل Vuelidate.                                              |
| `BaseTextArea.vue`               | `Textarea` + `FloatLabel`                          | حقل نصي متعدد الأسطر.                                                                                                                                                      |
| `BaseTextAreaWithVuelidate.vue`  | `BaseTextArea`                                     | نفس نمط محوّل Vuelidate كما في `BaseInputTextWithVuelidate`.                                                                                                               |
| `BaseInputNumber.vue`            | `InputNumber`                                      | حقل رقمي مع `min` / `max` / `step` وأزرار دوّارة.                                                                                                                          |
| `BaseInputTags.vue`              | (مخصص)                                             | شرائح وسوم نص حر؛ تُضاف الوسوم عند Enter/الفاصلة وتُحذف عند Backspace.                                                                                                     |
| `BaseInputGroup.vue`             | `InputGroup` + `BaseButton`                        | حقل نصي مقترن بزر إجراء (بأسلوب البحث).                                                                                                                                    |
| `BaseCheckbox.vue`               | `Checkbox`                                         | خانة اختيار ثنائية أو مربوطة بقيمة مع تسمية.                                                                                                                               |
| `BaseRadioButtons.vue`           | `RadioButton`                                      | مجموعة أزرار اختيار مدفوعة بمصفوفة `options: [{label, value}]`.                                                                                                            |
| `BaseToggleButton.vue`           | `BaseButton`                                       | زر بحالتين (تسميات وأيقونات تشغيل / إيقاف) مربوط عبر `v-model`.                                                                                                            |
| `BaseCalendar.vue`               | `DatePicker` + `FloatLabel`                        | منتقي تاريخ / تاريخ-وقت. يحترم `platform.timepicker_increment` ومحلّ المستخدم عبر `calendarLocales`.                                                                       |
| `BaseColorPicker.vue`            | `<input type="color">` أصلي + `InputText`          | منتقي ألوان مع احتياطي نص سداسي عشري؛ يستخدم `colorjs.io` للتحقق من إدخال السداسي العشري اليدوي.                                                                           |
| `BaseRating.vue`                 | `Rating`                                           | حقل تقييم بالنجوم.                                                                                                                                                         |
| `BaseFileUpload.vue`             | `<input type="file">` أصلي + `BaseButton`          | منتقي ملف واحد يشغّل زرًا بأسلوب المرفق.                                                                                                                                   |
| `BaseFileUploadMultiple.vue`     | `<input type="file" multiple>` أصلي + `BaseButton` | المتغير متعدد الملفات من `BaseFileUpload`.                                                                                                                                 |
| `BaseUploader.vue`               | Uppy `Dashboard`                                   | رافع Uppy كامل (كاميرا ويب، صوت، محرر صور، رفع XHR) مع محليات مربوطة بـ `appLocale` الحالي. استخدم هذا للرفع الغني مع التقدّم؛ واستخدم `BaseFileUpload*` للمرفقات البسيطة. |

### التحديد والإكمال التلقائي

| المكوّن                | يغلّف                        | الغرض                                                                                                            |
| ---------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `BaseSelect.vue`       | `Dropdown` + `FloatLabel`    | قائمة منسدلة ذات اختيار واحد مع زر مسح اختياري.                                                                  |
| `BaseMultiSelect.vue`  | `MultiSelect` + `FloatLabel` | قائمة منسدلة متعددة الاختيار تعرض العناصر المحددة كشرائح (chips).                                                |
| `BaseSearchSelect.vue` | `Dropdown` with `filter`     | قائمة منسدلة ذات اختيار واحد مع مربع بحث مدمج، وتمرير افتراضي اختياري، وقالب خيار بسطرين (`label` + `sublabel`). |
| `BaseAutocomplete.vue` | `AutoComplete`               | إكمال تلقائي غير متزامن (حد أدنى 3 أحرف). يدعم الاختيار الفردي أو المتعدد وفتحة `chip` لتخصيص الشرائح.           |
| `BaseUserFinder.vue`   | `BaseTable` + `userService`  | جدول بحث عن المستخدمين مع ترقيم الصفحات وتحديد الصفوف. استخدمه عندما تحتاج ميزة إلى منتقي مستخدمين بأسلوب إداري. |

### الأزرار والإجراءات

| المكوّن                          | يغلّف               | الغرض                                                                                                                                                                                                                                                                                                                    |
| -------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `BaseButton.vue`                 | `Button` (PrimeVue) | زر Chamilo القياسي. يحل الأيقونات عبر `chamiloIconToClass`، ويوحّد `type` إلى `severity`/`variant` في PrimeVue، ويعرض `BaseAppLink` داخليًا عند إعطاء `route` أو `toUrl` (بحيث يعالج المكوّن نفسه حالات رابط الموجّه والرابط العادي والزر البسيط). قيم `type` المقبولة مدرجة في `validators.js` → `buttonTypeValidator`. |
| `BaseAdvancedSettingsButton.vue` | `BaseButton`        | زر كشف يبدّل لوحة «إعدادات متقدمة» مُدرَجة عبر `v-model`.                                                                                                                                                                                                                                                                |
| `BaseToolbar.vue`                | `Toolbar`           | شريط أدوات للإجراءات مع فتحات `start` / `end` (أو فتحة افتراضية واحدة). خاصية اختيارية `showTopBorder` لتنسيق الفاصل.                                                                                                                                                                                                    |

### العرض والبيانات

| المكوّن              | يغلّف                       | الغرض                                                                                                                                                                          |
| -------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `BaseTable.vue`      | `DataTable` (PrimeVue)      | جدول بيانات Chamilo القياسي. يدعم الوضع من جهة الخادم (`lazy`)، والفرز متعدد الأعمدة، والمرشح العام، وتحديد الصفوف، والترقيم. مرّر الأعمدة كأبناء `<Column>` (مسجّلة عالميًا). |
| `BaseCard.vue`       | `Card`                      | غلاف بطاقة يمرّر فتحات `header` و`title` و`subtitle` و`footer` والفتحة الافتراضية (المحتوى).                                                                                   |
| `BaseChart.vue`      | `Chart`                     | إعداد مسبق لمخطط دائري. مرّر كائن `data` متوافقًا مع Chart.js.                                                                                                                 |
| `BaseChip.vue`       | `Chip`                      | شريحة تُعرض من كائن `{value, labelField, imageField}`، مع زر إزالة اختياري.                                                                                                    |
| `BaseTag.vue`        | `Tag`                       | وسم تسمية ملوّن. يربط `warning` في Chamilo بـ `warn` في PrimeVue.                                                                                                              |
| `BaseAvatarList.vue` | `Avatar` + `BaseUserAvatar` | صف صور رمزية مع عدّاد فائض (مثل "+3")؛ يُدار بواسطة `useAvatarList`.                                                                                                           |
| `BaseUserAvatar.vue` | `Avatar`                    | صورة رمزية للمستخدم مع احتياطي للصورة، وحالة تحميل، وتسمية قابلة للوصول.                                                                                                       |
| `BaseIcon.vue`       | `<i class="mdi …">`         | عارض أيقونات Chamilo. يضيف شارة اختيارية (نص أو أيقونة)، وتلميحًا، ومعدّل حجم. مرّر دائمًا اسمًا دلاليًا من Chamilo (مثل `"edit"`)، وليس صنف MDI خامًا.                        |
| `BaseIconField.vue`  | `IconField` + `InputText`   | حقل بحث مع أيقونة عدسة مكبرة في المقدمة.                                                                                                                                       |
| `BaseDivider.vue`    | `Divider`                   | فاصل أفقي أو عمودي، مع عنوان ومحاذاة اختياريين.                                                                                                                                |

### التنقل والقوائم

| المكوّن                    | يغلّف                   | الغرض                                                                                                                                                         |
| -------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BaseMenu.vue`             | `Menu` (منبثقة)         | قائمة منبثقة تفهم مسارات الموجّه داخل عناصر `model[]`.                                                                                                        |
| `BaseDropdownMenu.vue`     | (مخصص)                  | محفّز قائمة منسدلة خفيف مع تنسيق الفتح الواحد (فتح واحدة يغلق الأخريات).                                                                                      |
| `BaseContextMenu.vue`      | (مخصص)                  | قائمة سياق بالنقر الأيمن / موضعية، تُتحكم بها عبر `visible` + `position`.                                                                                     |
| `BaseSidebarPanelMenu.vue` | `PanelMenu`             | قائمة تنقل بأسلوب الأكورديون تُستخدم في الأشرطة الجانبية؛ تتعقّب تلقائيًا المفاتيح الموسَّعة من النموذج.                                                      |
| `BaseRouteTabs.vue`        | صف `BaseAppLink`        | شريط تبويب يكون فيه كل تبويب رابط موجّه. يُبرَز التبويب النشط تلقائيًا بناءً على المسار الحالي.                                                               |
| `BaseAppLink.vue`          | `RouterLink` *أو* `<a>` | رابط ذكي: يعرض `<a>` عندما تُضبط `url` (خارجي/قديم)، وإلا يعرض `<RouterLink>` من Vue Router. استخدمه بدل أي من البدائيين ليبقى الربط الداخلي/الخارجي موحّدًا. |

### مربعات الحوار

`BaseDialog` هو الأساس؛ أما المكونات الأخرى فتتراكب فوقه لتدفقات التأكيد/الإلغاء والحذف الشائعة.

| المكوّن                       | يغلّف                     | الغرض                                                                                                                       |
| ----------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `BaseDialog.vue`              | `Dialog`                  | مربع حوار نمطي مع ترويسة معنونة (`headerIcon` اختياري) وجسم/تذييل عبر الفتحات. حالة الفتح هي `defineModel("isVisible")`.    |
| `BaseDialogConfirmCancel.vue` | `BaseDialog`              | مربع حوار تأكيد/إلغاء بزرّين. نوع التأكيد `type` (الشدة) و`icon` قابلان للتهيئة؛ يُصدِر `confirmClicked` / `cancelClicked`. |
| `BaseDialogDelete.vue`        | `BaseDialogConfirmCancel` | مربع حوار جاهز «هل أنت متأكد أنك تريد حذف هذا العنصر؟» مع زر تأكيد بأسلوب الخطر.                                            |

### المحرّر والمحتوى الغني

| المكوّن              | يغلّف                                           | الغرض                                                                                                                                       |
| -------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `BaseTinyEditor.vue` | TinyMCE (via the project's `components/Editor`) | محرّر نصوص غني مع `FloatLabel`، وتتبع حالة التركيز/الفراغ، والتكامل مع سياق المقرر الحالي (`cidReq`). استخدمه لأي حقل HTML يحرّره المستخدم. |

### المساعدات

| الملف             | الغرض                                                                                                                                                                                                                                                 |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ChamiloIcons.js` | يربط أسماء الأيقونات الدلالية (`edit`، `delete`، `eye-on`، `courses`، …) بفئات CSS الخاصة بـ MDI. نحو 127 مدخلاً. تصفّحها على `/admin/list-icons` في نسخة قيد التشغيل.                                                                                |
| `validators.js`   | مدقّقات خصائص مشتركة: `iconValidator` (يجب أن يكون اسم أيقونة Chamilo معروفاً)، `sizeValidator` (`normal` / `small` / `large`)، `buttonTypeValidator` (أنواع `BaseButton` المسموح بها). استوردها عند تعريف مكوّنات `Base*` جديدة تتبع هذه الاتفاقيات. |

### الاتفاقيات عبر مكوّنات Base

* **v-model عبر `defineModel()`** — تُعرَض القيمة (وكثيراً `isVisible` و`filters` و`selectedItems`) كنماذج؛ مرّرها بـ `v-model[:name]` بدلاً من `:prop` + `@update:prop`.
* **التسميات العائمة** — معظم حقول النماذج تغلف إدخالها في PrimeVue `FloatLabel variant="on"`. وفّر `label` (النص المعروض) و`id` (يُستخدم لربط `<label for>`).
* **رسائل التحقق** — تعرض الحقول `isInvalid` ورسالة صغيرة أسفل الإدخال (`errorText` أو `messageText` أو `smallText` حسب المكوّن). توجد متغيرات واعية لـ Vuelidate للأكثر شيوعاً.
* **الأيقونات** — مرّر أسماء Chamilo الدلالية، وليس فئات MDI الخام. تحلّ المكوّنات ذلك عبر `chamiloIconToClass`.
* **التحجيم** — `size="normal" | "small" | "large"` هو خاصية التحجيم التقليدية (انظر `sizeValidator`).
* **التركيب بدل التكرار** — `BaseDialogDelete` يغلّف `BaseDialogConfirmCancel` الذي يغلّف `BaseDialog`؛ و`BaseToggleButton` و`BaseAdvancedSettingsButton` يغلّفان `BaseButton`. عندما تحتاج متغيراً متكرراً لمكوّن موجود، فضّل تركيب `Base*` جديد فوقه بدلاً من إعادة تنفيذه في مجلد ميزة.

## مكوّنات التخطيط

تقع في `components/layout/`:

| المكوّن               | الغرض                                                           |
| --------------------- | --------------------------------------------------------------- |
| `DashboardLayout.vue` | التخطيط الرئيسي: الشريط العلوي + الشريط الجانبي + منطقة المحتوى |
| `Sidebar.vue`         | لوحة التنقل اليسرى (قابلة للطي)                                 |
| `TopbarLoggedIn.vue`  | الشريط العلوي مع الشعار وصندوق الوارد والصورة الرمزية           |

## مكوّنات مجالات الميزات

| Directory      | Components                                       | Purpose                                 |
| -------------- | ------------------------------------------------ | --------------------------------------- |
| `course/`      | بطاقات المقررات، مرشحات الكتالوج، نماذج المقررات | سرد المقررات وإدارتها                   |
| `session/`     | بطاقات الجلسات، الكتالوج                         | سرد الجلسات                             |
| `assignments/` | قوائم التسليمات، نوافذ التقييم المنبثقة، النماذج | سير عمل الواجبات                        |
| `chat/`        | DockedChat، رسائل الدردشة                        | الدردشة الفورية ومعلّم الذكاء الاصطناعي |
| `filemanager/` | CourseDocuments، PersonalFiles                   | متصفح الملفات وإدارتها                  |
| `installer/`   | Step1-Step7، EmailSettings                       | معالج التثبيت                           |
| `social/`      | GroupInfoCard، المنشورات الاجتماعية              | ميزات الشبكة الاجتماعية                 |
| `attendance/`  | AttendanceTable                                  | تتبّع الحضور                            |
| `usergroup/`   | GroupMembers                                     | إدارة مجموعات المستخدمين                |

## نظام الأيقونات

تستخدم الأيقونات **Material Design Icons (MDI)** كمكتبة الأيقونات الوحيدة: `<i class="mdi mdi-pencil"></i>`

يوفر الملف `ChamiloIcons.js` تعيينًا دلاليًا:

```javascript
export const chamiloIconToClass = {
  "edit": "mdi mdi-pencil",
  "delete": "mdi mdi-delete",
  "eye-on": "mdi mdi-eye",
  "courses": "mdi mdi-book-open-page-variant",
  // ... 127 mappings
}
```

تستخدم المكوّنات `BaseIcon` أو تشير إلى `chamiloIconToClass` لعرض الأيقونات بشكل متسق.

يمكن العثور على مرجع قابل للتصفح لجميع الأيقونات المتاحة في المنصة على `/admin/list-icons` في أي نسخة قيد التشغيل من Chamilo.

## أنماط المكوّنات

* **Composition API** — تستخدم المكوّنات صياغة `<script setup>` في Vue 3
* **تكامل PrimeVue** — استخدام مكثّف لمكوّنات PrimeVue (Button، DataTable، Dialog، Menu، وغيرها)
* **Axios لاستدعاءات API** — طلبات HTTP إلى واجهة برمجة التطبيقات الخلفية
* **Vue I18n** — يستخدم كل النص الموجّه للمستخدم مفاتيح الترجمة