تنسيق الفعاليات العالمية باستخدام Temporal

من الصعب جدًا جدولة الأحداث في مناطق زمنية مختلفة باستخدام عنصر Date القديم، خاصةً في فترة الانتقال إلى نظام التوقيت الصيفي (DST) عندما يمكن تخطّي الساعات أو تكرارها.

توفّر واجهة برمجة التطبيقات Temporal السمة Temporal.ZonedDateTime لتمثيل التاريخ والوقت في منطقة زمنية معيّنة، مع معالجة عمليات الانتقال إلى التوقيت الصيفي تلقائيًا وبشكل يمكن توقّعه.

كيفية الإعداد

لتنسيق الأحداث العالمية والتعامل مع التعارضات المحتملة في التوقيت الصيفي:

1. MANDATORY: Create a ZonedDateTime: Use Temporal.ZonedDateTime.from() to create a time-zone-aware date-time object.
2. إلزامي: التعامل مع الغموض: استخدِم الخيار disambiguation للتحكّم في السلوك عندما يكون الوقت غامضًا أو غير موجود (على سبيل المثال، أثناء تغييرات الساعة).
3. إلزامي: تحويل المناطق الزمنية: استخدِم .withTimeZone() للاطّلاع على الوقت المكافئ في موقع جغرافي آخر.

مثال: الجدولة ورصد التعارضات

// 1. Define the event time and target time zone
const date = "2025-03-09";
const time = "02:30"; // This time is skipped in New York during Spring Forward
const timeZone = "America/New_York";
const inputStr = `${date}T${time}[${timeZone}]`;

// 2. Detect conflicts using 'reject'
let hasConflict = false;
try {
  // 'reject' throws RangeError if the time is ambiguous or does not exist
  Temporal.ZonedDateTime.from(inputStr, { disambiguation: 'reject' });
} catch (e) {
  if (e instanceof RangeError) {
    hasConflict = true;
    console.log("This time falls in a DST transition gap or overlap.");
  }
}

// 3. Resolve the time safely using 'compatible' (default)
// 'compatible' will resolve to a valid time even if skipped or repeated
const hostTime = Temporal.ZonedDateTime.from(inputStr, { disambiguation: 'compatible' });
console.log(`Resolved time: ${hostTime.toString()}`);

// 4. Convert to another time zone (e.g., Tokyo)
const tokyoTime = hostTime.withTimeZone("Asia/Tokyo");
// Use toLocaleString() for user-facing display instead of manual hour/minute padding
console.log(`Tokyo time: ${tokyoTime.toLocaleString('en-US', { hour: 'numeric', minute: '2-digit' })}`);

التنفيذ الاستراتيجي وأفضل الممارسات

• يجب استخدام Temporal.ZonedDateTime للأحداث المرتبطة بموقع جغرافي معيّن (مثل اجتماع في مدينة معيّنة).
• يُرجى استخدام disambiguation: 'reject' إذا كنت بحاجة إلى رصد تعارضات في الجداول الزمنية وتحذير المستخدمين بشأنها أثناء الانتقال إلى التوقيت الصيفي.
• يُرجى استخدام disambiguation: 'compatible' (الخيار التلقائي) عندما تريد أن يختار النظام تلقائيًا وقتًا مناسبًا عند حدوث تعارضات.
• لا تستخدِم Temporal.PlainDateTime للأحداث العالمية، لأنّها لا تتضمّن معلومات المنطقة الزمنية ولا يمكنها احتساب تغييرات التوقيت الصيفي.
• يُرجى استخدام .withTimeZone() لاحتساب الوقت المكافئ في مواقع جغرافية أخرى بدون تغيير العنصر الأصلي (عناصر Temporal غير قابلة للتغيير).
• يجب استخدام تنسيق .toLocaleString() الأصلي (مثل { hour: 'numeric', minute: '2-digit' }) لعرض الوقت موجّه للمستخدمين بدلاً من العمليات الحسابية اليدوية للوقت والمساحة المتروكة.

استراتيجية الإجراءات الاحتياطية

الخيارات الاحتياطية وتوافق المتصفّحات مع Temporal

بالنسبة إلى المتصفّحات التي لا تتيح استخدام واجهة برمجة التطبيقات Temporal الأصلية، استخدِم ميزة الكشف عن الميزات وحمِّل temporal-polyfill بشكل ديناميكي (بحجم 15 كيلوبايت تقريبًا min+gz).

يُرجى العِلم أنّ استيراد temporal-polyfill لا يؤدي تلقائيًا إلى تعيين الكائن Temporal للنطاق العام. يُرجى تعيينه بشكل صريح إذا كان الرمز البرمجي يعتمد على globalThis.Temporal.

// Check if Temporal is supported natively
(async () => {
  if (typeof Temporal === 'undefined') {
    // Load the polyfill conditionally
    const module = await import('https://esm.sh/temporal-polyfill');
    globalThis.Temporal = module.Temporal;
    // Extend Date.prototype if needed
    Date.prototype.toTemporalInstant = module.toTemporalInstant;
  }
  initializeApp();
})();