# Alpine.js
[](https://alpinejs.codewithhugo.com/chat/)
توفر لك Alpine.js بنية تفاعلية (تصريحية) مثل أُطر العمل الشهيرة Vue و React بكُلفة وجهد أقل بكثير.
يمكنك الإحتفاظ بـ DOM والاستمرار في استخدامه، وإضافة الدّوال والوظائف له عند الحاجة.
يشبه إلى حد ما [Tailwind](https://tailwindcss.com/) ولكن في الجافاسكربت.
> ملاحظة: نشير إلى أن بُنية Alpine.js شبية جداً بـ [Vue](https://vuejs.org/) (أو [Angular](https://angularjs.org/)). أنا ممتن لهذه الأُطر بما قدموه في تطوير الويب.
#### ملاحظة:
يمكنك قراءة التوثيق بتنسيق أفضل "RTL" من الرابط التالي ([AlpineJs بالعربية](https://alpinejs.abdelhadi.org/#/)).
## التوثيق بلغات أخرى
| Language | Link for documentation |
| --- | --- |
| Arabic | [**التوثيق باللغة العربية**](./README.ar.md) |
| Chinese Traditional | [**繁體中文說明文件**](./README.zh-TW.md) |
| German | [**Dokumentation in Deutsch**](./README.de.md) |
| Indonesian | [**Dokumentasi Bahasa Indonesia**](./README.id.md) |
| Japanese | [**日本語ドキュメント**](./README.ja.md) |
| Portuguese | [**Documentação em Português**](./README.pt.md) |
| Russian | [**Документация на русском**](./README.ru.md) |
| Spanish | [**Documentación en Español**](./README.es.md) |
| Turkish | [**Türkçe Dokümantasyon**](./README.tr.md) |
| Français | [**Documentation en Français**](./README.fr.md) |
## التركيب
**باستعمال CDN:** أضف السطر البرمجي التالي في نهاية ``.
```html
```
سيقوم Alpine.js بتهيئة نفسه، سهلة أليس كذلك!
في بيئات التطوير، نوصي باستعمال إصدار محدّد كما في الرابط، لتجنب حدوث مشاكل غير متوقعة أو تصادمها مع الإصدارات الحديثة. على سبيل المثال، لاستخدام الإصدار الأخير (2.8.2) يمكنك كتابة:
```html
```
**باستعمال NPM:** قم بتنصيب الحزمة من NPM.
```js
npm i alpinejs
```
قم باستدعائها وتضمينها في مشروعك.
```js
import 'alpinejs'
```
**لدعم نسخة المتصفّح IE11** يرجى استعمال السُطور البرمجية التالية بدلاً عن السابق.
```html
```
لو تُلاحظ في السطور أعلاه كتبنا [module/nomodule pattern](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/) ، تسمح هذه الأنماط للمتصفحات الحديثة بتحميل مجموعة الوحدات بشكل تلقائي، بينما ستقوم IE11 والمتصفحات القديمة الأخرى تبحميل وحدات IE11 تلقائياً.
## طريقة الاستخدام
القائمة المنسدلة (Dropdown) والنوافذ (Modal)
```html
محتوى القائمة
```
*علامات التبويب (Tabs)*
```html
النافذة Foo
النافذة Bar
```
يمكنك أيضاً استخدامه في أماكن أخرى:
*التحضير المُسبق (Pre-fetching) لمُحتوى HTML.*
```html
جارٍ التحميل ...
```
## الشرح
هناك إجمالي 14 موجّهاً مُتاحا:
| الموجّه | الوصف |
| --: | --: |
| [`x-data`](#x-data) | إعلان أو تعريف حقل (Scope) جديد للمكوّن. |
| [`x-init`](#x-init) | ينفّذ تعليمات برمجية عند تشغيل إحدى المكوّنات. |
| [`x-show`](#x-show) | إظهار أو إزالة العناصر بناء على التعبيرات المنطقية `display: none;` صحيحة أو خاطئة. |
| [`x-bind`](#x-bind) | يضبط قيمة السّمة (attribute) على حسب نتائج تعليمات الجافاسكربت. |
| [`x-on`](#x-on) | يربط المُنصِت للأحداث (event listener) بالعنصر، يتم تنفيذ تعليمات الجافاسكربت عند التفاعل معه. |
| [`x-model`](#x-model) | يضيف اتصالا للبيانات ثنائي الإتجاه "two-way data binding" حيث أن القيم الذي يُدخلها المستخدم تتم مزامنتها مع قيمة بيانات العنصر للمكوّن. |
| [`x-text`](#x-text) | يعمل بشكل مشابه لـ `x-bind`، ولكنه يقوم بتحديث النص المضمن `innerText` داخل العنصر. |
| [`x-html`](#x-html) | يعمل بشكل مشابه لـ `x-bind`، ولكنه يقوم بتحديث النص المضمن `innerText` داخل العنصر. |
| [`x-ref`](#x-ref) | طريقة سهلة لاسترجاع عنصر داخل DOM موجود خارج المكوّن الخاص بك. |
| [`x-if`](#x-if) | إزالة عنصر تماماً من الـDOM. يجب استخدامه داخل وَسم `` |
| [`x-for`](#x-for) | ينشئ فروع DOM جديدة لكل عنصر من عناصر المصفوفة. يجب استخدامه داخل وَسم `` |
| [`x-transition`](#x-transition) | توجيه لعمل تأثيرات انتقالية في مراحل مختلفة على الأصناف (Classes) |
| [`x-spread`](#x-spread) | يسمح لك بربط الكائنات التي تحتوي على توجيهات Alpine بالعناصر، لتحسين إمكانية إعادة استخدامه بشكل أفضل. |
| [`x-cloak`](#x-cloak) | تتم إزالة هذه السمة عند تهيئة Alpine. مفيد لإخفاء DOM المُهيأ مسبقًا. |
و 6 خصائص سحرية:
| الخصائص السحرية | الوصف |
| --: | --: |
| [`$el`](#el) | ترجع فرع DOM الخاص بالمكوّن الأساسي (root component). |
| [`$refs`](#refs) | يسترجع عناصر DOM المميّزة بـ `x-ref` داخل المكوّن. |
| [`$event`](#event) | يرجع كائن الحدث "Event" الأصلي داخل المُنصت لأحداث المستخدم. |
| [`$dispatch`](#dispatch) | ينشئ حدثاً مخصصا `CustomEvent` ويرسله داخلياً باستخدام `.dispatchEvent()`. |
| [`$nextTick`](#nexttick) | بعد معالجة Alpine لتحديث DOM يتم تنفيذ تعليمات برمجية. |
| [`$watch`](#watch) | يقوم باستدعاء callback تم تحديده مسبقاً عندما يتم تعديل خاصية المُراقب "watched" |
## الرعاة
**هل تريد عرض شعارك هنا؟ [راسلني على تويتر](https://twitter.com/calebporzio)**
## مشاريع المجتمع
* [AlpineJS Weekly Newsletter](https://alpinejs.codewithhugo.com/newsletter/)
* [Spruce (State Management)](https://github.com/ryangjchandler/spruce)
* [Turbolinks Adapter](https://github.com/SimoTod/alpine-turbolinks-adapter)
* [Alpine Magic Helpers](https://github.com/KevinBatdorf/alpine-magic-helpers)
* [Awesome Alpine](https://github.com/ryangjchandler/awesome-alpine)
### الموجّهات
---
### `x-data`
**المثال:** `
...
`
**البُنية:** `
...
`
تعرّف `x-data` حقل/نطاق جديد للمكوّن، يخبر Alpine بتهيئة المكوّن الجديد بكائن البيانات المعرّف والمحدّد مسبقاً.
مشابه لخاصية `data` في المكونّات في إطار Vue.
**استخراج التعابير المنطقية للمكوّن**
يمكنك من استخراج مصدر البيانات والتعاملات ذات الصّلة إلى دوال قابلة لإعادة الاستخدام.
```html
// القائمة المنسدلة
```
> لمستخدمي مجمّع الوحدات (bundler): يرجى ملاحظة أن الدوال التي يصل إليها Alpine.js في النطاق العام (window). فلاستخدام x-data يجب أن تصرّحها إلى `window`. على سبيل المثال `window.dropdown = function () {}` (لأنه في Webpack ،Rollup ،Parcel وما إلى ذلك، الدّوال التي تكتبتها تكون بشكل افتراضي ضِمن نطاق الوحدة "module" وليس في نطاق الصفحة `window`).
يمكنك أيضاً دمج عدة كائنات متعددة معاً باستخدام محلّل الكائنات (object destructuring).
```html
```
---
### `x-init`
**المثال:** ``
**البُنية:** ``
ينفّذ `x-init` تعليمات برمجية عند تشغيل وتهيئة إحدى المكوّنات.
إذا أردت تنفيذ التعليمات البرمجية بعد أن يجري Alpine تحديثه على الـDOM (مُماثل لـ `mounted()` في Vue.js) يمكنك إرجاع callback من `x-init` وسيتم تشغيله بعدها:
`x-init="() => { // يمكننا الوصول إلى DOM بعد تهيئته // }"`
---
### `x-show`
**المثال:** ``
**البُنية:** ``
تمكّننا `x-show` من إظهار أو إزالة العناصر بناء على التعبيرات المنطقية `display: none;` صحيحة أو خاطئة.
**x-show.transition**
`x-show.transition` عبارة عن واجهة "API" يمكنها تحسين `x-show` وجعله أكثر جمالية باستخدام تأثيرات CSS transitions.
```html
يتم عمل تأثير بصري بالظهور "in" و الاختفاء "out"
```
| التوجيهات | الوصف |
| ---: | ---: |
| `x-show.transition` | يتلاشى ويتقلص بمرور الوقت (opacity, scale: 0.95, timing-function: cubic-bezier(0.4, 0.0, 0.2, 1), duration-in: 150ms, duration-out: 75ms). |
| `x-show.transition.in` | تأثير انتقالي "in" فقط. |
| `x-show.transition.out` | تأثير خارجي "out" فقط. |
| `x-show.transition.opacity` | تأثير التلاشي فقط. |
| `x-show.transition.scale` | تأثير على الحجم فقط. |
| `x-show.transition.scale.75` | ضبط قيمة الحجم `transform: scale(.75)`. |
| `x-show.transition.duration.200ms` | يضبط قيمة الانتقال الأولي "in" إلى 200 مللي ثانية. تأخذ قيمة الانتقال النهائي "out" نصف القيمة المحددة (في هذه الحالة 100 مللي ثانية). |
| `x-show.transition.origin.top.right` | تنسيق التحولات CSS transform الأصلية `transform-origin: top right` |
| `x-show.transition.in.duration.200ms.out.duration.50ms` | تأثيرات على فترات مختلفة "in" و "out". |
> ملاحظة: يمكنك دمج جميع التأثيرات مع بعضها البعض (على الرغم من أنها غريبة ربما): `x-show.transition.in.duration.100ms.origin.top.right.opacity.scale.85.out.duration.200ms.origin.bottom.left.opacity.scale.95`
> ملاحظة: سينتظر `x-show` إلى حين أن تنتهني جميع التأثيرات، إذا كنت تريد تجاهلها، أضف المعدّل `.immediate`
```html
```
---
### `x-bind`
> ملاحظة: يمكنك اختصار الكتابة باستعمال النقطتين ":" مثل `:type="..."`
**المثال:** ``
**البُنية:** ``
يضبط قيمة السّمة (attribute) على حسب نتائج تعليمات الجافاسكربت. ويمكن لهذه التعليمات أن تصل إلى جميع بيانات المكوّن. ويتم تحديثه في كل مرة يتم فيها تحديث بياناته.
> ملاحظة: يتم تحديث ارتباطات السمات (binding) فقط إذا تم تحديث قيّمها. يكتشف Alpine تلقائيًا هذه القيم والتحديثات ثم يحسّنها.
**استخدام `x-bind` لـ class attributes**
يتصرف `x-bind` بشكل مختلف قليلاً عند تحديد الصنف (class attribute).
بالنسبة للأصناف (classes) قم بتمرير كائن يكون مفتاحه هو اسم الفئة، وقيَمُ هذه الأزواج عبارة عن تعبيرات منطقية تحدّد ما إذا كان يتم تطبيق الصنف على العنصر أم لا.
مثال:
``
في هذا المثال يتم تطبيق الصنف "hidden" فقط عندما تكون قيمة foo صحيحة `true`.
**`x-bind` للسمات المنطقية (boolean attributes)**
يدعم `x-bind` المتغيرات بالإضافة إلى تعبيرات الجافاسكربت في حالة إذا كانت تُرجع قيمة منطقية صحيحة أو خاطئة (`true` أو `false`).
مثال:
```html
```
هنا تتم إضافة السمة `disabled` أو إزالتها بناءً على قيمة المتغيّر `myVar`.
تدعم كذلك Alpine سمات منطقية مختلفة HTML specification مثل: `disabled`,`readonly`,`required`,`checked`,`hidden`,`selected`,`open` وغيرها.
المُعدّل .camel
مثال:
**هل تريد عرض شعارك هنا؟ [راسلني على تويتر](https://twitter.com/calebporzio)**
## مشاريع المجتمع
* [AlpineJS Weekly Newsletter](https://alpinejs.codewithhugo.com/newsletter/)
* [Spruce (State Management)](https://github.com/ryangjchandler/spruce)
* [Turbolinks Adapter](https://github.com/SimoTod/alpine-turbolinks-adapter)
* [Alpine Magic Helpers](https://github.com/KevinBatdorf/alpine-magic-helpers)
* [Awesome Alpine](https://github.com/ryangjchandler/awesome-alpine)
### الموجّهات
---
### `x-data`
**المثال:** `