key مفاتيح القوائم
آخر تحديث: 2026-11-03
key مفاتيح القوائم
الـ key هو هوية العنصر داخل قائمة معروضة. يعتمد عليه React لتمييز العناصر التي تغيّرت وتلك التي ينبغي نقلها أو حذفها؛ والخطأ فيه يؤدي إلى حالات في غير مواضعها وإلى تداخل القيم في حقول الإدخال. ويجب أن يكون الـ key فريداً وثابتاً داخل القائمة نفسها. واختيار الـ key قرار صغير بأثر كبير على سلوك القائمة.
| المجموعة | العرض والحالة |
|---|---|
| النوع | نمط |
| منذ الإصدار | أقدم إصدارات React |
ℹ️ ملاحظة يحوّل المحرّر JSX إلى JavaScript ويعرض الواجهة الحقيقية داخل بيئة معزولة؛ تُركَّب المكوّنات تلقائياً دون استدعاء render يدوي.
📝 الصيغة
{items.map((item) => (
<li key={item.id}>{item.text}</li> // ✅ معرّف ثابت وفريد
))}
// ❌ key={index}: تختل الحالة عندما تكبر القائمة أو تصغر أو يُعاد ترتيبها⚙️ المعاملات
| key | معرّف ثابت وفريد للعنصر؛ يستخدمه React أثناء مقارنة القوائم لتحديد أي عنصر يُعاد استخدامه أو يُنقل أو يُدمَّر. |
|---|
القيمة المرجعة：لا قيمة معادة — مجرد اصطلاح برمجي ونموذج ذهني.
▶ مثال
المثال يعمل مباشرة: يُعرض تلقائياً عند التوسيع وتظهر التعديلات فوراً.
الناتج：
كل صف في القائمة هو «اسم مهمة + مربع إدخال». اكتب نصاً في بضعة صفوف ثم اضغط «insert at the top»: تظهر المهمة الجديدة في الأعلى ويبقى ما كتبته مع مهمته الأصلية — والـ key الثابت يتيح لـ React التعرّف على كل عنصر.💡 النقاط الأساسية
⚠️ تحذير لا تستخدم index كـ key حين تتوسّع القائمة أو تصغر أو يُعاد ترتيبها أو تُصفّى؛ فالحالة الداخلية للعناصر تنتقل معها مواضعها.
💡 نصيحة فضّل معرّفاً من الخادم أو معرّفاً تجارياً ثابتاً آخر؛ ولا تلجأ إلى الفهرس إلا للقوائم الساكنة تماماً التي لا تملك معرّفاً ثابتاً.
ℹ️ ملاحظة لا يُمرَّر الـ key إلى داخل المكوّن: props.key داخل الابن هو undefined، فمرّر البيانات التي تحتاجها كـ prop عادي.
🏷️ المزيد من العرض والحالة
💡 حالات ذات صلة
المزيد من الحالات قريباً.
📚 دروس ذات صلة
❓ الأسئلة الشائعة
س لماذا لا أستطيع استخدام فهرس المصفوفة كـ key؟
ج لأن الفهرس يتبع الموضع لا البيانات: بعد الإدراج أو الحذف أو إعادة الترتيب قد يسلّم React حالة العنصر A إلى العنصر B، فتتداخل حقول الإدخال وتتخطأ مربعات الاختيار.
س هل يمكن تكرار المفاتيح؟
ج يجب أن تكون فريدة داخل القائمة نفسها؛ والتكرار يسبب أخطاء عرض وتحذيرات. أما القوائم المختلفة فمستقلة، لكل منها أن ترقّم من 1.
س كيف أعالج تحذير missing key في الطرفية؟
ج المعنى أن العناصر المعادة من map بلا key. امنح كل عنصر معرّفاً ثابتاً وفريداً (الأفضل معرّف تجاري)، وتأكد من وضعه على العنصر الخارجي لعنصر القائمة.
