هماهنگ کردن رویدادهای جهانی با Temporal

زمان‌بندی رویدادها در مناطق زمانی مختلف با شیء قدیمی Date بسیار دشوار است، به‌ویژه در زمان انتقال به «ساعت تابستانی» (DST) که ممکن است ساعت‌ها نادیده گرفته شوند یا تکرار شوند.

‫Temporal API‏ Temporal.ZonedDateTime را برای نمایش تاریخ و زمان در منطقه زمانی خاصی ارائه می‌دهد و انتقال‌های ساعت تابستانی را به‌طور خودکار و قابل‌پیش‌بینی مدیریت می‌کند.

نحوه پیاده‌سازی

برای هماهنگ کردن رویدادهای جهانی و رسیدگی به تداخل‌های احتمالی ساعت تابستانی:

1. اجباری: ایجاد ZonedDateTime: از Temporal.ZonedDateTime.from() برای ایجاد شیء تاریخ-زمان آگاه از منطقه زمانی استفاده کنید.
2. اجباری: مدیریت ابهام: از گزینه disambiguation برای کنترل رفتار در مواقعی که زمان مبهم است یا وجود ندارد (مثلاً درطول تغییرات ساعت) استفاده کنید.
3. MANDATORY: Convert Time Zones: Use .withTimeZone() to see the equivalent time in another location.

مثال: زمان‌بندی و تشخیص تداخل

// 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 API بومی پشتیبانی نمی‌کنند، از تشخیص ویژگی استفاده کنید و temporal-polyfill (~۱۵ کیلوبایت 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();
})();