Alpinejs NPM | npm.io

Alpine.js

npm bundle size npm version

توفر لك Alpine.js بنية تفاعلية (تصريحية) مثل أُطر العمل الشهيرة Vue و React بكُلفة وجهد أقل بكثير.

يمكنك الإحتفاظ بـ DOM والاستمرار في استخدامه، وإضافة الدّوال والوظائف له عند الحاجة.

يشبه إلى حد ما Tailwind ولكن في الجافاسكربت.

ملاحظة: نشير إلى أن بُنية Alpine.js شبية جداً بـ Vue (أو Angular). أنا ممتن لهذه الأُطر بما قدموه في تطوير الويب.

ملاحظة:

يمكنك قراءة التوثيق بتنسيق أفضل "RTL" من الرابط التالي (AlpineJs بالعربية).

التوثيق بلغات أخرى

Language	Link for documentation
Arabic	التوثيق باللغة العربية
Chinese Traditional	繁體中文說明文件
German	Dokumentation in Deutsch
Indonesian	Dokumentasi Bahasa Indonesia
Japanese	日本語ドキュメント
Portuguese	Documentação em Português
Russian	Документация на русском
Spanish	Documentación en Español
Turkish	Türkçe Dokümantasyon
Français	Documentation en Français

التركيب

باستعمال CDN: أضف السطر البرمجي التالي في نهاية <head>.

<script src="https://cdn.jsdelivr.net/gh/alpinejs/alpine@v2.x.x/dist/alpine.min.js" defer></script>

سيقوم Alpine.js بتهيئة نفسه، سهلة أليس كذلك!

في بيئات التطوير، نوصي باستعمال إصدار محدّد كما في الرابط، لتجنب حدوث مشاكل غير متوقعة أو تصادمها مع الإصدارات الحديثة. على سبيل المثال، لاستخدام الإصدار الأخير (2.8.2) يمكنك كتابة:

<script src="https://cdn.jsdelivr.net/gh/alpinejs/alpine@v2.8.2/dist/alpine.min.js" defer></script>

باستعمال NPM: قم بتنصيب الحزمة من NPM.

npm i alpinejs

قم باستدعائها وتضمينها في مشروعك.

import 'alpinejs'

لدعم نسخة المتصفّح IE11 يرجى استعمال السُطور البرمجية التالية بدلاً عن السابق.

<script type="module" src="https://cdn.jsdelivr.net/gh/alpinejs/alpine@v2.x.x/dist/alpine.min.js"></script>
<script nomodule src="https://cdn.jsdelivr.net/gh/alpinejs/alpine@v2.x.x/dist/alpine-ie11.min.js" defer></script>

لو تُلاحظ في السطور أعلاه كتبنا module/nomodule pattern ، تسمح هذه الأنماط للمتصفحات الحديثة بتحميل مجموعة الوحدات بشكل تلقائي، بينما ستقوم IE11 والمتصفحات القديمة الأخرى تبحميل وحدات IE11 تلقائياً.

طريقة الاستخدام

القائمة المنسدلة (Dropdown) والنوافذ (Modal)

<div x-data="{ open: false }">
    <button @click="open = true">فتح القائمة</button>

    <ul
        x-show="open"
        @click.away="open = false"
    >
        محتوى القائمة
    </ul>
</div>

علامات التبويب (Tabs)

<div x-data="{ tab: 'foo' }">
    <button :class="{ 'active': tab === 'foo' }" @click="tab = 'foo'">Foo</button>
    <button :class="{ 'active': tab === 'bar' }" @click="tab = 'bar'">Bar</button>

    <div x-show="tab === 'foo'">النافذة Foo</div>
    <div x-show="tab === 'bar'">النافذة Bar</div>
</div>

يمكنك أيضاً استخدامه في أماكن أخرى:

التحضير المُسبق (Pre-fetching) لمُحتوى HTML.

<div x-data="{ open: false }">
    <button
        @mouseenter.once="
            fetch('/dropdown-partial.html')
                .then(response => response.text())
                .then(html => { $refs.dropdown.innerHTML = html })
        "
        @click="open = true"
    >إظهار القائمة</button>

    <div x-ref="dropdown" x-show="open" @click.away="open = false">
        جارٍ التحميل ...
    </div>
</div>

الشرح

هناك إجمالي 14 موجّهاً مُتاحا:

الموجّه	الوصف
`x-data`	إعلان أو تعريف حقل (Scope) جديد للمكوّن.
`x-init`	ينفّذ تعليمات برمجية عند تشغيل إحدى المكوّنات.
`x-show`	إظهار أو إزالة العناصر بناء على التعبيرات المنطقية `display: none;` صحيحة أو خاطئة.
`x-bind`	يضبط قيمة السّمة (attribute) على حسب نتائج تعليمات الجافاسكربت.
`x-on`	يربط المُنصِت للأحداث (event listener) بالعنصر، يتم تنفيذ تعليمات الجافاسكربت عند التفاعل معه.
`x-model`	يضيف اتصالا للبيانات ثنائي الإتجاه "two-way data binding" حيث أن القيم الذي يُدخلها المستخدم تتم مزامنتها مع قيمة بيانات العنصر للمكوّن.
`x-text`	يعمل بشكل مشابه لـ `x-bind`، ولكنه يقوم بتحديث النص المضمن `innerText` داخل العنصر.
`x-html`	يعمل بشكل مشابه لـ `x-bind`، ولكنه يقوم بتحديث النص المضمن `innerText` داخل العنصر.
`x-ref`	طريقة سهلة لاسترجاع عنصر داخل DOM موجود خارج المكوّن الخاص بك.
`x-if`	إزالة عنصر تماماً من الـDOM. يجب استخدامه داخل وَسم `<template>`
`x-for`	ينشئ فروع DOM جديدة لكل عنصر من عناصر المصفوفة. يجب استخدامه داخل وَسم `<template>`
`x-transition`	توجيه لعمل تأثيرات انتقالية في مراحل مختلفة على الأصناف (Classes)
`x-spread`	يسمح لك بربط الكائنات التي تحتوي على توجيهات Alpine بالعناصر، لتحسين إمكانية إعادة استخدامه بشكل أفضل.
`x-cloak`	تتم إزالة هذه السمة عند تهيئة Alpine. مفيد لإخفاء DOM المُهيأ مسبقًا.

و 6 خصائص سحرية:

الخصائص السحرية	الوصف
`$el`	ترجع فرع DOM الخاص بالمكوّن الأساسي (root component).
`$refs`	يسترجع عناصر DOM المميّزة بـ `x-ref` داخل المكوّن.
`$event`	يرجع كائن الحدث "Event" الأصلي داخل المُنصت لأحداث المستخدم.
`$dispatch`	ينشئ حدثاً مخصصا `CustomEvent` ويرسله داخلياً باستخدام `.dispatchEvent()`.
`$nextTick`	بعد معالجة Alpine لتحديث DOM يتم تنفيذ تعليمات برمجية.
`$watch`	يقوم باستدعاء callback تم تحديده مسبقاً عندما يتم تعديل خاصية المُراقب "watched"

الرعاة

هل تريد عرض شعارك هنا؟ راسلني على تويتر

مشاريع المجتمع

الموجّهات

`x-data`

المثال: <div x-data="{ foo: 'bar' }">...</div>

البُنية: <div x-data="[object literal]">...</div>

تعرّف x-data حقل/نطاق جديد للمكوّن، يخبر Alpine بتهيئة المكوّن الجديد بكائن البيانات المعرّف والمحدّد مسبقاً.

مشابه لخاصية data في المكونّات في إطار Vue.

استخراج التعابير المنطقية للمكوّن

يمكنك من استخراج مصدر البيانات والتعاملات ذات الصّلة إلى دوال قابلة لإعادة الاستخدام.

<div x-data="dropdown()">
    <button x-on:click="open">فتح</button>

    <div x-show="isOpen()" x-on:click.away="close">
        // القائمة المنسدلة
    </div>
</div>

<script>
    function dropdown() {
        return {
            show: false,
            open() { this.show = true },
            close() { this.show = false },
            isOpen() { return this.show === true },
        }
    }
</script>

لمستخدمي مجمّع الوحدات (bundler): يرجى ملاحظة أن الدوال التي يصل إليها Alpine.js في النطاق العام (window). فلاستخدام x-data يجب أن تصرّحها إلى window. على سبيل المثال window.dropdown = function () {} (لأنه في Webpack ،Rollup ،Parcel وما إلى ذلك، الدّوال التي تكتبتها تكون بشكل افتراضي ضِمن نطاق الوحدة "module" وليس في نطاق الصفحة window).

يمكنك أيضاً دمج عدة كائنات متعددة معاً باستخدام محلّل الكائنات (object destructuring).

<div x-data="{...dropdown(), ...tabs()}">

`x-init`

المثال: <div x-data="{ foo: 'bar' }" x-init="foo = 'baz'"></div>

البُنية: <div x-data="..." x-init="[expression]"></div>

ينفّذ x-init تعليمات برمجية عند تشغيل وتهيئة إحدى المكوّنات.

إذا أردت تنفيذ التعليمات البرمجية بعد أن يجري Alpine تحديثه على الـDOM (مُماثل لـ mounted() في Vue.js) يمكنك إرجاع callback من x-init وسيتم تشغيله بعدها:

x-init="() => { // يمكننا الوصول إلى DOM بعد تهيئته // }"

`x-show`

المثال: <div x-show="open"></div>

البُنية: <div x-show="[expression]"></div>

تمكّننا x-show من إظهار أو إزالة العناصر بناء على التعبيرات المنطقية display: none; صحيحة أو خاطئة.

x-show.transition

x-show.transition عبارة عن واجهة "API" يمكنها تحسين x-show وجعله أكثر جمالية باستخدام تأثيرات CSS transitions.

<div x-show.transition="open">
    يتم عمل تأثير بصري بالظهور "in" و الاختفاء "out"
</div>

التوجيهات	الوصف
`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

<div x-show.immediate="open">
    <div x-show.transition="open">
</div>

`x-bind`

ملاحظة: يمكنك اختصار الكتابة باستعمال النقطتين ":" مثل :type="..."

المثال: <input x-bind:type="inputType">

البُنية: <input x-bind:[attribute]="[expression]">

يضبط قيمة السّمة (attribute) على حسب نتائج تعليمات الجافاسكربت. ويمكن لهذه التعليمات أن تصل إلى جميع بيانات المكوّن. ويتم تحديثه في كل مرة يتم فيها تحديث بياناته.

ملاحظة: يتم تحديث ارتباطات السمات (binding) فقط إذا تم تحديث قيّمها. يكتشف Alpine تلقائيًا هذه القيم والتحديثات ثم يحسّنها.

استخدام x-bind لـ class attributes

يتصرف x-bind بشكل مختلف قليلاً عند تحديد الصنف (class attribute).

بالنسبة للأصناف (classes) قم بتمرير كائن يكون مفتاحه هو اسم الفئة، وقيَمُ هذه الأزواج عبارة عن تعبيرات منطقية تحدّد ما إذا كان يتم تطبيق الصنف على العنصر أم لا.

مثال: <div x-bind:class="{ 'hidden': foo }"></div>

في هذا المثال يتم تطبيق الصنف "hidden" فقط عندما تكون قيمة foo صحيحة true.

x-bind للسمات المنطقية (boolean attributes)

يدعم x-bind المتغيرات بالإضافة إلى تعبيرات الجافاسكربت في حالة إذا كانت تُرجع قيمة منطقية صحيحة أو خاطئة (true أو false).

مثال:

اضغطني

</div>

هنا تتم إضافة السمة `disabled` أو إزالتها بناءً على قيمة المتغيّر `myVar`.

تدعم كذلك Alpine سمات منطقية مختلفة  HTML specification مثل:  `disabled`,`readonly`,`required`,`checked`,`hidden`,`selected`,`open` وغيرها.

المُعدّل .camel
مثال: <svg x-bind:view-box.camel="viewBox">

يقوم المعدّل بضبط وربط حالة الأحرف بصيغة camel case لاسم السمة. في المثال أعلاه، تم ربط قيمة viewBox بِسِمة viewBox (بدلاً من view-box).

---

### `x-on`

> ملاحظة: يمكنك اختصار الكتابة باستعمال النقطتين ":" مثل <span dir="ltr">`@click="..."`</span>

**المثال:** <span dir="ltr">`<button x-on:click="foo = 'bar'"></button>`</span>

**البُنية:** <span dir="ltr">`<button x-on:[event]="[expression]"></button>`</span>

يقوم x-on بإرفاق المُنصت للأحداث (event listener). عندما يتم حدث (event) من قِبل المستخدم يتم تنفيذ تعليمات الجافاسكربت المحددة.

يتم تحديث السِمات الأخرى للعنصر المرتبطة بمصدر البيانات هذا بمجرد تعديل البيانات الموجودة في التعليمات البرمجية.

> ملاحظة: اختياريًا، يمكن أيضًا تحديد اسم دالة الجافاسكربت.

**المثال:** <span dir="ltr">`<button x-on:click="myFunction"></button>`</span>

هذه تكافئ: <span dir="ltr">`<button x-on:click="myFunction($event)"></button>`</span>

**المُعدّل `keydown`**

**المثال:** <span dir="ltr">`<input type="text" x-on:keydown.escape="open = false">`</span>

يمكنك الإستجابة لأحداث معينة عند ضغط المستخدم في لوحة المفاتيح باستخدام المعدّلات `x-on:keydown`. يرجى ملاحظة أن هذا المُعدّل يستخدم صيغة kebab-case لتسمية قيم `Event.key`.

أمثلة: `enter`, `escape`, `arrow-up`, `arrow-down`

> يمكننا كذلك الإستجابة لأزرار لوحة المفاتيح الأساسية مثل <span dir="ltr">`x-on:keydown.cmd.enter="foo"`</span>

**المُعدّل <span dir="ltr">`.away`</span>**

**المثال:** <span dir="ltr">`<div x-on:click.away="showModal = false"></div>`</span>

لا يتم تنفيذ تعبير Event Handler إلا إذا لم يتم تشغيل الحدث بواسطة العنصر نفسه (أو مكوناته الفرعية).

هذا مفيد لإخفاء القوائم المنسدلة والنوافذ عندما يضغط المستخدم في مكان آخر.

**المُعدّل <span dir="ltr">`.prevent`</span>**
**المثال:** <span dir="ltr">`<input type="checkbox" x-on:click.prevent>`</span>

تؤدي إضافة <span dir="ltr">`.prevent`</span> داخل مستمع الحدث إلى استدعاء منع `preventDefault` في الحدث الذي سيتم تنفيذه. في المثال أعلاه، هذا يعني أن مربع الاختيار لن يتم تحديده بالفعل عندما ينقر المستخدم عليه.

**المُعدّل <span dir="ltr">`.stop`</span>**
**المثال::** <span dir="ltr">`<div x-on:click="foo = 'bar'"><button x-on:click.stop></button></div>`</span>

إضافة <span dir="ltr">`.stop`</span> إلى المنصت للأحداث يستدعي `stopPropagation.` في المثال أعلاه، يعني أن الحدث "click" لن ينتقل إلى  `<div>` الخارجي. بمعنى آخر، عندما ينقر المستخدم على الزر، لا يتم تعريف `foo` على أنه `bar`.

**المُعدّل <span dir="ltr">`.self`</span>**
**المثال:** <span dir="ltr">`<div x-on:click.self="foo = 'bar'"><button></button></div>`</span>

إضافة .self إلى المنصت للأحداث يأدي إلى تشغيل الحدث فقط إذا كان <span dir="ltr">`$event.target`</span> هو نفس العنصر. في المثال أعلاه، يعني أنه عند النقر على الزر "button" لن يتم تشغيل الحدث.

**المُعدّل <span dir="ltr">`.window`</span>**
**المثال:** <span dir="ltr">`<div x-on:resize.window="isOpen = window.outerWidth > 768 ? false : open"></div>`</span>

إضافة <span dir="ltr">`.window`</span> إلى منصت الأحداث، سيقوم بتثبيت منصت للأحداث على نافذة المتصفّح كله `window` بدلاً من DOM الذي قمت بتصريحه أو تحديده. هذا مفيد لك في حال أردت ضبط أحد المكوّنات وتغييرها على حسب حجم (أبعاد) المتصفّح. في المثال أعلاه سيتم إغلاق النافذة أو القائمة المنسدلة إذا تجاوزت أبعاد المتصفح 768 بكسل، خلاف ذلك نُبقيه على حالته.

>ملاحظة: يمكنك أيضًا استخدام معدّل `.document` لإرفاق المنصت بدلا من `window`.

**المُعدّل <span dir="ltr">`.once`</span>**
**المثال:** <span dir="ltr">`<button x-on:mouseenter.once="fetchSomething()"></button>`</span>

تعني إضافة المعدّل <span dir="ltr">`.once`</span> إلى المنصت للحدث أن المنصت (listener) يعمل مرة واحدة فقط. هذا مفيد للمهام التي تريد القيام بها مرة واحدة فقط، مثل الجلب الجزئي لشفرات HTML أو ما شابه.

**المُعدّل <span dir="ltr">`.passive`</span>**
**المثال:** <span dir="ltr">`<button x-on:mousedown.passive="interactive = true"></button>`</span>

إذا أضفنا <span dir="ltr">`.passive`</span> إلى المنصت للحدث، فإن هذا الرمز المميز سيعطل وظيفة `preventDefault()` ولن تعمل على أي حدث يتم تنفيذه. يمكن أن يساعدك أحياناً في تحسين أداء التمرير (scroll) على الأجهزة التي تعمل باللمس.

**المُعدّل <span dir="ltr">`.debounce`</span>**
**المثال:** <span dir="ltr">`<input x-on:input.debounce="fetchSomething()">`</span>

يتيح لك تحديد <span dir="ltr">`.debounce`</span> وقت تنفيذ الأحداث، لن يعمل معالج الأحداث (event handler) فقط إذا مرت فترة زمنية معينة منذ آخر حدث، عندما يكون المعالج جاهزاً للتنفيذ سيتم تنفيذ آخر استدعاء للمعالج.

مهلة الإنتظار "wait" الإفتراضية هي 250 مللي ثانية.

إذا أردت تخصيص مهلة الإنتظار يمكنك استخدام الطريقة التالية:

<div dir="ltr">

```html
<input x-on:input.debounce.750="fetchSomething()">
<input x-on:input.debounce.750ms="fetchSomething()">

المُعدّل .camel المثال: <input x-on:event-name.camel="doSomething()">

يقوم المنصت للأحداث بالإنصات إلى الأحداث التي تحمل حالة أحرف بصيغة camelCase. في هذا المثال سيتم تنفيذها للعناصر التي تحمل اسم eventName.

`x-model`

المثال: <input type="text" x-model="foo">

البُنية: <input type="text" x-model="[data item]">

يضيف x-model ربط بيانات ثنائي الإتجاه "two-way data binding" (أي أن ربط البيانات يكون في كلا الطرفين). بمعنى آخر، أن قيمة العنصر تتم مزامنتها مع قيمة بيانات عنصر المكوّن.

يكتشف x-model تلقائياً التغييرات التي تطرأ على العناصر التالية: text inputs ،checkboxes ،radio buttons ،textareas ،selects ،multiple selects. يمكنك فهم كيف يعمل ذلك في الخفاء في "سيناريوهات" إطار عمل Vue.

المُعدّل .number المثال: <input x-model.number="age">

يقوم .number بتحويل القيمة المدخلة عبر <input> إلى رقم. في حال تعذّر تحليل القيمة المدخلة لرقم فعلاً سيُرجع القيمة الأصلية المدخلة.

المُعدّل .debounce المثال: <input x-model.debounce="search">

يتيح لك تحديد .debounce وقت تنفيذ الأحداث، لن يعمل معالج الأحداث (event handler) فقط إذا مرت فترة زمنية معينة منذ آخر حدث، عندما يكون المعالج جاهزاً للتنفيذ سيتم تنفيذ آخر استدعاء للمعالج.

مهلة الإنتظار "wait" الإفتراضية هي 250 مللي ثانية.

إذا أردت تخصيص مهلة الإنتظار يمكنك استخدام الطريقة التالية:

<input x-model.debounce.750="search">
<input x-model.debounce.750ms="search">

`x-text`

المثال: <span x-text="foo"></span>

البُنية: <span x-text="[expression]"

يعمل بشكل مشابه لـ x-bind، ولكنه يقوم بتحديث النص المضمن innerText داخل العنصر.

`x-html`

المثال: <span x-html="foo"></span>

البُنية: <span x-html="[expression]"

يعمل بشكل مشابه لـ x-bind، ولكنه يقوم بتحديث شفرة HTML المضمنة innerText داخل العنصر.

:warning: في هذه الحالة نوصي بكتابة محتوى (شفرات نظيفة) ولا تسمح بمُدخلات المُستخدم (user-provided) :warning:
يمكن أن يؤدي عرض HTML على المتصفّح من جهات خارجية أن توقع موقعك بثغرات XSS.

`x-ref`

المثال: <div x-ref="foo"></div><button x-on:click="$refs.foo.innerText = 'bar'"></button>

البُنية: <div x-ref="[ref name]"></div><button x-on:click="$refs.[ref name].innerText = 'bar'"></button>

توفر x-ref طريقة مفيدة لجلب عناصر DOM خارج المكون الخاص بك، عندما تقوم بتعيين x-ref للعنصر، سيكون متاحاً لجميع معالجات الأحداث داخل الكائن عن طريق استدعاء $refs.

يوفر ذلك بديلا مفيدا في حال كان يجب استخدام الأمر document.querySelector في كثير من الأحيان للإشارة إلى العناصر.

يمكنك أيضا ربط القيم المتغيّرة (الديناميكية) بـ <span :x-ref="item.id"></span>.

`x-if`

المثال: <template x-if="true"><div>Some Element</div></template>

البُنية: <template x-if="[expression]"><div>Some Element</div></template>

إذا كانت وظيفة x-show (كما شرحناها سابقاً) غير كافية، فيمكن استخدام x-if بدلاً من ذلك لإزالة عنصر بالكامل من DOM.

نظرًا لأن Alpine لا يحتوي على DOM افتراضي، يجب استخدام x-if مع الوسم <template></template>. بحيث يسمح لـ Alpine بالبقاء مستقرًا والوصول إلى DOM الحقيقي.

ملاحظة: عند استخدام x-if، يجب أن يكون هناك عنصر جذر واحد (element root) على الأقل داخل <template></template>
ملاحظة: عند استخدام template في svg، ستحتاج إلى إضافة polyfill الذي يجب تنفيذه قبل تهيئة Alpine.js.

`x-for`

المثال:

<template x-for="item in items" :key="item">
    <div x-text="item"></div>
</template>

ملاحظة: الـ:key مفتاح اختياري، ومع ذلك، نوصى به.
ملاحظة: هذا :key مفتاح اختياري ، ومع ذلك، نوصى به وبشدة.

يُعدّ x-for مناسباً للحالات التي يلزم فيها إنشاء عقدة DOM جديدة لكل عنصر داخل المصفوفة. مشابه لـ v-for في Vue، ولكن الاختلاف الوحيد هو أنه يجب وضعه في وسم template بدلاً من عنصر DOM عادي.

إذا كنت ترغب في الوصول إلى الفهرس الحالي (current index) للتكرار، فاستخدم الصيغة التالية:

<template x-for="(item, index) in items" :key="index">
    <!-- يمكنك أيضًا الرجوع إلى "index" داخل التكرار إذا لزم الأمر. -->
    <div x-text="index"></div>
</template>

إذا كنت ترغب في الوصول إلى تكرار مصفوفة كائن (array object)، فاستخدم الصيغة التالية:

<template x-for="(item, index, collection) in items" :key="index">
    <!-- يمكنك أيضًا الرجوع إلى "collection" في التكرار متى احتجت إلى ذلك. -->
    <!-- العنصر الحالي. -->
    <div x-text="item"></div>
    <!--نفس العنصر المذكور أعلاه. -->
    <div x-text="collection[index]"></div>
    <!-- العنصر السابق. -->
    <div x-text="collection[index - 1]"></div>
</template>

ملاحظة: عند استخدام x-for، يجب أن يكون هناك عنصر جذر واحد (element root) على الأقل داخل template.
ملاحظة: عند استخدام template في svg، ستحتاج إلى إضافة polyfill الذي يجب تنفيذه قبل تهيئة Alpine.js.

تداخل `x-for`

يمكنك عمل حلقات تكرار داخل حلقات x-for ولكن يجب أن نلّف كل حلقة في عنصر. مثلا:

<template x-for="item in items">
    <div>
        <template x-for="subItem in item.subItems">
            <div x-text="subItem"></div>
        </template>
    </div>
</template>

التكرار داخل مجال:

يدعم Alpine صيغة i in n، حيث يمثّل n عدداً صحيحاً مما يسمح لك بعمل تكرار على مجال معين من العناصر.

<template x-for="i in 10">
    <span x-text="i"></span>
</template>

`x-transition`

المثال:

<div
    x-show="open"
    x-transition:enter="transition ease-out duration-300"
    x-transition:enter-start="opacity-0 transform scale-90"
    x-transition:enter-end="opacity-100 transform scale-100"
    x-transition:leave="transition ease-in duration-300"
    x-transition:leave-start="opacity-100 transform scale-100"
    x-transition:leave-end="opacity-0 transform scale-90"
>...</div>

<template x-if="open">
    <div
        x-transition:enter="transition ease-out duration-300"
        x-transition:enter-start="opacity-0 transform scale-90"
        x-transition:enter-end="opacity-100 transform scale-100"
        x-transition:leave="transition ease-in duration-300"
        x-transition:leave-start="opacity-100 transform scale-100"
        x-transition:leave-end="opacity-0 transform scale-90"
    >...</div>
</template>

المثال أعلاه يستخدم تنسيقات Tailwind CSS

يوفر Alpine ستة تأثيرات انتقالية مختلفة لتطبيق الفئات (Classes) على مراحل مختلفة من انتقال العنصر، بين الحالات "hidden" و "shown". تعمل هذه التوجيهات مع كل من x-show و x-if.

تعمل هذه تمامًا مثل توجيهات التأثير بـ VueJS، باستثناء أن لها أسماء مختلفة وأكثر منطقية:

التوجيه	الوصف
`:enter`	يتم تطبيقه طوال مرحلة الدخول.
`:enter-start`	تتم إضافته قبل إدراج العنصر وإزالة الإطار (frame) بعد إدراج العنصر.
`:enter-end`	تمت إضافة إطار (frame) واحد بعد إدراج العنصر (في نفس الوقت تتم إزالة `enter-start`) ، تتم إزالته عند انتهاء التأثير/التحريك.
`:leave`	تُطبق طوال مرحلة الخروج.
`:leave-start`	يُضاف مباشرة عند بدء انتهاء التأثير، وإزالته بعد إطار واحد.
`:leave-end`	تمت إضافة إطار بعد تشغيل "انتهاء التأثير" (في نفس الوقت الذي تتم فيه إزالة `leave-start`) ، وتتم إزالته عند انتهاء التأثير/التحريك.

`x-spread`

المثال:

<div x-data="dropdown()">
    <button x-spread="trigger">فتح القائمة المنسدلة</button>

    <span x-spread="dialogue">محتوى القائمة</span>
</div>

<script>
    function dropdown() {
        return {
            open: false,
            trigger: {
                ['@click']() {
                    this.open = true
                },
            },
            dialogue: {
                ['x-show']() {
                    return this.open
                },
                ['@click.away']() {
                    this.open = false
                },
            }
        }
    }
</script>

يتيح x-spread نقل ربط الكائنات التي تحتوي على توجيهات Alpine لعنصر ما، إلى كائن يمكن إعادة استخدامه.

مفاتيح الكائن (object keys) عبارة عن توجيهات (يمكن أن يكون أي توجيهات بما في ذلك المُعدّلات) والقيم عبارة عن عمليات callback يتم تنفيذ قيمها بواسطة Alpine.

ملاحظة: هناك بعض الأشياء التي يجب مراعاتها في x-spread:
الحالة الخاصة الوحيدة لـ spread هي استخدامه مع x-for. عند تطبيقه على التوجيه x-for، يجب إرجاع تعليمات نصيّة عادية بواسطة callback. مثال span dir="ltr">['x-for']() { return 'item in items' }
x-data و x-init لا يمكن استخدامهما داخل كائن "spread".

`x-cloak`

المثال: <div x-data="{}" x-cloak></div>

تتم إزالة سمة x-cloak من العنصر أثناء تهيئة Alpine. يساعد هذا في إخفاء DOM المهيأ مسبقاً. لكي يعمل هذا عليك بإضافة التعليمات التالية:

<style>
    [x-cloak] { display: none; }
</style>

الخصائص السحرية

باستثناء $el، لا يمكن استخدام الخصائص السحرية ضمن x-data في حال لم تتم تهيئة المكوّن بعد.

`$el`

المثال:

<div x-data>
    <button @click="$el.innerHTML = 'foo'">استبدلني بـ "foo"</button>
</div>

$el خاصية سحرية للوصول إلى فرع DOM الأساسي.

`$refs`

المثال:

<span x-ref="foo"></span>

<button x-on:click="$refs.foo.innerText = 'bar'"></button>

يسترجع عناصر DOM المميّزة بـ x-ref داخل المكوّن، مفيدًا عندما تحتاج عناصر DOM إلى التعديل يدويًا.

`$event`

المثال:

<input x-on:input="alert($event.target.value)">

يرجع كائن الحدث "Event" الأصلي داخل المُنصت لأحداث المستخدم.

ملاحظة: خاصية $event متاحة فقط في تعليمات DOM.

إذا أردت تمرير $event داخل دوال الجافاسكربت فيمكنك تمريرها مباشرة.

<button x-on:click="myFunction($event)"></button>

`$dispatch`

المثال:

<div @custom-event="console.log($event.detail.foo)">
    <button @click="$dispatch('custom-event', { foo: 'bar' })">
    <!--عند النقر عليه، يقوم console.log بطباعة "bar" -->
</div>

$dispatch هي طريقة مختصرة لإنشاء أحداث مخصصة CustomEvent وإرسالها داخلياً باستخدام .dispatchEvent() هناك العديد من حالات الاستخدام التي يكون فيها إرسال البيانات بين المكونات من خلال أحداث يحددها المستخدم خيارًا جيداً. هنا يمكنك العثور على مزيد من المعلومات حول نظام CustomEvent الأساسي في المتصفحات.

<div x-data="{ foo: 'bar' }">
    <span x-model="foo">
        <button @click="$dispatch('input', 'baz')">
        <!-- عندما يتم النقر فوق الزر `x-model` يتلقط حدث "input" الناشئ ويقوم بتحديث foo إلى"baz ". -->
    </span>
</div>

ملاحظة حول انتشار الحدث (Event Propagation)

إذا كنت ترغب في توقيف الأحداث التي يتم تشغيلها بواسطة عقد HTML داخل نفس التسلسل الهرمي المتداخل (يعني div داخل div وهكذا)، فيجب عليك استخدام المُعدِّل .window.

مثال:

<div x-data>
    <span @custom-event="console.log($event.detail.foo)"></span>
    <button @click="$dispatch('custom-event', { foo: 'bar' })">
<div>

ملاحظة: المثال أعلاه لن يعمل بشكل جيّد. لأنه إذا تم تشغيل الحدث المخصص، فسيتم انتشار "تشغيله" في العناصر الرئيسة المشتركة بـ div.

Dispatching to Components

يمكن أيضًا استخدام الطريقة الموضحة أعلاه لتمكين الاتصال بين المكونات:

مثال:

<div x-data @custom-event.window="console.log($event.detail)"></div>

<button x-data @click="$dispatch('custom-event', 'Hello World!')">
<!--عندما تنقر سيطبع console.log "Hello World!". -->

يمكنك أيضا استخدام $dispatch() لبدء تحديث البيانات من روابط x-model. على سبيل المثال:

<div x-data="{ foo: 'bar' }">
    <span x-model="foo">
        <button @click="$dispatch('input', 'baz')">
        <!-- بعد النقر على عنصر `<button>` ، سيعترض `x-model` حدث "input" ويحدّث foo بـ "bar" -->
    </span>
</div>

ملاحظ: خاصية $dispatch متاحة فقط ضمن تعليمات DOM.

إذا أردت تمرير $dispatch داخل دوال الجافاسكربت فيمكنك تمريرها مباشرة.

<button x-on:click="myFunction($dispatch)"></button>

`$nextTick`

المثال:

<div x-data="{ fruit: 'apple' }">
    <button
        x-on:click="
            fruit = 'pear';
            $nextTick(() => { console.log($event.target.innerText) });
        "
        x-text="fruit"
    ></button>
</div>

$nextTick هي خاصية تعني أن التعليمات لا يتم تنفيذها إلا بعد أن يقوم Alpine بتنفيذ تحديثات DOM التفاعلية. هذا مفيد إذا كنت لا تريد التفاعل مع DOM حتى يتم إجراء جميع تحديثات للبيانات.

`$watch`

المثال:

<div x-data="{ open: false }" x-init="$watch('open', value => console.log(value))">
    <button @click="open = ! open">Toggle Open</button>
</div>

تمكّنك $watch في المثال أعلاه من تفعيل open عند الضغط على الزر "button"، يقوم callback بتنفيذ console.log وطباعة القيمة الجديدة.

الحماية

إذا وجدت ثغرة أمنية، يُرجى إرسال بريد إلكتروني إلى: calebporzio@gmail.com.

يعتمد Alpine على function لتنفيذ خصائصه. على الرغم من كونها أكثرَ أماناً من eval() إلا أن هذه الممارسة مازالت محظورة في بعض البيئات المقيّدة مثل Google Chrome App باستخدام سياسة أمان المحتوى المقيد (CSP).

إذا كنت تستخدم Alpine في بيئة بها بيانات حساسة وتحتاج إلى CSP، فأنت بحاجة إلى تضمين التقييم غير الآمن unsafe-eval في سياستك. يساعد في وضع سياسات قوية على حماية المستخدمين عند استخدام المعلومات الشخصية والمالية.

نظرًا لأن السياسة تنطبق على جميع البرامج النصية في صفحتك، فمن المهم أن تتم مراجعة المكتبات الخارجية الأخرى المضمنة في موقعك بعناية للتأكد من أنها جديرة لاستعمالها وآمنة ولن تقدم أي ثغرة أمنية XSS أو (Cross Site Scripting vulnerability) عبر الموقع سواء باستخدام وظيفة eval() أو التلاعب بـ DOM لإدخال تعليمات برمجية ضارة في صفحتك.