فهرس الدليل
مقدمة عن Alpine.js
Alpine.js هو إطار عمل JavaScript خفيف يستخدم لإضافة تفاعلية وسلوك ديناميكي إلى صفحات الويب بسهولة. يركز على تبسيط كتابة الكود بتقنيات HTML و JavaScript، دون الحاجة إلى تحميل مكتبات ضخمة مثل Vue.js أو React. يعتبر خيارًا مثاليًا لتطبيقات بسيطة تحتاج إلى تحسين تجربة المستخدم.
تثبيت Alpine.js
1. التثبيت باستخدام CDN
أبسط طريقة لاستخدام Alpine.js هي عن طريق إضافته إلى مشروعك من خلال رابط CDN. كل ما عليك فعله هو إضافة هذا السطر داخل وسم <head>
أو في نهاية ملف الـ HTML قبل وسم الإغلاق <body>
:
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
HTMLبهذا، Alpine.js سيكون جاهز للاستخدام في أي مكان بصفحتك دون الحاجة إلى إعدادات إضافية.
2. التثبيت باستخدام NPM
إذا كنت تستخدم مدير حزم مثل NPM وتفضل تضمين Alpine.js ضمن مشروعك، يمكنك تثبيته عبر هذا الأمر:
npm install alpinejs
JavaScriptوبعد التثبيت، قم باستيراد المكتبة في ملف JavaScript الخاص بك:
import Alpine from 'alpinejs';
window.Alpine = Alpine;
Alpine.start();
JavaScriptبهذه الطريقة، يمكنك التحكم بشكل أكبر في كيفية تحميل واستخدام Alpine.js ضمن مشروعك.
3. التأكد من التثبيت
قم بإنشاء ملف html فيه المعلومات التالية:
<html>
<head>
<script defer
src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js">
</script>
</head>
<body>
<h1 x-data="{ message: 'Hello, from Alpine' }" x-text="message"></h1>
</body>
</html>
HTMLإذا ظهر لك Hello, from Alpine في المتصفح، هذا يعني أنك قمت بالتثبيت بنجاح.
الأساسيات
x-data
المفهوم
تستخدم لإنشاء نطاق بيانات تفاعلي (reactive data) داخل عنصر (والعناصر الفرعية له) على الصفحة. هذا يعني أن البيانات الموجودة داخل x-data
ستكون تفاعلية، أي أن أي تغييرات تُجرى على هذه البيانات ستؤدي إلى تحديث تلقائي للـ DOM (الواجهة)، مما يجعل التفاعل مع البيانات مرنًا وسهلاً.
كيف تعمل
x-data
هو حاوية لحفظ حالة العنصر، أي البيانات التي ترغب في تتبعها والتفاعل معها (مثل العدادات، قيم المدخلات، أو القيم الديناميكية الأخرى).- عند استخدام
x-data
، يصبح العنصر تفاعليًا، مما يعني أنه سيتم تحديث الـ DOM تلقائيًا عند تغيير البيانات دون الحاجة للتلاعب اليدوي بالـ JavaScript.
<html>
<head>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js">
</script>
</head>
<body>
<div x-data="{ name: 'Nawras' }">
<h1 x-text="name"></h1> <!-- Nawras -->
</div>
</body>
</html>
HTMLمثال على استخدام x-data
<html>
<head>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js">
</script>
</head>
<body>
<div x-data="{ name: 'Nawras', age: 200, salary: 80000 }">
<h1 x-text="name"></h1> <!-- Nawras -->
<p x-text="age"></p> <!-- 200 -->
<p x-text="salary"></p> <!-- 80000 -->
</div>
</body>
</html>
HTMLx-text
المفهوم
يستخدم لربط النص داخل عنصر مع قيمة من البيانات التفاعلية. يعمل x-text
على تحديث النص داخل العنصر تلقائيًا عندما تتغير البيانات المرتبطة به. باستخدام x-text
، يمكنك عرض أو تحديث النص داخل عنصر HTML بناءً على القيم المتغيرة في x-data
أو البيانات التفاعلية الأخرى.
كيف يعمل
x-text
يقوم بتغيير النص داخل العنصر الذي يتم تطبيقه عليه ليعكس قيمة البيانات التفاعلية أو التعبير الذي قمت بتمريره له.- عند تغيير قيمة البيانات المرتبطة بـ
x-text
, يتم تحديث النص داخل العنصر تلقائيًا دون الحاجة إلى إعادة تحميل الصفحة أو التعامل مع DOM باستخدام JavaScript.
مثال على استخدام x-text
<html>
<head>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js">
</script>
</head>
<body>
<div x-data="{ username: 'Ali' }">
<h1 x-text="username"></h1> <!-- Ali -->
</div>
</body>
</html>
HTMLx-show
المفهوم
يُستخدم لإظهار أو إخفاء عنصر بناءً على قيمة من البيانات التفاعلية. عندما تتغير القيمة المرتبطة بـ x-show
, فإن العنصر سيظهر أو يختفي على الصفحة بشكل ديناميكي. بشكل عام، هو يستخدم للتحكم في الرؤية أو الظهور للعناصر على الصفحة.
كيف يعمل
x-show
يقوم بتطبيق خاصيةdisplay
على العنصر بناءً على القيمة المُعطاة له.- عندما تكون القيمة المرتبطة بـ
x-show
صحيحة (مثلtrue
أو قيمة غير فارغة)، يتم إظهار العنصر - .عندما تكون القيمة خطأ (مثل
false
أوnull
)، يتم إخفاء العنصر.
مثال على استخدام x-show
<html>
<head>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js">
</script>
</head>
<body>
<div x-data="{ username: 'Ali', password: '123', showPassword: true }">
<h1 x-text="username"></h1> <!-- Ali -->
<p x-show='showPassword' x-text="password"></p> <!-- 123 -->
</div>
</body>
</html>
HTMLx-on:click
المفهوم
تستخدم للانتباه إلى حدث النقر (click) على عنصر معين. عند النقر على العنصر، يتم تنفيذ الأكواد أو التغييرات التي تحددها في هذا الحدث Event.
كيف يعمل
- عند استخدام
x-on:click
، يحدد Alpine.js أنه عندما يتم النقر على العنصر، يتم تنفيذ الكود المرتبط بهذا الحدث. - يمكنك من التفاعل مع المستخدم من خلال استجابة معينة للنقر على الأزرار أو العناصر الأخرى.
مثال على استخدام x-on:click
<html>
<head>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js">
</script>
</head>
<body>
<div x-data="{ username: 'Ali', password: '123', showPassword: false }">
<h1 x-text="username"></h1> <!-- Ali -->
<button x-on:click="showPassword=true">Show Password</button>
<p x-show='showPassword' x-text="password"></p> <!-- 123 -->
</div>
</body>
</html>
HTMLيمكنك استخدام الاختصار @click
بدلاً من x-on:click
. كلاهما يؤدي نفس الوظيفة، ولكن الاختصار @click
يعتبر أكثر بساطة وسهولة في الكتابة.
<html>
<head>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js">
</script>
</head>
<body>
<div x-data="{ username: 'Ali', password: '123', showPassword: false }">
<h1 x-text="username"></h1> <!-- Ali -->
<button @click="showPassword=true">Show Password</button>
<p x-show='showPassword' x-text="password"></p> <!-- 123 -->
</div>
</body>
</html>
HTMLالمزيد من الأساسيات
x-init
المفهوم
يُستخدم لتنفيذ تعليمات JavaScript عند تحميل المكون (component) لأول مرة، أي عندما يتم تهيئة المكون أو العنصر الذي يحتوي عليه. يساعد في تنفيذ الأكواد أو إعداد القيم الأولية للبيانات عند بدء تشغيل العنصر.
كيف تعمل
- يتم استخدام
x-init
لتشغيل كود عند تحميل الصفحة أو تهيئة الكائن التفاعلي. - يمكن استخدامه لإعداد القيم الافتراضية، أو لتشغيل دوال JavaScript أو أي عملية تحتاج إلى أن تحدث بمجرد أن يبدأ العنصر في الظهور على الصفحة
<html>
<head>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js">
</script>
</head>
<body>
<div x-data="{ name: '' }" x-init="name = 'Ali'">
<h1 x-text="name"></h1> <!-- Ali -->
</div>
</body>
</html>
HTMLادارة التفاعلات في دالة
المفهوم
من الممكن إضافة البيانات والدوال مباشرة في الكود HTML باستخدام x-data
و x-init
، لكن في بعض الأحيان يكون من الأفضل إدارة هذه التفاعلات داخل دوال JavaScript خارج HTML، مما يسهل تنظيم الكود ويجعله أكثر قابلية للصيانة والقراءة.
<html>
<head>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
</head>
<body>
<div x-data="initData()">
<h1 x-text="username"></h1> <!-- Ali -->
<button x-on:click="showPassword=true">Show Password</button>
<p x-show='showPassword' x-text="password"></p> <!-- 123 -->
</div>
<script>
function initData(){
return {
username: "Ali",
password: "123",
showPassword: false
}
}
</script>
</body>
</html>
HTMLالنماذج Forms
x-model
المفهوم
يُستخدم لربط القيم التفاعلية بين واجهة المستخدم (HTML) وبين البيانات (Data) الخاصة بك في JavaScript. يعمل هذا الموجه على مزامنة البيانات بين الحقول المدخلة (مثل input
أو textarea
) والقيم التي يتم تخزينها داخل المكون (داخل x-data
).
باستخدام x-model
، يمكن ربط القيم المدخلة في النماذج أو الحقول النصية بالبيانات في الجافا سكربت، مما يجعل التفاعل مع النموذج أسهل وأسرع. عندما يُدخل المستخدم قيمة في الحقل المرتبط بـ x-model
، يتم تحديث البيانات تلقائيًا.
كيف تعمل
- الربط التلقائي: عندما يغير المستخدم قيمة في عنصر مُرتبط بـ
x-model
، يتم تحديث البيانات تلقائيًا. - الانتقال من البيانات إلى الواجهة: إذا تم تحديث القيمة في البيانات داخل
x-data
, سيتم تحديث العنصر في HTML الذي يرتبط بـx-model
تلقائيًا.
<html>
<head>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
</head>
<body>
<div x-data="initData()">
<h1>
Hello, <span x-text="username"></span>
<span x-text="password"></span>
</h1>
<hr />
<form>
<input type="text" x-model="username" placeholder="Provide your username">
<input type="password" x-model="password" placeholder="Enter your password">
</form>
</div>
<script>
function initData() {
return {
username: "",
password: "",
}
}
</script>
</body>
</html>
HTML@submit
يتم تنفيذ التعليمات الموجودة في submit event عند تقديم نموذج ما.
<html>
<head>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
</head>
<body>
<div x-data="initData()">
<h1>
Hello, <span x-text="username"></span>
<span x-text="password"></span>
</h1>
<hr />
<form @submit.prevent="submitForm">
<input type="text" x-model="username" placeholder="Provide your username">
<input type="password" x-model="password" placeholder="Enter your password">
<button type="submit">Submit Form</button>
</form>
</div>
<script>
function initData() {
return {
username: "",
password: "",
submitForm() {
alert("Submitted");
}
}
}
</script>
</body>
</html>
HTMLالتحقق من المدخلات
يمكن التحقق من المدخلات وعرض رسالة خطأ أو نجاح كما في المثال التالي:
<html>
<head>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
</head>
<body>
<div x-data="initData()">
<h1>
Hello,
<span x-text="username"></span>
<span x-text="password"></span>
</h1>
<hr />
<!-- Message Section: Displays error or success message -->
<div class="message">
<p class="error" x-show="showError" x-text="errorMessage"></p>
<p class="success" x-show="showSuccess" x-text="successMessage"></p>
</div>
<!-- Form Section -->
<form @submit.prevent="submitForm">
<input type="text" x-model="username" placeholder="Provide your username">
<input type="password" x-model="password" placeholder="Enter your password">
<button type="submit">Submit Form</button>
</form>
</div>
<script>
function initData() {
return {
username: "",
password: "",
showError: false,
showSuccess: false,
errorMessage: "",
successMessage: "",
// Handle form submission
submitForm() {
// Reset error and success states
this.showError = false;
this.showSuccess = false;
// Validate username
if (!this.username) {
this.errorMessage = "You must provide a username";
this.showError = true;
return;
}
// Validate password
if (!this.password) {
this.errorMessage = "You must provide a password";
this.showError = true;
return;
}
// If form is valid, show success message
this.showSuccess = true;
this.successMessage = "The form has been submitted successfully";
}
}
}
</script>
</body>
</html>
HTMLآلية عمل الكود
1- تهيئة البيانات (x-data
):
- يقوم الكود بتخزين البيانات داخل دالة
initData
التي تحتوي على المتغيرات التالية:username
: لتخزين اسم المستخدم.password
: لتخزين كلمة المرور.showError
: لتحديد ما إذا كان يجب عرض رسالة الخطأ.showSuccess
: لتحديد ما إذا كان يجب عرض رسالة النجاح.errorMessage
: لتخزين رسالة الخطأ.successMessage
: لتخزين رسالة النجاح.
2- التفاعل مع النموذج:
- عند تقديم النموذج عبر الزر إرسال:
- يتم التحقق أولًا إذا كان حقل اسم المستخدم فارغًا أو كلمة المرور فارغة.
- إذا كان أحد الحقلين فارغًا، يتم عرض رسالة خطأ.
- إذا كانت المدخلات صحيحة، يتم إخفاء رسائل الخطأ وعرض رسالة نجاح.
3- التحقق من المدخلات (دالة submitForm
):
- إذا كان حقل اسم المستخدم فارغًا: تظهر رسالة خطأ تطلب إدخال اسم المستخدم.
- إذا كان حقل كلمة المرور فارغًا: تظهر رسالة خطأ تطلب إدخال كلمة المرور.
- إذا كانت الحقول كاملة: تظهر رسالة نجاح تؤكد أن النموذج تم إرساله بنجاح.
4- الرسائل التفاعلية:
- رسالة خطأ: تظهر فقط إذا كانت المدخلات غير كاملة (
x-show="showError"
). - رسالة نجاح: تظهر فقط إذا كانت المدخلات صحيحة (
x-show="showSuccess"
).
x-bind
x-bind
يُستخدم لربط قيمة ديناميكية إلى سمة (attribute) معينة لعنصر HTML. يتيح لك تعديل الخصائص (مثل href
, src
, class
, style
, وغيرها) بناءً على البيانات في Alpine.js.
في المثال السابق، يمكن اضافة CSS Class بشكل ديناميكي لرسالة الخطأ أو النجاح.
<html>
<head>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
<style>
.red{background: red;color: white;}
.green{background: green;color: white;}
</style>
</head>
<body>
<div x-data="initData()">
<h1>
Hello,
<span x-text="username"></span>
<span x-text="password"></span>
</h1>
<hr />
<!-- Message Section: Displays error or success message -->
<div class="message" x-bind:class="{'red': showError, 'green': showSuccess}">
<p class="error" x-show="showError" x-text="errorMessage"></p>
<p class="success" x-show="showSuccess" x-text="successMessage"></p>
</div>
<!-- Form Section -->
<form @submit.prevent="submitForm">
<input type="text" x-model="username" placeholder="Provide your username">
<input type="password" x-model="password" placeholder="Enter your password">
<button type="submit">Submit Form</button>
</form>
</div>
<script>
function initData() {
return {
username: "",
password: "",
showError: false,
showSuccess: false,
errorMessage: "",
successMessage: "",
// Handle form submission
submitForm() {
// Reset error and success states
this.showError = false;
this.showSuccess = false;
// Validate username
if (!this.username) {
this.errorMessage = "You must provide a username";
this.showError = true;
return;
}
// Validate password
if (!this.password) {
this.errorMessage = "You must provide a password";
this.showError = true;
return;
}
// If form is valid, show success message
this.showSuccess = true;
this.successMessage = "The form has been submitted successfully";
}
}
}
</script>
</body>
</html>
HTMLآلية عمل الكود
الكود يستخدم x-bind:class
لإضافة أو إزالة CSS Classes بناءً على قيم البيانات:
- إذا كانت
showError
تساويtrue
، يتم إضافةred
. - إذا كانت
showSuccess
تساويtrue
، يتم إضافةgreen
.
بمعنى آخر، red
و green
تتغير بشكل ديناميكي استنادًا إلى قيم المتغيرات في البيانات.
في Alpine.js، يمكنك استخدام اختصار x-bind
عن طريق استخدام :
بدلاً من كتابة x-bind:
بالكامل. هذا يجعل الكود أكثر نظافة وأسهل في القراءة.
Example:
<button x-bind:disabled="isDisabled">Submit</button>
<button :disabled="isDisabled">Submit</button>
HTMLالعرض الشرطي والتكراري
x-for
يُستخدم لتكرار عناصر معينة داخل قائمة أو مجموعة من البيانات، مثل المصفوفات. عند استخدامه، يُنشئ مكررًا للعناصر تلقائيًا بناءً على بيانات معينة. يمكنك التفكير فيه كطريقة لإنشاء العناصر بشكل ديناميكي باستخدام بنية قائمة (مثل <ul>
أو <table>
)، وتسهيل عرض المحتوى من المصفوفات أو الكائنات داخل الكود دون الحاجة إلى كتابة العناصر بشكل يدوي.
<html>
<head>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
</head>
<body>
<div x-data="listData()">
<h2>Product List</h2>
<ul>
<template x-for="item in items" :key="item.id">
<li>
<span x-text="item.title"></span>:
<span x-text="item.price"></span> USD
</li>
</template>
</ul>
</div>
<script>
function listData() {
return {
items: [
{ id: 1, title: "Product 1", price: "50" },
{ id: 2, title: "Product 2", price: "60" },
{ id: 3, title: "Product 3", price: "70" },
{ id: 4, title: "Product 4", price: "0" },
{ id: 5, title: "Product 5", price: "0" }
]
}
}
</script>
</body>
</html>
HTMLلماذا نستخدم template
في Alpine.js؟
- لا يظهر في DOM: عنصر
<template>
لا يتم عرضه في DOM، بل يُستخدم فقط كـ “قالب” (أو هيكل) يمكن تكراره. هذا يسمح بإنشاء عناصر متعددة دون إدخال عناصر HTML إضافية لا داعي لها. - تحسين الأداء: عند وضع
x-for
على<template>
، يقوم Alpine بنسخ المحتوى داخل القالب وتكراره مباشرةً في الـ DOM. هذا الأسلوب يكون أسرع وأخفّ، ويسمح لـ Alpine بإدارة العناصر المتكررة بشكل أكثر كفاءة. - وضوح الكود: استخدام
<template>
يجعل الكود أوضح، حيث يدل المطورين على أن المحتوى بداخله هو للتكرار فقط، ويجعل الكود منظمًا وسهل القراءة.
يُستخدم العنصر <template> كعنصر حاوية لهيكل الكود الذي تريد تكراره عدة مرات، ولكن template لا يظهر فعليًا في صفحة HTML النهائية.
توضيح الكود
<ul>
<template x-for="item in items" :key="item.id">
<li>
<span x-text="item.title"></span>:
<span x-text="item.price"></span> USD
</li>
</template>
</ul>
HTMLهذا الكود يستخدم Alpine.js لإنشاء قائمة (ul) من المنتجات (items) حيث يتم عرض كل منتج (item) على شكل عنصر قائمة (li) يتضمن عنوان المنتج وسعره.
يمرّ على كل عنصر في مصفوفة items
، ويعرض تفاصيل كل منتج مثل العنوان والسعر داخل عنصر <li>
.
x-for="item in items"
: يكرّر العناصر في مصفوفةitems
.:key="item.id"
: يستخدمid
من كل عنصر كـ “مفتاح” لتسريع إعادة التحديث.- داخل التكرار، يتم عرض العنوان والسعر باستخدام
x-text
.
بشكل عام، يستخدم x-for
لتكرار HTML بناءً على مجموعة من البيانات في Alpine.js.
x-if
المفهوم
تستخدم لعرض أو إخفاء العناصر بناءً على شرط معين. عندما يكون الشرط صحيحًا، يتم إضافة العنصر إلى DOM (الشجرة الهيكلية للصفحة)؛ وعندما يكون الشرط غير صحيح، يتم إزالته.
كيف تعمل
- x-if=”condition”: إذا كانت القيمة في condition صحيحة (مثل true أو أي قيمة غير فارغة)، سيظهر العنصر في الصفحة.
- إذا كانت القيمة غير صحيحة (مثل false أو null)، سيتم إزالة العنصر بالكامل من الصفحة.
<html>
<head>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
</head>
<body>
<div x-data="listData()">
<h2>Product List</h2>
<ul>
<template x-for="item in items" :key="item.id">
<template x-if="item.price >= 60">
<li>
<span x-text="item.title"></span>:
<span x-text="item.price"></span> USD
</li>
</template>
</template>
</ul>
</div>
<script>
function listData() {
return {
items: [
{ id: 1, title: "Product 1", price: "50" },
{ id: 2, title: "Product 2", price: "60" },
{ id: 3, title: "Product 3", price: "70" },
{ id: 4, title: "Product 4", price: "0" },
{ id: 5, title: "Product 5", price: "0" }
]
}
}
</script>
</body>
HTMLتوضيح الكود
<template x-if="item.price >= 60">
: يتحقق من إذا كان سعر العنصر (item.price
) أكبر من أو يساوي 60.- إذا كانت القيمة
true
، سيتم عرض الـ<li>
داخل الـ<template>
. - إذا كانت القيمة
false
، فلن يتم عرض العنصر.
- إذا كانت القيمة
<li>
: يعرض تفاصيل العنصر إذا كانت الشروط (item.price >= 60
) صحيحة، بما في ذلك:<span x-text="item.title"></span>
: يعرض عنوان المنتج.<span x-text="item.price"></span> USD
: يعرض سعر المنتج متبوعًا بـ “USD”.
ببساطة: الكود يستخدم x-if
لعرض العناصر التي يكون سعرها أكبر من أو يساوي 60.
x-if
يقوم بإضافة أو إزالة العنصر من DOM بشكل كامل، بينما x-show
يختبئ العنصر باستخدام CSS (يبقى في DOM).
بعد دراستك لكل هذا الدليل، ستكون على دراية بأساسيات Alpine وسيكون لديك القدرة على إنشاء مشروع متكامل باستخدام Alpine.
إن شاء الله سيكون هنالك دليل شامل للموضوعات المتقدمة في Alpine.js