يتيح لك إنشاء جدول بيانات تفاعلي باستخدام JavaScript إضافة وظائف البحث والفرز والتصفية وتقسيم الصفحات وتصدير البيانات إلى CSV، دون الحاجة إلى الاعتماد على مكتبات خارجية.
بدلًا من بناء هذه الوظائف واحدة تلو الأخرى، يمكنك البدء بمشروع جاهز يعتمد على HTML5 وCSS3 وVanilla JavaScript، ثم تعديل البيانات والتصميم ليتناسب مع موقعك أو تطبيقك.
 |
| يوفر المشروع واجهة موحدة لتنظيم السجلات والبحث فيها وفرزها وتصفيتها مع إمكانية تصدير النتائج إلى CSV. |
في هذا الدليل، نستعرض مشروع KERLION Advanced Data Table، ونشرح طريقة عمله والملفات التي يتكون منها، وكيفية تشغيله وتخصيصه، مع توضيح آلية معالجة البيانات وتصديرها، والقيود التي ينبغي معرفتها قبل استخدامه في مشروع فعلي.
ما هو مشروع KERLION Advanced Data Table؟
KERLION Advanced Data Table هو مكوّن واجهة أمامية لإنشاء جدول بيانات تفاعلي يدعم اللغة العربية واتجاه الكتابة من اليمين إلى اليسار (RTL).
يعتمد المشروع على ثلاث تقنيات أساسية:
- HTML5: لبناء هيكل الجدول وعناصر التحكم.
- CSS3: لتنسيق الواجهة وجعلها متجاوبة مع أحجام الشاشات المختلفة.
- Vanilla JavaScript: لمعالجة البيانات وتنفيذ البحث والفرز والتصفية وتقسيم الصفحات والتصدير.
لا يحتاج المشروع إلى مكتبات JavaScript خارجية أو قاعدة بيانات أو واجهة API لتشغيل نسخته التجريبية. تخزن السجلات داخل مصفوفة في ملف JavaScript، وتُنفّذ العمليات عليها مباشرة داخل متصفح المستخدم.
لمن يناسب هذا المشروع؟
يمكن الاستفادة من الكود في عدة حالات، منها:
- مطورو الواجهات الأمامية الذين يحتاجون إلى مكوّن جدول جاهز.
- أصحاب المواقع الذين يريدون عرض قوائم الموظفين أو العملاء أو المنتجات.
- المطورون الذين يحتاجون إلى البحث والتصفية داخل مجموعة من السجلات.
- المبتدئون والمتوسطون الذين يريدون فهم كيفية ربط HTML وCSS وJavaScript في تطبيق عملي.
- المطورون الذين يبحثون عن كود جدول بيانات HTML جاهز للتحميل والتخصيص.
متى يكون استخدامه مناسبا؟
يكون المشروع مناسبًا عندما تكون البيانات متاحة داخل الواجهة الأمامية، ويكون المطلوب تنظيمها وعرضها مع توفير أدوات للتعامل معها.
أما إذا كان التطبيق يحتاج إلى تسجيل البيانات وحفظ التعديلات ومزامنتها بين المستخدمين، فستحتاج إلى تطوير طبقة خلفية وربط الجدول بمصدر بيانات دائم.
مميزات جدول البيانات التفاعلي ووظائفه
يجمع المشروع مجموعة من الوظائف التي يحتاج إليها المطور عند إنشاء جدول HTML مع البحث والفرز والتصفية.
البحث الفوري داخل جميع حقول البيانات
يوفر المشروع حقل بحث يتيح الوصول إلى السجلات دون الحاجة إلى التنقل بينها يدويا.
يمكن البحث باستخدام:
- الرقم التعريفي للسجل.
- الاسم.
- البريد الإلكتروني.
- الوظيفة.
- التاريخ.
- الحالة.
تعمل عملية البحث أثناء الكتابة؛ فعند إدخال كلمة أو جزء منها، يعيد JavaScript معالجة السجلات وعرض النتائج المطابقة.
ومن النقاط المهمة أن البحث لا يقتصر على السجلات الموجودة في الصفحة الحالية، بل يفحص مصفوفة البيانات كاملة.
كذلك يستخدم المشروع دالة normalizeText لمعالجة النصوص قبل المقارنة، بما يساعد على تحسين البحث باللغة العربية من خلال إزالة بعض علامات التشكيل وتوحيد الصيغة النصية.
فرز البيانات حسب الأعمدة
يمكن ترتيب السجلات بالنقر على عناوين الأعمدة المدعومة بالفرز.
يدعم الإصدار الحالي الترتيب حسب:
- الرقم.
- الاسم.
- البريد الإلكتروني.
- الوظيفة.
- التاريخ.
يستطيع المستخدم التبديل بين الترتيب التصاعدي والتنازلي بالنقر على العمود نفسه مرة أخرى.
ويستخدم المشروع Intl.Collator لمقارنة النصوص، مع إعدادات مناسبة للمقارنة باللغة العربية والتعامل مع الأرقام الموجودة داخل النصوص.
تصفية البيانات حسب الوظيفة والحالة
إلى جانب البحث النصي، يوفر المشروع قائمتين لتصفية السجلات:
تصفية الوظيفة: تعرض السجلات المرتبطة بوظيفة محددة، مثل مطور واجهات أو مصمم واجهات أو محلل بيانات.
تصفية الحالة: تسمح بالاختيار بين ثلاث حالات:
- نشط active.
- غير نشط inactive.
- قيد المراجعة pending.
يمكن الجمع بين البحث النصي والفلاتر في الوقت نفسه. على سبيل المثال، يستطيع المستخدم البحث عن اسم معين مع تحديد وظيفة وحالة محددتين.
وهذا يجعل الوصول إلى البيانات أكثر دقة من الاعتماد على البحث وحده.
تقسيم صفحات جدول البيانات وتغيير عدد النتائج
عندما تحتوي البيانات على عدد كبير من السجلات، يصبح عرضها جميعًا في صفحة واحدة أقل ملاءمة للاستخدام.
لهذا يتضمن المشروع نظام Pagination لتقسيم النتائج إلى صفحات، مع إمكانية اختيار عدد السجلات المعروضة في كل صفحة.
الخيارات المتاحة في الإصدار الحالي هي:
- 5 سجلات.
- 10 سجلات.
- 20 سجلًا.
- 50 سجلا.
كما تتضمن الواجهة أزرار الانتقال إلى الصفحة السابقة والتالية، ومؤشرًا يوضح رقم الصفحة الحالية وإجمالي الصفحات.
تعاد عملية حساب الصفحات عند تغيير البحث أو الفلاتر أو عدد النتائج، ويعاد ضبط الصفحة الحالية إلى الصفحة الأولى عند تغيير هذه الخيارات.
تصدير جميع النتائج المطابقة إلى CSV
من الوظائف المهمة في المشروع إمكانية تنزيل البيانات بصيغة CSV.
تسمح هذه الوظيفة بنقل السجلات إلى برامج الجداول الإلكترونية أو الاحتفاظ بنسخة قابلة للمعالجة خارج المتصفح.
والأهم أن التصدير يشمل جميع السجلات المطابقة للبحث والفلاتر الحالية، وليس السجلات الظاهرة في الصفحة المفتوحة فقط.
فإذا كانت نتائج البحث موزعة على عدة صفحات، يحصل المستخدم على جميع النتائج المطابقة في ملف واحد.
دعم اللغة العربية واتجاه RTL
صممت الواجهة لتناسب المحتوى العربي، ويظهر ذلك في عدة أجزاء:
- تحديد لغة الصفحة باستخدام lang="ar".
- تحديد اتجاه الكتابة باستخدام dir="rtl".
- محاذاة محتوى الجدول إلى اليمين.
- استخدام تنسيق عربي لعرض التواريخ والأرقام.
- معالجة النصوص العربية أثناء البحث.
- استخدام UTF-8 عند إنشاء ملفات CSV، مع إضافة BOM للمساعدة على عرض العربية بصورة صحيحة في برامج الجداول المتوافقة.
تصميم متجاوب للكمبيوتر والهواتف
يستخدم ملف styles.css قواعد CSS Responsive Design لتعديل توزيع عناصر الواجهة وفق مساحة الشاشة. على الشاشات الكبيرة، تظهر أدوات البحث والتصفية في صفوف منظمة، بينما تتحول إلى ترتيب رأسي على الشاشات الصغيرة.
أما الجدول نفسه فيحتفظ بعرض أدنى مناسب للأعمدة، وتُستخدم منطقة تمرير أفقي عند عدم اتساع شاشة الهاتف لعرض جميع الأعمدة.
 |
| تتكيف واجهة الجدول مع الشاشات الصغيرة من خلال ترتيب أدوات التحكم رأسيًا وإتاحة التمرير الأفقي للوصول إلى الأعمدة كاملة. |
وبذلك يستطيع المستخدم الوصول إلى البيانات دون فقدان الأعمدة أو ضغط محتوياتها بصورة تضعف وضوح القراءة.
موضع الصورة الأولى:
لقطة شاشة فعلية للواجهة الرئيسية للمشروع على الكمبيوتر، تظهر بطاقات الإحصائيات والجدول وأدوات البحث والتصفية.
مكونات المشروع والملفات البرمجية المستخدمة
يتكون مشروع KERLION Advanced Data Table من مجموعة ملفات مستقلة، لكل منها وظيفة محددة.
| الملف | الوظيفة |
|---|---|
index.html |
بناء واجهة الجدول وعناصر التحكم |
styles.css |
تنسيق التصميم والاستجابة للشاشات |
table.js |
معالجة البيانات وتنفيذ الوظائف التفاعلية |
README.md |
تعليمات التشغيل والتخصيص |
LICENSE |
شروط استخدام المشروع |
ملف index.html: بناء واجهة الجدول باستخدام HTML
يحتوي هذا الملف على البنية الأساسية للواجهة.
يعتمد الجدول على عناصر HTML الدلالية، وأهمها:
- <table> لإنشاء الجدول.
- <thead> لتحديد عناوين الأعمدة.
- <tbody> لاحتواء صفوف البيانات.
- <th> لعناوين الأعمدة.
- <td> لخلايا البيانات.
يوجد أيضًا عدد من العناصر المخصصة للتفاعل، مثل حقل البحث وقوائم التصفية وأزرار التنقل والتصدير.
ومن الأمثلة المهمة على ذلك:
<table id="dataTable">
<thead>
<tr>
<th>الرقم</th>
<th>الاسم</th>
<th>البريد الإلكتروني</th>
<th>الوظيفة</th>
<th>الحالة</th>
<th>تاريخ التسجيل</th>
</tr>
</thead>
<tbody id="tableBody">
<!-- Generated by JavaScript -->
</tbody>
</table>
لاحظ أن عنصر tbody لا يحتوي على السجلات مباشرة في ملف HTML؛ إذ يتولى JavaScript إنشاء الصفوف وإضافتها عند تشغيل الصفحة.
كذلك يربط الملف ملفي التصميم والبرمجة:
<link rel="stylesheet" href="styles.css"> <script src="table.js" defer></script>
استخدام defer يجعل المتصفح ينفذ ملف JavaScript بعد تحليل مستند HTML، مما يتيح للعناصر المطلوبة أن تكون موجودة عند بدء تشغيل الكود.
ملف styles.css: تصميم الجدول وجعله متجاوبا
يتولى هذا الملف التحكم في المظهر البصري للجدول.
توجد فيه قواعد لتنسيق:
- الحاوية الرئيسية.
- رأس الصفحة.
- بطاقات الإحصائيات.
- حقل البحث وقوائم التصفية.
- الجدول وصفوفه وأعمدته.
- أزرار الفرز والتنقل.
- رسائل عدم وجود نتائج.
- العرض على الشاشات اللوحية والهواتف.
ومن الأساليب المستخدمة متغيرات CSS، التي تجعل تعديل الألوان أسهل دون الحاجة إلى البحث عن كل قيمة داخل الملف.
مثال:
:root {
--bg: #f5f7fb;
--surface: #ffffff;
--text: #172033;
--muted: #68758a;
--primary: #087f5b;
--border: #e0e6ef;
}
يمكنك تغيير هذه القيم لتعديل الألوان الأساسية للواجهة.
أما الاستجابة لأحجام الشاشات فتُنفذ باستخدام Media Queries، مثل قواعد نقاط التوقف الموجودة في ملف المشروع.
موضع الصورة الثانية:
لقطة شاشة فعلية للجدول على الهاتف، توضح ترتيب أدوات التحكم والتمرير الأفقي للأعمدة.
ملف table.js: تنفيذ وظائف الجدول التفاعلية
هذا هو الملف المسؤول عن منطق التطبيق.
يحتوي على مصفوفة البيانات، ودوال البحث والفرز والتصفية، ودوال إنشاء الصفوف وتحديث الواجهة باستخدام JavaScript، إضافة إلى نظام Pagination وتصدير CSV.
كما يتولى ربط عناصر الصفحة بالأحداث التي ينفذها المستخدم، مثل الكتابة داخل حقل البحث أو تغيير الفلاتر أو الضغط على أزرار الفرز.
ملف README.md وملف LICENSE
يحتوي README.md على معلومات المشروع وطريقة تشغيله وتخصيص البيانات، بينما يوضح LICENSE شروط استخدام الكود.
وجود هذين الملفين مهم عند إعادة استخدام المشروع لأن الأول يساعد المطور على فهم طريقة التعامل معه، والثاني يحدد الحقوق والالتزامات المرتبطة بإعادة استخدامه وتوزيعه.
شرح طريقة عمل جدول البيانات التفاعلي باستخدام JavaScript
لفهم طريقة إنشاء جدول تفاعلي JavaScript، من المفيد تتبع مسار البيانات داخل المشروع، بدءًا من تخزين السجلات، مرورًا بمعالجتها، وانتهاءً بعرض النتائج في الجدول.
يعتمد الإصدار الحالي على مصفوفة JavaScript واحدة كمصدر للبيانات، ثم ينفذ عمليات البحث والفرز والتصفية عليها قبل تحديد السجلات التي ستظهر في الصفحة.
تخزين البيانات داخل مصفوفة JavaScript
توجد البيانات التجريبية في ملف table.js داخل مصفوفة باسم records.
يمثل كل عنصر في المصفوفة سجلًا مستقلًا، ويحتوي على مجموعة من الخصائص التي تحدد المعلومات المرتبطة به.
مثال مبسط:
const records = [
{
id: 1001,
name: "أحمد محمد",
email: "ahmed@example.com",
role: "مطور واجهات",
status: "active",
date: "2026-01-12"
},
{
id: 1002,
name: "سارة علي",
email: "sara@example.com",
role: "مصمم واجهات",
status: "pending",
date: "2026-01-15"
}
];
تخزن المصفوفة مجموعة من الكائنات، ويحتوي كل كائن على ستة حقول:
| الخاصية | الاستخدام |
|---|---|
id |
الرقم التعريفي |
name |
الاسم |
email |
البريد الإلكتروني |
role |
الوظيفة |
status |
حالة السجل |
date |
التاريخ |
هذا التنظيم يجعل الوصول إلى البيانات ومعالجتها أسهل؛ إذ يمكن استخدام اسم الخاصية للوصول إلى قيمتها بدلًا من الاعتماد على ترتيب القيم داخل مصفوفة فرعية.
ملاحظة: البيانات الموجودة في الإصدار v1.0.0 تجريبية ووهمية، والغرض منها توضيح طريقة عمل الجدول. يجب استبدالها ببيانات المشروع الفعلية عند التخصيص.
ربط JavaScript بعناصر HTML باستخدام DOM
يحتاج JavaScript إلى الوصول إلى عناصر HTML حتى يتمكن من قراءة مدخلات المستخدم وتحديث الجدول.
يستخدم المشروع document.getElementById للوصول إلى العناصر المطلوبة.
مثال:
const elements = {
tableBody: document.getElementById("tableBody"),
searchInput: document.getElementById("searchInput"),
roleFilter: document.getElementById("roleFilter"),
statusFilter: document.getElementById("statusFilter"),
pageSize: document.getElementById("pageSize"),
exportCsv: document.getElementById("exportCsv")
};
تجمع مراجع العناصر داخل كائن واحد باسم elements حتى يسهل الوصول إليها من مختلف الدوال.
فعندما يحتاج البرنامج إلى قراءة نص البحث، يمكنه استخدام:
const query = elements.searchInput.value;
وعندما يحتاج إلى تحديث محتوى الجدول، يستطيع الوصول مباشرة إلى عنصر tbody من خلال:
elements.tableBody.innerHTML = "";
قبل تنفيذ الوظائف، يتحقق المشروع أيضًا من وجود عناصر HTML المطلوبة. فإذا كان أحدها مفقودًا، يعرض رسالة خطأ في وحدة التحكم ويتوقف عن متابعة التهيئة.
البحث داخل جدول HTML باستخدام JavaScript
تتم عملية البحث داخل الدالة getFilteredRecords، التي تقرأ قيمة حقل البحث وقيم الفلاتر، ثم تفحص السجلات الموجودة في مصفوفة records.
يستخدم المشروع دالة normalizeText لتوحيد النصوص قبل المقارنة.
مقطع مبسط من منطق البحث:
function normalizeText(value) {
return String(value ?? "")
.normalize("NFKC")
.replace(/[\u064B-\u065F\u0670]/g, "")
.trim()
.toLocaleLowerCase("ar");
}
تؤدي هذه الدالة عدة وظائف:
- تحويل القيمة إلى نص.
- تطبيق Unicode Normalization باستخدام NFKC.
- إزالة مجموعة من علامات التشكيل.
- حذف المسافات الزائدة من بداية النص ونهايته.
- تحويل الأحرف إلى صيغة صغيرة وفق إعداد اللغة العربية، بما يفيد عند مقارنة النصوص التي تحتوي على أحرف لاتينية.
بعد ذلك يستخدم المشروع filter() لفحص السجلات:
const filteredRecords = records.filter(record => {
return [
record.id,
record.name,
record.email,
record.role,
record.date,
statusLabels[record.status]
].some(value =>
normalizeText(value).includes(query)
);
});
تبحث الدالة عن النص المدخل داخل الحقول المحددة، وتحتفظ بالسجل إذا وجدت تطابقًا في حقل واحد على الأقل.
تستخدم some() لأن المطلوب ليس مطابقة جميع الحقول، بل يكفي العثور على النص داخل أحدها.
وهكذا يمكن للمستخدم كتابة الاسم أو البريد الإلكتروني أو الوظيفة أو حتى الحالة للوصول إلى السجلات المرتبطة بعبارة البحث.
فرز البيانات باستخدام JavaScript
بعد الحصول على السجلات المطابقة، يمكن ترتيبها وفق العمود الذي اختاره المستخدم.
يستخدم المشروع Array.sort() لتنفيذ عملية الفرز، مع دالة مقارنة اسمها compareRecords.
function compareRecords(a, b, key) {
if (key === "id") {
return Number(a.id) - Number(b.id);
}
if (key === "date") {
return String(a.date).localeCompare(
String(b.date)
);
}
return collator.compare(
String(a[key] ?? ""),
String(b[key] ?? "")
);
}
تختلف طريقة المقارنة بحسب نوع البيانات:
- الأرقام تقارن بعد تحويلها إلى قيم رقمية.
- التواريخ تُقارن باعتبارها نصوصًا بصيغة ISO YYYY-MM-DD المستخدمة في بيانات المشروع.
- الحقول النصية تستخدم Intl.Collator لمقارنة القيم.
أما تحديد اتجاه الفرز فيتم من خلال متغير sortState:
let sortState = {
key: null,
direction: 1
};
تمثل key العمود المحدد، بينما تحدد direction اتجاه الترتيب.
القيمة 1 تعني الترتيب التصاعدي، والقيمة -1 تعني الترتيب التنازلي.
وعند النقر على عنوان عمود جديد، يبدأ الفرز تصاعديًا. أما النقر على العمود نفسه مرة أخرى فيعكس الاتجاه.
تصفية البيانات JavaScript
تنفذ التصفية بالتزامن مع البحث داخل getFilteredRecords.
ويعتمد المشروع على شرطين إضافيين:
const matchesRole =
!selectedRole || record.role === selectedRole;
const matchesStatus =
!selectedStatus || record.status === selectedStatus;
وفي النهاية يجمع المشروع الشروط:
return matchesSearch &&
matchesRole &&
matchesStatus;
هذا يعني أن السجل يجب أن يطابق البحث النصي والوظيفة والحالة المحددة في الوقت نفسه.
إنشاء صفوف الجدول وتحديث الواجهة
بعد معالجة البيانات، تأتي مرحلة عرض النتائج داخل HTML.
يستخدم المشروع الدالة createRow لإنشاء صف لكل سجل، ثم يجمع الصفوف داخل عنصر tbody.
ومن النقاط المهمة هنا استخدام escapeHTML قبل إدراج البيانات النصية في HTML.
function escapeHTML(value) {
const characters = {
"&": "&",
"<": "<",
">": ">",
'"': """,
"'": "'"
};
return String(value ?? "").replace(
/[&<>"']/g,
character => characters[character]
);
}
تستبدل الدالة الرموز الخاصة بنظائرها النصية الآمنة، حتى لا تُفسر القيم القادمة من البيانات على أنها عناصر أو تعليمات HTML.
يستخدم المشروع هذه المعالجة عند إنشاء خلايا الجدول، وهو إجراء مهم لتقليل مخاطر إدراج محتوى HTML غير موثوق داخل الصفحة.
أما الدالة المسؤولة عن تحديث النتائج فهي renderTable.
يمكن تلخيص تسلسل عملها كالتالي:
- الحصول على السجلات المطابقة للبحث والفلاتر.
- ترتيب السجلات وفق إعداد الفرز الحالي.
- حساب عدد الصفحات.
- تحديد السجلات الخاصة بالصفحة الحالية.
- إنشاء صفوف HTML وعرضها.
- تحديث الإحصائيات ومعلومات التنقل.
- تحديث مؤشرات الفرز.
هذا التنظيم يجعل تحديث الجدول يتم من خلال نقطة مركزية واحدة، بدل تكرار منطق العرض في كل حدث.
كيف يعمل تقسيم صفحات جدول البيانات؟
بعد البحث والفرز، يستخدم المشروع slice() للحصول على الجزء الذي ينتمي إلى الصفحة الحالية.
يحسب موضع البداية بهذه المعادلة:
const start = (currentPage - 1) * pageSize;
ثم تحدد السجلات المعروضة:
const pageRecords = sorted.slice(
start,
start + pageSize
);
على سبيل المثال، إذا كان عدد النتائج 22 سجلًا، وكان عدد السجلات في الصفحة الواحدة 10:
- الصفحة الأولى تعرض السجلات من 1 إلى 10.
- الصفحة الثانية تعرض السجلات من 11 إلى 20.
- الصفحة الثالثة تعرض السجلين 21 و22.
يحسب عدد الصفحات باستخدام:
const pageCount = Math.ceil(
sorted.length / pageSize
);
تستخدم Math.ceil() لتقريب الناتج إلى العدد الصحيح الأعلى، حتى تخصص صفحة أخيرة للسجلات المتبقية.
وتعاد عملية حساب الصفحات عند تغيير البحث أو التصفية أو عدد النتائج، حتى لا يبقى المستخدم في صفحة لم تعد موجودة بعد تقلص عدد السجلات.
كيفية تصدير جدول HTML إلى CSV باستخدام JavaScript
تسمح وظيفة تصدير جدول HTML إلى CSV بإنشاء ملف يحتوي على البيانات التي اختار المستخدم عرضها وفق البحث والفلاتر الحالية.
في مشروع KERLION، تنفذ العملية داخل الدالة exportToCSV، وتعتمد على عدة خطوات متتابعة.
أولا: جمع السجلات المطابقة قبل التصدير
يبدأ المشروع بالحصول على البيانات بعد تطبيق البحث والفلاتر والفرز:
const filtered = getSortedRecords(
getFilteredRecords()
);
لاحظ أن الدالة لا تستخدم pageRecords، التي تحتوي على السجلات المعروضة في الصفحة الحالية فقط.
بل تستخدم النتائج الكاملة، وهذا هو السبب في أن ملف CSV يحتوي على جميع السجلات المطابقة حتى عندما تكون موزعة على صفحات متعددة.
ثانيا: تجهيز عناوين الأعمدة والبيانات
يحدد المشروع أسماء الأعمدة التي ستظهر في ملف CSV:
const headers = [
"الرقم",
"الاسم",
"البريد الإلكتروني",
"الوظيفة",
"الحالة",
"تاريخ التسجيل"
];
ثم يحول كل سجل إلى مصفوفة من القيم:
const rows = filtered.map(record => [
record.id,
record.name,
record.email,
record.role,
statusLabels[record.status] || "غير معروف",
record.date
]);
تضمن هذه الخطوة أن تكون البيانات المصدرة مرتبة وفق الأعمدة المحددة، مع تحويل قيم الحالة الداخلية إلى تسميات عربية مناسبة.
ثالثا: معالجة القيم وتحويلها إلى CSV
يجب التعامل مع بعض الرموز داخل القيم قبل تحويلها إلى ملف CSV، خصوصًا الفواصل وعلامات الاقتباس.
يستخدم المشروع الدالة التالية:
function escapeCSV(value) {
let text = String(value ?? "");
if (/^[\s]*[=+\-@]/.test(text)) {
text = "'" + text;
}
return `"${text.replace(/"/g, '""')}"`;
}
تؤدي هذه الدالة وظيفتين أساسيتين:
- إحاطة القيمة بعلامات اقتباس مزدوجة، مع مضاعفة علامات الاقتباس الموجودة داخلها.
- إضافة فاصلة عليا للقيم التي تبدأ برموز قد تتعامل معها برامج الجداول على أنها صيغ، لتقليل مخاطر حقن الصيغ.
بعد ذلك تجمع الحقول والصفوف:
const csvContent = [
headers,
...rows
].map(row => {
return row.map(escapeCSV).join(",");
}).join("\r\n");
تستخدم الفاصلة للفصل بين الحقول، بينما تفصل \r\n بين الصفوف.
رابعا: استخدام Blob API لإنشاء ملف قابل للتنزيل
بعد تجهيز محتوى CSV، يحتاج المتصفح إلى تحويل النص إلى ملف يمكن تنزيله.
هنا تظهر فائدة واجهة Blob API، التي تتيح إنشاء كائن يمثل مجموعة من البيانات.
يستخدم المشروع:
const blob = new Blob(
["\uFEFF", csvContent],
{
type: "text/csv;charset=utf-8;"
}
);
توجد علامة \uFEFF في بداية المحتوى لتمثيل UTF-8 BOM.
تساعد هذه العلامة بعض برامج الجداول الإلكترونية على التعرف على ترميز النصوص العربية وعرضها بصورة صحيحة.
بعد إنشاء الملف، ينشئ المشروع رابطًا مؤقتا:
const url = URL.createObjectURL(blob);
ثم ينشئ عنصر رابط HTML ويحدد اسم الملف ومصدره:
const link = document.createElement("a");
link.href = url;
link.download = "kerlion-data-table.csv";
document.body.appendChild(link);
link.click();
link.remove();
يؤدي الضغط البرمجي على الرابط إلى بدء تنزيل الملف في المتصفح.
وأخيرا يحرر الرابط المؤقت بعد انتهاء الحاجة إليه:
URL.revokeObjectURL(url);
يستخدم الإصدار الحالي تأخيرًا قصيرًا قبل تنفيذ عملية التحرير حتى تتاح للمتصفح فرصة بدء التنزيل.
ما أهمية UTF-8 عند تصدير البيانات العربية؟
قد تظهر النصوص العربية بصورة غير صحيحة في بعض البرامج إذا لم يتم التعرف على الترميز المستخدم في الملف.
لهذا يحدد المشروع نوع المحتوى باستخدام:
text/csv;charset=utf-8;
ويضيف BOM إلى بداية الملف.
يساعد هذا الإجراء على تحسين التوافق مع برامج الجداول الإلكترونية التي تستفيد من علامة BOM عند فتح ملفات CSV.
 |
| يساعد استخدام UTF-8 مع إضافة BOM على تحسين ظهور النصوص العربية عند فتح ملفات CSV في برامج الجداول الإلكترونية المتوافقة. |
ومع ذلك، قد تختلف طريقة التعامل مع الترميز حسب البرنامج المستخدم وإعداداته.
موضع الصورة الثالثة:
لقطة فعلية لملف CSV بعد تنزيله وفتحه في برنامج جداول إلكترونية، تظهر عناوين الأعمدة والبيانات العربية بصورة صحيحة.
أمان البيانات عند عرضها وتصديرها
عند استخدام جدول بيانات JavaScript مع بيانات حقيقية، لا يكفي الاهتمام بوظائف العرض فقط؛ بل يجب الانتباه إلى طبيعة البيانات وطريقة التعامل معها.
يتضمن المشروع إجراءين مهمين:
- استخدام escapeHTML عند إدراج القيم داخل صفوف HTML، لتقليل مخاطر تفسير البيانات النصية كتعليمات HTML.
- استخدام escapeCSV لمعالجة بعض القيم التي قد تفسرها برامج الجداول على أنها صيغ.
هذه الإجراءات تقلل بعض المخاطر، لكنها لا تمثل نظامًا أمنيا متكاملا، ولا تغني عن التحقق من البيانات ومراجعة مصادرها.
كذلك لا ينبغي استخدام بيانات شخصية أو سرية في النسخة التجريبية المنشورة، خصوصًا أن المشروع لا يتضمن نظام مصادقة أو صلاحيات وصول.
كيفية تنزيل مشروع KERLION Advanced Data Table وتشغيله
بعد التعرف على وظائف المشروع وآلية عمله، يمكنك الحصول على ملفات الإصدار الرسمي v1.0.0 وتشغيلها مباشرة في متصفحك.
الوصول إلى المستودع البرمجي على GitHub
توجد ملفات المشروع داخل مكتبة KERLION Code Snippets، وتحديدًا في المجلد:
javascript/advanced-data-table
يمكنك الوصول إلى ملفات المشروع من خلال: فتح مجلد Advanced Data Table على GitHub.
تنزيل ملفات المشروع
يتوفر الإصدار v1.0.0 كملف ZIP مستقل ضمن مرفقات الإصدار الرسمي على GitHub.
KERLION-Advanced-Data-Table-v1.0.0.zip
يمكنك أيضا تنزيل الملفات الأساسية بصورة منفصلة من مجلد المشروع على GitHub عند الحاجة:
- index.html
- styles.css
- table.js
تشغيل الجدول في المتصفح
بعد تنزيل الملفات، اتبع الخطوات التالية:
- فك ضغط ملف ZIP.
- تأكد من وجود الملفات الأساسية الثلاثة في مجلد واحد.
- افتح ملف index.html باستخدام متصفح حديث.
- انتظر تحميل الواجهة والبيانات التجريبية.
- جرّب البحث والفرز والتصفية والتنقل بين الصفحات.
- اضغط على زر تنزيل CSV لاختبار تصدير النتائج.
لا تحتاج إلى تثبيت Node.js أو تشغيل أوامر بناء المشروع؛ فالنسخة الحالية لا تعتمد على عملية Build أو مكتبات خارجية.
كذلك لا تحتاج إلى تشغيل خادم محلي لمجرد تجربة البيانات التجريبية، إذ يمكن فتح ملف HTML مباشرة في المتصفح.
كيفية تخصيص جدول البيانات وإضافة سجلاتك الخاصة
بعد تشغيل المشروع، تأتي الخطوة الأهم: استبدال البيانات التجريبية ببيانات موقعك أو تطبيقك.
تتم عملية التخصيص الأساسية داخل ملف table.js، وتحديدًا في مصفوفة records.
تعديل مصفوفة records
افتح ملف JavaScript وابحث عن:
const records = [
ستجد مجموعة من السجلات التجريبية، ويمكنك استبدالها بسجلاتك الخاصة.
على سبيل المثال، إذا كنت تطور لوحة لعرض بيانات الموظفين، يمكنك استخدام البنية التالية:
const records = [
{
id: 2001,
name: "أحمد محمود",
email: "ahmed@company.com",
role: "مطور واجهات",
status: "active",
date: "2026-09-15"
},
{
id: 2002,
name: "سارة محمد",
email: "sara@company.com",
role: "مصممة واجهات",
status: "pending",
date: "2026-09-18"
}
];
المهم هو الحفاظ على أسماء الخصائص التي يعتمد عليها الكود، لأن دوال البحث والفرز والتصفية والعرض والتصدير تستخدم هذه الأسماء للوصول إلى القيم.
الالتزام بقيم الحالات المدعومة
يستخدم المشروع ثلاث قيم داخلية للحالة:
| القيمة في JavaScript | النص الظاهر |
|---|---|
active |
نشط |
inactive |
غير نشط |
pending |
قيد المراجعة |
تحدد التسميات داخل الكائن:
const statusLabels = {
active: "نشط",
inactive: "غير نشط",
pending: "قيد المراجعة"
};
وتستخدم هذه القيم أيضا لتحديد تنسيق شارة الحالة داخل الجدول.
إذا أضفت حالة جديدة، فلن يكفي وضعها داخل السجل فقط؛ بل ستحتاج إلى تحديث القيم المرتبطة بها في statusLabels وstatusClasses وخيارات الحالة في ملف HTML، وفقًا لما تريد دعمه.
تخصيص قائمة الوظائف
لا تحتاج إلى كتابة خيارات الوظائف يدويًا داخل HTML.
يتولى المشروع إنشاء خيارات قائمة الوظائف تلقائيًا من القيم الموجودة في مصفوفة records.
تنفذ هذه العملية داخل:
function initializeRoleFilter() {
const roles = [...new Set(
records.map(record => record.role)
)].sort(collator.compare);
roles.forEach(role => {
const option = document.createElement("option");
option.value = role;
option.textContent = role;
elements.roleFilter.appendChild(option);
});
}
تعمل map() على استخراج الوظائف من السجلات، وتستخدم Set لإزالة القيم المكررة، ثم ترتب الوظائف وتضاف إلى قائمة التصفية.
بالتالي، عند إضافة وظيفة جديدة إلى أحد السجلات، ستظهر ضمن خيارات التصفية بعد تحميل الصفحة.
تخصيص أعمدة الجدول
إذا أردت إضافة حقل جديد، مثل رقم الهاتف أو القسم، فستحتاج إلى تعديل أكثر من موضع.
على سبيل المثال، إضافة عمود رقم الهاتف تتطلب:
- إضافة عنوان العمود إلى thead داخل index.html.
- إضافة خاصية الهاتف إلى كل سجل في records.
- تحديث دالة createRow لإظهار القيمة داخل خلية جديدة.
- تحديث البحث إذا أردت البحث باستخدام رقم الهاتف.
- إضافة عنوان الهاتف وقيمته إلى بيانات CSV إذا أردت تضمينه في الملف المصدر.
مثال مبسط لإضافة الخاصية إلى سجل:
{
id: 2001,
name: "أحمد محمود",
email: "ahmed@company.com",
phone: "01000000000",
role: "مطور واجهات",
status: "active",
date: "2026-09-15"
}
إضافة الخاصية وحدها لا تجعلها تظهر تلقائيًا في الجدول؛ لأن بنية الأعمدة ودالة إنشاء الصفوف محددتان بصورة صريحة داخل المشروع.
تخصيص تصميم الجدول وألوانه
يمكنك تعديل مظهر الجدول من خلال ملف styles.css.
ابدأ بمتغيرات CSS الموجودة داخل :root، ثم عدّل الألوان والخلفيات والحدود والمسافات حسب تصميم موقعك.
ويمكنك أيضًا تعديل:
- حجم الخطوط.
- عرض الأعمدة.
- المسافات الداخلية للخلايا.
- شكل أزرار البحث والتصفية.
- ألوان حالات السجلات.
- قواعد العرض على الهاتف.
من الأفضل الاحتفاظ ببنية التصميم الأساسية في البداية، ثم إجراء التعديلات تدريجيًا حتى لا تتأثر قابلية الاستخدام.
حدود الإصدار الحالي ومتى تحتاج إلى تطوير إضافي؟
على الرغم من أن المشروع يوفر مجموعة مفيدة من وظائف التعامل مع البيانات، فمن المهم فهم نطاقه الحقيقي قبل استخدامه في تطبيق يعتمد على بيانات فعلية.
KERLION Advanced Data Table هو مكوّن واجهة أمامية، وليس نظامًا متكاملًا لإدارة قواعد البيانات.
البيانات مخزنة داخل ملف JavaScript
يحتوي الإصدار الحالي على بيانات تجريبية داخل مصفوفة records.
وهذا يعني أن البيانات تُحمّل مع الصفحة، وأن عمليات البحث والفرز والتصفية تُنفذ على هذه المصفوفة داخل المتصفح.
لا يتضمن المشروع آلية لاستيراد البيانات تلقائيًا من ملفات خارجية أو مصادر بعيدة.
لا توجد قاعدة بيانات أو واجهة API
لا يتصل المشروع بقاعدة بيانات، ولا يحتوي على خدمة خلفية أو واجهة API.
إذا أردت استخدامه لعرض سجلات حقيقية ضمن تطبيق متكامل، فستحتاج إلى تطوير آلية لجلب البيانات من المصدر المناسب، ثم تمريرها إلى منطق الجدول، وقد يتطلب ذلك الاستعانة بخدمات تطوير البرمجيات.
يمكن أن يكون هذا المصدر واجهة API أو نظامًا خلفيًا خاصًا بتطبيقك، وفقًا لبنية المشروع الذي تعمل عليه.
لا توجد خاصية لحفظ التغييرات بصورة دائمة
لا يوفر الإصدار الحالي وظائف لإضافة السجلات أو تعديلها أو حذفها مع حفظ هذه التغييرات بصورة دائمة.
كما لا يحتوي على نظام تخزين محلي أو مزامنة تلقائية للبيانات.
لذلك، فإن أي تعديل مباشر على مصفوفة البيانات أثناء تطوير الصفحة لا يمثل عملية حفظ دائمة؛ فعند إعادة تحميل الصفحة، تُقرأ البيانات المحددة داخل ملف JavaScript من جديد.
ما الذي تحتاج إلى تطويره لاستخدام الجدول داخل تطبيق متكامل؟
يعتمد ذلك على متطلبات التطبيق، لكن قد تحتاج إلى إضافة العناصر التالية:
| المتطلب | التطوير المطلوب |
|---|---|
| جلب البيانات الحقيقية | الربط بمصدر بيانات أو API |
| حفظ السجلات | قاعدة بيانات وآلية تخزين خلفية |
| إضافة وتعديل وحذف البيانات | عمليات CRUD |
| حماية البيانات | مصادقة وصلاحيات وتحقق من المدخلات |
| التعامل مع مجموعات ضخمة | معالجة البيانات وتقسيم الصفحات من جهة الخادم عند الحاجة |
هذه إمكانات يمكن إضافتها في مرحلة تطوير لاحقة، وليست وظائف متوفرة في الإصدار v1.0.0.
وتحديد هذا الفرق مهم حتى لا يُستخدم المكوّن باعتباره بديلًا عن نظام إدارة بيانات يحتاج إلى تخزين ومصادقة وصلاحيات.
الإصدار الرسمي ورخصة استخدام المشروع
يتوفر مشروع KERLION Advanced Data Table ضمن مكتبة KERLION Code Snippets، وقد صدر الإصدار المستقر الأول منه تحت الوسم v1.0.0.
معلومات الإصدار v1.0.0
| الخاصية | التفاصيل |
|---|---|
| اسم المشروع | KERLION Advanced Data Table |
| الإصدار | v1.0.0 |
| التقنيات | HTML5 وCSS3 وJavaScript |
| المكتبات الخارجية | لا توجد |
| نوع الترخيص | MIT |
| تاريخ الإصدار المحلي في مصر | 3 نوفمبر 2026 |
عرض الإصدار الرسمي v1.0.0 على GitHub
رخصة MIT وطريقة الاستفادة من المشروع
يُوزع المشروع بموجب رخصة MIT، وهي رخصة مفتوحة المصدر تسمح باستخدام الكود ونسخه وتعديله ودمجه في مشروعات أخرى وإعادة توزيعه، بما في ذلك الاستخدام التجاري، وفقًا لشروط الرخصة.
من أهم هذه الشروط الاحتفاظ بإشعار حقوق النشر ونص الترخيص عند توزيع نسخ من البرنامج أو أجزاء جوهرية منه.
يمكنك الاطلاع على نص الرخصة الكامل داخل مجلد المشروع على GitHub.
الخاتمة
يوفر KERLION Advanced Data Table نقطة بداية عملية للمطورين الذين يحتاجون إلى جدول HTML تفاعلي يدعم البحث والفرز والتصفية وتقسيم الصفحات وتصدير CSV باستخدام JavaScript دون مكتبات خارجية.
يمكن تشغيل المشروع مباشرة في المتصفح، ثم تخصيص مصفوفة البيانات والتصميم والأعمدة بما يتناسب مع طبيعة التطبيق.
لكن ينبغي مراعاة أن الإصدار الحالي يعتمد على بيانات محلية تجريبية ولا يوفر قاعدة بيانات أو تخزينًا دائمًا. لذلك، فإن استخدامه داخل تطبيق متكامل يتطلب ربطه بمصدر بيانات مناسب وإضافة آليات التخزين والحماية بحسب متطلبات المشروع.
ابدأ بتنزيل الإصدار v1.0.0، واستكشف الملفات البرمجية، واستخدمه أساسًا لبناء جدول بيانات يتناسب مع احتياجات مشروعك.
تنزيل KERLION Advanced Data Table v1.0.0
أسئلة شائعة حول مشروع KERLION Advanced Data Table
توجد بعض الاعتبارات التي ينبغي معرفتها قبل دمج جدول البيانات التفاعلي في موقع أو تطبيق فعلي، خصوصًا ما يتعلق بتوسيع وظائفه، والتعامل مع البيانات الحقيقية، وتوافقه مع متطلبات المشروع.
هل يمكن استخدام KERLION Advanced Data Table داخل لوحة تحكم إدارية؟
نعم، يمكن استخدامه مكوّنًا لعرض السجلات داخل لوحة التحكم، مثل بيانات الموظفين والعملاء والمنتجات. لكن الإصدار الحالي يوفر وظائف العرض والبحث والفرز والتصفية فقط، ولا يتضمن نظامًا لإدارة السجلات أو حفظ التعديلات. لذلك يحتاج إلى تطوير إضافي ليتناسب مع متطلبات لوحة التحكم المتكاملة.
هل يمكن ربط الجدول ببيانات قادمة من خادم بدلًا من مصفوفة JavaScript؟
نعم، يمكن تطوير المشروع لاستقبال البيانات من مصدر خارجي، لكن هذه الإمكانية غير موجودة في الإصدار الحالي. يتطلب ذلك إضافة آلية لجلب البيانات وربطها بمنطق الجدول، مع تعديل طريقة معالجة السجلات لتناسب البيانات المستلمة من الخادم بدلًا من الاعتماد على المصفوفة الثابتة.
ماذا يحدث عند إضافة عمود جديد دون تحديث جميع الملفات المرتبطة به؟
لن يظهر العمود الجديد بصورة صحيحة بمجرد إضافة عنوانه أو خاصيته إلى مصفوفة البيانات. يجب تحديث بنية الجدول ودالة إنشاء الصفوف، وإضافة الحقل إلى منطق البحث إذا لزم الأمر، وكذلك إلى عناوين وقيم CSV إذا كنت تريد تضمينه في الملفات المصدرة.
هل يمكن استخدام المشروع مع عدد كبير جدًا من السجلات؟
يعتمد الإصدار الحالي على تحميل جميع السجلات داخل المتصفح، ثم تنفيذ البحث والفرز والتصفية عليها باستخدام JavaScript. لذلك قد تصبح المعالجة أقل ملاءمة مع مجموعات البيانات الضخمة. في هذه الحالة، يمكن تطوير نظام لجلب النتائج ومعالجتها وتقسيم صفحاتها من جهة الخادم.
هل يوفر المشروع حماية كافية لاستخدام بيانات العملاء الحقيقية؟
لا، الإجراءات الأمنية الموجودة لا تكفي وحدها لحماية بيانات العملاء في تطبيق فعلي. يستخدم المشروع معالجة للنصوص عند عرضها وتصديرها لتقليل بعض المخاطر، لكنه لا يتضمن مصادقة أو صلاحيات وصول أو نظامًا متكاملًا لحماية البيانات، ولذلك يحتاج إلى تطوير طبقة حماية مناسبة قبل التعامل مع بيانات حساسة.
هل يمكن تغيير حالات السجلات وإضافة حالات جديدة إلى الجدول؟
نعم، يمكن تخصيص حالات السجلات، لكن إضافة حالة جديدة تتطلب تحديث أكثر من موضع في المشروع. يجب تعديل كائن statusLabels وكائن statusClasses وخيارات التصفية داخل HTML، حتى يتعرف الجدول على الحالة الجديدة ويعرض اسمها وتنسيقها بصورة صحيحة.
هل تسمح رخصة MIT باستخدام المشروع في المنتجات التجارية؟
نعم، تسمح رخصة MIT باستخدام المشروع وتعديله ودمجه في منتجات تجارية وإعادة توزيعه. لكن عند توزيع نسخ من البرنامج أو أجزاء جوهرية منه، يجب الاحتفاظ بإشعار حقوق النشر ونص الترخيص. لذلك يُنصح بمراجعة ملف LICENSE المرفق بالمشروع قبل إعادة توزيعه.
اختبر فهمك لجدول البيانات التفاعلي باستخدام JavaScript
تتضمن الاختبارات التالية ثلاثة أسئلة تقيس فهمك لمشروع KERLION Advanced Data Table، وقدرتك على تطبيق المعلومات في مواقف عملية، وتحليل إمكاناته وحدوده قبل استخدامه في مشروع فعلي.
ما الوظيفة الأساسية للدالة normalizeText في مشروع KERLION Advanced Data Table؟
لديك جدول يحتوي على 22 سجلًا، واخترت عرض 10 سجلات في الصفحة الواحدة. ثم أردت تنزيل جميع السجلات المطابقة لعملية البحث والتصفية الحالية. أي طريقة يعتمد عليها المشروع لتحقيق ذلك؟
تريد استخدام KERLION Advanced Data Table داخل تطبيق لإدارة الموظفين، بحيث يستطيع المستخدمون إضافة السجلات وتعديلها وحذفها، مع حفظ التغييرات بصورة دائمة ومزامنتها. ما القرار الأنسب بناء على حدود الإصدار الحالي؟
مساحة للنقاش: يمثل KERLION Advanced Data Table نقطة انطلاق عملية لبناء جداول بيانات تفاعلية باللغة العربية، مع إمكانية تخصيص وظائفها وتصميمها وفق احتياجات التطبيق. لكن نجاح دمجها يعتمد على فهم حدودها وإضافة التخزين والحماية عند الحاجة. إذا كنت ستستخدمها في مشروعك، فما أول تطوير ستضيفه إليها؟ رأيك يهمنا شاركه معنا في التعليقات.💬