صِوان مِحور الابعاد الثلاث XYZ

حل مشكلة MongoServerError: unknown operator: $expr في MongoDB 6.10.0

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 5 Oct 2026 10:27:50 GMT

شفافية المحتوى: تم توليد وتنسيق هذا المقال آلياً عبر محرك صِوان AI لتقديم محتوى تقني دقيق، مباشر، وخالٍ من الحشو المزعج.

في هذا المقال، سنتناول مشكلة تقنية محددة قد تواجهها عند العمل مع MongoDB، وهي الخطأ "MongoServerError: unknown operator: $expr" على الرغم من استخدامك للإصدار 6.10.0. يعد عامل التشغيل $expr أداة قوية تسمح لك ببناء تعبيرات استعلام تستخدم تعبيرات التجميع داخل مرحلة $match، وقد تم تقديمه في MongoDB 3.6. لذا، فإن ظهوره كـ "عامل تشغيل غير معروف" في إصدار حديث مثل 6.10.0 أمر غير متوقع ويشير عادةً إلى مشكلة أساسية تحتاج إلى تشخيص دقيق.

فهم الخطأ: "unknown operator: $expr"

يحدث الخطأ "MongoServerError: unknown operator: $expr" عندما يحاول خادم MongoDB معالجة استعلام يتضمن عامل التشغيل $expr، لكنه يفشل في التعرف عليه. في الظروف العادية، يجب أن يتعرف MongoDB 6.10.0 على هذا العامل دون أي مشاكل، حيث إنه مدعوم منذ سنوات عديدة. هذا التناقض هو ما يجعل هذا الخطأ محيرًا ويستدعي فحصًا منهجيًا.

معلومة!
يسمح عامل التشغيل $expr باستخدام تعبيرات التجميع (aggregation expressions) مباشرة داخل مرحلة $match، مما يتيح لك مقارنة الحقول داخل نفس المستند أو إجراء عمليات حسابية معقدة كجزء من معايير التصفية.

الأسباب المحتملة للخطأ

على الرغم من أن MongoDB 6.10.0 يدعم $expr، إلا أن هناك عدة أسباب محتملة لظهور هذا الخطأ:

إصدار MongoDB غير صحيح أو قديم

هذا هو السبب الأكثر شيوعًا. قد تعتقد أنك متصل بإصدار 6.10.0، ولكنك في الواقع متصل بمثيل MongoDB أقدم لا يدعم $expr (أي إصدار أقدم من 3.6). يمكن أن يحدث هذا بسبب:

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

أخطاء في الصياغة أو الاستخدام

على الرغم من أن الخطأ يشير إلى "عامل تشغيل غير معروف"، إلا أن أخطاء الصياغة الدقيقة يمكن أن تؤدي أحيانًا إلى رسائل خطأ مضللة. تأكد من أن $expr مستخدم بشكل صحيح ضمن سياق استعلام التجميع (aggregation pipeline).

برامج التشغيل أو العملاء القديمة

في حالات نادرة جدًا، قد لا يقوم برنامج تشغيل MongoDB (مثل برنامج تشغيل Node.js أو Python) أو أداة العميل (مثل mongosh) بإرسال الاستعلام بشكل صحيح إلى الخادم إذا كان قديمًا جدًا ولا يدعم ميزات الإصدارات الأحدث. ومع ذلك، فإن هذا أقل احتمالًا بكثير من مشكلة إصدار الخادم.

عدم اتساق في مجموعة النسخ المتماثلة/المجزأة

إذا كنت تعمل في بيئة مجموعة نسخ متماثلة (replica set) أو مجموعة مجزأة (sharded cluster)، فقد تكون بعض العقد (nodes) تعمل بإصدار أقدم من MongoDB، بينما تعتقد أن المجموعة بأكملها تعمل بالإصدار 6.10.0. يمكن أن يؤدي الاستعلام الذي يصل إلى عقدة قديمة إلى هذا الخطأ.

حلول عملية ومباشرة

التحقق من إصدار MongoDB الفعلي

هذه هي الخطوة الأكثر أهمية. يجب عليك التحقق من الإصدار الفعلي لمثيل MongoDB الذي تتصل به.

اتصل بمثيل MongoDB باستخدام mongosh أو برنامج تشغيل العميل الخاص بك.
نفّذ الأمر التالي للتحقق من إصدار الخادم:

db.version()

يجب أن تكون النتيجة مشابهة لما يلي:

"6.0.10" // إذا رأيت إصدارًا أقل من 3.6، فهذا هو السبب.
// إذا رأيت "6.0.10" أو أعلى، فالمشكلة ليست في إصدار الخادم.

بالإضافة إلى ذلك، يمكنك التحقق من featureCompatibilityVersion، والذي يحدد مجموعة الميزات المتوافقة مع الإصدار:

db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })

يجب أن يكون الإخراج مشابهًا لـ { "featureCompatibilityVersion" : { "version" : "6.0" }, "ok" : 1 } أو أعلى. إذا كان الإصدار أقل من 3.6، فهذا يؤكد أنك متصل بمثيل قديم.

نصيحة!
إذا وجدت أنك متصل بإصدار قديم، فتأكد من إيقاف تشغيل جميع مثيلات mongod القديمة وبدء تشغيل المثيل الصحيح (6.10.0) أو الاتصال بالخادم الصحيح.

مراجعة صياغة الاستعلام

تأكد من أن استخدامك لـ $expr صحيح ضمن مرحلة $match في استعلام التجميع. إليك مثال على الاستخدام الصحيح:

db.collection.aggregate([
  {
    $match: {
      $expr: {
        $gt: [ "$fieldA", "$fieldB" ] // مقارنة قيم حقلين داخل نفس المستند
      }
    }
  }
])

في هذا المثال، يقوم $expr بتضمين تعبير تجميع $gt (أكبر من) لمقارنة قيم fieldA و fieldB.

تحديث برنامج تشغيل MongoDB

إذا كنت قد تأكدت من أن خادم MongoDB يعمل بالإصدار 6.10.0، ولكن المشكلة لا تزال قائمة، ففكر في تحديث برنامج تشغيل MongoDB الخاص بلغتك البرمجية إلى أحدث إصدار مستقر. على سبيل المثال:

Node.js: npm update mongodb
Python: pip install --upgrade pymongo
Java: تحديث التبعية في ملف pom.xml أو build.gradle.

ضمان توحيد إصدارات العقد

إذا كنت تعمل مع مجموعة نسخ متماثلة أو مجموعة مجزأة، تأكد من أن جميع أعضاء المجموعة يعملون بالإصدار 6.10.0. يمكنك التحقق من إصدار كل عضو عن طريق الاتصال به بشكل فردي وتشغيل db.version(). إذا كانت هناك أي عقدة قديمة، فستحتاج إلى ترقيتها.

تحذير!
يجب أن يتم ترقية مجموعات النسخ المتماثلة والمجموعات المجزأة بعناية فائقة ووفقًا لإرشادات ترقية MongoDB الرسمية لتجنب فقدان البيانات أو تعطل الخدمة.

الأسئلة الشائعة

ما هو عامل التشغيل $expr وما فائدته؟

عامل التشغيل $expr في MongoDB يسمح لك باستخدام تعبيرات التجميع (aggregation expressions) داخل مرحلة $match. فائدته الرئيسية هي تمكين الاستعلامات المعقدة التي تتطلب مقارنة حقول داخل نفس المستند، أو إجراء عمليات حسابية، أو استخدام منطق شرطي كجزء من معايير التصفية، مما يوفر مرونة كبيرة في الاستعلامات.

لماذا قد يظهر خطأ "unknown operator: $expr" في إصدار حديث مثل 6.10.0؟

على الرغم من أن $expr مدعوم منذ MongoDB 3.6، فإن ظهوره كـ "عامل تشغيل غير معروف" في الإصدار 6.10.0 يشير غالبًا إلى أنك متصل عن طريق الخطأ بمثيل MongoDB أقدم من 3.6. الأسباب الشائعة تشمل تشغيل مثيلات متعددة من MongoDB، أو الاتصال بالخادم الخطأ، أو عدم اتساق الإصدارات في مجموعة النسخ المتماثلة/المجزأة. من الضروري التحقق من الإصدار الفعلي للخادم الذي تتصل به.

في الختام، على الرغم من أن الخطأ "MongoServerError: unknown operator: $expr" قد يبدو محيرًا في MongoDB 6.10.0، إلا أن الحل يكمن دائمًا تقريبًا في التحقق من الإصدار الفعلي لمثيل MongoDB الذي تتصل به. بمجرد التأكد من أنك تعمل على الإصدار الصحيح وأن صياغة الاستعلام دقيقة، يجب أن يتم حل المشكلة.

المشاركات ذات الصلة

المقال الأصلي:
حل مشكلة MongoServerError: unknown operator: $expr في MongoDB 6.10.0
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

إتقان سطر الأوامر: دليلك الشامل لأوامر Git Bash

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 28 Sep 2026 10:27:49 GMT

يُعد Git Bash أداة قوية وضرورية للمطورين، حيث يوفر بيئة سطر أوامر شبيهة بـ Unix على أنظمة التشغيل Windows، مما يتيح التفاعل الفعال مع نظام التحكم بالإصدار Git. يركز هذا المقال على تقديم حلول عملية لأوامر Git Bash الأكثر استخدامًا، مع التركيز على الدقة والوضوح.

ما هو Git Bash؟

Git Bash هو تطبيق يوفر طبقة محاكاة لـ Bash (Bourne Again SHell) لتشغيل أوامر Git على نظام Windows. يشتمل على Git نفسه، بالإضافة إلى أدوات مساعدة أخرى مثل SSH و SCP، مما يجعله بيئة متكاملة لإدارة مشاريعك البرمجية والتعامل مع المستودعات المحلية والبعيدة.

تهيئة Git والإعدادات الأولية

قبل البدء في استخدام Git، من الضروري تهيئة اسم المستخدم والبريد الإلكتروني الخاص بك. هذه المعلومات ستظهر في جميع التزاماتك (commits).

تعيين اسم المستخدم:

git config --global user.name "اسمك هنا"

تعيين البريد الإلكتروني:

git config --global user.email "بريدك_الإلكتروني@مثال.كوم"

التحقق من الإعدادات:
```
git config --list
```

أوامر Git الأساسية

إنشاء مستودع جديد

لتحويل مجلد مشروعك إلى مستودع Git، استخدم الأمر git init. هذا ينشئ مجلد .git مخفيًا يحتوي على جميع البيانات اللازمة لتتبع التغييرات.

git init

إضافة الملفات والالتزام بالتغييرات

بعد إجراء التغييرات على ملفاتك، تحتاج إلى "إضافة" هذه التغييرات إلى منطقة التجهيز (staging area) ثم "الالتزام" بها (commit) لتسجيلها في سجل Git.

إضافة ملف واحد:
```
git add اسم_الملف.txt
```
إضافة جميع الملفات المعدلة:
```
git add .
```
الالتزام بالتغييرات:
```
git commit -m "رسالة وصفية للالتزام"
```
معلومة!
يجب أن تكون رسالة الالتزام واضحة وموجزة لتصف التغييرات التي تم إجراؤها.

التحقق من الحالة والسجل

لمعرفة حالة مستودعك وسجل التغييرات، استخدم الأوامر التالية:

عرض حالة المستودع: يظهر الملفات المعدلة، المضافة للتجهيز، وغير المتتبعة.
```
git status
```
عرض سجل الالتزامات: يعرض قائمة بالالتزامات السابقة، مع معرف الالتزام، المؤلف، التاريخ، والرسالة.
```
git log
```
لعرض سجل مختصر، استخدم git log --oneline.

التعامل مع المستودعات البعيدة

تتيح لك هذه الأوامر التفاعل مع المستودعات المستضافة على منصات مثل GitHub أو GitLab.

استنساخ مستودع بعيد

لنسخ مستودع موجود من خادم بعيد إلى جهازك المحلي:

git clone <URL_المستودع>

مثال:
git clone https://github.com/user/repo.git

إضافة مستودع بعيد

إذا كان لديك مستودع محلي وترغب في ربطه بمستودع بعيد:

git remote add origin <URL_المستودع>

معلومة!
"origin" هو الاسم التقليدي للمستودع البعيد الرئيسي.

دفع وسحب التغييرات

لتبادل التغييرات بين مستودعك المحلي والمستودع البعيد:

دفع التغييرات (Push): لإرسال التزاماتك المحلية إلى المستودع البعيد.
```
git push -u origin main
```
الخيار -u (أو --set-upstream) يربط الفرع المحلي بالفرع البعيد، مما يسمح لك باستخدام git push و git pull لاحقًا بدون تحديد origin main.
سحب التغييرات (Pull): لجلب التغييرات من المستودع البعيد ودمجها في فرعك المحلي.
```
git pull origin main
```

الفروع والدمج (Branching & Merging)

تعتبر الفروع ميزة أساسية في Git تسمح للمطورين بالعمل على ميزات جديدة أو إصلاح الأخطاء بشكل مستقل عن الفرع الرئيسي للمشروع.

إنشاء وتبديل الفروع

إنشاء فرع جديد:

git branch اسم_الفرع_الجديد

التبديل إلى فرع:
```
git checkout اسم_الفرع
```
إنشاء وتبديل في خطوة واحدة:
```
git checkout -b اسم_الفرع_الجديد
```
عرض الفروع:
```
git branch
```
الفرع الحالي يظهر بعلامة نجمة.

دمج الفروع

بعد الانتهاء من العمل على فرع، يمكنك دمجه مرة أخرى في الفرع الرئيسي (أو أي فرع آخر).

التبديل إلى الفرع الهدف: (مثلاً، الفرع الرئيسي main)
```
git checkout main
```
دمج الفرع الآخر:
```
git merge اسم_الفرع_للمزج
```
تحذير!
قد تحدث تعارضات دمج (merge conflicts) إذا كانت هناك تغييرات متضاربة في نفس الأسطر من الملفات. يجب حل هذه التعارضات يدويًا قبل إتمام الدمج.
حذف الفرع بعد الدمج: (اختياري)
```
git branch -d اسم_الفرع_للحذف
```

أوامر إضافية مفيدة

هذه بعض الأوامر التي قد تحتاجها في سيناريوهات مختلفة:

التراجع عن التغييرات المحلية (قبل الالتزام):
```
git restore اسم_الملف
```
للتراجع عن جميع التغييرات في المجلد الحالي (غير الملتزم بها): git restore .
إلغاء التجهيز (Unstaging) لملف:
```
git restore --staged اسم_الملف
```
التراجع عن آخر التزام (Soft Reset):
```
git reset --soft HEAD~1
```
هذا يعيد الفرع إلى الالتزام السابق، مع الاحتفاظ بالتغييرات في منطقة التجهيز.
التراجع عن آخر التزام (Hard Reset):
```
git reset --hard HEAD~1
```
تحذير!
هذا الأمر خطير لأنه يحذف جميع التغييرات غير الملتزم بها ويعيد المستودع إلى حالة الالتزام المحدد. استخدمه بحذر شديد.

ما الفرق بين Git Bash و Git GUI؟

Git Bash هو واجهة سطر أوامر (CLI) تتيح لك تنفيذ أوامر Git مباشرة. بينما Git GUI هو واجهة رسومية للمستخدم (GUI) توفر طريقة مرئية للتفاعل مع Git، مما قد يكون أسهل للمبتدئين ولكنه أقل مرونة وقوة من سطر الأوامر.

كيف أحل تعارضات الدمج (Merge Conflicts)؟

عند حدوث تعارض، سيقوم Git بوضع علامات خاصة في الملفات المتعارضة (<<<<<<<، =======، >>>>>>>). يجب عليك فتح هذه الملفات يدويًا، وحذف العلامات، واختيار الإصدار الصحيح من الكود، ثم حفظ الملفات، وإضافتها مرة أخرى إلى منطقة التجهيز (git add .)، وأخيرًا الالتزام بالدمج (git commit).

هل يمكنني استخدام Git Bash مع أي مستودع Git بعيد؟

نعم، يمكن لـ Git Bash التفاعل مع أي مستودع Git بعيد، سواء كان مستضافًا على GitHub، GitLab، Bitbucket، أو حتى خادم Git خاص بك، طالما أن لديك الأذونات اللازمة (عادةً عبر SSH أو HTTPS).

يُعد إتقان أوامر Git Bash أمرًا بالغ الأهمية لأي مطور يسعى لتحسين سير عمله والتحكم الكامل في مشاريع البرمجيات. من خلال هذه الأوامر الأساسية والمتقدمة، يمكنك إدارة مستودعاتك بفعالية، التعاون مع الفرق، والحفاظ على سجل نظيف لتغييراتك.

المشاركات ذات الصلة

المقال الأصلي:
إتقان سطر الأوامر: دليلك الشامل لأوامر Git Bash
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

احتراف SVG: دليل شامل لأحدث التطورات والتقنيات

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 21 Sep 2026 10:28:07 GMT

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

ما هو SVG ولماذا هو مهم؟

SVG (Scalable Vector Graphics) هو تنسيق صور قائم على XML لرسومات ثنائية الأبعاد يدعم التفاعل والرسوم المتحركة. على عكس الصور النقطية (مثل JPEG و PNG)، لا تعتمد رسومات SVG على البكسلات، مما يعني أنها يمكن أن تتوسع إلى أي حجم دون فقدان الجودة. هذه الميزة تجعلها مثالية لتصميم الويب المتجاوب (Responsive Web Design) وتطبيقات الأجهزة المحمولة.

تشمل المزايا الرئيسية لـ SVG ما يلي:

المرونة في التوسع: يمكن تغيير حجمها دون تشويه.
حجم ملف صغير: غالباً ما تكون ملفات SVG أصغر من نظيراتها النقطية.
قابلة للتحرير: يمكن تحريرها باستخدام أي محرر نصوص أو برامج رسوميات متجهة.
قابلة للبحث والفهرسة: محتواها نصي، مما يجعلها قابلة للبحث بواسطة محركات البحث.
قابلة للتحريك والتفاعل: يمكن تحريكها وتعديلها باستخدام CSS و JavaScript.

احتراف SVG: المفاهيم الأساسية

لتبدأ في احتراف SVG، يجب فهم العناصر الأساسية التي تشكل أي رسم SVG.

الأشكال الأساسية والمسارات

تتكون رسومات SVG من مجموعة من الأشكال الهندسية البسيطة والمسارات المعقدة:

<rect>: لإنشاء مستطيلات ومربعات.
<circle>: لإنشاء دوائر.
<ellipse>: لإنشاء أشكال بيضاوية.
<line>: لإنشاء خطوط مستقيمة.
<polyline>: لإنشاء سلسلة من الخطوط المتصلة.
<polygon>: لإنشاء أشكال مغلقة متعددة الأضلاع.
<path>: العنصر الأكثر قوة، يسمح بإنشاء أي شكل معقد باستخدام أوامر مثل M (move to)، L (line to)، C (cubic Bezier curve)، Z (close path).

<svg width="200" height="200">
  <path d="M10 10 L100 10 L100 100 L10 100 Z" fill="blue" stroke="black" stroke-width="3"/>
</svg>

التحويلات والتجميعات

يمكن تطبيق التحويلات (مثل الترجمة، الدوران، التحجيم، الانحراف) على عناصر SVG باستخدام السمة transform. لتطبيق تحويلات متعددة أو تجميع عناصر معاً، يُستخدم العنصر <g> (group).

<svg width="200" height="200">
  <g transform="translate(50,50) rotate(45)">
    <rect x="0" y="0" width="50" height="50" fill="red"/>
  </g>
</svg>

التدرجات والأنماط

يمكن استخدام التدرجات اللونية (<linearGradient> و <radialGradient>) والأنماط (<pattern>) لملء الأشكال بخلفيات أكثر تعقيداً وجاذبية.

النصوص والخطوط

يسمح عنصر <text> بإضافة نصوص إلى رسومات SVG، ويمكن التحكم في خصائص الخط (مثل الحجم واللون والنمط) باستخدام CSS. يمكن استخدام <tspan> لتنسيق أجزاء معينة من النص.

تقنيات SVG المتقدمة

بعد إتقان الأساسيات، يمكن للمطورين استكشاف تقنيات أكثر تقدماً لإنشاء رسومات SVG ديناميكية وتفاعلية.

تنسيق SVG باستخدام CSS

يمكن تنسيق عناصر SVG بالكامل باستخدام CSS، تماماً مثل عناصر HTML. يمكن التحكم في خصائص مثل fill (لون التعبئة)، stroke (لون الحدود)، stroke-width (عرض الحدود)، وحتى transform و opacity.

rect {
  fill: #3498db;
  stroke: #2980b9;
  stroke-width: 2px;
  transition: fill 0.3s ease;
}
rect:hover {
  fill: #e74c3c;
}

معالجة SVG باستخدام JavaScript

يمكن لـ JavaScript التفاعل مع رسومات SVG عن طريق معالجة نموذج كائن المستند (DOM) الخاص بها. يتيح ذلك إنشاء رسوم متحركة ديناميكية، وتغيير الخصائص بناءً على تفاعلات المستخدم، وحتى إنشاء رسومات SVG بالكامل برمجياً. مكتبات مثل GSAP و D3.js تسهل هذه العملية بشكل كبير.

الفلاتر وأقنعة القص (Clipping Paths)

الفلاتر (<filter>): تسمح بتطبيق تأثيرات بصرية معقدة مثل الظلال، الضبابية، وتغيير الألوان. يتم تعريف الفلاتر داخل عنصر <defs> ثم يتم تطبيقها باستخدام السمة filter.
أقنعة القص (<clipPath>): تُستخدم لقص جزء من الرسم، مما يظهر فقط الأجزاء التي تقع داخل شكل محدد.

أحدث التطورات في SVG

تستمر تقنيات الويب في التطور، و SVG ليست استثناءً. إليك بعض أحدث التطورات التي يجب على المحترفين معرفتها:

رسوم SVG المتحركة و Web Animations API (WAAPI)

بينما يمكن استخدام CSS و JavaScript لإنشاء رسوم متحركة لـ SVG، فإن Web Animations API (WAAPI) يوفر طريقة أكثر قوة ومرونة لإنشاء الرسوم المتحركة المعقدة والمزامنة مباشرة في المتصفح. إنه يجمع بين قوة الرسوم المتحركة المستندة إلى CSS والتحكم الدقيق في JavaScript.

إمكانية الوصول (Accessibility) في SVG

أصبحت إمكانية الوصول جزءاً لا يتجزأ من تطوير الويب. لضمان أن تكون رسومات SVG سهلة الاستخدام للجميع، بما في ذلك مستخدمي برامج قراءة الشاشة، يجب استخدام العناصر والسمات التالية:

<title>: يوفر عنواناً وصفياً للرسم.
<desc>: يوفر وصفاً أطول وأكثر تفصيلاً.
سمات ARIA: مثل aria-labelledby و role="img" لربط SVG بالنص البديل.

SVG في مكونات الويب (Web Components)

تتيح مكونات الويب (Custom Elements, Shadow DOM) تغليف رسومات SVG المعقدة ومنطقها التفاعلي في مكونات قابلة لإعادة الاستخدام. هذا يعزز قابلية الصيانة ويقلل من تكرار الكود، مما يجعل إدارة المشاريع الكبيرة أسهل.

SVG و WebAssembly (WASM)

على الرغم من أن SVG يتم تحليله وعرضه بواسطة المتصفح، إلا أن هناك اهتماماً متزايداً باستخدام WebAssembly (WASM) لتقديم رسومات SVG المعقدة أو عمليات المعالجة الثقيلة. يمكن أن يؤدي ذلك إلى تحسينات كبيرة في الأداء لتطبيقات الويب التي تعتمد بشكل كبير على رسومات SVG الديناميكية والمعقدة.

نصائح عملية لاحتراف SVG

ابدأ بالأساسيات: تأكد من فهمك العميق للأشكال الأساسية والمسارات وكيفية عملها.
استخدم محررات الرسوم المتجهة: برامج مثل Inkscape (مجاني) أو Adobe Illustrator يمكن أن تساعدك في إنشاء رسومات SVG معقدة وتصديرها.
تحسين ملفات SVG: استخدم أدوات مثل SVGO لتقليل حجم ملفات SVG عن طريق إزالة البيانات غير الضرورية.
تعلم CSS لتنسيق SVG: إتقان تنسيق SVG باستخدام CSS يفتح لك عالماً من الإمكانيات الجمالية والتفاعلية.
استكشف JavaScript للتفاعل: تعلم كيفية معالجة SVG DOM باستخدام JavaScript لإنشاء رسوم متحركة وتفاعلات مخصصة.
ركز على إمكانية الوصول: اجعل رسومات SVG الخاصة بك متاحة للجميع من خلال استخدام السمات المناسبة.
ابقَ على اطلاع: تابع أحدث مواصفات SVG وتطورات الويب لتبقى في طليعة التقنيات.

معلومة!
يمكن تضمين SVG مباشرة في HTML باستخدام وسم <svg>، أو كملف خارجي باستخدام وسم <img>، أو كصورة خلفية في CSS. كل طريقة لها مزاياها وعيوبها.

ما الفرق الرئيسي بين SVG والصور النقطية؟

الفرق الرئيسي هو أن SVG رسومات متجهة تعتمد على المعادلات الرياضية، مما يسمح بتغيير حجمها دون فقدان الجودة. بينما الصور النقطية (مثل PNG و JPEG) تعتمد على البكسلات، وتفقد جودتها عند التكبير.

هل يمكن تحريك SVG باستخدام CSS فقط؟

نعم، يمكن تحريك SVG باستخدام خصائص CSS مثل transform و transition و animation. ومع ذلك، قد تكون الرسوم المتحركة الأكثر تعقيداً أو التفاعلية أسهل في التنفيذ باستخدام JavaScript أو Web Animations API.

المشاركات ذات الصلة

المقال الأصلي:
احتراف SVG: دليل شامل لأحدث التطورات والتقنيات
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

ربط Scroll-Timeline المشروط ضمن استعلامات حاويات CSS

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 14 Sep 2026 10:27:43 +0100

في عالم تطوير الويب الحديث، أصبحت القدرة على إنشاء تجارب مستخدم ديناميكية ومتجاوبة أمراً حاسماً. مع ظهور استعلامات حاويات CSS (CSS Container Queries) و Scroll-Timeline، أصبح لدى المطورين أدوات قوية لتحقيق ذلك. ومع ذلك، فإن الجمع بين هاتين التقنيتين لإنشاء ربط مشروط للـ Scroll-Timeline بناءً على سياق الحاوية يتطلب فهماً دقيقاً وتطبيقاً ذكياً. يهدف هذا المقال إلى استكشاف هذا التحدي وتقديم حلول عملية.

ما هي استعلامات حاويات CSS؟

تُعد استعلامات حاويات CSS ثورة في تصميم الويب المتجاوب، حيث تسمح للمطورين بتطبيق الأنماط بناءً على حجم أو خصائص الحاوية الأصلية للعنصر، بدلاً من حجم منفذ العرض (viewport) بالكامل. هذا يمنح مرونة غير مسبوقة في تصميم المكونات المستقلة التي تتكيف مع سياقها الخاص.

.card-container {
  container-type: inline-size;
  container-name: card;
}

@container card (min-width: 400px) {
  .card-title {
    font-size: 1.5rem;
  }
  .card-image {
    display: block;
  }
}

معلومة!
تُمكن container-type و container-name العنصر من أن يصبح حاوية استعلام، مما يتيح للعناصر الداخلية الاستجابة لتغييراته.

فهم Scroll-Timeline

تُمكن Scroll-Timeline المطورين من ربط الرسوم المتحركة بتقدم التمرير، مما يفتح الباب أمام تأثيرات تمرير جذابة وسلسة. بدلاً من الاعتماد على التوقيت المستند إلى الوقت، يمكن للرسوم المتحركة أن تبدأ وتتوقف وتتغير سرعتها بناءً على موضع التمرير لعنصر معين أو للمستند بأكمله.

.animated-element {
  animation: fade-in linear forwards;
  animation-timeline: scroll(root); /* أو scroll(self) */
  animation-range: entry 0% cover 50%;
}

@keyframes fade-in {
  from { opacity: 0; transform: translateY(20px); }
  to { opacity: 1; transform: translateY(0); }
}

التحدي: الربط المشروط

يكمن التحدي في دمج Scroll-Timeline مع استعلامات الحاويات في أن خصائص Scroll-Timeline (مثل animation-timeline و animation-range) تُطبق عادةً بشكل مباشر على العناصر، بينما تُحدد استعلامات الحاويات الأنماط بناءً على سياق الحاوية. قد نرغب في تفعيل تأثير تمرير معين فقط عندما تكون الحاوية كبيرة بما يكفي، أو تعطيله عندما تكون صغيرة لتجنب تشتيت المستخدم أو لتبسيط التجربة.

لا توجد آلية مدمجة مباشرة في CSS تسمح بتفعيل أو تعطيل animation-timeline بشكل مشروط ضمن @container. هذا يتطلب نهجاً غير مباشر.

حلول عملية للربط المشروط

الطريقة الأولى: الاستفادة من متغيرات CSS

تُعد متغيرات CSS (Custom Properties) أداة قوية لتمرير القيم ديناميكياً عبر CSS. يمكننا استخدامها لتعيين قيم Scroll-Timeline بشكل مشروط داخل استعلامات الحاويات، ثم استخدام هذه المتغيرات في تعريف الرسوم المتحركة.

.scroll-container {
  container-type: inline-size;
  container-name: my-container;
  /* القيم الافتراضية أو المعطلة */
  --scroll-timeline-name: none;
  --scroll-timeline-range: auto;
}

@container my-container (min-width: 600px) {
  /* تفعيل Scroll-Timeline عند استيفاء الشرط */
  --scroll-timeline-name: scroll(self);
  --scroll-timeline-range: entry 0% cover 50%;
}

.animated-item {
  animation: slide-in linear forwards;
  animation-timeline: var(--scroll-timeline-name);
  animation-range: var(--scroll-timeline-range);
}

@keyframes slide-in {
  from { transform: translateX(-100%); opacity: 0; }
  to { transform: translateX(0); opacity: 1; }
}

في هذا المثال، يتم تعيين --scroll-timeline-name و --scroll-timeline-range إلى قيم "معطلة" (none و auto) بشكل افتراضي. عند استيفاء شرط @container، يتم تحديث هذه المتغيرات بقيم Scroll-Timeline المرغوبة، مما يؤدي إلى تفعيل الرسوم المتحركة.

الطريقة الثانية: التطبيق المشروط للأنماط الكاملة

بدلاً من استخدام المتغيرات، يمكننا تطبيق خصائص Scroll-Timeline بأكملها مباشرة داخل كتلة @container. هذا النهج أكثر وضوحاً في بعض الحالات.

.scroll-container {
  container-type: inline-size;
  container-name: my-container;
}

.animated-item {
  /* الأنماط الأساسية */
  opacity: 0; /* مخفي افتراضياً */
  transform: translateY(20px);
  transition: opacity 0.3s, transform 0.3s; /* انتقال سلس عند عدم وجود Scroll-Timeline */
}

@container my-container (min-width: 700px) {
  .animated-item {
    animation: fade-up linear forwards;
    animation-timeline: scroll(self);
    animation-range: entry 0% cover 50%;
    /* إلغاء الانتقال اليدوي عند تفعيل Scroll-Timeline */
    transition: none;
  }
}

@keyframes fade-up {
  from { opacity: 0; transform: translateY(20px); }
  to { opacity: 1; transform: translateY(0); }
}

هنا، يتم تطبيق الرسوم المتحركة المستندة إلى التمرير فقط عندما تكون الحاوية أكبر من 700 بكسل. عندما تكون الحاوية أصغر، قد نختار إما إخفاء العنصر، أو تطبيق انتقال CSS بسيط، أو عرضه بدون أي تأثير تمرير.

اعتبارات وأفضل الممارسات

الأداء: تأكد من أن الرسوم المتحركة خفيفة ولا تسبب مشاكل في الأداء، خاصة على الأجهزة الأقل قوة. اختبر على نطاق واسع.
إمكانية الوصول: توفير بدائل للرسوم المتحركة أو تعطيلها للمستخدمين الذين يفضلون تقليل الحركة (باستخدام @media (prefers-reduced-motion)).
الدعم المتصفح: تحقق من دعم المتصفحات لكل من استعلامات الحاويات و Scroll-Timeline. قد تحتاج إلى استخدام polyfills أو تقديم تجارب بديلة للمتصفحات القديمة.
التعقيد: تجنب الإفراط في تعقيد المنطق. كلما كان الحل أبسط، كان أسهل في الصيانة والتصحيح.

نصيحة: عند استخدام scroll(self)، تأكد من أن العنصر الذي يتم تطبيق الرسوم المتحركة عليه هو نفسه الذي يمكن التمرير فيه، أو أن لديه سلفاً قابلاً للتمرير لكي يعمل الـ timeline بشكل صحيح.

هل يمكنني استخدام JavaScript للتحكم في ربط Scroll-Timeline المشروط؟

نعم، يمكن استخدام JavaScript لإضافة أو إزالة فئات CSS التي تحتوي على خصائص Scroll-Timeline بناءً على حجم الحاوية أو أي منطق آخر. ومع ذلك، فإن الحلول المستندة إلى CSS (مثل متغيرات CSS أو @container مباشرة) تُفضل عادةً للبساطة والأداء عندما يكون ذلك ممكناً.

ما هو الفرق بين scroll(root) و scroll(self)؟

scroll(root) يربط الرسوم المتحركة بتقدم التمرير للمستند بأكمله (عادةً <html> أو <body>). بينما scroll(self) يربط الرسوم المتحركة بتقدم التمرير للعنصر نفسه أو أقرب سلف قابل للتمرير له. هذا الأخير مفيد جداً للمكونات المعزولة.

المشاركات ذات الصلة

المقال الأصلي:
ربط Scroll-Timeline المشروط ضمن استعلامات حاويات CSS
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

حل مشكلة req.body غير المعرف في Express.js

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 31 Aug 2026 10:27:45 +0100

تعرف على الأسباب الشائعة لكون req.body غير معرف في Express.js وكيفية استخدام express.json() و express.urlencoded() لحل المشكلة بفعالية.

في تطوير تطبيقات الويب باستخدام Express.js، قد تواجه مشكلة شائعة حيث تجد أن الكائن req.body غير معرف (undefined) عند محاولة الوصول إلى البيانات المرسلة في جسم الطلب (request body). تحدث هذه المشكلة عادةً عندما لا يقوم Express بمعالجة أو تحليل جسم الطلب بشكل صحيح. يهدف هذا المقال إلى تقديم حلول عملية ومباشرة لهذه المشكلة.

لماذا يكون `req.body` غير معرف؟

بشكل افتراضي، لا يقوم Express.js بتحليل جسم الطلب القادم من العميل. هذا يعني أنه إذا أرسل العميل بيانات بتنسيق JSON أو URL-encoded أو أي تنسيق آخر في جسم الطلب، فإن Express لن يتعرف عليها تلقائيًا ولن يملأ الكائن req.body بها. للوصول إلى هذه البيانات، يجب عليك استخدام middleware مخصص لتحليل جسم الطلب.

الحل: استخدام الـ Middleware المدمج في Express

الحل الأكثر شيوعًا وفعالية لهذه المشكلة هو استخدام الـ middleware المدمج في Express لتحليل جسم الطلب. Express يوفر دوال مساعدة لهذا الغرض:

express.json(): لتحليل الطلبات ذات الرأس Content-Type: application/json.
express.urlencoded(): لتحليل الطلبات ذات الرأس Content-Type: application/x-www-form-urlencoded.

تطبيق `express.json()`

إذا كان تطبيقك يتلقى بيانات بتنسيق JSON (وهو الشائع في واجهات برمجة التطبيقات RESTful)، فيجب عليك استخدام express.json(). قم بإضافته كـ middleware على مستوى التطبيق (global middleware) قبل تعريف مساراتك (routes).

const express = require('express');
const app = express();
const PORT = 3000;

// استخدام middleware لتحليل جسم الطلب بتنسيق JSON
app.use(express.json());

app.post('/api/data', (req, res) => {
  // الآن، req.body سيكون متاحًا إذا كان الطلب يحتوي على JSON
  const data = req.body;
  console.log('Received data:', data);

  if (!data || Object.keys(data).length === 0) {
    return res.status(400).send('No data provided in the request body.');
  }

  res.status(200).json({ message: 'Data received successfully!', yourData: data });
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

معلومة!
تأكد من أن العميل الذي يرسل الطلب يضبط رأس Content-Type إلى application/json. إذا لم يتم ضبطه بشكل صحيح، فلن يتمكن express.json() من تحليل الجسم.

تطبيق `express.urlencoded()`

إذا كنت تتعامل مع بيانات مرسلة من نماذج HTML التقليدية (مثل

) التي تستخدم ترميز URL (application/x-www-form-urlencoded)، فستحتاج إلى express.urlencoded().

const express = require('express');
const app = express();
const PORT = 3000;

// استخدام middleware لتحليل جسم الطلب بتنسيق URL-encoded
app.use(express.urlencoded({ extended: true }));

app.post('/submit-form', (req, res) => {
  // الآن، req.body سيكون متاحًا إذا كان الطلب يحتوي على بيانات URL-encoded
  const formData = req.body;
  console.log('Form data:', formData);

  if (!formData || Object.keys(formData).length === 0) {
    return res.status(400).send('No form data provided.');
  }

  res.status(200).send(`Thank you, ${formData.name}! Your email is ${formData.email}.`);
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

معلومة!
الخيار { extended: true } يسمح بتحليل الكائنات والجداول المتداخلة (nested objects and arrays) من بيانات URL-encoded. يوصى به بشكل عام.

ترتيب الـ Middleware مهم

من الأهمية بمكان أن تقوم بتسجيل middleware تحليل جسم الطلب (مثل express.json() أو express.urlencoded()) قبل أي مسارات (routes) أو middleware آخر يحاول الوصول إلى req.body. إذا قمت بتسجيله بعد المسار، فلن يتم تنفيذه للطلبات التي تصل إلى ذلك المسار، وسيظل req.body غير معرف.

const express = require('express');
const app = express();

// صحيح: middleware قبل المسار
app.use(express.json());

app.post('/data', (req, res) => {
  console.log(req.body); // سيعمل بشكل صحيح
  res.send('OK');
});

// خطأ: middleware بعد المسار
// app.post('/another-data', (req, res) => {
//   console.log(req.body); // سيكون undefined
//   res.send('OK');
// });
// app.use(express.json()); // هذا متأخر جدًا لهذا المسار

التحقق من رأس `Content-Type`

لكي يعمل middleware تحليل جسم الطلب بشكل صحيح، يجب أن يرسل العميل رأس Content-Type الصحيح في طلبه. على سبيل المثال:

لبيانات JSON: Content-Type: application/json
لبيانات URL-encoded: Content-Type: application/x-www-form-urlencoded

إذا كان رأس Content-Type مفقودًا أو غير صحيح، فلن يتمكن middleware من تحديد كيفية تحليل جسم الطلب، وسيظل req.body غير معرف.

نصيحة!
عند اختبار واجهة برمجة التطبيقات الخاصة بك باستخدام أدوات مثل Postman أو Insomnia أو cURL، تأكد دائمًا من ضبط رأس Content-Type بشكل صحيح بالإضافة إلى إرسال جسم الطلب.

استكشاف الأخطاء وإصلاحها

إذا كنت لا تزال تواجه مشكلة، جرب الخطوات التالية:

تحقق من الـ Middleware: تأكد من أنك قمت بتضمين app.use(express.json()); و/أو app.use(express.urlencoded({ extended: true })); في ملف التطبيق الرئيسي الخاص بك.
تحقق من الترتيب: تأكد من أن الـ middleware هذا يقع قبل أي مسارات تحاول الوصول إلى req.body.
تحقق من رأس Content-Type: استخدم أدوات المطور في المتصفح أو أدوات مثل Postman للتحقق من أن رأس Content-Type يتم إرساله بشكل صحيح من العميل.
سجل req بالكامل: قبل الوصول إلى req.body، قم بتسجيل الكائن req بالكامل أو req.headers و req.method و req.url للتحقق من أن الطلب يصل كما هو متوقع.

الخلاصة

مشكلة req.body غير المعرف في Express.js هي مشكلة شائعة ولكن حلها بسيط. من خلال فهم أن Express لا يقوم بتحليل جسم الطلب افتراضيًا واستخدام الـ middleware المناسب مثل express.json() و express.urlencoded()، يمكنك الوصول بسهولة إلى البيانات المرسلة من العميل. تذكر دائمًا أهمية ترتيب الـ middleware والتحقق من رأس Content-Type لضمان سير عمل سلس لتطبيقك.

هل أحتاج إلى تثبيت حزمة body-parser بشكل منفصل؟

لا، بدءًا من Express 4.16.0، تم تضمين وظائف body-parser (مثل json() و urlencoded()) مباشرة في Express نفسه. لذلك، لا تحتاج إلى تثبيت body-parser كحزمة منفصلة بعد الآن.

ماذا لو كنت أرسل بيانات متعددة الأجزاء (multipart/form-data)؟

إذا كنت ترسل بيانات متعددة الأجزاء (عادةً لرفع الملفات)، فإن express.json() و express.urlencoded() لن تكون كافية. ستحتاج إلى استخدام middleware متخصص مثل Multer لمعالجة هذا النوع من الطلبات.

المشاركات ذات الصلة

المقال الأصلي:
حل مشكلة req.body غير المعرف في Express.js
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

احتراف GitHub: دليلك الشامل لأحدث التطورات

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 7 Sep 2026 10:27:50 +0100

يُعد GitHub المنصة الرائدة عالميًا للتحكم في إصدار التعليمات البرمجية والتعاون بين المطورين. احترافه لم يعد خيارًا، بل ضرورة لكل مطور يسعى للتميز في عالم البرمجيات الحديث. يهدف هذا المقال إلى تقديم خارطة طريق عملية لاحتراف GitHub، مع تسليط الضوء على أبرز التطورات التي غيرت طريقة عملنا.

ما هو GitHub؟

GitHub هو خدمة استضافة لمستودعات Git، مبنية على نظام التحكم في الإصدار الموزع (Git). يسمح للمطورين بالتعاون في المشاريع من أي مكان في العالم، وتتبع التغييرات، وإدارة الإصدارات المختلفة للتعليمات البرمجية. إنه ليس مجرد مكان لتخزين الكود، بل هو نظام بيئي كامل يدعم دورة حياة تطوير البرمجيات.

المفاهيم الأساسية لاحتراف GitHub

لتبدأ رحلة الاحتراف، يجب أولاً فهم وتطبيق المفاهيم الأساسية لـ Git وGitHub:

المستودعات (Repositories)

المستودع هو المجلد الرئيسي لمشروعك، حيث يتم تخزين جميع ملفات المشروع وسجل التغييرات. تعلم كيفية إنشاء مستودعات جديدة (عامة وخاصة) واستنساخ (git clone) المستودعات الموجودة هو الخطوة الأولى.

git clone https://github.com/user/repo.git

الفروع (Branches)

الفروع تسمح لك بالعمل على ميزات جديدة أو إصلاح الأخطاء بمعزل عن الكود الرئيسي (main أو master). احتراف إدارة الفروع (إنشاء، التبديل، الدمج) أمر بالغ الأهمية لسير عمل فعال.

إنشاء فرع جديد: git branch feature-x
التبديل إلى الفرع: git checkout feature-x
إنشاء والتبديل مباشرة: git checkout -b feature-x

الالتزامات (Commits)

الالتزام هو لقطة للتغييرات التي أجريتها في نقطة زمنية معينة. اكتب رسائل التزام واضحة وموجزة تصف التغييرات بدقة. هذا يسهل تتبع تاريخ المشروع وفهم التغييرات لاحقًا.

git add .
git commit -m "أضف ميزة تسجيل الدخول"

طلبات السحب (Pull Requests - PRs)

طلبات السحب هي قلب التعاون في GitHub. تسمح لك باقتراح دمج التغييرات من فرعك إلى فرع آخر (عادةً main). تعلم كيفية إنشاء PRs فعالة، ومراجعة كود الآخرين، والتعامل مع التعليقات والتعديلات.

معلومة!
PRs ليست فقط لدمج الكود؛ إنها فرصة للمراجعة، المناقشة، وتحسين جودة الكود.

النسخ المتفرع (Forking)

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

أحدث التطورات والميزات المتقدمة في GitHub

للانتقال من مستوى المبتدئ إلى المحترف، يجب استكشاف واستخدام الميزات المتقدمة التي يقدمها GitHub:

GitHub Actions

تُعد GitHub Actions أداة قوية لأتمتة مهام سير العمل (CI/CD) مباشرة داخل مستودعك. يمكنك بناء، اختبار، ونشر تطبيقك تلقائيًا عند كل التزام أو طلب سحب. احترافها يقلل من الأخطاء البشرية ويسرع عملية التطوير.

name: CI/CD Pipeline

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '16'
    - name: Install dependencies
      run: npm install
    - name: Run tests
      run: npm test

GitHub Packages

تسمح لك GitHub Packages باستضافة حزم البرمجيات الخاصة بك (مثل npm، Maven، NuGet) مباشرة على GitHub. هذا يبسط إدارة التبعيات ويوفر حلاً موحدًا لاستضافة الكود والحزم.

GitHub Codespaces

Codespaces يوفر بيئة تطوير متكاملة (IDE) قائمة على السحابة، يمكن الوصول إليها مباشرة من متصفحك. يتيح لك بدء العمل على مشروعك في ثوانٍ، دون الحاجة إلى إعداد بيئة محلية معقدة. إنه يغير قواعد اللعبة للتعاون السريع والانضمام إلى المشاريع.

GitHub Copilot

مدعومًا بالذكاء الاصطناعي، يقدم Copilot اقتراحات للكود في الوقت الفعلي أثناء الكتابة. يمكنه تسريع عملية الترميز بشكل كبير، خاصة للمهام المتكررة أو عند العمل بلغات وأطر عمل جديدة. تعلم كيفية الاستفادة منه لتحسين إنتاجيتك.

ميزات الأمان المتقدمة

يقدم GitHub مجموعة من الأدوات لتعزيز أمان الكود، مثل Dependabot الذي يقوم بفحص التبعيات بحثًا عن الثغرات الأمنية وتحديثها تلقائيًا، وCode Scanning الذي يكتشف المشكلات الأمنية المحتملة في الكود الخاص بك.

خطوات عملية لاحتراف GitHub

الممارسة العملية المستمرة

لا يمكن احتراف GitHub بالقراءة فقط. قم بإنشاء مشاريع شخصية، جرب جميع الأوامر والميزات، وادفع الكود بانتظام. كلما زادت ممارستك، زادت ثقتك ومهارتك.

المساهمة في المشاريع مفتوحة المصدر

المساهمة في المشاريع مفتوحة المصدر هي أفضل طريقة لتطبيق ما تعلمته في بيئة حقيقية. ستتعلم كيفية العمل ضمن فرق، ومراجعة الكود، والتعامل مع سير عمل PRs المعقدة.

البقاء على اطلاع دائم

GitHub يتطور باستمرار. تابع المدونة الرسمية لـ GitHub، وحضر الندوات عبر الإنترنت، واقرأ عن الميزات الجديدة فور إطلاقها. هذا يضمن أنك دائمًا في طليعة التطورات.

نصيحة!
استخدم وثائق GitHub الرسمية كمصدر أساسي للتعلم. إنها شاملة ومحدثة باستمرار.

هل أحتاج إلى معرفة Git قبل استخدام GitHub؟

نعم، GitHub مبني على Git. فهم أساسيات Git (مثل الالتزامات، الفروع، الدمج) ضروري لاستخدام GitHub بفعالية.

ما الفرق بين GitHub و GitLab؟

كلاهما منصات لاستضافة مستودعات Git، لكن GitLab يركز بشكل أكبر على دورة حياة DevOps الكاملة، بما في ذلك CI/CD المدمج، في حين أن GitHub كان يركز تقليديًا على استضافة الكود والتعاون، ولكنه توسع بشكل كبير في DevOps مؤخرًا مع GitHub Actions وCodespaces.

المشاركات ذات الصلة

المقال الأصلي:
احتراف GitHub: دليلك الشامل لأحدث التطورات
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

تحويل وسم hr إلى تحفة فنية: دمج SVG المتكرر كفاصل مرئي

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 24 Aug 2026 10:28:00 +0100

في عالم تصميم الويب الحديث، لم يعد الاكتفاء بالعناصر الافتراضية للمتصفح خياراً جذاباً. عنصر <hr />، الذي يُستخدم تقليدياً لإنشاء فاصل أفقي، غالباً ما يفتقر إلى المرونة الجمالية. لحسن الحظ، توفر رسوم SVG (Scalable Vector Graphics) حلاً قوياً ومبتكراً لتحويل هذا الفاصل البسيط إلى عنصر تصميم جذاب ومتكرر، يتماشى مع هوية موقعك البصرية.

ما هو SVG ولماذا نستخدمه؟

SVG هو تنسيق صور قائم على XML للرسومات المتجهة ثنائية الأبعاد. على عكس الصور النقطية (مثل JPG أو PNG)، لا تفقد رسوم SVG جودتها عند تكبيرها أو تصغيرها، مما يجعلها مثالية للاستخدام في تصميم الويب سريع الاستجابة. عند استخدام SVG كفاصل مرئي، يمكننا تحقيق تصاميم معقدة وديناميكية لا يمكن تحقيقها بسهولة باستخدام CSS وحده أو صور نقطية.

معلومة!
يمكن تضمين رسوم SVG مباشرة في HTML أو CSS، مما يقلل من طلبات HTTP ويحسن أداء التحميل.

قيود
التقليدية والحاجة للبديل

بشكل افتراضي، يظهر عنصر <hr /> كخط أفقي رفيع، يختلف مظهره قليلاً بين المتصفحات. على الرغم من إمكانية تعديل بعض خصائصه الأساسية مثل اللون والارتفاع باستخدام CSS، إلا أن تحقيق أنماط معقدة أو متكررة يتطلب تجاوز قدراته المحدودة. هنا يأتي دور SVG لتقديم حلول تصميم لا نهائية، من الخطوط المتموجة إلى الأنماط الهندسية المتكررة.

تصميم SVG لفاصل مرئي متكرر

يكمن سر استخدام SVG كفاصل متكرر في إنشاء نمط صغير يمكن تكراره أفقياً (أو رأسياً). لنفترض أننا نريد إنشاء فاصل بنمط "نقاط متقطعة". يمكننا تصميم جزء صغير من هذا النمط في SVG.

<svg width="10" height="2" viewBox="0 0 10 2" xmlns="http://www.w3.org/2000/svg">
  <circle cx="1" cy="1" r="1" fill="#888" />
</svg>

في هذا المثال، أنشأنا SVG بعرض 10 بكسل وارتفاع 2 بكسل يحتوي على دائرة صغيرة. عند تكرار هذا النمط، سيبدو كخط من النقاط المتباعدة.

تطبيق SVG المتكرر كخلفية

لتحويل SVG إلى فاصل مرئي متكرر، سنستخدم خاصية background-image في CSS، مع تضمين SVG مباشرة كـ data:image/svg+xml. هذا يضمن أن المتصفح يقوم بتحميل SVG كصورة خلفية ويقوم بتكرارها.

خطوات التنفيذ العملي

الخطوة 1: إعداد عنصر <hr /> في HTML

نبدأ بعنصر <hr /> بسيط في ملف HTML الخاص بك:

<!DOCTYPE html>
<html lang="ar">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>SVG HR Example</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <h1>مقال حول SVG كفاصل <hr /></h1>
    <p>هذا نص قبل الفاصل.</p>
    <hr />
    <p>هذا نص بعد الفاصل.</p>
    <hr class="dots" />
    <p>فاصل بنقاط.</p>
    <hr class="wave" />
    <p>فاصل بموجة.</p>
</body>
</html>

الخطوة 2: تصميم SVG للنمط

سنستخدم نمطاً بسيطاً من الخطوط المائلة المتكررة. يمكن تحويل هذا SVG إلى تنسيق URL لسهولة تضمينه في CSS.
```
<svg width="10" height="10" viewBox="0 0 10 10" xmlns="http://www.w3.org/2000/svg">
  <line x1="0" y1="10" x2="10" y2="0" stroke="#ccc" stroke-width="1" />
</svg>
```
هذا النمط سيخلق خطوطاً مائلة متكررة. يمكن تعديل stroke و stroke-width لتغيير اللون والسماكة.

الخطوة 3: تطبيق CSS على <hr />

الآن، سنقوم بتطبيق النمط على عنصر <hr /> باستخدام CSS. سنقوم بإزالة الحدود الافتراضية وتعيين SVG كخلفية متكررة.

hr {
    border: none; /* إزالة الحدود الافتراضية */
    height: 10px; /* تحديد ارتفاع الفاصل ليتناسب مع ارتفاع SVG */
    background-image: url("data:image/svg+xml,%3Csvg width='10' height='10' viewBox='0 0 10 10' xmlns='http://www.w3.org/2000/svg'%3E%3Cline x1='0' y1='10' x2='10' y2='0' stroke='%23ccc' stroke-width='1' /%3E%3C/svg%3E");
    background-repeat: repeat-x; /* تكرار النمط أفقياً */
    background-size: 10px 10px; /* حجم النمط الواحد */
    margin: 2em 0; /* مسافة أعلى وأسفل الفاصل */
}
/* مثال على نمط آخر: نقاط */
hr.dots {
    height: 2px;
    background-image: url("data:image/svg+xml,%3Csvg width='10' height='2' viewBox='0 0 10 2' xmlns='http://www.w3.org/2000/svg'%3E%3Ccircle cx='1' cy='1' r='1' fill='%23888' /%3E%3C/svg%3E");
    background-repeat: repeat-x;
    background-size: 10px 2px;
}
/* مثال على نمط آخر: موجة */
hr.wave {
    height: 20px;
    background-image: url("data:image/svg+xml,%3Csvg width='40' height='20' viewBox='0 0 40 20' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M0 10 Q10 0 20 10 T40 10' stroke='%23f00' fill='none' stroke-width='2'/%3E%3C/svg%3E");
    background-repeat: repeat-x;
    background-size: 40px 20px;
}

لاحظ أننا قمنا بترميز SVG ليكون آمناً للاستخدام في URL. يمكن استخدام أدوات عبر الإنترنت لترميز SVG إلى URL إذا كان النمط معقداً.

نصيحة: لإنشاء أنماط SVG معقدة، يمكنك تصميمها في محرر رسومي مثل Adobe Illustrator أو Inkscape، ثم تصديرها كـ SVG. بعد ذلك، قم بتحسين الكود وإزالة أي عناصر غير ضرورية قبل ترميزها لـ CSS.

اعتبارات إمكانية الوصول

عند استبدال <hr /> برسوم SVG، من المهم التأكد من أن الفاصل لا يزال ينقل المعنى الدلالي الصحيح إذا كان ذلك مطلوباً. إذا كان الفاصل مجرد عنصر تزييني، فلا بأس. ولكن إذا كان يمثل فاصل محتوى ذا معنى، فتأكد من أن القارئات الشاشة لا تتجاهله تماماً. يمكن إضافة aria-hidden="true" إذا كان تزيينياً بحتاً، أو استخدام role="separator" إذا كان له معنى دلالي.

كيف يمكنني جعل SVG المتكرر مستجيباً؟

بما أننا نستخدم SVG كصورة خلفية، فإن استجابته تعتمد على كيفية تحديد background-size. إذا استخدمت وحدات نسبية مثل % أو vw لـ background-size، فسيتكيف النمط مع حجم العنصر الأب. تأكد أيضاً من أن height الخاص بـ hr يتكيف مع الشاشات المختلفة باستخدام استعلامات الوسائط (Media Queries).

هل يمكنني تحريك SVG المستخدم كفاصل؟

نعم، يمكن تحريك رسوم SVG باستخدام CSS Animations أو JavaScript. ومع ذلك، عند استخدامها كـ background-image، تكون خيارات التحريك محدودة. لتحريك النمط نفسه، ستحتاج إلى تضمين SVG مباشرة في HTML واستخدام CSS أو JavaScript لتحريك مساراته أو أشكاله، أو استخدام @keyframes مع background-position لإنشاء تأثير تمرير.

المشاركات ذات الصلة

المقال الأصلي:
تحويل <hr /> إلى تحفة فنية: دمج SVG المتكرر كفاصل مرئي
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

احتراف Docker: دليلك العملي لأحدث التطورات

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 17 Aug 2026 10:27:52 +0100

في عالم تطوير البرمجيات الحديث، أصبح Docker أداة لا غنى عنها لتبسيط عملية بناء التطبيقات ونشرها وإدارتها. يتيح Docker للمطورين تغليف تطبيقاتهم مع جميع تبعياتها في "حاويات" (Containers) خفيفة الوزن وقابلة للنقل، مما يضمن تشغيلها بشكل متسق عبر أي بيئة. هذا المقال يرشدك نحو احتراف Docker ويستعرض أبرز التطورات الحديثة.

ما هو Docker ولماذا هو ضروري؟

Docker هو منصة مفتوحة المصدر لأتمتة نشر التطبيقات كحاويات محمولة ومستقلة. يحل مشكلة "يعمل على جهازي" (It works on my machine) من خلال توفير بيئة تشغيل موحدة. تكمن أهميته في:

التناسق: يضمن تشغيل التطبيق بنفس الطريقة في بيئات التطوير، الاختبار، والإنتاج.
العزل: كل حاوية تعمل في بيئتها المعزولة، مما يمنع تضارب التبعيات.
السرعة والكفاءة: بدء تشغيل الحاويات أسرع بكثير من الأجهزة الافتراضية، وتستهلك موارد أقل.
قابلية النقل: يمكن نقل الحاويات بسهولة بين الخوادم السحابية أو المحلية.

المفاهيم الأساسية لاحتراف Docker

لإتقان Docker، يجب فهم هذه اللبنات الأساسية:

ملفات Dockerfile

هي نصوص برمجية تحتوي على تعليمات لبناء صورة Docker (Docker Image). كل سطر يمثل طبقة (Layer) في الصورة. احترافها يعني كتابة ملفات Dockerfile فعالة ومحسّنة.

python:3.9-slim
/app
requirements.txt .
pip install -r requirements.txt
. .
["python", "app.py"]

نصيحة!
استخدم صورًا أساسية صغيرة (مثل -slim أو alpine) لتقليل حجم الصور النهائية.

الصور والحاويات

الصور (Images): قوالب للقراءة فقط تحتوي على التطبيق وجميع تبعياته. تُبنى من ملفات Dockerfile.
الحاويات (Containers): نسخ قابلة للتشغيل من الصور. هي المثيل الحي للتطبيق.

أوامر أساسية: docker build لبناء الصور، docker run لتشغيل الحاويات، docker ps لعرض الحاويات قيد التشغيل.

المجلدات والشبكات

المجلدات (Volumes): تُستخدم لتخزين البيانات المستمرة خارج الحاوية، مما يضمن بقاء البيانات حتى بعد حذف الحاوية.
الشبكات (Networking): تسمح للحاويات بالتواصل مع بعضها البعض ومع العالم الخارجي. Docker يوفر عدة أنماط شبكات (bridge, host, overlay).

تقنيات Docker المتقدمة

Docker Compose

أداة لتعريف وتشغيل تطبيقات Docker متعددة الحاويات. باستخدام ملف YAML واحد، يمكنك تكوين جميع الخدمات والشبكات والمجلدات اللازمة لتطبيقك.

"3.8"

  web:
    .
    
      - "8000:8000"
    
      - .:/app
    
      - db
  
    image: postgres:13
    
      POSTGRES_DB: mydatabase
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password

الأمر docker-compose up يشغل جميع الخدمات المحددة.

أدوات الأوركسترا (Swarm/Kubernetes)

لإدارة ونشر الحاويات على نطاق واسع في بيئات الإنتاج، تُستخدم أدوات الأوركسترا. Docker Swarm هو حل Docker الأصلي، بينما Kubernetes هو المعيار الصناعي لإدارة مجموعات الحاويات المعقدة.

البناء متعدد المراحل (Multi-stage Builds)

تقنية لتقليل حجم صور Docker النهائية بشكل كبير. تسمح لك باستخدام مراحل بناء مختلفة، حيث يتم التخلص من الأدوات والتبعيات غير الضرورية في الصورة النهائية.

node:16-alpine AS builder
/app
package*.json ./
npm install
. .
npm run build

nginx:alpine
--from=builder /app/build /usr/share/nginx/html
80
["nginx", "-g", "daemon off;"]

أحدث التطورات في Docker

BuildKit

محرك بناء أسرع وأكثر كفاءة لـ Docker. يقدم ميزات مثل التخزين المؤقت الذكي، البناء المتوازي، ودعم بناء الصور متعددة المنصات. يتم تمكينه افتراضيًا في الإصدارات الحديثة من Docker.

حاويات التطوير (Dev Containers) وتحسينات Docker Desktop

تتيح لك Dev Containers (مدعومة في VS Code و Docker Desktop) تحديد بيئة تطوير كاملة داخل حاوية Docker. هذا يضمن أن كل مطور يعمل في نفس البيئة الموحدة، مما يقلل من مشكلات التوافق. كما أن Docker Desktop يستمر في إضافة ميزات جديدة لتبسيط تجربة المطور.

أفضل ممارسات الأمان

الأمان أصبح محور اهتمام كبير. تشمل التطورات التركيز على:

صور أساسية موثوقة: استخدام صور من مصادر رسمية ومعروفة.
فحص الثغرات: أدوات مثل Docker Scout و Trivy لفحص الصور بحثًا عن الثغرات الأمنية.
مبدأ الامتياز الأقل: تشغيل الحاويات كمستخدمين غير جذريين (non-root) وتقليل الأذونات.

نصائح عملية لاحتراف Docker

الممارسة المستمرة: قم ببناء مشاريعك الخاصة باستخدام Docker، وجرب سيناريوهات مختلفة.
التعمق في الوثائق الرسمية: وثائق Docker الرسمية هي المصدر الأفضل والأكثر دقة.
فهم مبادئ Linux: بما أن Docker يعتمد على نواة Linux، فإن فهم أساسياتها سيعزز فهمك لعمل الحاويات.
المشاركة في المجتمع: انضم إلى منتديات Docker والمجموعات عبر الإنترنت لتبادل الخبرات وحل المشكلات.
تجربة أدوات الأوركسترا: ابدأ بـ Docker Compose ثم انتقل إلى Kubernetes لفهم إدارة الحاويات على نطاق واسع.

تحذير!
تجنب تشغيل الحاويات بامتيازات جذرية (root) ما لم يكن ذلك ضروريًا للغاية، لتقليل المخاطر الأمنية.

خاتمة

احتراف Docker هو رحلة مستمرة تتطلب الفهم العميق للمفاهيم الأساسية، والممارسة العملية للتقنيات المتقدمة، ومواكبة أحدث التطورات. من خلال تطبيق هذه الإرشادات، ستتمكن من تسخير قوة Docker لبناء ونشر تطبيقات أكثر كفاءة وموثوقية، مما يجعلك مطورًا أو مهندس DevOps أكثر قيمة في سوق العمل.

ما الفرق بين الصورة والحاوية في Docker؟

الصورة (Image) هي قالب ثابت للقراءة فقط يحتوي على التطبيق وجميع تبعياته. أما الحاوية (Container) فهي نسخة قابلة للتشغيل من الصورة، وهي المثيل الحي للتطبيق الذي يمكنك التفاعل معه.

لماذا يجب استخدام Docker Compose؟

يُستخدم Docker Compose لتعريف وتشغيل تطبيقات Docker متعددة الحاويات بسهولة. يسمح لك بتكوين جميع الخدمات والشبكات والمجلدات اللازمة لتطبيقك في ملف YAML واحد، مما يبسط عملية الإعداد والإدارة لبيئات التطوير المعقدة.

المشاركات ذات الصلة

المقال الأصلي:
احتراف Docker: دليلك العملي لأحدث التطورات
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

احتراف Google Apps Script: المسار العملي وأحدث التطورات

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 10 Aug 2026 10:27:53 +0100

في عالم يزداد فيه الاعتماد على الأتمتة والحلول السحابية، يبرز Google Apps Script كأداة قوية لا غنى عنها للمطورين ومحترفي الأعمال على حد سواء. إنها منصة برمجية قائمة على السحابة تتيح لك توسيع وتخصيص وأتمتة تطبيقات Google Workspace (مثل جداول البيانات، المستندات، Gmail، التقويم، و Drive) باستخدام لغة JavaScript. يهدف هذا المقال إلى إرشادك نحو احتراف هذه الأداة وتقديم لمحة عن أحدث التطورات فيها.

ما هو Google Apps Script؟

Google Apps Script (GAS) هو بيئة تطوير قائمة على السحابة تمكنك من كتابة أكواد JavaScript للتفاعل مع خدمات Google. لا يتطلب تثبيت أي برامج على جهازك، فكل ما تحتاجه هو متصفح ويب وحساب Google. يتيح لك GAS إنشاء وظائف مخصصة، أتمتة المهام المتكررة، بناء تطبيقات ويب بسيطة، وربط خدمات Google ببعضها البعض أو بخدمات خارجية.

كيفية احتراف Google Apps Script

يتطلب احتراف Google Apps Script مزيجًا من المعرفة النظرية والتطبيق العملي. إليك مسار عملي لتحقيق ذلك:

1. أساسيات JavaScript المتينة

بما أن Google Apps Script مبني على JavaScript، فإن الفهم العميق للغة الأم هو حجر الزاوية. ركز على المفاهيم الأساسية مثل:

المتغيرات وأنواع البيانات.
الدوال (Functions) وكيفية تعريفها واستدعائها.
هياكل التحكم (الشروط والحلقات التكرارية).
الكائنات (Objects) والمصفوفات (Arrays).
مفاهيم البرمجة غير المتزامنة (Asynchronous Programming) الأساسية، على الرغم من أن GAS يتعامل مع الكثير منها خلف الكواليس.

معلومة!
يستخدم Google Apps Script حاليًا محرك V8 JavaScript، مما يعني أنه يدعم أحدث ميزات اللغة.

2. التعلم بالمشاريع العملية

لا شيء يضاهي التعلم بالتطبيق. ابدأ بمشاريع صغيرة وبسيطة ثم تدرج إلى الأكثر تعقيدًا:

إنشاء قائمة مخصصة: أضف قائمة جديدة إلى Google Sheet أو Doc لتشغيل وظيفة معينة.
أتمتة إرسال البريد الإلكتروني: اكتب سكربت يرسل رسائل بريد إلكتروني بناءً على بيانات في جدول بيانات.
تسجيل البيانات: استخدم GAS لتسجيل بيانات من نموذج Google Forms إلى Google Sheet.
تطبيقات الويب البسيطة: أنشئ تطبيق ويب يعرض بيانات من جدول بيانات أو يتفاعل مع المستخدم.

3. استكشاف خدمات Google المدمجة

تكمن قوة GAS في قدرته على التفاعل مع خدمات Google الأخرى. تعرف على الكائنات العالمية (Global Objects) التي توفرها كل خدمة:

SpreadsheetApp للتعامل مع جداول البيانات.
GmailApp و MailApp لإرسال واستقبال رسائل البريد الإلكتروني.
DriveApp لإدارة الملفات والمجلدات في Google Drive.
CalendarApp للتعامل مع التقويمات والأحداث.
DocumentApp و FormsApp للمستندات والنماذج.
UrlFetchApp لإجراء طلبات HTTP إلى واجهات برمجة تطبيقات خارجية.

اقرأ الوثائق الرسمية لكل خدمة لفهم الطرق (Methods) والخصائص (Properties) المتاحة.

4. تصحيح الأخطاء والتحسين

تعد مهارات تصحيح الأخطاء (Debugging) وتحسين الأداء ضرورية. استخدم:

Logger.log() لتتبع قيم المتغيرات وسير عمل السكربت.
مصحح الأخطاء المدمج (Debugger) في محرر Apps Script.
فهم قيود Apps Script (مثل حدود التنفيذ اليومية) وكيفية تصميم السكربتات لتكون فعالة.

5. المجتمع والموارد

لا تتردد في الاستفادة من المجتمع. تعد وثائق Google Apps Script الرسمية (Google Developers) مصدرًا لا يقدر بثمن. كما أن مواقع مثل Stack Overflow ومنتديات Google الخاصة بـ Apps Script توفر حلولًا لمشاكل شائعة.

أحدث التطورات في Google Apps Script

تشهد Google Apps Script تطورات مستمرة لتعزيز أدائها وقدراتها:

محرك V8 JavaScript: تم تحديث بيئة التشغيل لدعم محرك V8 JavaScript، مما يوفر أداءً أفضل ويدعم أحدث ميزات JavaScript (مثل async/await، let، const، و arrow functions).
Clasp (Command Line Apps Script Project): أداة سطر أوامر تتيح للمطورين تطوير مشاريع Apps Script محليًا باستخدام محرر الأكواد المفضل لديهم، ثم مزامنتها مع Google Drive. هذا يحسن سير عمل التطوير بشكل كبير.
تحسينات على محرر الأكواد: تحديثات مستمرة على محرر الأكواد المدمج لتحسين تجربة المستخدم، بما في ذلك إكمال تلقائي أفضل، وتصحيح أخطاء أكثر كفاءة، ودعم أفضل لأنواع TypeScript (على الرغم من أن Apps Script لا يزال يعتمد على JavaScript).
تكامل أوسع مع Google Cloud Platform: تسهيل ربط مشاريع Apps Script بخدمات GCP الأخرى، مما يفتح آفاقًا جديدة للمشاريع الأكثر تعقيدًا.

تحذير!
عند التعامل مع بيانات حساسة أو واجهات برمجة تطبيقات خارجية، تأكد دائمًا من تطبيق أفضل ممارسات الأمان والتحقق من صحة المدخلات.

إليك مثال بسيط يوضح كيفية إضافة قائمة مخصصة إلى Google Sheet وتشغيل وظيفة:

function onOpen(e) {
  SpreadsheetApp.getUi()
      .createMenu('أدوات مخصصة')
      .addItem('تشغيل وظيفة', 'myCustomFunction')
      .addToUi();
}

function myCustomFunction() {
  SpreadsheetApp.getUi().alert('تم تشغيل الوظيفة المخصصة!');
  Logger.log('تم تنفيذ الوظيفة بنجاح.');
}

نصيحة! لتحقيق أقصى استفادة من Google Apps Script، حاول دائمًا كتابة أكواد قابلة لإعادة الاستخدام، واستخدم التعليقات التوضيحية، واختبر وظائفك بانتظام.

هل أحتاج إلى معرفة JavaScript لتعلم Google Apps Script؟

نعم، معرفة أساسيات JavaScript ضرورية للغاية، حيث أن Google Apps Script مبني عليها بالكامل. كلما كان فهمك لـ JavaScript أعمق، كلما تمكنت من كتابة سكربتات أكثر كفاءة وتعقيدًا.

ما الفرق بين Google Apps Script و JavaScript العادي؟

Google Apps Script هو بيئة تشغيل خاصة لـ JavaScript تعمل على خوادم Google. بينما JavaScript العادي يمكن تشغيله في المتصفح (Client-side) أو على الخادم (Node.js)، فإن Apps Script مصمم خصيصًا للتفاعل مع خدمات Google Workspace ويحتوي على كائنات وواجهات برمجة تطبيقات (APIs) فريدة لهذه الخدمات (مثل SpreadsheetApp، GmailApp). كما أنه لا يتطلب إعداد بيئة تطوير محلية.

في الختام، يمثل Google Apps Script أداة قوية ومرنة لأتمتة المهام وتوسيع قدرات Google Workspace. من خلال بناء أساس قوي في JavaScript، والممارسة المستمرة عبر المشاريع العملية، واستكشاف خدمات Google المدمجة، والبقاء على اطلاع بأحدث التطورات، يمكنك احتراف هذه المنصة وتحويل أفكارك إلى حلول عملية تزيد من إنتاجيتك وكفاءتك.

المشاركات ذات الصلة

المقال الأصلي:
احتراف Google Apps Script: المسار العملي وأحدث التطورات
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

احتراف GitHub: دليلك الشامل لأحدث التطورات والممارسات

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 27 Jul 2026 10:27:44 +0100

تُعد منصة GitHub حجر الزاوية في عالم تطوير البرمجيات الحديث، فهي ليست مجرد خدمة لاستضافة مستودعات Git، بل هي بيئة متكاملة للتعاون، إدارة المشاريع، وأتمتة سير العمل. احتراف GitHub لم يعد خياراً، بل ضرورة لكل مطور يسعى للتميز والإنتاجية.

ما هو GitHub ولماذا هو أساسي؟

GitHub هي منصة قائمة على الويب تستخدم نظام التحكم في الإصدارات Git. تسمح للمطورين بالتعاون على المشاريع، تتبع التغييرات في الكود، وإدارة دورة حياة تطوير البرمجيات بكفاءة. يكمن جوهر GitHub في تسهيل العمل الجماعي، حيث يمكن لعدة مطورين العمل على نفس المشروع في وقت واحد دون تضارب، مع الحفاظ على سجل كامل ودقيق لجميع التعديلات.

احتراف GitHub: المفاهيم الأساسية

لتبدأ رحلتك نحو احتراف GitHub، يجب أن تتقن المفاهيم الأساسية لنظام Git وكيفية تطبيقها على GitHub.

المستودعات (Repositories)

المستودع هو المجلد الرئيسي لمشروعك، حيث يتم تخزين جميع الملفات، الأكواد، وسجل التغييرات. يمكن أن يكون المستودع عاماً (Public) أو خاصاً (Private).

إنشاء مستودع جديد: من واجهة GitHub، اختر "New repository".
استنساخ مستودع (Cloning): لجلب نسخة من المستودع إلى جهازك المحلي، استخدم الأمر:

git clone <URL_المستودع>

التعديلات والالتزامات (Commits)

الالتزام هو لقطة للتغييرات التي أجريتها على مشروعك. كل التزام يحتوي على رسالة توضيحية تصف التغييرات.

إضافة التغييرات للمنطقة المؤقتة (Staging Area):

git add .

إنشاء التزام (Commit):

git commit -m "رسالة توضيحية للتغييرات"

الفروع (Branches)

الفروع تسمح لك بالعمل على ميزات جديدة أو إصلاح الأخطاء دون التأثير على الكود الرئيسي للمشروع (عادةً فرع main أو master).

إنشاء فرع جديد:

git branch <اسم_الفرع>

التبديل إلى فرع:

git checkout <اسم_الفرع>

دمج الفروع (Merging): بعد الانتهاء من العمل على فرع، يمكنك دمجه مع الفرع الرئيسي:

git checkout main
git merge <اسم_الفرع>

الدفع والسحب (Push & Pull)

للمزامنة بين المستودع المحلي والمستودع البعيد (على GitHub):

الدفع (Push): لإرسال التغييرات من المستودع المحلي إلى GitHub:

git push origin <اسم_الفرع>

السحب (Pull): لجلب التغييرات من GitHub إلى المستودع المحلي:

git pull origin <اسم_الفرع>

الميزات المتقدمة في GitHub

بعد إتقان الأساسيات، يمكنك استكشاف الميزات التي تعزز التعاون وتسرع سير العمل.

طلبات السحب (Pull Requests - PRs)

هي قلب التعاون في GitHub. تسمح للمطورين باقتراح تغييرات على فرع آخر (عادةً main). يمكن للمراجعين مناقشة التغييرات، تقديم الملاحظات، والموافقة عليها قبل الدمج.

نصيحة!
اكتب رسائل PR واضحة وموجزة، واشرح الغرض من التغييرات، وكيف تم اختبارها.

المشكلات (Issues)

أداة لتتبع الأخطاء، طلبات الميزات، وتحسينات المشروع. يمكن ربط المشكلات بطلبات السحب لتتبع التقدم.

إجراءات GitHub (GitHub Actions)

تتيح لك أتمتة مهام سير العمل مباشرة داخل مستودعك. يمكنك بناء، اختبار، ونشر الكود تلقائياً عند كل دفع أو طلب سحب. هذا يمثل أساس الدمج المستمر (CI) والنشر المستمر (CD).

مثال: يمكنك إعداد GitHub Action لتشغيل اختبارات الوحدة تلقائياً في كل مرة يتم فيها دفع كود جديد إلى فرع main.

صفحات GitHub (GitHub Pages)

خدمة استضافة مجانية للمواقع الثابتة مباشرة من مستودعك. مثالية للمدونات، وثائق المشاريع، أو السير الذاتية.

أحدث التطورات في GitHub

تتطور GitHub باستمرار لتقديم أدوات أكثر قوة وذكاءً للمطورين.

GitHub Copilot

مساعد برمجة يعمل بالذكاء الاصطناعي، تم تطويره بالتعاون مع OpenAI. يقترح Copilot سطوراً كاملة من الكود أو دوال بناءً على السياق الذي تكتب فيه، مما يزيد من سرعة البرمجة ويقلل من الأخطاء.

GitHub Codespaces

بيئات تطوير فورية وقابلة للتكوين بالكامل تعمل في السحابة. تتيح لك بدء العمل على مشروعك في ثوانٍ من أي جهاز، دون الحاجة لإعداد بيئة تطوير محلية معقدة. هذا يعزز المرونة ويقلل من وقت الإعداد.

تحسينات الأمان (Security Enhancements)

تواصل GitHub تعزيز ميزات الأمان مثل Dependabot الذي يقوم بفحص تبعيات مشروعك للكشف عن الثغرات الأمنية وتحديثها تلقائياً، و Code Scanning الذي يكتشف الثغرات الأمنية في الكود الخاص بك قبل النشر.

الدمج مع الذكاء الاصطناعي (AI Integration)

بالإضافة إلى Copilot، تستكشف GitHub المزيد من طرق دمج الذكاء الاصطناعي لتحسين تجربة المطور، مثل تلخيص طلبات السحب، اقتراح مراجعات الكود، وتحسين البحث عن الكود.

أفضل الممارسات لاحتراف GitHub

رسائل الالتزام الواضحة: اكتب رسائل التزام وصفية وموجزة.
استراتيجيات الفروع: استخدم استراتيجيات مثل Git Flow أو GitHub Flow لإدارة الفروع بفعالية.
مراجعة الكود: شارك في مراجعة الكود لتعلم من الآخرين وتحسين جودة الكود.
استخدام القوالب: استخدم قوالب لطلبات السحب والمشكلات لتوحيد المعلومات المطلوبة.
التعلم المستمر: تابع مدونة GitHub الرسمية وقنوات المطورين للبقاء على اطلاع بأحدث الميزات والتطورات.

ما الفرق بين Git و GitHub؟

Git هو نظام تحكم في الإصدارات موزع (DVCS) لتتبع التغييرات في الكود. GitHub هي منصة قائمة على الويب تستضيف مستودعات Git وتوفر أدوات للتعاون وإدارة المشاريع.

هل GitHub مجاني للاستخدام؟

نعم، GitHub يقدم خطة مجانية للمستودعات العامة والخاصة، مع قيود على بعض الميزات المتقدمة التي تتطلب خططاً مدفوعة.

ما هي أهمية GitHub Actions؟

تسمح GitHub Actions بأتمتة مهام سير العمل مثل بناء الكود، اختباره، ونشره، مما يسرع عملية التطوير ويضمن جودة الكود من خلال الدمج المستمر والنشر المستمر (CI/CD).

المشاركات ذات الصلة

المقال الأصلي:
احتراف GitHub: دليلك الشامل لأحدث التطورات والممارسات
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

تحديد نطاق خصائص CSS المخصصة: بديل فعال لمتغيرات الثيم الجذرية؟

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 20 Jul 2026 10:27:53 +0100

في عالم تطوير الويب الحديث، أصبحت إدارة الأنماط القابلة للتخصيص والصيانة أمرًا بالغ الأهمية. توفر خصائص CSS المخصصة (المعروفة أيضًا بمتغيرات CSS) أداة قوية لتحقيق ذلك، ولكن السؤال يظل: أين يجب تعريف هذه المتغيرات؟ هل يجب أن تكون عالمية على مستوى :root، أم يجب تحديد نطاقها على مستوى المكونات الفردية؟ يستكشف هذا المقال هذا التساؤل، مقدمًا تحليلاً عمليًا لمساعدتك في اتخاذ القرار الأنسب لمشاريعك.

فهم خصائص CSS المخصصة

خصائص CSS المخصصة هي كيانات معرفة من قبل المؤلف تحتوي على قيم يمكن إعادة استخدامها في مستند CSS. يتم تعريفها باستخدام بادئة مزدوجة الشرطة (--) ويمكن الوصول إليها باستخدام دالة var(). تتيح هذه الخصائص إنشاء أنظمة تصميم ديناميكية ومرنة، مما يسهل إدارة الثيمات والتخصيصات.


:root {
  --primary-color: #007bff;
  --secondary-color: #6c757d;
}

.button {
  background-color: var(--primary-color);
  color: white;
  padding: 10px 15px;
  border: none;
}

متغيرات الثيم العالمية في :root

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

مزايا المتغيرات العالمية

سهولة الإدارة المركزية: يمكن تغيير قيمة واحدة في :root لتنعكس على الفور في كل مكان يتم استخدام هذا المتغير فيه.
الاتساق الشامل: يضمن تطبيق ثيم متسق عبر التطبيق بأكمله.
الوصول السهل: يمكن الوصول إلى أي متغير معرف في :root من أي مكان في شجرة DOM بسبب آلية التتالي.

عيوب المتغيرات العالمية

احتمال التضارب: قد يؤدي تعريف عدد كبير من المتغيرات العالمية إلى تضارب في الأسماء أو صعوبة في تتبع استخداماتها.
نقص التغليف: لا توفر المتغيرات العالمية أي تغليف، مما يعني أن أي مكون يمكنه الوصول إليها وتعديلها، مما قد يؤدي إلى آثار جانبية غير مقصودة.
صعوبة التخصيص المحلي: إذا كان مكون معين يحتاج إلى تجاوز قيمة عالمية، فقد يتطلب ذلك كتابة CSS إضافي أو استخدام متغيرات جديدة، مما يزيد من التعقيد.

تحديد النطاق على جذر المكون

يقوم هذا النهج بتعريف خصائص CSS المخصصة مباشرة على العنصر الجذر للمكون (مثل .my-component). هذا يعني أن المتغيرات تكون متاحة فقط داخل هذا المكون وذريته، مما يوفر مستوى من التغليف.


.card {
  --card-bg-color: #ffffff;
  --card-border-radius: 8px;
  background-color: var(--card-bg-color);
  border-radius: var(--card-border-radius);
  padding: 20px;
  border: 1px solid #eee;
}

.card.dark {
  --card-bg-color: #333333; /* Override for dark theme */
  color: white;
}

مزايا تحديد النطاق على المكون

التغليف المعزز: تظل المتغيرات محصورة داخل المكون، مما يقلل من خطر التضارب مع الأنماط الأخرى في التطبيق.
النمطية وقابلية إعادة الاستخدام: يصبح المكون أكثر استقلالية وقابلية لإعادة الاستخدام، حيث يحمل معه جميع متغيراته الخاصة.
سهولة التخصيص المحلي: يمكن للمكونات بسهولة تجاوز قيم المتغيرات الخاصة بها دون التأثير على المكونات الأخرى أو الثيم العام.
وضوح الكود: يصبح من الواضح أي المتغيرات تنتمي إلى أي مكون، مما يسهل الصيانة والفهم.

عيوب تحديد النطاق على المكون

صعوبة تطبيق الثيم الشامل: إذا كان كل مكون يحدد متغيراته الخاصة، فقد يصبح من الصعب فرض ثيم موحد على مستوى التطبيق بأكمله.
التكرار المحتمل: قد تضطر إلى تعريف متغيرات متشابهة (مثل --text-color) في مكونات متعددة، مما يؤدي إلى تكرار الكود.
تعقيد إدارة الثيمات المعقدة: في أنظمة التصميم الكبيرة ذات الثيمات المتعددة، قد يصبح تتبع المتغيرات المحلية وتنسيقها أمرًا معقدًا.

النهج الهجين: الأفضل من العالمين

في كثير من الحالات، يكون النهج الأمثل هو الجمع بين كلا الطريقتين. يمكن استخدام متغيرات :root لتعريف القيم الأساسية للثيم العام (مثل لوحة الألوان الأساسية، الخطوط، المسافات القياسية). بعد ذلك، يمكن للمكونات استخدام هذه المتغيرات العالمية كقيم افتراضية، مع القدرة على تعريف متغيرات خاصة بها أو تجاوز القيم العالمية عند الحاجة.


:root {
  --global-primary-color: #007bff;
  --global-font-size: 16px;
}

.button {
  --button-bg-color: var(--global-primary-color); /* Use global as default */
  --button-font-size: var(--global-font-size);
  background-color: var(--button-bg-color);
  font-size: var(--button-font-size);
  padding: 10px 15px;
}

.button.alt {
  --button-bg-color: #28a745; /* Override locally */
}

معلومة!
يسمح هذا النهج الهجين بالاستفادة من الاتساق الذي توفره المتغيرات العالمية، مع الحفاظ على مرونة وتغليف المكونات الفردية.

الخلاصة

تحديد نطاق خصائص CSS المخصصة على جذر المكون هو بالتأكيد بديل جيد لمتغيرات الثيم العالمية، خاصة عندما يكون الهدف هو تعزيز التغليف، النمطية، وقابلية إعادة استخدام المكونات. ومع ذلك، فإنه ليس حلاً شاملاً لكل السيناريوهات. للحصول على أفضل النتائج، يوصى بتبني نهج هجين:

استخدم :root لتعريف المتغيرات الأساسية التي تشكل جوهر نظام التصميم الخاص بك وتتطلب اتساقًا شاملاً.
استخدم تحديد النطاق على مستوى المكون لتعريف المتغيرات الخاصة بالمكون، أو لتوفير تجاوزات محلية للقيم العالمية.

هذا التوازن يضمن أن تتمتع بتوحيد الثيم على مستوى التطبيق، مع الحفاظ على مرونة المكونات واستقلاليتها، مما يؤدي إلى قاعدة كود CSS أكثر قابلية للصيانة والتوسع.

ما الفرق الرئيسي بين متغيرات :root والمتغيرات المحددة النطاق على المكون؟

متغيرات :root هي عالمية ومتاحة في أي مكان في شجرة DOM، مما يجعلها مثالية للثيمات الشاملة. أما المتغيرات المحددة النطاق على المكون، فهي متاحة فقط داخل المكون نفسه وذريته، مما يوفر تغليفًا أفضل وقابلية لإعادة الاستخدام.

هل يمكنني استخدام متغير عالمي كقيمة افتراضية لمتغير محلي؟

نعم، هذا هو جوهر النهج الهجين. يمكنك تعريف متغير عالمي في :root، ثم استخدام هذا المتغير كقيمة لمتغير محلي داخل مكون، مع إمكانية تجاوز القيمة المحلية لاحقًا إذا لزم الأمر.

المشاركات ذات الصلة

المقال الأصلي:
تحديد نطاق خصائص CSS المخصصة: بديل فعال لمتغيرات الثيم الجذرية؟
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

حل مشكلة TS7053: الوصول الآمن للقيم المفهرسة في TypeScript و Angular

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 13 Jul 2026 10:27:49 +0100

تُعد مشكلة TS7053، التي تشير إلى "Element implicitly has an 'any' type because expression of type 'string' can't be used to index type '{}'", من الأخطاء الشائعة التي يواجهها المطورون عند محاولة الوصول إلى خصائص كائن ديناميكياً في TypeScript دون توفير معلومات كافية عن النوع. يبرز هذا الخطأ بشكل خاص في سياق Angular عند محاولة تهيئة خاصية لمكون باستخدام قيمة مفهرسة مأخوذة من كائن `environment`.

فهم خطأ TS7053

يحدث خطأ TS7053 عندما يحاول TypeScript الوصول إلى خاصية كائن باستخدام مفتاح ديناميكي (مثل متغير سلسلة) ولا يستطيع المترجم التأكد من أن الكائن يمتلك هذه الخاصية أو أن نوعها معروف. في السيناريو المحدد الذي ذكرته:

<app-carte [id] = "environment[region + '_id']">

يفترض TypeScript أن الكائن `environment` قد لا يحتوي على مفتاح مثل 'dev_id' أو 'prod_id'، أو أنه لا يمتلك توقيع فهرس (index signature) يسمح بالوصول إليه باستخدام سلسلة. هذا السلوك هو جزء من نظام الأنواع الصارم في TypeScript لضمان السلامة ومنع أخطاء وقت التشغيل.

حلول عملية

لحل هذه المشكلة، نحتاج إلى تزويد TypeScript بمعلومات نوعية كافية حول كائن `environment` ليعرف أنه يمكن الوصول إليه ديناميكياً. إليك عدة طرق للقيام بذلك، بدءاً من الأقل أماناً وصولاً إلى الأكثر قوة.

الحل 1: تأكيد النوع (Type Assertion)

تأكيد النوع هو أسرع طريقة لتجاوز الخطأ، لكنه يقلل من سلامة النوع. أنت تخبر TypeScript بشكل أساسي "أنا أعرف أفضل، ثق بي".

import { Component } from '@angular/core';
import { environment } from 'src/environments/environment'; // تأكد من المسار الصحيح

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  region: string = 'dev'; // أو أي قيمة أخرى
  env = environment; // اجعل environment متاحاً في القالب

  // في القالب: <app-carte [id]="getCarteId()">
  getCarteId(): string {
    const key = this.region + '_id';
    // تأكيد النوع هنا: نخبر TypeScript أن env هو Record
    return (this.env as Record<string, any>)[key];
  }
}

تحذير!
استخدام any أو Record<string, any> يزيل فحص النوع لهذه الخاصية، مما قد يؤدي إلى أخطاء وقت التشغيل إذا لم تكن الخاصية موجودة بالفعل.

الحل 2: حارس النوع (Type Guard)

يمكنك استخدام حارس النوع للتحقق من وجود الخاصية قبل محاولة الوصول إليها. هذا يضيف طبقة من الأمان ولكنه لا يحل مشكلة TS7053 مباشرة في القالب ما لم يتم دمجها مع تأكيد النوع أو إعادة هيكلة الكود.

import { Component } from '@angular/core';
import { environment } from 'src/environments/environment';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  region: string = 'dev';
  env = environment;

  getCarteId(): string | undefined {
    const key = this.region + '_id';
    // استخدام حارس النوع للتحقق من وجود الخاصية
    if (key in this.env) {
      // لا يزال قد يتطلب تأكيد نوع إذا كان env غير مصنف بشكل جيد
      return (this.env as Record<string, string>)[key];
    }
    return undefined; // أو قيمة افتراضية
  }
}

في القالب، ستحتاج إلى التعامل مع القيمة المحتملة undefined:

<app-carte [id]="getCarteId() || 'default_id'"></app-carte>

الحل 3: التصنيف القوي مع توقيع الفهرس (Index Signature) - الحل الموصى به

هذا هو الحل الأكثر قوة وسلامة. قم بتعريف واجهة (interface) لكائن `environment` تتضمن توقيع فهرس. هذا يخبر TypeScript صراحة أن الكائن يمكن الوصول إليه باستخدام مفاتيح سلسلة.

تعريف الواجهة: أنشئ واجهة في ملف منفصل (مثل src/app/types/environment.ts) أو مباشرة في ملف `environment.ts` الخاص بك.
```
export interface AppEnvironment {
  production: boolean;
  apiUrl: string;
  // توقيع الفهرس: يسمح بالوصول إلى أي خاصية بسلسلة
  // ويحدد أن قيم هذه الخصائص ستكون من نوع string (أو أي نوع آخر مناسب)
  [key: string]: string | boolean;
}
```
معلومة!
إذا كانت بعض خصائص environment ليست من نوع string (مثل production: boolean)، فيجب أن يشمل توقيع الفهرس جميع الأنواع المحتملة (مثال: string | boolean).

تطبيق الواجهة على كائن environment: قم بتحديث ملفات environment.ts و environment.prod.ts لتتوافق مع الواجهة.

import { AppEnvironment } from '../app/types/environment'; // تأكد من المسار

export const environment: AppEnvironment = {
  production: false,
  apiUrl: 'http://localhost:3000',
  dev_id: 'dev_carte_123',
  test_id: 'test_carte_456'
};

import { AppEnvironment } from '../app/types/environment'; // تأكد من المسار

export const environment: AppEnvironment = {
  production: true,
  apiUrl: 'https://api.yourdomain.com',
  prod_id: 'prod_carte_789'
};

استخدام الكائن المصنف في المكون: الآن، يمكن لـ TypeScript فهم الوصول الديناميكي بأمان.

import { Component } from '@angular/core';
import { environment } from 'src/environments/environment'; // سيعرف TypeScript الآن نوعه

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  region: string = 'dev';
  env = environment; // env الآن من نوع AppEnvironment

  // لا حاجة لدالة مساعدة إذا كان الوصول مباشراً في القالب
}

تحديث القالب:
```

<app-carte [id]="env[region + '_id'] as string"></app-carte>
```
لاحظ أن as string قد يكون ضرورياً إذا كان توقيع الفهرس يسمح بأنواع متعددة (مثل string | boolean) وكنت تحتاج إلى string بشكل خاص.

الخاتمة وأفضل الممارسات

يُعد التصنيف القوي لكائن environment باستخدام توقيع الفهرس هو الحل الأكثر أماناً واستدامة لمشكلة TS7053. إنه يضمن أن الكود الخاص بك متوافق مع مبادئ TypeScript للسلامة النوعية، ويقلل من الأخطاء المحتملة في وقت التشغيل، ويوفر تجربة تطوير أفضل مع إكمال الكود والتحقق من الأخطاء.

تجنب استخدام any قدر الإمكان، واعتمد على التصنيف الصريح لتعزيز موثوقية وقابلية صيانة تطبيقك.

ما هو توقيع الفهرس (Index Signature) في TypeScript؟

توقيع الفهرس هو ميزة في TypeScript تسمح لك بتعريف أنواع الخصائص التي يمكن الوصول إليها ديناميكياً في كائن باستخدام مفتاح (عادةً سلسلة أو رقم). يتم تعريفه بالشكل [key: string]: Type أو [index: number]: Type داخل واجهة أو نوع.

هل يمكنني استخدام Optional Chaining مع الوصول المفهرس؟

نعم، يمكنك استخدام Optional Chaining (?.) إذا كان الكائن نفسه قد يكون null أو undefined، ولكن ليس للوصول المفهرس مباشرة. ومع ذلك، يمكنك دمجه مع Nullish Coalescing (??) لتوفير قيمة افتراضية إذا كانت الخاصية غير موجودة أو null/undefined بعد الوصول الآمن للنوع. مثال: env[key] ?? 'default_value'.

ما الفرق بين as any و as Record<string, any>؟

as any يزيل كل فحص للنوع من هذا التعبير، مما يجعله غير آمن تماماً. as Record<string, any> يخبر TypeScript أن الكائن هو كائن عام حيث يمكن أن يكون لأي مفتاح سلسلة قيمة من نوع any. إنه أكثر تحديداً قليلاً من any ولكنه لا يزال يقلل من السلامة النوعية بشكل كبير للوصول الديناميكي.

المشاركات ذات الصلة

المقال الأصلي:
حل مشكلة TS7053: الوصول الآمن للقيم المفهرسة في TypeScript و Angular
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

TypeScript: تحديات متقدمة في قيود الأنواع، حل الوحدات، واستنتاج العموميات

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Fri, 10 Jul 2026 20:08:16 +0100

في عالم تطوير البرمجيات الحديث، أصبحت TypeScript أداة لا غنى عنها لبناء تطبيقات قوية وقابلة للصيانة. بفضل نظام الأنواع القوي الذي توفره، يمكن للمطورين اكتشاف الأخطاء مبكرًا وتحسين جودة الكود. ومع ذلك، فإن الغوص في أعماق TypeScript يكشف عن تحديات متقدمة تتطلب فهمًا دقيقًا للمفاهيم الأساسية والمتقدمة. يستكشف هذا المقال ثلاثة من هذه التحديات: تطبيق قيود القراءة فقط الصارمة، معالجة أخطاء حل الوحدات في Angular، ومشكلة تقاطع الأنواع غير المشروط من استنتاج الأنواع العامة.

تطبيق قيود القراءة فقط الصارمة (Strict Readonly Constraints)

يُعد ضمان ثبات البيانات (Immutability) مبدأ تصميميًا أساسيًا في العديد من أنماط البرمجة، خاصة في التطبيقات التي تعتمد على إدارة الحالة المعقدة. توفر TypeScript أدوات قوية لفرض قيود القراءة فقط على مستوى الأنواع، مما يمنع التعديلات غير المقصودة على الخصائص أو الكائنات.

استخدام معدل `readonly`

المعدل readonly هو الطريقة الأكثر وضوحًا لتعيين خاصية كقراءة فقط. يمكن تعيين قيمتها فقط أثناء التهيئة أو داخل مُنشئ الكلاس.

interface User {
  readonly id: string;
  name: string;
}

const user: User = { id: "123", name: "أحمد" };
user.name = "علي"; // مسموح
// user.id = "456"; // خطأ: لا يمكن تعيين 'id' لأنه خاصية للقراءة فقط.

الأنواع المساعدة `Readonly<T>`

لفرض قيود القراءة فقط على جميع خصائص كائن موجود، يمكن استخدام النوع المساعد Readonly<T>. هذا النوع ينشئ نوعًا جديدًا تكون جميع خصائصه للقراءة فقط.

interface Config {
  apiUrl: string;
  timeout: number;
}

const defaultConfig: Readonly<Config> = {
  apiUrl: "https://api.example.com",
  timeout: 5000,
};

// defaultConfig.apiUrl = "https://new.api.com"; // خطأ: لا يمكن تعيين 'apiUrl' لأنه خاصية للقراءة فقط.

ضمان الثبات العميق (Deep Immutability)

تحدي Readonly<T> هو أنه يطبق القيد على المستوى السطحي فقط. إذا كانت الخاصية نفسها كائنًا، فستظل قابلة للتعديل. لفرض ثبات عميق، نحتاج إلى أنواع مساعدة مخصصة أو مكتبات.

type DeepReadonly<T> = {
  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
};

interface Settings {
  user: {
    id: string;
    preferences: { theme: string };
  };
}

const appSettings: DeepReadonly<Settings> = {
  user: {
    id: "user1",
    preferences: { theme: "dark" },
  },
};

// appSettings.user.preferences.theme = "light"; // خطأ: لا يمكن تعيين 'theme' لأنه خاصية للقراءة فقط.

معلومة!
يُعد الثبات العميق أمرًا بالغ الأهمية في أنماط مثل Redux أو React Context لضمان عدم حدوث طفرات غير متوقعة في الحالة.

معالجة خطأ استيراد مكونات Angular (-991010) مع مسارات TypeScript

يواجه العديد من مطوري Angular خطأ -991010 عند استخدام تعيينات paths في ملف tsconfig.json لتنظيم الاستيرادات. يشير هذا الخطأ عادةً إلى مشكلة في حل الوحدات (Module Resolution)، حيث لا يتمكن TypeScript أو أدوات البناء من تحديد موقع الوحدات المستوردة بشكل صحيح.

الأسباب الجذرية

تكوين tsconfig.json غير صحيح: قد لا تكون baseUrl أو paths محددة بشكل صحيح، أو قد لا تتطابق مع بنية المشروع الفعلية.
عدم فهم أدوات البناء للمسارات: لا تفهم أدوات البناء مثل Webpack أو Rollup تعيينات paths في tsconfig.json بشكل افتراضي.
مشاكل في بيئة وقت التشغيل (Node.js): عند تشغيل الاختبارات أو الخوادم في Node.js، قد لا يتم حل المسارات المستعارة بشكل صحيح.

استراتيجيات تصحيح الأخطاء والحلول

التحقق من tsconfig.json:
تأكد من أن baseUrl يشير إلى الجذر المشترك لجميع الوحدات، وأن paths تعكس المسارات الصحيحة.
```
{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@app/*": ["app/*"],
      "@env/*": ["environments/*"],
      "@shared/*": ["app/shared/*"]
    }
  }
}
```
تكوين أدوات البناء (Angular CLI):
عادةً ما يتعامل Angular CLI مع هذا الأمر تلقائيًا. إذا كنت تستخدم تكوينًا مخصصًا لـ Webpack، فتأكد من إضافة TsConfigPathsPlugin أو تكوين alias يدويًا.
حل المسارات في Node.js:
لبيئات Node.js (مثل الاختبارات باستخدام Jest)، استخدم حزمًا مثل tsconfig-paths أو module-alias لتمكين Node.js من فهم تعيينات paths.
```
// في ملف إعداد Jest (مثل setup-jest.ts)
import 'tsconfig-paths/register';
```
تجنب المسارات المطلقة في بعض الحالات:
في بعض الأحيان، قد يكون استخدام الاستيرادات النسبية (../../) أكثر موثوقية للمكونات الداخلية جدًا، خاصة إذا كانت تعيينات المسارات معقدة.

تحذير!
يمكن أن يؤدي التكوين الخاطئ لـ baseUrl و paths إلى مشاكل في الأداء أثناء عملية البناء أو أخطاء في وقت التشغيل.

مشكلة تقاطع الأنواع غير المشروط من استنتاج الأنواع العامة

تُعد الأنواع العامة (Generics) والأنواع الشرطية (Conditional Types) من أقوى ميزات TypeScript، لكن استخدامها معًا يمكن أن يؤدي إلى سلوكيات غير متوقعة، مثل مشكلة تقاطع الأنواع غير المشروط (Unconditional Type Intersection).

فهم المشكلة

تحدث هذه المشكلة عندما يقوم TypeScript باستنتاج نوع عام بطريقة تؤدي إلى تقاطع غير مقصود للأنواع، خاصة في سياق الأنواع الشرطية الموزعة (Distributive Conditional Types). عندما يتم تطبيق نوع شرطي على نوع عام يمثل اتحادًا (Union)، فإنه يتوزع على أعضاء الاتحاد. ومع ذلك، إذا لم يتم التحكم في هذا التوزيع بعناية، فقد ينتهي بنا المطاف بتقاطع غير مرغوب فيه للنتائج.

type MyConditional<T> = T extends string ? { a: string } : { b: number };

// إذا كان T هو string | number، فإن MyConditional<T> سيوزع
// MyConditional<string> | MyConditional<number>
// وهو { a: string } | { b: number }

// ولكن في بعض السيناريوهات المعقدة، قد يتم استنتاج T كـ string & number (never)
// أو قد يؤدي إلى تقاطع غير مقصود إذا كان T يستخدم في سياق آخر.

// مثال مبسط يوضح كيف يمكن أن يحدث تقاطع غير مقصود:
type IntersectIfString<T> = T extends string ? T & { isString: true } : T;

function process<T>(value: T): IntersectIfString<T> {
  if (typeof value === 'string') {
    // هنا، TypeScript قد لا يضيق T إلى string بشكل كامل في سياق النوع العام
    // وقد ينتهي النوع المستنتج بـ T & { isString: true } حتى لو كان T ليس string
    return { ...value as any, isString: true }; // مثال توضيحي
  }
  return value as IntersectIfString<T>;
}

const result = process(123); // المتوقع 123 (number)
// ولكن في سيناريوهات معقدة، قد يتم استنتاج نوع مثل number & { isString: true } (never)
// أو قد يظهر سلوك غريب إذا كان التوزيع غير متحكم به.

تظهر هذه المشكلة بشكل أكثر شيوعًا عند التعامل مع أنواع عامة معقدة تتضمن أنواعًا شرطية متداخلة أو عند محاولة استنتاج أنواع بناءً على خصائص موجودة في كائنات ذات أنواع عامة.

التأثير والحلول

يؤثر هذا السلوك على سلامة الأنواع، حيث يمكن أن يؤدي إلى أنواع never غير متوقعة أو أنواع تقاطع لا معنى لها، مما يجعل الكود أكثر عرضة للأخطاء في وقت التشغيل. لتشخيص هذه المشكلة، يمكن استخدام أدوات المطور في VS Code لتحليل الأنواع المستنتجة.

منع التوزيع:
يمكن منع الأنواع الشرطية من التوزيع عن طريق تغليف النوع العام في مصفوفة (Tuple). على سبيل المثال، [T] extends [U] ? ... : ... بدلاً من T extends U ? ... : ....
تحديد قيود عامة أكثر صرامة:
تضييق النطاق المحتمل للنوع العام T باستخدام قيود extends يمكن أن يساعد TypeScript على استنتاج الأنواع بشكل أكثر دقة.
استخدام أنواع مساعدة:
تقسيم الأنواع الشرطية المعقدة إلى أنواع مساعدة أصغر يمكن أن يجعل عملية الاستنتاج أكثر وضوحًا لـ TypeScript.
الاستنتاج الصريح:
في بعض الحالات، قد يكون من الضروري تحديد الأنواع بشكل صريح بدلاً من الاعتماد كليًا على الاستنتاج.

معلومة!
فهم كيفية عمل استنتاج الأنواع الشرطية الموزعة أمر بالغ الأهمية لتجنب هذه المشكلة. تذكر أن T extends U ? X : Y يتوزع على أعضاء الاتحاد T، بينما [T] extends [U] ? X : Y لا يتوزع.

ما الفرق بين readonly و Readonly<T>؟

readonly هو معدل يُطبق على خاصية واحدة داخل واجهة أو كلاس لجعلها غير قابلة للتعديل بعد التهيئة. أما Readonly<T> فهو نوع مساعد (Utility Type) يأخذ نوعًا T ويُنشئ نوعًا جديدًا تكون جميع خصائصه للقراءة فقط بشكل سطحي.

كيف يمكنني حل خطأ -991010 في Angular إذا كنت أستخدم Webpack مخصصًا؟

إذا كنت تستخدم تكوين Webpack مخصصًا، فيجب عليك التأكد من أن Webpack يفهم تعيينات paths في tsconfig.json. يمكنك تحقيق ذلك عن طريق استخدام TsConfigPathsPlugin من حزمة tsconfig-paths-webpack-plugin في تكوين Webpack الخاص بك، أو عن طريق تكوين alias يدويًا في قسم resolve في Webpack.

ما هي إحدى الطرق الفعالة لمنع مشكلة تقاطع الأنواع غير المشروط في الأنواع الشرطية؟

إحدى الطرق الفعالة هي منع التوزيع (Distributivity) في الأنواع الشرطية. يمكنك القيام بذلك عن طريق تغليف النوع العام في مصفوفة (Tuple) عند استخدامه في الشرط، مثل [T] extends [U] ? X : Y بدلاً من T extends U ? X : Y. هذا يضمن أن النوع الشرطي لا يتوزع على أعضاء الاتحاد داخل T.

المشاركات ذات الصلة

المقال الأصلي:
TypeScript: تحديات متقدمة في قيود الأنواع، حل الوحدات، واستنتاج العموميات
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

معالجة أخطاء تثبيت Playwright: حلول عملية لـ npx playwright install

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 6 Jul 2026 10:27:51 +0100

في عالم تطوير الويب الحديث، أصبحت أدوات الأتمتة والاختبار ضرورية لضمان جودة التطبيقات. Playwright، مكتبة أتمتة المتصفحات من Microsoft، تبرز كخيار قوي بفضل دعمها لمتصفحات متعددة وقدراتها المتقدمة. ومع ذلك، قد يواجه المطورون أحيانًا تحديات أثناء عملية التثبيت الأولية، خاصة عند تشغيل الأمر npx playwright install. يهدف هذا المقال إلى تقديم حلول عملية ومباشرة لأكثر الأخطاء شيوعًا التي قد تواجهها، مما يضمن تجربة تثبيت سلسة.

فهم مشكلة "npx playwright install"

عند تشغيل الأمر npx playwright install، يقوم Playwright بتنزيل وتثبيت الثنائيات الخاصة بالمتصفحات (Chromium، Firefox، WebKit) التي يحتاجها لتشغيل الاختبارات. هذه العملية تتطلب اتصالاً مستقرًا بالإنترنت، وأذونات كافية للملفات، وإصدارًا متوافقًا من Node.js. يمكن أن تؤدي أي مشكلة في هذه المتطلبات إلى فشل التثبيت وظهور رسائل خطأ مختلفة.

معلومة!
Playwright لا يقوم بتثبيت المتصفحات الفعلية كنظام تشغيل، بل يقوم بتنزيل نسخ مخصصة ومحسّنة للاستخدام مع Playwright.

حلول عملية لمشكلة التثبيت

التحقق من إصدار Node.js و npm

يتطلب Playwright إصدارات حديثة من Node.js و npm ليعمل بشكل صحيح. قد يؤدي استخدام إصدار قديم إلى مشكلات في التوافق أو أخطاء أثناء التثبيت.

التحقق من الإصدارات الحالية:
```
node -v
npm -v
```
تحديث Node.js و npm:
إذا كانت الإصدارات قديمة، يوصى بتحديثها. يمكنك استخدام مدير الإصدارات مثل NVM (Node Version Manager) أو n.
```
npm install -g n
sudo n latest
```
أو باستخدام NVM:
```
nvm install node
nvm use node
```

معالجة مشكلات الشبكة والوكيل (Proxy)

تُعد مشكلات الاتصال بالشبكة من الأسباب الشائعة لفشل التنزيل. قد تكون جدار الحماية (Firewall)، أو الشبكات الافتراضية الخاصة (VPN)، أو خوادم الوكيل (Proxy) في بيئات الشركات هي السبب.

تعطيل مؤقت لجدار الحماية/VPN:
حاول تعطيل جدار الحماية أو VPN مؤقتًا ثم أعد تشغيل أمر التثبيت.
تكوين إعدادات الوكيل:
إذا كنت تستخدم خادم وكيل، تأكد من تكوينه بشكل صحيح لـ npm ولبيئة التشغيل:
```
export HTTP_PROXY="http://your.proxy.com:port"
export HTTPS_PROXY="http://your.proxy.com:port"
npm config set proxy http://your.proxy.com:port
npm config set https-proxy http://your.proxy.com:port
```
في نظام Windows، استخدم set بدلاً من export.
تحديد مضيف تنزيل Playwright:
في بعض الحالات، قد تحتاج إلى تحديد مضيف تنزيل Playwright يدويًا إذا كانت هناك مشكلات في الوصول إلى الخوادم الافتراضية:
```
export PLAYWRIGHT_DOWNLOAD_HOST="https://playwright.azureedge.net"
```

أذونات الملفات والمجلدات

يمكن أن تظهر أخطاء الأذونات (مثل EACCES) إذا لم يكن لدى المستخدم الحالي الصلاحيات الكافية لكتابة الملفات في مجلدات النظام أو مجلدات npm.

استخدام sudo (لأنظمة Linux/macOS):
حاول تشغيل الأمر بصلاحيات المدير:
```
sudo npx playwright install
```
تكوين unsafe-perm (بحذر):
يمكنك تجاوز مشكلات الأذونات عن طريق تعيين unsafe-perm إلى true في npm، ولكن هذا يقلل من الأمان.
```
npm config set unsafe-perm true
```
تحذير!
استخدام unsafe-perm true قد يقلل من أمان نظامك. استخدمه بحذر وفقط إذا كنت تفهم المخاطر.

مسح ذاكرة التخزين المؤقت لـ npm

قد تتسبب ذاكرة التخزين المؤقت لـ npm التالفة أو القديمة في حدوث أخطاء أثناء التثبيت.

مسح ذاكرة التخزين المؤقت:
```
npm cache clean --force
```
إعادة المحاولة:
بعد مسح ذاكرة التخزين المؤقت، أعد تشغيل أمر التثبيت:
```
npx playwright install
```

إعادة تثبيت Playwright

في بعض الأحيان، قد يكون هناك تلف في تثبيت Playwright نفسه. يمكن أن تساعد إعادة التثبيت النظيفة في حل المشكلة.

إلغاء تثبيت Playwright:
```
npm uninstall playwright
```
إعادة تثبيت Playwright:
```
npm install playwright
```
تثبيت المتصفحات:
```
npx playwright install
```

تثبيت المتصفحات يدوياً مع التبعيات

إذا استمرت المشكلات، يمكنك محاولة تثبيت المتصفحات بشكل صريح، مع التأكد من تثبيت تبعيات النظام (خاصة في أنظمة Linux).

تثبيت المتصفحات مع تبعيات النظام (لأنظمة Linux):
```
npx playwright install --with-deps
```
معلومة!
الخيار --with-deps يقوم بتثبيت تبعيات نظام التشغيل المطلوبة لتشغيل المتصفحات (مثل مكتبات الرسوميات).
تثبيت متصفحات محددة:
إذا كنت تحتاج فقط إلى متصفحات معينة، يمكنك تحديدها:
```
npx playwright install chromium firefox webkit
```

التحقق من مساحة القرص

تتطلب ثنائيات المتصفحات مساحة تخزين كبيرة. تأكد من وجود مساحة كافية على القرص الصلب قبل محاولة التثبيت.

نصيحة!
بعد تطبيق أي من هذه الحلول، يوصى دائمًا بإعادة تشغيل الطرفية أو بيئة التطوير قبل محاولة التثبيت مرة أخرى لضمان تطبيق جميع التغييرات في المتغيرات البيئية أو الإعدادات.

الخاتمة

تُعد أخطاء التثبيت جزءًا طبيعيًا من عملية تطوير البرمجيات، وفهم الأسباب الجذرية لها هو مفتاح الحل. من خلال اتباع الخطوات المذكورة أعلاه، يمكنك معالجة معظم المشكلات المتعلقة بـ npx playwright install واستئناف عملك في أتمتة الويب بثقة. تذكر دائمًا التحقق من وثائق Playwright الرسمية للحصول على أحدث المعلومات وأكثرها تفصيلاً.

لماذا يفشل أمر npx playwright install عادة؟

يفشل هذا الأمر عادة بسبب مشكلات في الاتصال بالشبكة (جدار الحماية، الوكيل)، أو أذونات الملفات غير الكافية، أو إصدار Node.js غير المتوافق، أو ذاكرة التخزين المؤقت لـ npm التالفة.

ماذا يفعل الخيار --with-deps عند تثبيت Playwright؟

الخيار --with-deps (المتاح بشكل أساسي لأنظمة Linux) يقوم بتثبيت تبعيات نظام التشغيل الإضافية المطلوبة لتشغيل المتصفحات، مثل مكتبات الرسوميات، والتي لا يتم تضمينها عادةً في تثبيت Playwright الأساسي.

المشاركات ذات الصلة

المقال الأصلي:
معالجة أخطاء تثبيت Playwright: حلول عملية لـ npx playwright install
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

معالجة مشكلة Node.js: تجميد مطابقة الملفات الديناميكية في الحلقات غير المتزامنة

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 29 Jun 2026 10:27:46 +0100

في بيئات Node.js، قد يواجه المطورون تحديات خطيرة عند التعامل مع مطابقة الملفات الديناميكية بناءً على مدخلات المستخدم ضمن حلقات غير متزامنة. يمكن أن يؤدي هذا السيناريو إلى تجميد التطبيق أو تشغيل جميع العمال في نفس الوقت، مما يؤثر بشكل كبير على الأداء واستجابة النظام. يستكشف هذا المقال الأسباب الجذرية لهذه المشكلة ويقدم حلولاً عملية لتجاوزها.

السبب الجذري للمشكلة

تنشأ مشكلة التجميد أو التشغيل المتزامن لجميع العمال عادةً من مزيج من العوامل:

العمليات المتزامنة في حلقة الحدث: على الرغم من أن Node.js يعتمد على نموذج I/O غير المحظور، إلا أن بعض العمليات مثل قراءة الملفات الكبيرة بشكل متزامن (باستخدام fs.readFileSync) أو تنفيذ تعبيرات منتظمة (Regex) معقدة على سلاسل نصية طويلة، يمكن أن تحظر حلقة الحدث (Event Loop) وتجعل التطبيق غير مستجيب.
الحلقات غير المتزامنة غير الفعالة: عند استخدام حلقات غير متزامنة مثل for...of مع await داخلها، أو Promise.all مع عدد كبير من الوعود التي تتضمن عمليات I/O مكثفة أو معالجة بيانات، يمكن أن يؤدي ذلك إلى استنزاف موارد النظام إذا لم يتم التعامل معها بكفاءة.
مطابقة الملفات الديناميكية: تتطلب مطابقة الملفات الديناميكية (مثل البحث عن ملفات تطابق نمط معين بناءً على إدخال المستخدم) الوصول إلى نظام الملفات (File System) بشكل متكرر، وهو ما يمكن أن يكون مكلفاً من حيث الأداء.
نموذج العامل الواحد (Single-Threaded Model): على الرغم من وجود وحدات مثل cluster و worker_threads، فإن Node.js في جوهره يعمل على خيط واحد (Single Thread) لحلقة الحدث. أي عملية تحظر هذا الخيط ستؤثر على استجابة التطبيق بأكمله.

حلول عملية

1. تفريغ المهام الثقيلة باستخدام Worker Threads

لحل مشكلة حظر حلقة الحدث، يمكن نقل العمليات كثيفة الاستخدام لوحدة المعالجة المركزية (CPU-intensive) مثل مطابقة التعبيرات المنتظمة المعقدة أو عمليات I/O المكثفة إلى Worker Threads. يسمح ذلك لحلقة الحدث الرئيسية بالبقاء حرة ومستجيبة.


const { parentPort } = require('worker_threads');
const fs = require('fs').promises;
const path = require('path');

parentPort.on('message', async ({ directory, pattern }) => {
  try {
    const files = await fs.readdir(directory);
    const regex = new RegExp(pattern, 'i'); // 'i' for case-insensitive
    const matchedFiles = files.filter(file => regex.test(file));
    parentPort.postMessage({ status: 'success', matchedFiles });
  } catch (error) {
    parentPort.postMessage({ status: 'error', message: error.message });
  }
});


const { Worker } = require('worker_threads');

async function findFiles(directory, pattern) {
  return new Promise((resolve, reject) => {
    const worker = new Worker('./worker.js');
    worker.postMessage({ directory, pattern });
    worker.on('message', (message) => {
      if (message.status === 'success') {
        resolve(message.matchedFiles);
      } else {
        reject(new Error(message.message));
      }
      worker.terminate();
    });
    worker.on('error', reject);
    worker.on('exit', (code) => {
      if (code !== 0) reject(new Error(`Worker stopped with exit code ${code}`));
    });
  });
}

// Example usage
// findFiles('/path/to/search', 'user_input_pattern')
//   .then(files => console.log('Matched files:', files))
//   .catch(err => console.error('Error:', err));

2. استخدام I/O غير المتزامن للملفات

تأكد دائماً من استخدام واجهات برمجة تطبيقات I/O غير المتزامنة للملفات (مثل fs.promises) لتجنب حظر حلقة الحدث. تجنب fs.readFileSync و fs.readdirSync في سياقات الويب أو التطبيقات التي تتطلب استجابة عالية.


const fs = require('fs').promises;

async function getFileContent(filePath) {
  try {
    const content = await fs.readFile(filePath, 'utf8');
    return content;
  } catch (error) {
    console.error(`Failed to read file ${filePath}:`, error);
    throw error;
  }
}

3. مطابقة الملفات بكفاءة

بدلاً من قراءة جميع الملفات ثم تطبيق التعبير المنتظم، فكر في استراتيجيات أكثر كفاءة:

استخدام مكتبات Glob: مكتبات مثل fast-glob يمكنها التعامل مع أنماط المطابقة المعقدة بكفاءة عالية.
الفهرسة المسبقة (Pre-indexing): إذا كانت قائمة الملفات لا تتغير كثيراً، يمكنك فهرسة أسمائها مسبقاً في الذاكرة أو قاعدة بيانات لعمليات البحث السريعة.
تحسين التعبيرات المنتظمة: تأكد من أن التعبيرات المنتظمة التي تستخدمها محسّنة ولا تتسبب في ReDoS (Regular Expression Denial of Service).

4. Debouncing لمدخلات المستخدم

إذا كانت مطابقة الملفات يتم تشغيلها بواسطة إدخال المستخدم (مثل حقل بحث)، فاستخدم تقنية Debouncing لتقليل عدد مرات تشغيل عملية البحث. هذا يمنع إرسال طلبات متعددة في وقت قصير جداً.


function debounce(func, delay) {
  let timeout;
  return function(...args) {
    const context = this;
    clearTimeout(timeout);
    timeout = setTimeout(() => func.apply(context, args), delay);
  };
}

// Example usage in a web context (conceptual)
// const searchInput = document.getElementById('searchBox');
// searchInput.addEventListener('keyup', debounce(async (event) => {
//   const searchTerm = event.target.value;
//   // Trigger file matching logic here
//   console.log('Searching for:', searchTerm);
// }, 300));

5. تخزين النتائج مؤقتاً (Caching)

إذا كانت عمليات البحث عن الملفات المتكررة لنفس النمط أو في نفس الدليل تعطي نفس النتائج، ففكر في تخزين النتائج مؤقتاً. يمكن أن يقلل هذا بشكل كبير من حمل I/O على نظام الملفات.


const fileMatchCache = new Map(); // Store results: Map

async function getCachedMatchedFiles(directory, pattern) {
  const cacheKey = `${directory}:${pattern}`;
  if (fileMatchCache.has(cacheKey)) {
    console.log('Returning from cache:', cacheKey);
    return fileMatchCache.get(cacheKey);
  }

  // If not in cache, perform the search (e.g., using a worker thread)
  const matchedFiles = await findFiles(directory, pattern); // findFiles from worker example
  fileMatchCache.set(cacheKey, matchedFiles);
  return matchedFiles;
}

معلومة!
تأكد من تطبيق سياسة إبطال ذاكرة التخزين المؤقت (Cache Invalidation) إذا كانت الملفات في الدليل تتغير بشكل متكرر.

6. تحديد العمليات المتزامنة

عند التعامل مع عدد كبير من الملفات أو المهام، استخدم أدوات مثل p-limit أو p-queue للتحكم في عدد العمليات غير المتزامنة التي تعمل في وقت واحد. هذا يمنع استنزاف موارد النظام.


const pLimit = require('p-limit');
const limit = pLimit(5); // Allow up to 5 concurrent operations

async function processFile(filePath) {
  // Simulate heavy file processing
  await new Promise(resolve => setTimeout(resolve, 100)); 
  return `Processed: ${filePath}`;
}

async function processAllFiles(filePaths) {
  const tasks = filePaths.map(filePath => limit(() => processFile(filePath)));
  const results = await Promise.all(tasks);
  return results;
}

// Example usage:
// processAllFiles(['file1.txt', 'file2.txt', ..., 'fileN.txt'])
//   .then(results => console.log(results));

ملخص: لمعالجة مشكلة تجميد Node.js بسبب مطابقة الملفات الديناميكية، يجب التركيز على تفريغ المهام كثيفة الاستخدام لوحدة المعالجة المركزية، واستخدام I/O غير المتزامن، وتحسين خوارزميات المطابقة، وتطبيق تقنيات مثل Debouncing والتخزين المؤقت، وتحديد العمليات المتزامنة.

المشاركات ذات الصلة

المقال الأصلي:
معالجة مشكلة Node.js: تجميد مطابقة الملفات الديناميكية في الحلقات غير المتزامنة
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

Docker: ضمان استمرارية نشر الوسائط على AWS ومنع الأعطال

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 22 Jun 2026 10:27:56 +0100

إن مشكلة "المشارك الأول يعمل، والمشارك الثاني يعطل نشر الوسائط على AWS" هي سيناريو كلاسيكي لمتلازمة "يعمل على جهازي". غالباً ما تنبع هذه المشكلة من تناقضات بيئية، حيث تختلف التبعيات، التكوينات، أو إعدادات نظام التشغيل الأساسية بين بيئات التطوير وإعداد AWS الإنتاجي، أو حتى بين أجهزة المطورين المختلفين. يقدم Docker حلاً قوياً من خلال تغليف التطبيقات وتبعاتها في حاويات محمولة ومعزولة، مما يضمن بيئة تنفيذ متسقة عبر جميع المراحل والمشاركين.

تحليل المشكلة

تعاني طرق النشر التقليدية في كثير من الأحيان من:

جحيم التبعيات (Dependency Hell): قد تتعارض الإصدارات المختلفة من المكتبات أو أوقات التشغيل المطلوبة بواسطة مكونات متنوعة.
انحراف البيئة (Environment Drift): لا يتم تكرار التكوينات أو التحديثات اليدوية على جهاز واحد على الأجهزة الأخرى.
عدم اتساق الأدوات: قد يستخدم المطورون إصدارات مختلفة من أدوات البناء، المترجمات، أو أنظمة التشغيل.
عدم تطابق التكوين: قد تختلف متغيرات البيئة، مسارات الملفات، أو سلاسل اتصال قاعدة البيانات.

تصبح هذه التناقضات حرجة في نشر الوسائط، حيث يجب تكوين برامج ترميز معينة، مكتبات، أو أدوات معالجة بدقة لتعمل بشكل صحيح. يمكن أن يؤدي أي انحراف طفيف إلى فشل عمليات التحويل، أو تحميلات معطلة، أو محتوى غير قابل للوصول.

Docker كحل جذري

يعالج Docker هذه التحديات من خلال مفهوم الحاويات:

التغليف: يتم تجميع التطبيق، جنباً إلى جنب مع جميع مكتباته، تبعياته، وملفات التكوين الخاصة به، في صورة Docker واحدة.
العزل: تعمل كل حاوية في بيئتها المعزولة الخاصة بها، مما يمنع التعارضات مع التطبيقات الأخرى أو النظام المضيف.
قابلية النقل: يمكن تشغيل نفس صورة Docker بشكل متسق على أي نظام مثبت عليه Docker، سواء كان جهاز كمبيوتر محمول للمطور، خادم اختبار، أو مثيل إنتاج على AWS.

هذا يعني أنه إذا قام المشارك الأول بنشر الوسائط بنجاح باستخدام تطبيق Dockerized، فسيستخدم المشارك الثاني نفس صورة Docker بالضبط، مما يضمن نفس البيئة ويمنع الأعطال غير المتوقعة.

خطوات التنفيذ العملي لنشر الوسائط على AWS

تحديد متطلبات التطبيق: حدد جميع التبعيات، مكتبات الوسائط (مثل FFmpeg)، إصدارات وقت التشغيل (مثل Node.js، Python)، وأي أدوات مساعدة يحتاجها تطبيق نشر الوسائط.

إنشاء Dockerfile: اكتب Dockerfile لتحديد كيفية بناء صورة Docker لتطبيقك. يجب أن يتضمن هذا تثبيت جميع التبعيات، نسخ كود التطبيق، وتحديد أمر التشغيل.


# استخدم صورة أساسية مناسبة (مثلاً، Node.js أو Python)
FROM node:18-alpine

# تعيين دليل العمل داخل الحاوية
WORKDIR /app

# نسخ ملفات تعريف التبعيات وتثبيتها
COPY package.json package-lock.json ./
RUN npm install

# تثبيت FFmpeg (مثال لتطبيق وسائط)
RUN apk add --no-cache ffmpeg

# نسخ كود التطبيق
COPY . .

# تعريض المنفذ الذي يستمع إليه التطبيق
EXPOSE 3000

# أمر تشغيل التطبيق
CMD ["npm", "start"]

بناء صورة Docker: قم ببناء الصورة محلياً للتأكد من أنها تعمل كما هو متوقع.
```
docker build -t media-publisher:latest .
        
```
اختبار الصورة محلياً: شغل الحاوية محلياً واختبر وظائف نشر الوسائط.
```
docker run -p 3000:3000 media-publisher:latest
        
```

دفع الصورة إلى Amazon ECR: بعد التأكد من أن الصورة تعمل، قم بإنشاء مستودع في Amazon Elastic Container Registry (ECR) وادفع الصورة إليه. هذا يضمن أن جميع المشاركين وبيئات AWS يمكنهم الوصول إلى نفس الصورة الموثوقة.


aws ecr get-login-password --region your-region | docker login --username AWS --password-stdin your-aws-account-id.dkr.ecr.your-region.amazonaws.com
docker tag media-publisher:latest your-aws-account-id.dkr.ecr.your-region.amazonaws.com/media-publisher:latest
docker push your-aws-account-id.dkr.ecr.your-region.amazonaws.com/media-publisher:latest

النشر على AWS ECS أو EKS: استخدم Amazon Elastic Container Service (ECS) أو Amazon Elastic Kubernetes Service (EKS) لنشر وإدارة الحاويات. قم بإنشاء تعريف مهمة (Task Definition) في ECS أو ملف نشر (Deployment) في EKS يشير إلى صورة Docker المخزنة في ECR.
معلومة!
استخدم متغيرات البيئة (Environment Variables) في تعريف مهمة ECS أو ملف نشر EKS لإدارة الإعدادات الخاصة بالبيئة (مثل مفاتيح API، عناوين URL لقواعد البيانات) دون تعديل الصورة نفسها.

من خلال هذه الخطوات، يتم توحيد بيئة نشر الوسائط. عندما يعمل مشارك جديد على المشروع، فإنه يسحب نفس صورة Docker من ECR، مما يضمن أن لديه نفس الإعدادات والتبعيات التي عملت للمشارك الأول، وبالتالي يمنع الأعطال الناتجة عن عدم التوافق البيئي.

الفوائد الرئيسية:

التناسق: بيئة تشغيل متطابقة عبر جميع مراحل التطوير والاختبار والإنتاج.
العزل: منع تعارضات التبعيات بين التطبيقات المختلفة.
السرعة: تسريع عملية الإعداد للمطورين الجدد وتقليل وقت حل المشكلات البيئية.
الموثوقية: تقليل احتمالية حدوث أخطاء "يعمل على جهازي" بشكل كبير.

الخاتمة

إن مشكلة "المشارك الأول يعمل، والمشارك الثاني يعطل نشر الوسائط على AWS" هي عَرَض كلاسيكي لغياب التوحيد البيئي. يوفر Docker حلاً قوياً وفعالاً لهذه المشكلة من خلال تمكين فرق العمل من بناء ونشر تطبيقاتهم في بيئات معزولة ومتسقة. من خلال تبني ممارسات Docker، يمكن للمؤسسات ضمان استمرارية عمليات نشر الوسائط على AWS، وتقليل وقت التوقف عن العمل، وتحسين كفاءة فريق التطوير بشكل كبير.

ما هو Docker وما فائدته في هذا السيناريو؟

Docker هو منصة لإنشاء وتشغيل وإدارة الحاويات. في هذا السيناريو، يسمح Docker بتغليف تطبيق نشر الوسائط وجميع تبعياته في "صورة" واحدة، مما يضمن أن البيئة التي يعمل فيها التطبيق متطابقة تماماً عبر جميع المطورين وبيئات النشر على AWS، وبالتالي يمنع الأعطال الناتجة عن اختلاف البيئات.

هل Docker معقد للمطورين الجدد؟

قد يتطلب Docker منحنى تعلم أولياً، لكن الفوائد التي يقدمها من حيث التناسق والتبسيط في الإعداد تفوق التعقيد الأولي. بمجرد إعداد Dockerfile وصورة التطبيق، يصبح تشغيل التطبيق للمطورين الجدد أمراً بسيطاً للغاية باستخدام أمر docker run واحد، مما يقلل بشكل كبير من مشاكل إعداد البيئة.

المشاركات ذات الصلة

المقال الأصلي:
Docker: ضمان استمرارية نشر الوسائط على AWS ومنع الأعطال
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

React.js و TypeScript: التوافق الأمثل لتطوير الواجهة الأمامية

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Fri, 19 Jun 2026 22:33:54 +0100

في عالم تطوير الواجهة الأمامية سريع التطور، يبحث المطورون باستمرار عن الأدوات والتقنيات التي تعزز الكفاءة، وتحسن جودة الكود، وتضمن قابلية الصيانة على المدى الطويل. من بين هذه الأدوات، يبرز التوافق بين مكتبة React.js وإطار عمل TypeScript كحل قوي يقدم مزايا لا تقدر بثمن. يهدف هذا المقال إلى تحليل معمق لكيفية تحقيق هذا التوافق للمزايا القصوى في تطوير الواجهة الأمامية.

ما هو React.js؟

React.js هي مكتبة جافاسكريبت مفتوحة المصدر لبناء واجهات المستخدم، تم تطويرها بواسطة فيسبوك. تشتهر React بنهجها القائم على المكونات (Component-Based Architecture)، والذي يسمح للمطورين بتقسيم واجهة المستخدم إلى أجزاء صغيرة ومستقلة وقابلة لإعادة الاستخدام. هذا النهج يبسط عملية التطوير ويجعل إدارة واجهات المستخدم المعقدة أسهل بكثير. تعتمد React على مفهوم "الواجهة الافتراضية" (Virtual DOM) لتحسين الأداء، حيث تقوم بتحديث الأجزاء الضرورية فقط من الواجهة عند حدوث تغييرات.

ما هو TypeScript؟

TypeScript هي لغة برمجة مفتوحة المصدر تم تطويرها وصيانتها بواسطة مايكروسوفت. إنها مجموعة شاملة من جافاسكريبت (Superset of JavaScript)، مما يعني أن أي كود جافاسكريبت صالح هو أيضًا كود TypeScript صالح. الميزة الأساسية لـ TypeScript هي إضافة نظام الأنواع الثابتة (Static Typing) إلى جافاسكريبت. هذا يسمح للمطورين بتحديد أنواع المتغيرات، والدوال، وخصائص الكائنات أثناء مرحلة التطوير، مما يساعد على اكتشاف الأخطاء المحتملة قبل تشغيل الكود.

لماذا ندمج React.js و TypeScript؟

دمج React.js مع TypeScript ليس مجرد خيار، بل أصبح معيارًا صناعيًا للعديد من المشاريع الكبيرة والمعقدة. هذا التوافق يوفر مجموعة من الفوائد التي تعزز تجربة التطوير وجودة المنتج النهائي.

جودة الكود المحسنة

يعد نظام الأنواع الثابتة في TypeScript حجر الزاوية في تحسين جودة الكود. عند استخدام TypeScript مع React، يمكن للمطورين تحديد أنواع الخصائص (props) والحالة (state) للمكونات بدقة. هذا يقلل بشكل كبير من الأخطاء الشائعة التي تحدث بسبب عدم تطابق الأنواع أو تمرير بيانات غير متوقعة بين المكونات.

معلومة!
يساعد TypeScript في اكتشاف الأخطاء في وقت الترجمة (compile-time) بدلاً من وقت التشغيل (runtime)، مما يوفر الوقت والجهد في تصحيح الأخطاء.

تجربة مطور أفضل

يوفر TypeScript ميزات قوية لتحسين تجربة المطور (Developer Experience):

الإكمال التلقائي (Autocompletion): بفضل معلومات الأنواع، يمكن للمحررات الذكية (مثل VS Code) توفير اقتراحات دقيقة للإكمال التلقائي لأسماء الخصائص والدوال، مما يسرع عملية الكتابة ويقلل من الأخطاء المطبعية.
إعادة الهيكلة الآمنة (Safer Refactoring): عند إعادة هيكلة الكود، يمكن لـ TypeScript تحديد جميع الأماكن التي تحتاج إلى تحديث بسبب تغيير في نوع أو اسم خاصية، مما يضمن أن التغييرات لا تكسر أجزاء أخرى من التطبيق.
وثائق ذاتية (Self-Documenting Code): تحديد الأنواع يجعل الكود أكثر وضوحًا وقابلية للقراءة، حيث يمكن للمطورين الآخرين فهم الغرض من المتغيرات والخصائص دون الحاجة إلى وثائق خارجية مكثفة.

قابلية صيانة وتوسع أفضل

مع نمو حجم التطبيق وتعقيده، تصبح قابلية الصيانة والتوسع أمرًا بالغ الأهمية. يساعد TypeScript في تحقيق ذلك من خلال:

بنية كود واضحة: الأنواع الواضحة تجعل الكود أسهل في الفهم والصيانة من قبل فرق متعددة من المطورين.
تقليل الأخطاء: الكشف المبكر عن الأخطاء يقلل من عدد المشكلات التي تظهر في بيئة الإنتاج، مما يقلل من تكاليف الصيانة.
دعم المشاريع الكبيرة: في المشاريع التي تضم مئات المكونات وآلاف الأسطر من الكود، يوفر TypeScript شبكة أمان تمنع الأخطاء الشائعة وتسهل إدارة التعقيد.

التطبيق العملي: إعداد مشروع React مع TypeScript

بدء مشروع React مع TypeScript أمر بسيط نسبيًا. يمكن استخدام أداة create-react-app أو Vite لإنشاء قالب مشروع جاهز.

التثبيت

لإنشاء مشروع React مع TypeScript باستخدام create-react-app، يمكنك استخدام الأمر التالي:

npx create-react-app my-app --template typescript

أو باستخدام Vite، وهو أسرع وأكثر حداثة:

npm create vite@latest my-vite-app -- --template react-ts

مثال على مكون React مع TypeScript

لنلقِ نظرة على مثال بسيط لمكون React مكتوب بـ TypeScript. سنقوم بتعريف واجهة (interface) لخصائص المكون لضمان تمرير البيانات الصحيحة.

// تعريف واجهة لخصائص المكون
interface GreetingProps {
  name: string;
  age?: number; // خاصية اختيارية
}

// تعريف المكون الوظيفي باستخدام TypeScript
const Greeting: React.FC<GreetingProps> = ({ name, age }) => {
  return (
    <div>
      <h2>Hello, {name}!</h2>
      {age && <p>You are {age} years old.</p>}
    </div>
  );
};

export default Greeting;

في هذا المثال، قمنا بتعريف الواجهة GreetingProps التي تحدد أن المكون يتوقع خاصية name من نوع string، وخاصية age اختيارية من نوع number. هذا يضمن أن أي استخدام للمكون Greeting يجب أن يلتزم بهذه الأنواع.

import React from 'react';
import Greeting from './components/Greeting';

function App() {
  return (
    <div className="App">
      <Greeting name="Alice" age={30} />
      <Greeting name="Bob" /> // العمر اختياري، لذا هذا صالح
      <Greeting name={123} /> // سيحدث خطأ في الترجمة: 'name' يجب أن يكون string
    </div>
  );
}

export default App;

تحذير!
إذا حاولت تمرير قيمة غير صحيحة لخاصية name (مثل رقم بدلاً من نص)، فسيقوم TypeScript بالإبلاغ عن خطأ في وقت الترجمة، مما يمنع هذا النوع من الأخطاء من الوصول إلى بيئة التشغيل.

نصيحة!
استخدم React.FC (اختصار لـ Function Component) لتحديد نوع المكون الوظيفي، والذي يوفر أنواعًا تلقائية لـ children و displayName وغيرها.

هل يمكنني تحويل مشروع React موجود إلى TypeScript؟

نعم، يمكن تحويل مشروع React موجود إلى TypeScript تدريجيًا. تبدأ العملية عادةً بإعادة تسمية ملفات .js إلى .tsx أو .ts وتثبيت حزم TypeScript اللازمة، ثم البدء في إضافة الأنواع تدريجيًا إلى المكونات والدوال.

ما هو الفرق الرئيسي بين TypeScript و JavaScript؟

الفرق الرئيسي هو أن TypeScript يضيف نظام الأنواع الثابتة إلى JavaScript. هذا يعني أنه يمكنك تحديد أنواع المتغيرات والدوال، مما يساعد على اكتشاف الأخطاء في وقت الترجمة ويوفر تجربة تطوير أفضل مع ميزات مثل الإكمال التلقائي وإعادة الهيكلة الآمنة. JavaScript هي لغة ديناميكية الأنواع.

هل استخدام TypeScript يبطئ عملية التطوير؟

في البداية، قد يستغرق الأمر بعض الوقت الإضافي لتعلم TypeScript وتحديد الأنواع. ومع ذلك، على المدى الطويل، يؤدي TypeScript إلى تسريع عملية التطوير بشكل كبير من خلال تقليل الأخطاء، وتحسين قابلية القراءة، وتوفير أدوات تطوير قوية، مما يوفر وقتًا ثمينًا في تصحيح الأخطاء والصيانة.

المشاركات ذات الصلة

المقال الأصلي:
React.js و TypeScript: التوافق الأمثل لتطوير الواجهة الأمامية
المصدر: صِوان AI
شكر خاص لـ GEMINI و جمال الحزازي.

إدارة الثوابت والتحقق منها في واجهات برمجة تطبيقات Express.js باستخدام TypeScript

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 15 Jun 2026 10:27:58 +0100

شفافية المحتوى: تم توليد وتنسيق هذا المقال آلياً عبر محرك Sawan AI لتقديم محتوى تقني دقيق، مباشر، وخالٍ من الحشو المزعج.

في تطوير واجهات برمجة التطبيقات (APIs) باستخدام Express.js و TypeScript، يعد تعريف الثوابت وإدارتها بشكل فعال أمرًا بالغ الأهمية للحفاظ على جودة الكود، وتحسين قابلية القراءة، وتقليل الأخطاء المحتملة. يركز هذا المقال على تقديم حلول عملية لتعريف قوائم الثوابت والتحقق من أن قيمة متغير ما تقع ضمن هذه القوائم، مع التركيز على أفضل الممارسات الهندسية.

لماذا تعريف الثوابت في واجهات برمجة تطبيقات TypeScript Express؟

يساهم تعريف الثوابت في تحسين العديد من جوانب جودة الكود. أولاً، يزيد من قابلية القراءة من خلال استبدال "الأرقام السحرية" أو السلاسل النصية المتكررة بأسماء ذات معنى. ثانيًا، يعزز سهولة الصيانة؛ فإذا تغيرت قيمة ثابت، يكفي تعديله في مكان واحد فقط. أخيرًا، ومع استخدام TypeScript، توفر الثوابت التحقق من النوع (Type Safety) في وقت التصريف، مما يقلل بشكل كبير من الأخطاء في وقت التشغيل.

معلومة!
يُعد استخدام TypeScript مع Express.js ميزة قوية، حيث يضيف طبقة من الأمان والوضوح إلى تطبيقك، خاصة عند التعامل مع البيانات المدخلة والمخرجة.

تعريف قوائم الثوابت في TypeScript

هناك عدة طرق لتعريف قوائم الثوابت في TypeScript، كل منها يناسب سيناريوهات مختلفة. سنستعرض أبرز هذه الطرق مع أمثلة عملية.

1. استخدام التعدادات (Enums)

تُعد التعدادات طريقة ممتازة لتعريف مجموعة من القيم المتصلة. يمكن أن تكون قيمها رقمية أو نصية.


<mark class='block' data-before='تعريف تعداد للأدوار:'>export enum UserRole {
  ADMIN = "admin",
  EDITOR = "editor",
  VIEWER = "viewer",
}</mark>

<mark class='block' data-before='استخدام التعداد:'>const currentUserRole: UserRole = UserRole.ADMIN;
console.log(currentUserRole); // "admin"</mark>

معلومة!
تُنشئ التعدادات كائنات JavaScript في وقت التشغيل، مما يتيح لك الوصول إلى القيم والأسماء بسهولة.

2. استخدام أنواع الاتحاد (Union Types) مع الأنواع الحرفية (Literal Types)

هذه الطريقة توفر تعريفًا خفيف الوزن لمجموعة محددة من القيم، وتُعد مفيدة للتحقق من النوع في وقت التصريف.


<mark class='block' data-before='تعريف نوع اتحاد للأدوار:'>export type AllowedUserRole = "admin" | "editor" | "viewer";
</mark>
<mark class='block' data-before='استخدام نوع الاتحاد:'>const userPermission: AllowedUserRole = "editor";
// const invalidPermission: AllowedUserRole = "guest"; // خطأ في التصريف</mark>

3. استخدام مصفوفات أو كائنات `const` مع `as const`

عندما تحتاج إلى قائمة من الثوابت التي يمكن تكرارها أو استخدامها كمرجع في وقت التشغيل، فإن استخدام مصفوفات أو كائنات `const` مع `as const` هو الخيار الأمثل. يخبر `as const` TypeScript بمعاملة القيم كأنواع حرفية (literal types)، مما يجعل المصفوفة أو الكائن "للقراءة فقط" (read-only) ويحسن التحقق من النوع.


<mark class='block' data-before='تعريف مصفوفة ثوابت للحالات:'>export const VALID_ORDER_STATUSES = [
  "pending",
  "processing",
  "shipped",
  "delivered",
  "cancelled",
] as const;
</mark>
<mark class='block' data-before='تعريف كائن ثوابت لنقاط النهاية:'>export const API_ENDPOINTS = {
  USERS: "/api/users",
  PRODUCTS: "/api/products",
  ORDERS: "/api/orders",
} as const;
</mark>

تحذير!
استخدام `as const` يحول المصفوفة أو الكائن إلى نوع للقراءة فقط، مما يمنع التعديل غير المقصود على القيم في وقت التشغيل.

التحقق مما إذا كانت قيمة متغير موجودة في القائمة

بعد تعريف قوائم الثوابت، الخطوة التالية هي التحقق مما إذا كانت قيمة متغير معين تقع ضمن هذه القوائم. هذا أمر شائع في التحقق من صحة المدخلات (validation) في واجهات برمجة التطبيقات.

1. التحقق باستخدام التعدادات (Enums)

يمكنك استخدام `Object.values()` للحصول على مصفوفة من قيم التعداد ثم استخدام `.includes()` للتحقق.


import { Request, Response, NextFunction } from 'express';
import { UserRole } from '../constants/user-roles'; // افتراض أنك عرفت UserRole enum

<mark class='block green' data-before='+'>export const checkUserRole = (allowedRoles: UserRole[]) => {
  return (req: Request, res: Response, next: NextFunction) => {
    const userRole = req.headers['x-user-role'] as string; // افتراض أن الدور يأتي من الهيدر

    if (!userRole || !Object.values(UserRole).includes(userRole as UserRole)) {
      return res.status(403).send('Invalid or missing user role.');
    }

    if (!allowedRoles.includes(userRole as UserRole)) {
      return res.status(403).send('Access denied.');
    }

    next();
  };
};</mark>

<mark class='block' data-before='استخدام الوسيط في Express:'>// app.get('/admin-dashboard', checkUserRole([UserRole.ADMIN]), (req, res) => {
//   res.send('Welcome to the admin dashboard!');
// });</mark>

2. التحقق باستخدام مصفوفات `const`

تُعد هذه الطريقة الأكثر مباشرة وفعالية للتحقق من وجود قيمة في قائمة محددة من الثوابت، مع الحفاظ على التحقق من النوع بفضل `as const`.


import { VALID_ORDER_STATUSES } from '../constants/app-settings';

<mark class='block green' data-before='+'>export function isValidOrderStatus(status: string): status is typeof VALID_ORDER_STATUSES[number] {
  return (VALID_ORDER_STATUSES as readonly string[]).includes(status);
}</mark>

<mark class='block' data-before='مثال على الاستخدام في معالج مسار Express:'>import { Request, Response } from 'express';

export const updateOrderStatus = (req: Request, res: Response) => {
  const { id } = req.params;
  const { newStatus } = req.body;

  if (!isValidOrderStatus(newStatus)) {
    return res.status(400).send(`Invalid status: ${newStatus}. Allowed statuses are: ${VALID_ORDER_STATUSES.join(', ')}`);
  }

  // منطق تحديث الحالة في قاعدة البيانات
  res.status(200).send(`Order ${id} updated to ${newStatus}`);
};</mark>

حل!
باستخدام `status is typeof VALID_ORDER_STATUSES[number]`، فإننا نُعلم TypeScript أن المتغير `status`، بعد اجتياز التحقق، سيكون من أحد الأنواع الحرفية المحددة في المصفوفة، مما يوفر تحكمًا قويًا بالنوع.

يُعد تعريف الثوابت والتحقق منها جزءًا لا يتجزأ من بناء واجهات برمجة تطبيقات قوية وموثوقة باستخدام Express.js و TypeScript. من خلال تطبيق هذه الأساليب، يمكنك تعزيز قابلية صيانة الكود، وتقليل الأخطاء، وتحسين تجربة المطور بشكل عام.

المشاركات ذات الصلة

المقال الأصلي:
إدارة الثوابت والتحقق منها في واجهات برمجة تطبيقات Express.js باستخدام TypeScript
المصدر: صوان محور XYZ
شكر خاص لـ GEMINI و جمال الحزازي.

تبديد الغموض: إعلانات دوال ومكونات React TypeScript

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 1 Jun 2026 10:27:47 +0100

في عالم تطوير الواجهات الأمامية الحديث، أصبحت React.js و TypeScript ثنائيًا لا غنى عنه لإنشاء تطبيقات قوية وقابلة للصيانة. ومع ذلك، يواجه العديد من المطورين، خاصة الجدد منهم، بعض الالتباس عند محاولة فهم كيفية إعلان الدوال العادية ومكونات React الوظيفية (Function Components) باستخدام TypeScript. يهدف هذا المقال إلى تبديد هذا الغموض من خلال تقديم شروحات عملية وأمثلة واضحة.

فهم الالتباس الأساسي

ينبع الالتباس غالبًا من حقيقة أن كلًا من الدوال العادية ومكونات React الوظيفية هي في جوهرها دوال JavaScript. ومع ذلك، فإن سياقهما واستخدامهما في تطبيق React يختلفان بشكل كبير. تتوقع React أن تعيد المكونات الوظيفية عناصر JSX، بينما يمكن للدوال العادية أن تعيد أي نوع من البيانات أو لا تعيد شيئًا على الإطلاق (void). يضيف TypeScript طبقة من التحقق الثابت للنوع (Static Type Checking) التي تتطلب تحديد أنواع المدخلات والمخرجات بدقة، مما يجعل التمييز بينهما أكثر أهمية.

إعلان الدوال العادية في TypeScript

عند إعلان دالة JavaScript عادية في TypeScript، يجب تحديد أنواع المعاملات (Parameters) ونوع القيمة المرتجعة (Return Type) بشكل صريح. هذا يضمن أن الدالة تعمل بالبيانات المتوقعة وتعيد النوع الصحيح، مما يحسن من موثوقية الكود.

الدوال المسماة (Named Functions)

هذا هو الشكل التقليدي لإعلان الدالة، حيث يتم تحديد اسمها وأنواعها بوضوح.

function sum(a: number, b: number): number {
  return a + b;
}

function greet(name: string): void {
  console.log(`Hello, ${name}!`);
}

دوال السهم (Arrow Functions)

تُستخدم دوال السهم بشكل شائع في JavaScript الحديثة، ويمكن تطبيق نفس مبادئ تحديد الأنواع عليها.

const multiply = (a: number, b: number): number => a * b;

const logMessage = (message: string): void => {
  console.log(message);
};

معلومة!
تذكر أن هذه الدوال لا ترتبط بـ React بشكل مباشر؛ إنها مجرد دوال مساعدة يمكن استخدامها في أي جزء من تطبيقك.

إعلان مكونات React الوظيفية في TypeScript

تختلف مكونات React الوظيفية عن الدوال العادية في أنها تتلقى props كمعامل وحيد وتعيد عناصر JSX. هناك طريقتان رئيسيتان لتحديد أنواع هذه المكونات في TypeScript.

استخدام `React.FC` (أو `FC`)

كان React.FC (اختصار لـ Function Component) هو النمط الموصى به لتحديد أنواع مكونات React الوظيفية. يوفر هذا النوع بعض الميزات مثل تضمين نوع children بشكل ضمني.

import React from 'react';

interface GreetingProps {
  name: string;
  age?: number; // خاصية اختيارية
}

const Greeting: React.FC<GreetingProps> = ({ name, age }) => {
  return (
    <div>
      <h2>Hello, {name}!</h2>
      {age && <p>You are {age} years old.</p>}
    </div>
  );
};

export default Greeting;

تحذير!
على الرغم من شيوع React.FC، إلا أنه لم يعد النمط الموصى به في العديد من المشاريع الحديثة. أحد أسباب ذلك هو أنه يضيف children كخاصية اختيارية بشكل ضمني، مما قد يؤدي إلى سلوك غير متوقع إذا لم تكن تتوقع children دائمًا.

النمط المباشر (الموصى به)

يُعد تحديد أنواع الخصائص مباشرة في معامل الدالة هو النمط المفضل حاليًا. يمنحك هذا تحكمًا أكبر في أنواع الخصائص، بما في ذلك children.

import React from 'react';

interface ButtonProps {
  onClick: () => void;
  label: string;
  children?: React.ReactNode; // تحديد <code>children</code> بشكل صريح
}

const Button = ({ onClick, label, children }: ButtonProps) => {
  return (
    <button onClick={onClick}>
      {label}
      {children}
    </button>
  );
};

export default Button;

إذا كنت تتوقع دائمًا وجود children، يمكنك استخدام React.PropsWithChildren لتسهيل الأمر:

import React from 'react';

interface CardProps {
  title: string;
}

const Card = ({ title, children }: React.PropsWithChildren<CardProps>) => {
  return (
    <div style={{ border: '1px solid gray', padding: '10px' }}>
      <h3>{title}</h3>
      {children}
    </div>
  );
};

export default Card;

أفضل الممارسات والنصائح

كن صريحًا دائمًا: حدد أنواع المعاملات والقيم المرتجعة بوضوح لكل من الدوال العادية والمكونات.
تفضيل النمط المباشر للمكونات: استخدم تحديد أنواع الخصائص مباشرة في معامل الدالة لمكونات React الوظيفية. هذا يمنحك تحكمًا أفضل ووضوحًا أكبر.
استخدم React.PropsWithChildren عند الحاجة: إذا كان مكونك يتوقع children دائمًا، فإن React.PropsWithChildren طريقة نظيفة لإضافة هذا النوع دون كتابته يدويًا.
فهم React.ReactNode: استخدم React.ReactNode لخاصية children عندما يمكن أن تكون أي شيء يمكن لـ React عرضه (سلاسل، أرقام، عناصر JSX، مصفوفات من هذه الأنواع، إلخ).

حل!
باتباع هذه الإرشادات، يمكنك كتابة كود React و TypeScript أكثر وضوحًا وقابلية للصيانة، مما يقلل من الالتباس ويحسن تجربة التطوير.

المشاركات ذات الصلة

المقال الأصلي:
تبديد الغموض: إعلانات دوال ومكونات React TypeScript
المصدر: صوان محور XYZ
شكر خاص لـ GEMINI و جمال الحزازي.

تصدير Excel في Node.js: إضافة روابط تشعبية لألسنة العمل

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 25 May 2026 10:27:47 +0100

في سياق تطوير تطبيقات الويب التي تتطلب تصدير البيانات إلى ملفات Excel، يواجه المطورون أحيانًا الحاجة إلى إنشاء تجربة مستخدم أكثر تفاعلية. إحدى هذه المتطلبات هي القدرة على إضافة روابط تشعبية (hyperlinks) توجه المستخدم مباشرة إلى ألسنة عمل (sheets) محددة داخل نفس المصنف (workbook)، مما يسهل التنقل ويحسن من قابلية استخدام التقرير المصدر. هذا المقال يقدم حلولاً هندسية عملية لتحقيق ذلك باستخدام Node.js.

فهم الروابط التشعبية الداخلية في Excel

قبل الغوص في التفاصيل التقنية، من المهم فهم كيفية عمل الروابط التشعبية الداخلية في Excel. عندما تنشئ رابطًا تشعبيًا داخل Excel يوجه إلى ورقة عمل أخرى، فإنك في الواقع تشير إلى اسم الورقة متبوعًا بعلامة التعجب واسم الخلية (على سبيل المثال، #SheetName!A1). هذه الصيغة هي المفتاح الذي سنستخدمه لبرمجة هذه الروابط في Node.js.

معلومة!
تعتبر مكتبة ExcelJS خيارًا ممتازًا في Node.js للتعامل مع ملفات Excel (.xlsx)، حيث توفر واجهة برمجية قوية لإنشاء، قراءة، وتعديل المصنفات، بما في ذلك دعم الروابط التشعبية.

اختيار الأداة المناسبة

لتحقيق هذا الهدف في Node.js، سنعتمد على مكتبة ExcelJS نظرًا لمرونتها وقدرتها على التعامل مع تفاصيل بنية ملفات Excel. توفر هذه المكتبة وظائف مباشرة لإضافة الروابط التشعبية إلى الخلايا، مما يجعلها مثالية لمهمتنا.

تطبيق الروابط التشعبية لألسنة العمل باستخدام ExcelJS

الخطوات التالية توضح كيفية إنشاء مصنف Excel، إضافة ألسنة عمل متعددة، ثم إضافة رابط تشعبي في ورقة عمل رئيسية يوجه إلى ورقة عمل أخرى.

الإعداد الأولي وإنشاء المصنف

أولاً، قم بتثبيت ExcelJS إذا لم تكن قد فعلت ذلك بالفعل:

npm install exceljs

بعد التثبيت، يمكنك البدء بإنشاء مصنف جديد وإضافة ألسنة العمل.

const ExcelJS = require('exceljs');

async function createExcelWithTabLinks() {
    const workbook = new ExcelJS.Workbook();
    workbook.creator = 'Your Name';
    workbook.lastModifiedBy = 'Your Name';
    workbook.created = new Date();
    workbook.modified = new Date();

    // إضافة ألسنة العمل
    const summarySheet = workbook.addWorksheet('الملخص');
    const detailsSheet1 = workbook.addWorksheet('تفاصيل_1');
    const detailsSheet2 = workbook.addWorksheet('تفاصيل_2');

    // إعداد بعض البيانات في ألسنة العمل التفصيلية
    detailsSheet1.getCell('A1').value = 'هذه بيانات تفاصيل 1';
    detailsSheet2.getCell('A1').value = 'هذه بيانات تفاصيل 2';

    // ... (يمكنك إضافة المزيد من البيانات هنا) ...

    return { workbook, summarySheet, detailsSheet1, detailsSheet2 };
}

إضافة الروابط التشعبية إلى ورقة الملخص

الآن، سنقوم بإضافة الروابط التشعبية إلى ورقة "الملخص" التي ستوجه المستخدم إلى ألسنة العمل التفصيلية.

async function addHyperlinks(workbook, summarySheet) {
    // الرابط التشعبي لورقة 'تفاصيل_1'
    summarySheet.getCell('A1').value = {
        text: 'انتقل إلى تفاصيل 1',
        hyperlink: '#تفاصيل_1!A1' // الصيغة الأساسية للرابط الداخلي
    };
    summarySheet.getCell('A1').font = { color: { argb: 'FF0000FF' }, underline: true };

    // الرابط التشعبي لورقة 'تفاصيل_2'
    summarySheet.getCell('A2').value = {
        text: 'انتقل إلى تفاصيل 2',
        hyperlink: '#تفاصيل_2!A1'
    };
    summarySheet.getCell('A2').font = { color: { argb: 'FF0000FF' }, underline: true };

    // ... (يمكنك إضافة المزيد من الروابط هنا) ...
}

لاحظ كيف يتم تحديد خاصية hyperlink في كائن قيمة الخلية. القيمة '#تفاصيل_1!A1' هي التي تخبر Excel بالانتقال إلى الخلية A1 في ورقة العمل المسماة "تفاصيل_1".

تصدير ملف Excel

أخيرًا، قم بتصدير المصنف إلى ملف.

const path = require('path');

async function exportExcel() {
    const { workbook, summarySheet } = await createExcelWithTabLinks();
    await addHyperlinks(workbook, summarySheet);

    const filePath = path.join(__dirname, 'تقرير_مع_روابط.xlsx');
    await workbook.xlsx.writeFile(filePath);
    console.log(`تم إنشاء ملف Excel بنجاح في: ${filePath}`);
}

exportExcel().catch(error => {
    console.error('حدث خطأ أثناء إنشاء ملف Excel:', error);
});

تحذير!
تأكد من أن أسماء ألسنة العمل في خاصية hyperlink تتطابق تمامًا مع الأسماء الفعلية لألسنة العمل التي تم إنشاؤها. أي اختلاف سيؤدي إلى رابط غير صالح.

أفضل الممارسات والاعتبارات

لضمان تجربة تصدير Excel فعالة وموثوقة، يجب مراعاة بعض أفضل الممارسات:

التعامل مع أسماء الأوراق: إذا كانت أسماء ألسنة العمل تحتوي على مسافات أو أحرف خاصة، فإن Excel يتعامل معها تلقائيًا بوضعها بين علامات اقتباس مفردة (على سبيل المثال، #'My Sheet'!A1). ExcelJS يتعامل مع هذا بشكل جيد، ولكن من الجيد أن تكون على دراية به.
تجربة المستخدم: اجعل نص الرابط واضحًا ووصفيًا. يمكن أيضًا استخدام تنسيق الخط (اللون الأزرق والتسطير) لتمييز الروابط، كما هو موضح في الأمثلة.
الأداء: بالنسبة لملفات Excel الكبيرة جدًا أو التي تحتوي على عدد كبير من الروابط، قد تحتاج إلى تحسين الأداء من خلال معالجة الدفق (streaming) أو تقسيم العمليات.
التحقق من الأخطاء: أضف معالجة الأخطاء المناسبة عند كتابة الملف لضمان التعامل السليم مع أي مشكلات قد تنشأ أثناء عملية التصدير.

إن القدرة على توجيه المستخدمين بسلاسة داخل المستندات الكبيرة ليست مجرد ميزة، بل هي ضرورة لتحسين كفاءة استهلاك البيانات.
مطور برمجيات

حل!
باستخدام ExcelJS، يمكنك بسهولة إنشاء مصنفات Excel ديناميكية تحتوي على روابط تشعبية داخلية، مما يحول تقاريرك الثابتة إلى أدوات تفاعلية.

هل يمكنني إضافة روابط تشعبية لملفات خارجية بدلاً من ألسنة العمل الداخلية؟

نعم، يمكن لـ ExcelJS دعم الروابط التشعبية لملفات خارجية أو عناوين URL على الويب. بدلاً من استخدام صيغة #SheetName!A1، يمكنك ببساطة توفير عنوان URL الكامل أو مسار الملف في خاصية hyperlink، مثل 'https://www.example.com' أو 'file:///C:/path/to/file.xlsx'.

ماذا لو كان اسم ورقة العمل يحتوي على مسافات أو أحرف خاصة؟

في Excel، يتم تضمين أسماء ألسنة العمل التي تحتوي على مسافات أو أحرف خاصة بعلامات اقتباس مفردة في الروابط التشعبية (على سبيل المثال، #'My Data Sheet'!A1). يتعامل ExcelJS مع هذا بشكل تلقائي عند تحديد اسم الورقة بشكل صحيح في خاصية hyperlink.

المشاركات ذات الصلة

المقال الأصلي:
تصدير Excel في Node.js: إضافة روابط تشعبية لألسنة العمل
المصدر: صوان محور XYZ
شكر خاص لـ GEMINI و جمال الحزازي.

Cloudflare وحظر طلبات الـ API المباشرة: حلول هندسية

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 18 May 2026 10:27:57 +0100

في هذا المقال، نستعرض ظاهرة حظر Cloudflare لطلبات واجهة برمجة التطبيقات (API) المباشرة التي تُرسل من خلال أدوات برمجية مثل `curl` أو مكتبات `requests` في Python، بينما لا يتم حظر نفس الطلبات عند إجرائها عبر متصفحات الويب مثل Google Chrome. سنقدم شروحات هندسية عملية وحلولًا دقيقة لهذه المشكلة الشائعة.

فهم آليات حظر Cloudflare

تستخدم Cloudflare مجموعة معقدة من الآليات للكشف عن الروبوتات والتهديدات المحتملة. المتصفحات الحديثة مثل Chrome تتصرف بطريقة "بشرية" متوقعة، بينما الطلبات المباشرة من الأدوات البرمجية غالبًا ما تفتقر إلى هذه الخصائص، مما يثير شكوك أنظمة Cloudflare الأمنية.

بصمات المتصفح ورؤوس الطلبات

Cloudflare تفحص بدقة رؤوس HTTP المرسلة مع كل طلب. المتصفحات ترسل مجموعة غنية من الرؤوس، مثل User-Agent، Accept، Accept-Language، Accept-Encoding، Referer، و Origin. بالإضافة إلى ذلك، يتم تحليل ترتيب هذه الرؤوس وقيمها المحددة. الطلبات المباشرة من السكربتات غالبًا ما تكون مبسطة، أو تستخدم قيمًا افتراضية، أو تفتقر إلى التناسق الذي تتوقعه Cloudflare من متصفح حقيقي.

تحديات JavaScript وملفات تعريف الارتباط

العديد من آليات Cloudflare الأمنية تعتمد على تنفيذ JavaScript في المتصفح لجمع معلومات إضافية حول العميل أو لحل تحديات CAPTCHA. الطلبات المباشرة لا تنفذ JavaScript ولا تتعامل مع ملفات تعريف الارتباط (Cookies) التي قد تكون ضرورية للمصادقة أو لتجاوز التحقق الأولي من Cloudflare.

تشخيص سبب الحظر

تحديد السبب الدقيق للحظر هو الخطوة الأولى نحو تطبيق الحل الصحيح. يتطلب ذلك مقارنة دقيقة بين سلوك المتصفح وسلوك السكربت.

تحليل رؤوس HTTP

قارن رؤوس الطلب بين طلب ناجح من Chrome وطلب فاشل من الـ API. استخدم أدوات المطور (Developer Tools) في Chrome (علامة تبويب Network) أو أدوات اعتراض حركة المرور مثل Wireshark. ابحث عن الاختلافات في الرؤوس المذكورة أعلاه. غالبًا ما يكون User-Agent هو السبب الأكثر شيوعًا، يليه Accept ورؤوس أخرى.

curl -v \
     -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36" \
     -H "Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9" \
     -H "Accept-Language: en-US,en;q=0.9" \
     -H "Accept-Encoding: gzip, deflate, br" \
     -H "Referer: https://example.com/" \
     -H "Origin: https://example.com" \
     "https://api.example.com/data"

فحص سلوك المتصفح

راقب تدفق الشبكة في Chrome Developer Tools. هل هناك عمليات إعادة توجيه (redirects) قبل الوصول إلى الـ API الفعلي؟ هل يتم تعيين ملفات تعريف ارتباط جديدة؟ هل يتم تنفيذ JavaScript معقد قبل إرسال طلب الـ API؟ قد تشير هذه السلوكيات إلى تحديات أمنية تقوم Cloudflare بفرضها.

سجلات Cloudflare

إذا كان لديك وصول إلى لوحة تحكم Cloudflare الخاصة بالموقع المستهدف، تحقق من سجلات Firewall Events أو Analytics. قد توضح هذه السجلات قاعدة الحظر المحددة التي تم تفعيلها (مثل Bot Fight Mode، Rate Limiting، Managed Rules)، مما يوفر معلومات قيمة حول سبب الحظر.

حلول هندسية عملية

تتطلب معالجة حظر Cloudflare نهجًا متعدد الأوجه، يعتمد على مستوى التحكم الذي لديك في إعدادات Cloudflare والتعقيد المطلوب.

محاكاة رؤوس المتصفح

الخطوة الأولى والأكثر شيوعًا هي محاكاة رؤوس HTTP الخاصة بالمتصفح بدقة قدر الإمكان. قم بنسخ جميع الرؤوس ذات الصلة من طلب متصفح ناجح.

User-Agent: استخدم أحدث `User-Agent` من متصفح حقيقي.
Accept, Accept-Language, Accept-Encoding: انسخ هذه الرؤوس كما هي.
Referer, Origin: اضبطها لتعكس المصدر المتوقع للطلب.
Cookies: إذا كانت هناك ملفات تعريف ارتباط ضرورية، قم بإدارتها يدويًا أو باستخدام مكتبات تدعم الجلسات.

import requests

headers = {
    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36',
    'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9',
    'Accept-Language': 'en-US,en;q=0.9',
    'Accept-Encoding': 'gzip, deflate, br',
    'Referer': 'https://example.com/',
    'Origin': 'https://example.com/'
}
response = requests.get('https://api.example.com/data', headers=headers)
print(response.status_code)

استخدام المتصفحات بلا رأس (Headless Browsers)

لتجاوز تحديات JavaScript وملفات تعريف الارتباط المعقدة، استخدم متصفحات بلا رأس مثل Puppeteer (Node.js) أو Selenium (Python). هذه الأدوات تحاكي متصفحًا حقيقيًا بالكامل، بما في ذلك تنفيذ JavaScript، إدارة ملفات تعريف الارتباط، وحتى حل تحديات CAPTCHA إذا تم تكوينها بشكل صحيح.

ملاحظة: استخدام المتصفحات بلا رأس يستهلك موارد حاسوبية وشبكية أكثر بكثير من الطلبات المباشرة، وقد يكون أبطأ في التنفيذ.

رموز API لـ Cloudflare وقوائم IP البيضاء

إذا كنت المالك أو لديك إذن بالوصول إلى إعدادات Cloudflare للموقع المستهدف، فإن الحل الأمثل هو استخدام رموز API أو إضافة عناوين IP الخاصة بخادمك إلى القائمة البيضاء (Whitelist) في قواعد جدار الحماية (Firewall Rules) لـ Cloudflare. هذا يضمن أن طلباتك المباشرة لن يتم حظرها، ويعد النهج الأكثر أمانًا وفعالية.

إدارة معدل الطلبات (Rate Limiting)

قد يكون الحظر ناتجًا عن تجاوز حدود معدل الطلبات التي تفرضها Cloudflare. قم بتطبيق تأخيرات (delays) بين الطلبات أو استخدم خوارزميات التراجع الأسي (exponential backoff) لتقليل وتيرة الطلبات، خاصة عند التعامل مع أخطاء HTTP 429 Too Many Requests.

تحذير: محاولة تجاوز آليات Cloudflare الأمنية دون إذن صريح قد ينتهك شروط الخدمة وقد يؤدي إلى حظر دائم لعنوان IP الخاص بك أو لشبكتك بالكامل. تأكد دائمًا من أنك تعمل ضمن الأطر القانونية والأخلاقية.

هل يمكن لـ Cloudflare التمييز بين طلب API من Python وطلب من متصفح حقيقي؟

نعم، Cloudflare تستخدم تقنيات متقدمة مثل تحليل رؤوس HTTP، بصمات المتصفح، وتنفيذ JavaScript للتمييز بين الطلبات الشرعية من المتصفحات وتلك الآلية أو التي تأتي من سكربتات.

ما هو أفضل نهج لتجنب الحظر عند استخدام API خلف Cloudflare؟

النهج الأفضل يعتمد على السيناريو. إذا كان لديك تحكم في إعدادات Cloudflare، استخدم رموز API أو قوائم IP البيضاء. إذا لم يكن كذلك، فحاول محاكاة سلوك المتصفح بدقة قدر الإمكان، أو استخدم متصفحًا بلا رأس (headless browser) إذا كانت تحديات JavaScript معقدة.

المشاركات ذات الصلة

المقال الأصلي:
Cloudflare وحظر طلبات الـ API المباشرة: حلول هندسية
المصدر: صوان محور XYZ
شكر خاص لـ GEMINI و جمال الحزازي.

احتراف CSS: من الأساسيات إلى أحدث التطورات

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 11 May 2026 10:27:49 +0100

في عالم تطوير الويب، تُعد لغة CSS (أوراق الأنماط المتتالية) حجر الزاوية لتصميم واجهات المستخدم الجذابة والوظيفية. يتطلب احترافها فهمًا عميقًا للمفاهيم الأساسية ومواكبة التطورات المستمرة التي تُحدث ثورة في طريقة بناء الأنماط. يهدف هذا المقال إلى تقديم مسار عملي لاحتراف CSS وتسليط الضوء على أبرز الميزات الحديثة التي تعزز المرونة والأداء.

إتقان أساسيات CSS

لا يمكن احتراف CSS دون فهم راسخ لمبادئها الأساسية. هذه المبادئ هي اللبنات التي تُبنى عليها جميع التصميمات المعقدة.

المحددات والخصوصية

تُعد المحددات (Selectors) الآلية الأساسية لاستهداف عناصر HTML وتطبيق الأنماط عليها. فهم أنواعها (الفئة، المعرف، العنصر، السمة، الزائفة) أمر بالغ الأهمية. ترتبط الخصوصية (Specificity) ارتباطًا وثيقًا بالمحددات، حيث تحدد القاعدة التي ستُطبق عندما تتضارب عدة قواعد على نفس العنصر. تُحسب الخصوصية بناءً على وزن المحددات (المعرفات > الفئات/السمات > العناصر).


#header h1 { color: blue; } /* خصوصية أعلى */
.main-title { color: red; } /* خصوصية أقل */

نموذج الصندوق والتخطيط

يُعد نموذج الصندوق (Box Model) مفهومًا أساسيًا يصف كيفية عرض عناصر HTML كصناديق مستطيلة، تتكون من المحتوى، الحشوة (padding)، الحدود (border)، والهامش (margin). إتقان هذا النموذج ضروري للتحكم الدقيق في التباعد والمحاذاة.

بالإضافة إلى ذلك، تُعد تقنيات التخطيط الحديثة مثل Flexbox و CSS Grid أدوات لا غنى عنها لبناء تخطيطات معقدة ومتجاوبة بسهولة وفعالية. يوفر Flexbox تحكمًا أحادي البعد (صف أو عمود)، بينما يوفر CSS Grid تحكمًا ثنائي الأبعاد (صفوف وأعمدة)، مما يجعله مثاليًا للتخطيطات الشبكية.

معلومة!
يُنصح بالبدء بـ Flexbox للتخطيطات البسيطة ذات البعد الواحد، والانتقال إلى CSS Grid للتخطيطات المعقدة ثنائية الأبعاد.

التقنيات المتقدمة وأفضل الممارسات

بعد إتقان الأساسيات، يمكن للمطورين الانتقال إلى تقنيات أكثر تقدمًا وممارسات تضمن قابلية الصيانة والأداء.

التصميم المتجاوب

يُعد التصميم المتجاوب (Responsive Design) ضرورة قصوى في العصر الحالي لضمان عرض الموقع بشكل مثالي على مختلف الأجهزة وأحجام الشاشات. تُستخدم استعلامات الوسائط (Media Queries) لتطبيق أنماط مختلفة بناءً على خصائص الجهاز مثل العرض والارتفاع والاتجاه.


@media (max-width: 768px) {
  .container {
    flex-direction: column;
  }
}

كما تُستخدم الوحدات النسبية مثل `rem` و `em`، بالإضافة إلى وحدات عرض وارتفاع النافذة `vw` و `vh`، لإنشاء تصميمات تتكيف بمرونة.

هندسة CSS وقابلية الصيانة

للحفاظ على قواعد أنماط كبيرة ومنظمة، تُعد منهجيات مثل BEM (Block, Element, Modifier) و SMACSS (Scalable and Modular Architecture for CSS) مفيدة للغاية. تساعد هذه المنهجيات في تنظيم الكود، تقليل التكرار، وتحسين قابلية القراءة والصيانة.

تُعد متغيرات CSS (CSS Custom Properties) أداة قوية لتعريف قيم قابلة لإعادة الاستخدام، مما يسهل إدارة الثيمات وتحديث الأنماط على نطاق واسع.


:root {
  --primary-color: #007bff;
  --spacing-unit: 16px;
}

.button {
  background-color: var(--primary-color);
  padding: var(--spacing-unit);
}

أحدث تطورات CSS

تشهد CSS تطورات مستمرة تُضيف ميزات قوية تعزز قدرات المطورين.

استعلامات الحاويات (@container)

تُعد استعلامات الحاويات (Container Queries) ثورة في التصميم المتجاوب. بدلاً من الاستجابة لحجم إطار العرض (viewport)، تسمح استعلامات الحاويات للعناصر بالاستجابة لحجم الحاوية الأصلية التي توجد بداخلها. هذا يوفر مرونة غير مسبوقة في بناء مكونات قابلة لإعادة الاستخدام تتكيف مع سياقها.


.card-container {
  container-type: inline-size;
}

@container (min-width: 400px) {
  .card-title {
    font-size: 1.5rem;
  }
  .card-image {
    display: block;
  }
}

طبقات التتالي (@layer)

تُقدم طبقات التتالي (Cascade Layers) طريقة جديدة لإدارة خصوصية CSS. تسمح بتنظيم قواعد الأنماط في طبقات، حيث تُطبق الطبقات اللاحقة فوق الطبقات السابقة، بغض النظر عن ترتيبها في ورقة الأنماط أو خصوصية المحددات داخل الطبقة. هذا يمنح المطورين تحكمًا أكبر في التتالي ويقلل من الحاجة إلى استخدام `!important`.


@layer base, components, utilities;

@layer base {
  body { margin: 0; }
}

@layer components {
  .button {
    padding: 10px 20px;
    background-color: blue;
  }
}

@layer utilities {
  .button { /* هذه القاعدة ستتغلب على قاعدة .button في طبقة components */
    background-color: green;
  }
}

محددات جديدة ووحدات عرض جديدة

يُعد المحدد `:has()` (المحدد الأبوي) إضافة قوية تسمح باستهداف عنصر بناءً على محتواه أو وجود عناصر معينة بداخله. على سبيل المثال، يمكن تحديد عنصر `div` يحتوي على صورة.

كما ظهرت وحدات عرض جديدة مثل `dvh` (dynamic viewport height)، `svh` (small viewport height)، و `lvh` (large viewport height) لمعالجة مشكلة شريط العنوان في متصفحات الجوال، مما يوفر تحكمًا أكثر دقة في ارتفاعات العناصر.

نصيحة!
لمواكبة هذه التطورات، يُنصح بمتابعة المدونات التقنية المتخصصة مثل CSS-Tricks و web.dev/css، وتجربة الميزات الجديدة في بيئات التطوير.

ما الفرق الرئيسي بين Flexbox و CSS Grid؟

Flexbox مصمم للتخطيطات أحادية البعد (صف واحد أو عمود واحد)، بينما CSS Grid مصمم للتخطيطات ثنائية الأبعاد (صفوف وأعمدة متعددة)، مما يجعله مثاليًا لتخطيطات الصفحة الكاملة.

لماذا تُعتبر استعلامات الحاويات مهمة؟

تسمح استعلامات الحاويات للعناصر بالاستجابة لحجم الحاوية الأصلية بدلاً من حجم إطار العرض الكلي، مما يوفر مرونة أكبر في بناء مكونات قابلة لإعادة الاستخدام تتكيف مع سياقها الخاص.

كيف تساعد طبقات التتالي في إدارة CSS؟

تسمح طبقات التتالي بتنظيم قواعد الأنماط في طبقات ذات أولوية محددة، مما يمنح المطورين تحكمًا أفضل في التتالي ويقلل من مشكلات الخصوصية، خاصة في المشاريع الكبيرة أو عند استخدام مكتبات CSS خارجية.

المشاركات ذات الصلة

المقال الأصلي:
احتراف CSS: من الأساسيات إلى أحدث التطورات
المصدر: صوان محور XYZ
شكر خاص لـ GEMINI و جمال الحزازي.

حل مشكلة عدم ظهور صور المصغرات للمشاركات ذات الصلة في بلوجر

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 4 May 2026 10:27:52 +0100

في هذا المقال، سنتناول مشكلة شائعة يواجهها العديد من مستخدمي منصة بلوجر (Blogger) وهي عدم ظهور الصور المصغرة (thumbnails) للمشاركات ذات الصلة (Related Posts). تؤثر هذه المشكلة سلبًا على تجربة المستخدم وجمالية المدونة، وقد تشير إلى وجود أخطاء في قالب المدونة أو في طريقة معالجة الصور. سنقدم شروحات تقنية وحلولاً عملية لمعالجة هذه المشكلة.

فهم المشكلة وتأثيرها

تعتبر المشاركات ذات الصلة ميزة حيوية لتحسين تفاعل الزوار داخل المدونة، حيث تشجعهم على استكشاف المزيد من المحتوى ذي الصلة بالمقالة التي يقرؤونها. عندما لا تظهر الصور المصغرة، يصبح القسم أقل جاذبية وقد يتجاهله الزوار، مما يؤدي إلى زيادة معدل الارتداد (Bounce Rate) وتقليل الوقت الذي يقضيه الزائر في الموقع. من الناحية التقنية، غالبًا ما تنبع هذه المشكلة من عدم قدرة الكود البرمجي للقالب على استخراج عنوان URL الصحيح للصورة المصغرة أو من عدم وجود صورة مصغرة قابلة للاستخدام.

تحذير!
قبل إجراء أي تعديلات على قالب مدونتك، تأكد دائمًا من أخذ نسخة احتياطية كاملة للقالب. هذا يضمن إمكانية استعادة القالب إلى حالته الأصلية في حال حدوث أي خطأ غير متوقع.

الأسباب الشائعة لعدم ظهور الصور المصغرة

هناك عدة أسباب تقنية وراء عدم ظهور الصور المصغرة، أبرزها:

عدم وجود صورة مميزة (Featured Image): في بعض الأحيان، يعتمد كود المشاركات ذات الصلة على وجود صورة محددة كصورة مميزة للمقالة. إذا لم يتم تعيين صورة كهذه، قد يفشل الكود في العثور على أي صورة لعرضها.
مشاكل في كود الـ HTML/JavaScript للودجت: قد يكون الكود المخصص للمشاركات ذات الصلة (سواء كان جزءًا من القالب أو ويدجت مضافًا) يحتوي على أخطاء تمنعه من استخراج `data:post.thumbnailUrl` بشكل صحيح، أو قد لا يتضمن منطقًا للتعامل مع الحالات التي لا تتوفر فيها الصورة المصغرة.
مشاكل في استضافة الصور: إذا كانت الصور مستضافة على خدمات خارجية غير متاحة للعامة أو تتطلب مصادقة، فقد لا يتمكن بلوجر من الوصول إليها وعرضها.
تغييرات في بنية بلوجر: قد تحدث تحديثات في بنية بلوجر تؤثر على طريقة استدعاء البيانات، مما يتطلب تحديث الكود في القوالب القديمة.

حلول عملية وخطوات استكشاف الأخطاء

لحل مشكلة عدم ظهور الصور المصغرة، اتبع الخطوات التالية بدقة:

الخطوة 1: التحقق من صور المشاركات

تأكد من أن جميع المشاركات التي تظهر في قسم "المشاركات ذات الصلة" تحتوي على صورة واحدة على الأقل داخل محتواها. يفضل أن تكون الصورة الأولى في المقال هي الصورة التي ترغب في عرضها كصورة مصغرة.
إذا كانت المشاركة لا تحتوي على صور، قم بإضافة صورة ذات صلة وحفظ المشاركة.

هذه هي الخطوة الأكثر أهمية وتتطلب بعض المعرفة الأساسية بـ HTML و XML في قوالب بلوجر.

انتقل إلى لوحة تحكم بلوجر > المظهر > تعديل HTML.
ابحث عن الكود الخاص بويدجت المشاركات ذات الصلة. غالبًا ما يكون ضمن وسم `` أو ``، وقد يحتوي على كلمات مثل "related posts" أو "similar posts".
ابحث داخل الكود عن الأجزاء المسؤولة عن عرض الصور. عادةً ما تبحث عن `img` tags أو المتغيرات التي تحمل اسم `thumbnailUrl` أو `post.firstImageUrl`.

معلومة!
المتغير القياسي في بلوجر لاستدعاء الصورة المصغرة هو data:post.thumbnailUrl. تأكد من أن الكود يستخدم هذا المتغير بشكل صحيح.

إذا كان الكود لا يتضمن منطقًا للتعامل مع عدم وجود الصورة المصغرة، يمكنك إضافة شرط للتحقق من وجودها وعرض صورة افتراضية بدلاً منها. إليك مثال على كيفية تعديل الكود:

<b:loop values='data:posts' var='post'>
  <div class='related-post-item'>
    <a expr:href='data:post.url'>
      <b:if cond='data:post.thumbnailUrl'>
        <img expr:src='data:post.thumbnailUrl' class='related-post-thumbnail'/>
      <b:else/>
        <img src='https://4.bp.blogspot.com/-_Y5xQ-1-y-0/AAAAAAAAAAI/AAAAAAAAB/s1600/default-thumbnail.png' class='related-post-thumbnail'/> <!-- استبدل بالرابط الخاص بصورتك الافتراضية -->
      </b:if>
      <span class='related-post-title'><data:post.title/></span>
    </a>
  </div>
</b:loop>

في هذا المثال، قمنا بإضافة وسم `` للتحقق مما إذا كان `data:post.thumbnailUrl` موجودًا. إذا كان كذلك، يتم عرض الصورة المصغرة للمشاركة. وإلا، يتم عرض صورة افتراضية (يجب عليك استبدال الرابط بصورة افتراضية من اختيارك). هذا يضمن ظهور صورة دائمًا، حتى لو لم تكن هناك صورة مصغرة للمشاركة.

الخطوة 3: التحقق من استضافة الصور وإمكانية الوصول إليها

تأكد من أن الصور المستخدمة في مشاركاتك مستضافة بشكل صحيح على بلوجر أو على خدمة استضافة صور عامة. إذا كنت تستخدم صورًا من ألبومات Google Photos (Picasa سابقًا) وكانت هذه الألبومات خاصة، فلن يتمكن بلوجر من عرضها. اجعل الألبومات عامة أو أعد تحميل الصور مباشرة إلى مشاركات بلوجر.

الخطوة 4: تعارضات JavaScript

إذا كان ويدجت المشاركات ذات الصلة يعتمد على كود JavaScript مخصص، فقد تحدث تعارضات مع سكربتات أخرى في القالب. للتحقق من ذلك:

افتح مدونتك في المتصفح.
اضغط على F12 لفتح أدوات المطور (Developer Tools).
انتقل إلى تبويب Console. ابحث عن أي رسائل خطأ باللون الأحمر، والتي قد تشير إلى مشاكل في JavaScript.
إذا وجدت أخطاء، حاول تعطيل السكربتات المخصصة للمشاركات ذات الصلة مؤقتًا (عن طريق إزالتها أو وضعها داخل تعليق HTML ``) لمعرفة ما إذا كانت المشكلة تختفي. إذا اختفت، فهذا يؤكد وجود تعارض.

إذا استمرت المشكلة بعد تجربة جميع الحلول المذكورة أعلاه، قد يكون الحل الأبسط هو استخدام ويدجت "المشاركات الشائعة" (Popular Posts) الافتراضي من بلوجر، والذي عادةً ما يعرض الصور المصغرة بشكل صحيح. يمكنك إضافة هذا الودجت من لوحة تحكم بلوجر > التخطيط > إضافة أداة.

اعتبارات متقدمة

في بعض القوالب المعقدة، قد يتم معالجة الصور المصغرة بواسطة سكربتات خارجية أو وظائف مخصصة داخل القالب. في هذه الحالات، قد تحتاج إلى مراجعة وثائق القالب أو التواصل مع مطور القالب للحصول على دعم فني. تأكد أيضًا من أن القالب الذي تستخدمه متوافق مع أحدث إصدارات بلوجر.

حل!
تطبيق التعديلات المذكورة في الخطوة 2، خاصة إضافة الشرط <b:if cond='data:post.thumbnailUrl'> مع صورة افتراضية، غالبًا ما يحل المشكلة بشكل فعال ويضمن ظهور الصور المصغرة أو بديلها.

الأسئلة الشائعة

لماذا لا تظهر الصور المصغرة للمشاركات ذات الصلة في مدونتي على بلوجر؟

غالبًا ما يكون السبب هو عدم وجود صورة مميزة في المشاركة، أو خطأ في كود الودجت الخاص بالمشاركات ذات الصلة في قالب HTML، أو مشاكل في استضافة الصور.

ما هو المتغير الذي يستخدمه بلوجر لعرض الصور المصغرة؟

المتغير القياسي هو data:post.thumbnailUrl. يجب أن يتضمن كود الودجت الخاص بك هذا المتغير لاستدعاء الصورة المصغرة.

هل يمكنني تعيين صورة افتراضية إذا لم تكن هناك صورة مصغرة للمشاركة؟

نعم، يمكنك استخدام شرط <b:if cond='data:post.thumbnailUrl'> في قالب HTML الخاص بك لعرض صورة افتراضية عندما لا تتوفر الصورة المصغرة للمشاركة. راجع الخطوة 2 في هذا المقال للحصول على مثال.

المشاركات ذات الصلة

المقال الأصلي:
حل مشكلة عدم ظهور صور المصغرات للمشاركات ذات الصلة في بلوجر
المصدر: صوان محور XYZ
شكر خاص لـ GEMINI و جمال الحزازي.

تحويل فتح عنصر <dialog> بانتقال سلس باستخدام Tailwind CSS

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Mon, 27 Apr 2026 10:28:06 +0100

في تطوير الويب الحديث، أصبح تقديم تجربة مستخدم سلسة أمرًا بالغ الأهمية. عنصر <dialog> الأصلي في HTML يوفر طريقة قياسية لعرض مربعات الحوار، لكنه يفتقر إلى آليات الانتقال المدمجة لفتح وإغلاق سلس. يهدف هذا المقال إلى تقديم حل عملي لدمج انتقالات أنيقة باستخدام Tailwind CSS و JavaScript، مع التركيز على الدقة الهندسية والكفاءة.

فهم عنصر <dialog> والتحديات

عنصر <dialog> هو عنصر HTML دلالي مصمم لتمثيل مربع حوار أو مكون تفاعلي آخر، مثل نافذة منبثقة أو فحص. عند استخدامه مع طريقة showModal()، فإنه يفتح مربع الحوار في طبقة علوية، مما يجعله فوق جميع المحتويات الأخرى، ويضيف تلقائيًا خلفية (backdrop) تعتم بقية الصفحة. ومع ذلك، فإن السلوك الافتراضي لفتح وإغلاق مربع الحوار يكون فوريًا، حيث ينتقل من display: none إلى display: block (أو ما شابه) دون أي تأثير بصري.

يكمن التحدي الرئيسي في أن الانتقال المباشر من display: none إلى أي قيمة أخرى لا يمكن أن يكون متحركًا (animated) بشكل مباشر باستخدام CSS. لتحقيق انتقال سلس، نحتاج إلى التحكم في خصائص مثل opacity و transform بينما يكون العنصر مرئيًا بالفعل في DOM، حتى لو كان مخفيًا بصريًا في البداية.

هيكل <dialog> الأولي

لنبدأ بهيكل HTML الأساسي لمربع حوار وزر لفتحه:

<button id="openDialogBtn" class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">
  فتح مربع الحوار
</button>

<dialog id="myDialog" class="p-6 rounded-lg shadow-xl bg-white">
  <h2 class="text-2xl font-bold mb-4">عنوان مربع الحوار</h2>
  <p>هذا هو محتوى مربع الحوار الخاص بي.</p>
  <div class="mt-6 flex justify-end gap-2">
    <button id="closeDialogBtn" class="bg-gray-300 hover:bg-gray-400 text-gray-800 font-bold py-2 px-4 rounded">
      إغلاق
    </button>
  </div>
</dialog>

تطبيق الانتقالات باستخدام Tailwind CSS و JavaScript

لتحقيق الانتقال المطلوب، سنقوم بتطبيق فئات Tailwind CSS التي تحدد الحالة الأولية (المخفية) والحالة النهائية (الظاهرة) لمربع الحوار والخلفية. ستقوم JavaScript بعد ذلك بإدارة إضافة وإزالة هذه الفئات، بالإضافة إلى استدعاء طرق showModal() و close().

فئات Tailwind CSS للانتقال

سنحتاج إلى فئات لتعريف الحالة الأولية (مخفية) والحالة النهائية (ظاهرة) لمربع الحوار والخلفية. سنستخدم فئات opacity و transform من Tailwind CSS.

/* تنسيقات عامة للخلفية */
dialog::backdrop {
  @apply bg-black/50 transition-opacity duration-300 ease-out;
}

/* حالة الفتح - يتم إضافتها بواسطة JS */
dialog[open]::backdrop {
  @apply opacity-100;
}

/* حالة الإغلاق - يتم إزالتها بواسطة JS */
dialog::backdrop {
  @apply opacity-0;
}

/* تنسيقات عامة لمربع الحوار */
dialog {
  @apply transition-all duration-300 ease-out;
}

/* حالة الفتح - يتم إضافتها بواسطة JS */
dialog.opacity-100.scale-100 {
  @apply opacity-100 scale-100;
}

/* حالة الإغلاق - يتم إزالتها بواسطة JS */
dialog:not(.opacity-100.scale-100) {
  @apply opacity-0 scale-95;
}

في هذا المثال، نستخدم dialog[open]::backdrop و dialog::backdrop للتحكم في الخلفية. بالنسبة لمربع الحوار نفسه، سنعتمد على فئات Tailwind المضافة بواسطة JavaScript.

JavaScript لإدارة حالة مربع الحوار

تتطلب هذه الطريقة استخدام JavaScript لإدارة فئات CSS وتوقيت استدعاء طرق showModal() و close().

const dialog = document.getElementById('myDialog');
const openDialogBtn = document.getElementById('openDialogBtn');
const closeDialogBtn = document.getElementById('closeDialogBtn');

// وظيفة لفتح مربع الحوار بانتقال
openDialogBtn.addEventListener('click', () => {
  dialog.showModal(); // يجعل مربع الحوار مرئيًا (display: block)
  // إضافة فئات الانتقال بعد فترة قصيرة للسماح للمتصفح بتطبيق display: block
  setTimeout(() => {
    dialog.classList.add('opacity-100', 'scale-100');
    dialog.classList.remove('opacity-0', 'scale-95');
  }, 10); // تأخير صغير جدًا
});

// وظيفة لإغلاق مربع الحوار بانتقال
closeDialogBtn.addEventListener('click', () => {
  dialog.classList.remove('opacity-100', 'scale-100');
  dialog.classList.add('opacity-0', 'scale-95');

  // إغلاق مربع الحوار بعد انتهاء الانتقال
  dialog.addEventListener('transitionend', function handler() {
    dialog.close();
    dialog.removeEventListener('transitionend', handler); // إزالة المستمع بعد الاستخدام
  }, { once: true });
});

// إغلاق مربع الحوار عند النقر خارج المحتوى (سلوك افتراضي لـ dialog)
dialog.addEventListener('click', (event) => {
  if (event.target === dialog) {
    closeDialogBtn.click(); // محاكاة النقر على زر الإغلاق
  }
});

// تهيئة الحالة الأولية لمربع الحوار
dialog.classList.add('opacity-0', 'scale-95');

في هذا الكود، عند فتح مربع الحوار، نستخدم showModal() أولاً، ثم نضيف فئات opacity-100 و scale-100 بعد تأخير بسيط. هذا يسمح للمتصفح بتطبيق display: block قبل بدء الانتقال البصري. عند الإغلاق، نزيل فئات الحالة المفتوحة ونضيف فئات الحالة المخفية، ثم ننتظر حدث transitionend قبل استدعاء dialog.close() لضمان إغلاق مربع الحوار بعد اكتمال الانتقال البصري.

اعتبارات متقدمة وأفضل الممارسات

إمكانية الوصول (ARIA)

عنصر <dialog> الأصلي يتمتع بدعم جيد لإمكانية الوصول بشكل افتراضي، حيث يتعامل مع التركيز (focus) و Esc لإغلاق مربع الحوار. ومع ذلك، عند تخصيص السلوك باستخدام JavaScript، يجب التأكد من عدم كسر هذه الميزات. الحل المقدم هنا يحافظ على معظم هذه السلوكيات.

انتقال الخلفية (Backdrop)

يمكن أيضًا تطبيق الانتقالات على الخلفية باستخدام ::backdrop. في مثالنا، قمنا بتطبيق transition-opacity duration-300 ease-out على dialog::backdrop. يجب ملاحظة أن dialog::backdrop لا يمكن التحكم فيه مباشرة بفئات Tailwind CSS، بل يتطلب استخدام CSS عادي أو تضمين @apply داخل ملف CSS الرئيسي لـ Tailwind.

معلومة!
تأكد من أن مدة الانتقال في JavaScript (مثل duration-300) تتطابق مع المدة المحددة في فئات Tailwind CSS لضمان تزامن مثالي بين إغلاق مربع الحوار وانتهاء الانتقال.

المرونة والتخصيص

يمكن تعديل فئات Tailwind CSS (مثل scale-95، translate-y-4، duration-300) بسهولة لتناسب متطلبات التصميم المختلفة. يمكن أيضًا إضافة انتقالات أخرى مثل transform-gpu لتحسين الأداء البصري.

باستخدام هذه الطريقة، يمكن للمطورين الاستفادة من قوة عنصر <dialog> الأصلي مع إضافة لمسة عصرية من الانتقالات السلسة التي توفرها Tailwind CSS، مما يحسن تجربة المستخدم بشكل كبير.

المشاركات ذات الصلة

المقال الأصلي:
تحويل فتح عنصر <dialog> بانتقال سلس باستخدام Tailwind CSS
المصدر: صوان محور XYZ
شكر خاص لـ GEMINI و جمال الحزازي.

صمم ونفذ مصادقة مفاتيح API قوية وآمنة لتطبيقات Node.js بفعالية

jamal@elhizazi.me (صِوان مِحور الابعاد الثلاث XYZ) — Tue, 17 Mar 2026 09:54:39 GMT

شفافية المحتوى: تم توليد وتنسيق هذا المقال آلياً عبر محرك Siwane AI لتقديم محتوى تقني دقيق، مباشر.

في عالم تطوير الويب الحديث، تعد واجهات برمجة التطبيقات (APIs) العمود الفقري للتطبيقات الموزعة. يتطلب تأمين هذه الواجهات استراتيجيات مصادقة قوية، وتبرز مصادقة مفاتيح API كحل فعال وبسيط لتطبيقات Node.js. يهدف هذا المقال إلى تقديم دليل هندسي معمق للمطورين حول كيفية تصميم وتنفيذ نظام مصادقة يعتمد على مفاتيح API قوية وآمنة باستخدام Node.js و Express.js.

تصميم بنية المفتاح والتخزين الآمن

لضمان أمان نظام المصادقة، يجب أن تبدأ العملية بتصميم مفاتيح API قوية وآمنة، تليها استراتيجيات تخزين لا يمكن اختراقها.

توليد مفاتيح API قوية

يجب أن تكون مفاتيح API فريدة وغير قابلة للتخمين. نوصي باستخدام سلاسل عشوائية مشفرة أو معرفات فريدة عالميًا (UUIDs) كقاعدة للمفتاح. يمكن تحقيق ذلك باستخدام وحدة `crypto` المدمجة في Node.js لتوليد بايتات عشوائية ثم تحويلها إلى تنسيق قابل للاستخدام مثل Base64 أو Hexadecimal. يجب أن يكون طول المفتاح كافيًا لضمان التوزيع العشوائي الكافي، عادة ما لا يقل عن 32 بايتًا (256 بت) من العشوائية، مما ينتج عنه سلسلة أطول بكثير عند التشفير.


const crypto = require('crypto');

function generateApiKey() {
  return crypto.randomBytes(32).toString('hex'); // 32 bytes = 64 hex characters
}

// مثال للاستخدام
const newApiKey = generateApiKey();
console.log(newApiKey);

التخزين الآمن لمفاتيح API

أحد أهم مبادئ الأمان هو عدم تخزين المفتاح الأصلي أبدًا في قاعدة البيانات أو أي مكان آخر بعد التوليد الأولي. بدلاً من ذلك، يجب تخزين تجزئة (hash) المفتاح. تُستخدم خوارزميات التجزئة أحادية الاتجاه مثل `bcrypt` أو `Argon2` لهذا الغرض. هذه الخوارزميات مصممة لتكون بطيئة ومقاومة لهجمات القوة الغاشمة (brute-force attacks) وجداول قوس قزح (rainbow tables).


const bcrypt = require('bcrypt');
const SALT_ROUNDS = 10; // عدد جولات التمليح

async function hashApiKey(apiKey) {
  return await bcrypt.hash(apiKey, SALT_ROUNDS);
}

async function compareApiKey(apiKey, hashedApiKey) {
  return await bcrypt.compare(apiKey, hashedApiKey);
}

// مثال للاستخدام
async function example() {
  const newApiKey = generateApiKey(); // من الدالة السابقة
  const hashedKey = await hashApiKey(newApiKey);
  // تخزين hashedKey في قاعدة البيانات
  console.log('Hashed Key:', hashedKey);

  // عند المصادقة:
  const isValid = await compareApiKey(newApiKey, hashedKey);
  console.log('Is Valid:', isValid);
}
example();

تحذير!
يجب التأكد من أن المفتاح الأصلي لا يُعرض للمستخدم إلا مرة واحدة عند إنشائه، ولا يتم تسجيله أو تخزينه في أي مكان.

تنفيذ المصادقة وإدارة المفاتيح

بعد تصميم المفاتيح وتخزينها بأمان، ننتقل إلى تنفيذ آلية المصادقة وإدارة دورة حياة المفتاح.

بناء Middleware للمصادقة

في Express.js، يمكن بناء middleware فعال لاعتراض الطلبات الواردة والتحقق من مفتاح API. يتم استخراج المفتاح عادة من رأس HTTP، مثل `x-api-key` أو `Authorization: ApiKey <key>`. يقوم الـ middleware بعد ذلك بالبحث عن المفتاح المقابل في قاعدة البيانات ومقارنة التجزئات.


const { compareApiKey } = require('../utils/keyHasher');
// افتراض دالة لجلب المفتاح المجزأ من قاعدة البيانات
// function getHashedApiKeyFromDB(apiKeyId) { ... }

async function apiKeyAuth(req, res, next) {
  const apiKey = req.headers['x-api-key'] || req.headers['authorization']?.split(' ')[1];

  if (!apiKey) {
    return res.status(401).json({ message: 'API Key missing' });
  }

  try {
    // في بيئة إنتاجية، ستبحث عن المفتاح المجزأ المرتبط بـ apiKey
    // هنا، نفترض أن لدينا مفتاح مجزأ مخزن مسبقًا للمقارنة
    const storedHashedKey = '$2b$10$EXAMPLE_HASH_FROM_DB'; // استبدل بهذا من DB

    const isValid = await compareApiKey(apiKey, storedHashedKey);

    if (isValid) {
      // يمكن إضافة معلومات المستخدم/العميل إلى req.user أو req.client
      next();
    } else {
      res.status(403).json({ message: 'Invalid API Key' });
    }
  } catch (error) {
    console.error('API Key authentication error:', error);
    res.status(500).json({ message: 'Internal server error' });
  }
}

module.exports = apiKeyAuth;

يمكن استخدام هذا الـ middleware في تطبيق Express.js كالتالي:


const express = require('express');
const apiKeyAuth = require('./middleware/apiKeyAuth');
const app = express();

app.use(express.json());

app.get('/protected-route', apiKeyAuth, (req, res) => {
  res.json({ message: 'Welcome, authenticated user!' });
});

app.listen(3000, () => console.log('Server running on port 3000'));

إدارة دورة حياة المفتاح (Key Lifecycle Management)

تعد إدارة دورة حياة المفتاح جزءًا حيويًا من استراتيجية أمنية شاملة:

التجديد (Rotation): يجب تشجيع المستخدمين على تجديد مفاتيح API بانتظام أو فرض ذلك تلقائيًا. هذا يقلل من نافذة التعرض للمفتاح المخترق.
الإلغاء (Revocation): يجب توفير آلية فورية لإلغاء المفاتيح عند الاشتباه في اختراقها أو عدم الحاجة إليها. يمكن تحقيق ذلك عن طريق وضع علامة "غير نشط" في قاعدة البيانات أو حذف التجزئة.
تحديد الصلاحية (Expiry): يمكن تعيين تاريخ انتهاء صلاحية للمفاتيح، مما يتطلب من المستخدمين تجديدها قبل انتهاء الصلاحية. هذا يضيف طبقة أخرى من الأمان.

لتحقيق إدارة فعالة، يجب أن يتضمن نموذج قاعدة البيانات الخاص بمفاتيح API حقولًا مثل `isActive` (منطقي)، `expiresAt` (تاريخ ووقت)، و`createdAt` (تاريخ ووقت).

أفضل الممارسات الأمنية والتحديات

بالإضافة إلى التنفيذ الأساسي، هناك تحديات أمنية شائعة يجب التخفيف منها لضمان نظام قوي.

التخفيف من التهديدات الأمنية

هجمات التخمين (Brute-Force): تنفيذ تحديد المعدل (Rate Limiting) على نقطة نهاية المصادقة أو على جميع نقاط النهاية المحمية. يمكن استخدام مكتبات مثل `express-rate-limit`.
إعادة استخدام المفاتيح: تشجيع أو فرض استخدام مفاتيح فريدة لكل تطبيق أو خدمة، وتجنب مشاركة المفاتيح بين بيئات مختلفة (تطوير، اختبار، إنتاج).
تأمين نقاط النهاية عبر قيود الوصول: تطبيق التحكم في الوصول المستند إلى الأدوار (RBAC) أو قوائم التحكم في الوصول (ACLs) لضمان أن المفتاح المصادق عليه لديه فقط الأذونات اللازمة للوصول إلى الموارد المحددة.
تسجيل ومراقبة الوصول: تسجيل جميع محاولات المصادقة الناجحة والفاشلة، ومراقبة هذه السجلات للكشف عن الأنشطة المشبوهة.

هل يمكن استخدام مفاتيح API كبديل لـ OAuth2؟

مفاتيح API مناسبة للمصادقة من خادم إلى خادم أو للتطبيقات التي لا تتطلب تفاعل المستخدم المباشر للمصادقة. OAuth2 أكثر ملاءمة للمصادقة التفويضية حيث يحتاج المستخدم إلى منح تطبيق طرف ثالث إذن الوصول إلى موارده دون مشاركة بيانات اعتماده.

ما هي المخاطر الرئيسية لتخزين مفاتيح API كنص واضح؟

تخزين مفاتيح API كنص واضح يعرضها للخطر الشديد. في حالة اختراق قاعدة البيانات، سيتمكن المهاجمون من الوصول الفوري إلى جميع المفاتيح، مما يمكنهم من انتحال هوية المستخدمين أو التطبيقات والوصول إلى الموارد المحمية. التجزئة (hashing) تحمي من هذا السيناريو.

المشاركات ذات الصلة

المقال الأصلي:
صمم ونفذ مصادقة مفاتيح API قوية وآمنة لتطبيقات Node.js بفعالية
المصدر: صوان محور XYZ
شكر خاص لـ GEMINI و جمال الحزازي.

صِوان مِحور الابعاد الثلاث XYZ

حل مشكلة MongoServerError: unknown operator: $expr في MongoDB 6.10.0

فهم الخطأ: "unknown operator: $expr"

الأسباب المحتملة للخطأ

إصدار MongoDB غير صحيح أو قديم

أخطاء في الصياغة أو الاستخدام

برامج التشغيل أو العملاء القديمة

عدم اتساق في مجموعة النسخ المتماثلة/المجزأة

حلول عملية ومباشرة

التحقق من إصدار MongoDB الفعلي

مراجعة صياغة الاستعلام

تحديث برنامج تشغيل MongoDB

ضمان توحيد إصدارات العقد

الأسئلة الشائعة

إتقان سطر الأوامر: دليلك الشامل لأوامر Git Bash

ما هو Git Bash؟

تهيئة Git والإعدادات الأولية

أوامر Git الأساسية

إنشاء مستودع جديد

إضافة الملفات والالتزام بالتغييرات

التحقق من الحالة والسجل

التعامل مع المستودعات البعيدة

استنساخ مستودع بعيد

إضافة مستودع بعيد

دفع وسحب التغييرات

الفروع والدمج (Branching & Merging)

إنشاء وتبديل الفروع

دمج الفروع

أوامر إضافية مفيدة

احتراف SVG: دليل شامل لأحدث التطورات والتقنيات

ما هو SVG ولماذا هو مهم؟

احتراف SVG: المفاهيم الأساسية

الأشكال الأساسية والمسارات

التحويلات والتجميعات

التدرجات والأنماط

النصوص والخطوط

تقنيات SVG المتقدمة

تنسيق SVG باستخدام CSS

معالجة SVG باستخدام JavaScript

الفلاتر وأقنعة القص (Clipping Paths)

أحدث التطورات في SVG

رسوم SVG المتحركة و Web Animations API (WAAPI)

إمكانية الوصول (Accessibility) في SVG

SVG في مكونات الويب (Web Components)

SVG و WebAssembly (WASM)

نصائح عملية لاحتراف SVG

ربط Scroll-Timeline المشروط ضمن استعلامات حاويات CSS

ما هي استعلامات حاويات CSS؟

فهم Scroll-Timeline

التحدي: الربط المشروط

حلول عملية للربط المشروط

الطريقة الأولى: الاستفادة من متغيرات CSS

الطريقة الثانية: التطبيق المشروط للأنماط الكاملة

اعتبارات وأفضل الممارسات

حل مشكلة req.body غير المعرف في Express.js

لماذا يكون req.body غير معرف؟

الحل: استخدام الـ Middleware المدمج في Express

تطبيق express.json()

تطبيق express.urlencoded()

ترتيب الـ Middleware مهم

التحقق من رأس Content-Type

استكشاف الأخطاء وإصلاحها

الخلاصة

احتراف GitHub: دليلك الشامل لأحدث التطورات

ما هو GitHub؟

المفاهيم الأساسية لاحتراف GitHub

المستودعات (Repositories)

الفروع (Branches)

الالتزامات (Commits)

طلبات السحب (Pull Requests - PRs)

النسخ المتفرع (Forking)

أحدث التطورات والميزات المتقدمة في GitHub

GitHub Actions

GitHub Packages

GitHub Codespaces

GitHub Copilot

ميزات الأمان المتقدمة

خطوات عملية لاحتراف GitHub

الممارسة العملية المستمرة

المساهمة في المشاريع مفتوحة المصدر

لماذا يكون `req.body` غير معرف؟

تطبيق `express.json()`

تطبيق `express.urlencoded()`

التحقق من رأس `Content-Type`

قيود
التقليدية والحاجة للبديل