تحميل الوظائف في TypeScript: دليل 2025 مع أمثلة

TypeScript Function Overloading: لماذا ليست "سحرًا" بل أداة للكود الذكي

إذا سبق لك أن كتبت دالة في JavaScript تقبل "مرة نصًا، ومرة رقمًا، ومرة مصفوفة"، فأنت تعرف هذه اللحظة المزعجة: داخل الدالة - جحيم من if، وخارجها - عدم يقين تام لمن يستدعي هذه الدالة. TypeScript يحل هذه المشكلة بأناقة، ولكن ليس دائمًا بشكل واضح. تحميل الوظائف (function overloading) لا يتعلق بإنشاء عدة دوال بنفس الاسم (كما في Java أو C++). إنه يتعلق بـ إعلان عدة تواقيع لتنفيذ واحد.

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

ما هو تحميل الوظائف في الواقع؟

تخيل أنك تكتب دالة formatDate. يجب أن تكون قادرة على:

\n
• استقبال كائن Date وإرجاع نص.
\n
• استقبال نص بتنسيق ISO وإرجاع نص.
\n
• استقبال رقم (timestamp) وإرجاع نص.
\n

إذا كتبت ببساطة function formatDate(input: Date | string | number): string، فلن يتمكن TypeScript من توضيح النوع الذي تمرره في استدعاء معين. سيعرض IDE النوع العام، وستفقد الإكمال التلقائي. التحميل يحل هذا:

// تواقيع التحميل (overload signatures)\nfunction formatDate(input: Date): string;\nfunction formatDate(input: string): string;\nfunction formatDate(input: number): string;\n\n// التنفيذ (implementation signature)\nfunction formatDate(input: Date | string | number): string {\n    if (input instanceof Date) {\n        return input.toISOString();\n    } else if (typeof input === 'string') {\n        return new Date(input).toISOString();\n    } else {\n        return new Date(input).toISOString();\n    }\n}

الآن، عندما تستدعي formatDate(new Date())، يعرف TypeScript أنه يتم إرجاع string، ويقترح الأنواع. لا يوجد سحر - هناك كتابة صارمة للأنواع.

القاعدة رقم 1: تواقيع التحميل لا يمكن أن تكون تنفيذًا

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

// ❌ خطأ: تكرار التنفيذ\nfunction foo(x: number): number {\n    return x * 2;\n}\nfunction foo(x: string): string {\n    return x.toUpperCase();\n}

TypeScript لا يدعم عمليات تنفيذ متعددة بنفس الاسم. دائمًا تنفيذ واحد، وإعلانات متعددة.

القاعدة رقم 2: ترتيب التواقيع مهم

يتحقق TypeScript من التواقيع من الأعلى إلى الأسفل. أول توقيع مطابق يحدد النوع المرتجع. لذلك:

\n
• ضع الأنواع الأكثر تحديدًا في الأعلى (مثل string قبل any).
\n
• تجنب التواقيع المتقاطعة التي قد تربك المترجم.
\n

// جيد: أولاً الحالة المحددة\nfunction createButton(label: string, disabled?: boolean): HTMLButtonElement;\nfunction createButton(options: { label: string; disabled?: boolean }): HTMLButtonElement;\nfunction createButton(labelOrOptions: string | { label: string; disabled?: boolean }, disabled?: boolean): HTMLButtonElement {\n    // التنفيذ\n}

القاعدة رقم 3: استخدم أنواع الاتحاد (Union Types) إذا كان عدد التواقيع أكثر من 3

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

\n
• حتى 3 تواقيع - استخدم التحميل.
\n
• أكثر من 3 - فكر في Union Type أو في