العمل مع التواريخ والوقت في TypeScript: من الألف إلى الياء

مقدمة: لماذا يتطلب العمل مع التواريخ في TypeScript اهتمامًا خاصًا

العمل مع التواريخ والوقت هو أحد أكثر المهام شيوعًا وفي نفس الوقت غدرًا في تطوير الويب. في TypeScript، الذي يعتبر طبقة علوية صارمة في التوصيف فوق JavaScript، ورث الكائن Date جميع "مزايا" سلفه: أشهر غير بديهية (العد من الصفر)، قابلية تغيير الطرق، ومشاكل المناطق الزمنية. ومع ذلك، باستخدام التوصيف الصارم والمكتبات الحديثة، يمكنك كتابة كود آمن وقابل للتنبؤ وسهل القراءة للعمل مع الوقت.

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

1. الأساسيات: كائن Date وتوصيفه في TypeScript

الإنشاء والطرق الأساسية

في TypeScript، كما في JavaScript، يتم استخدام الكائن المدمج Date للعمل مع التواريخ. يوفر TypeScript أنواعًا جاهزة له، لذلك لا حاجة لتعريفات إضافية.

// إنشاء التاريخ الحالي\nconst now: Date = new Date();\nconsole.log(now); // 2024-01-15T10:30:00.000Z\n\n// الإنشاء من سلسلة نصية (ISO 8601)\nconst specificDate: Date = new Date('2024-12-31T23:59:59');\n\n// الإنشاء من المكونات (السنة، الشهر [0-11]، اليوم، الساعات...)\nconst birthday: Date = new Date(1990, 0, 15); // 15 يناير 1990\n// انتبه: الشهر 0 = يناير!

مشكلة قابلية التغيير

طرق كائن Date تغير الكائن الأصلي. هذا يمكن أن يؤدي إلى أخطاء غير متوقعة. لا يمكن لـ TypeScript منع ذلك على مستوى الأنواع، ولكن يمكنك استخدام طرق غير قابلة للتغيير.

const date = new Date('2024-01-01');\ndate.setDate(date.getDate() + 5); // تغيير! date الآن 6 يناير\n// الأفضل إنشاء كائن جديد:\nconst newDate = new Date(date.getTime() + 5 * 24 * 60 * 60 * 1000);

توصيف Unix Timestamp

غالبًا ما يتم تمرير التواريخ كأرقام (مللي ثانية منذ 1970). استخدم type alias للوضوح:

type UnixTimestamp = number;\n\nfunction formatTimestamp(ts: UnixTimestamp): string {\n  return new Date(ts).toISOString();\n}\n\nconst myTimestamp: UnixTimestamp = 1705315200000;\nconsole.log(formatTimestamp(myTimestamp));

2. تنسيق وتحليل التواريخ

طرق التنسيق المدمجة

توفر JavaScript طرقًا أساسية للإخراج المترجم. في TypeScript تعمل "خارج الصندوق":

const date = new Date('2024-06-15T14:30:00');\n\n// سلاسل مترجمة\nconsole.log(date.toLocaleDateString('ar-SA')); // "١٥/٠٦/٢٠٢٤"\nconsole.log(date.toLocaleTimeString('en-US')); // "2:30:00 PM"\nconsole.log(date.toLocaleString('de-DE'));     // "15.6.2024, 14:30:00"\n\n// سلسلة ISO (مناسبة لـ API)\nconsole.log(date.toISOString()); // "2024-06-15T11:30:00.000Z" (دائمًا UTC)

تحليل السلاسل: المخاطر

تحليل السلاسل عبر المُنشئ new Date(str) يمكن أن يعطي نتائج غير متوقعة في متصفحات مختلفة. من الأفضل استخدام Date.parse() مع فحص صريح أو مكتبات خارجية.

// طريقة غير موثوقة\nconst parsed = new Date('2024/01/15'); // قد يعمل بشكل غير مستقر\n\n// طريقة موثوقة: ISO 8601\nconst safeParse = (dateStr: string): Date | null => {\n  const ts = Date.parse(dateStr);\n  return isNaN(ts) ? null : new Date(ts);\n};\n\nconst result = safeParse('2024-01-15T10:00:00Z');\nif (result) {\n  console.log(result.toISOString());\n}

3. المعالجة المتقدمة والمقارنة

مقارنة التواريخ

يمكن مقارنة التواريخ مباشرة عبر عوامل المقارنة، ولكن للمقارنة الدقيقة (المساواة) يجب تحويلها إلى رقم:

const date1 = new Date('2024-01-01');\nconst date2 = new Date('2024-01-0