Практика: локалізований календар із часовими зонами · fullstack.org.ua

Просунутий25 хв· Fullstack Team

Практика: локалізований календар із часовими зонами

Застосуєте Date, Intl і Temporal у практичному сценарії календаря з часовими зонами та локалізованим інтерфейсом.

Мета уроку

У цьому уроці побудуємо основу локалізованого календаря, який:

зберігає події як абсолютні моменти часу;
показує їх у часовій зоні користувача;
локалізує дату, час, назви місяців і днів тижня;
коректно працює з переходами на літній і зимовий час;
використовує Date, Intl і сучасний API Temporal;
розділяє момент часу, календарну дату та локальний час.

Головна ідея:

Подія має зберігатися як момент часу, а відображатися — у часовій зоні та локалі конкретного користувача.

Момент часу, локальна дата і часова зона

Розглянемо подію:

text

2026-03-29T09:00:00Z

javascript

const instant = new Date("2026-03-29T09:00:00Z");

const kyivFormatter = new Intl.DateTimeFormat("uk-UA", {
  dateStyle: "full",
  timeStyle: "short",
  timeZone: "Europe/Kyiv",
});

const newYorkFormatter = new Intl.DateTimeFormat("en-US", {
  dateStyle: "full",
  timeStyle: "short",
  timeZone: "America/New_York",
});

console.log(kyivFormatter.format(instant));
// неділя, 29 березня 2026 р. о 12:00

console.log(newYorkFormatter.format(instant));
// Sunday, March 29, 2026 at 5:00 AM

javascript

const formatter = new Intl.DateTimeFormat("uk-UA", {
  timeZone: "Europe/Kyiv",
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
  hour: "2-digit",
  minute: "2-digit",
  second: "2-digit",
  timeZoneName: "short",
});

console.log(formatter.format(new Date("2026-07-26T10:15:00Z")));

javascript

const events = [
  {
    id: 1,
    title: "Планування спринту",
    startsAt: "2026-03-29T09:00:00Z",
    durationMinutes: 60,
  },
  {
    id: 2,
    title: "Демонстрація функціональності",
    startsAt: "2026-03-29T15:30:00Z",
    durationMinutes: 45,
  },
  {
    id: 3,
    title: "Зустріч із командою з Токіо",
    startsAt: "2026-03-30T00:30:00Z",
    durationMinutes: 30,
  },
];

function createCalendarFormatters(locale, timeZone) {
  return {
    date: new Intl.DateTimeFormat(locale, {
      dateStyle: "full",
      timeZone,
    }),

    time: new Intl.DateTimeFormat(locale, {
      hour: "2-digit",
      minute: "2-digit",
      timeZone,
    }),

    dateTime: new Intl.DateTimeFormat(locale, {
      dateStyle: "medium",
      timeStyle: "short",
      timeZone,
    }),

    month: new Intl.DateTimeFormat(locale, {
      month: "long",
      year: "numeric",
      timeZone,
    }),

    weekday: new Intl.DateTimeFormat(locale, {
      weekday: "short",
      timeZone,
    }),
  };
}

function formatEvent(event, formatters) {
  const start = new Date(event.startsAt);
  const end = new Date(start.getTime() + event.durationMinutes * 60_000);

  return {
    id: event.id,
    title: event.title,
    startsAt: formatters.dateTime.format(start),
    endsAt: formatters.time.format(end),
    date: formatters.date.format(start),
  };
}

function renderCalendar(events, {
  locale = "uk-UA",
  timeZone = "Europe/Kyiv",
} = {}) {
  const formatters = createCalendarFormatters(locale, timeZone);

  const sortedEvents = [...events]
    .map((event) => ({
      ...event,
      instant: new Date(event.startsAt),
    }))
    .sort((a, b) => a.instant - b.instant);

  const result = {
    heading: formatters.month.format(sortedEvents[0]?.instant ?? new Date()),
    timeZone,
    events: sortedEvents.map((event) => formatEvent(event, formatters)),
  };

  return result;
}

const kyivCalendar = renderCalendar(events, {
  locale: "uk-UA",
  timeZone: "Europe/Kyiv",
});

const tokyoCalendar = renderCalendar(events, {
  locale: "ja-JP",
  timeZone: "Asia/Tokyo",
});

console.log("Календар користувача з Києва:");
console.log(kyivCalendar);

console.log("Календар користувача з Токіо:");
console.log(tokyoCalendar);

javascript

const formatter = new Intl.DateTimeFormat("uk-UA", {
  timeZone: "Europe/Kyiv",
  year: "numeric",
  month: "2-digit",
  day: "2-digit",
  hour: "2-digit",
  minute: "2-digit",
  hourCycle: "h23",
});

const parts = formatter.formatToParts(
  new Date("2026-03-29T09:00:00Z"),
);

const values = Object.fromEntries(
  parts
    .filter(({ type }) => type !== "literal")
    .map(({ type, value }) => [type, value]),
);

console.log(values);
// {
//   day: "29",
//   month: "03",
//   year: "2026",
//   hour: "12",
//   minute: "00"
// }

javascript

if (!globalThis.Temporal) {
  throw new Error("Це середовище не підтримує Temporal");
}

const instant = Temporal.Instant.from("2026-03-29T09:00:00Z");

const kyivTime = instant.toZonedDateTimeISO("Europe/Kyiv");
const newYorkTime = instant.toZonedDateTimeISO("America/New_York");

console.log(kyivTime.toString());
// 2026-03-29T12:00:00+03:00[Europe/Kyiv]

console.log(newYorkTime.toString());
// 2026-03-29T05:00:00-04:00[America/New_York]

javascript

const meeting = Temporal.Instant.from("2026-03-29T09:00:00Z")
  .toZonedDateTimeISO("Europe/Kyiv");

const sameMeetingInLondon = meeting.withTimeZone("Europe/London");

console.log(meeting.toString());
// 2026-03-29T12:00:00+03:00[Europe/Kyiv]

console.log(sameMeetingInLondon.toString());
// 2026-03-29T10:00:00+01:00[Europe/London]

javascript

const localDateTime = Temporal.PlainDateTime.from(
  "2026-03-29T12:00",
);

const zonedDateTime = localDateTime.toZonedDateTime({
  timeZone: "Europe/Kyiv",
});

const instant = zonedDateTime.toInstant();

console.log(zonedDateTime.toString());
// дата, час і зміщення для Europe/Kyiv

console.log(instant.toString());
// абсолютний момент у UTC

javascript

const localDateTime = Temporal.PlainDateTime.from(
  "2026-10-25T03:30",
);

const zonedDateTime = localDateTime.toZonedDateTime({
  timeZone: "Europe/Kyiv",
  disambiguation: "compatible",
});

console.log(zonedDateTime.toString());

javascript

try {
  const dateTime = Temporal.PlainDateTime.from(
    "2026-03-29T03:30",
  );

  const zoned = dateTime.toZonedDateTime({
    timeZone: "Europe/Kyiv",
    disambiguation: "reject",
  });

  console.log(zoned.toString());
} catch (error) {
  console.error("Вибраний час не існує в цій часовій зоні.");
}

javascript

if (!globalThis.Temporal) {
  throw new Error("Це середовище не підтримує Temporal");
}

function buildMonthGrid(year, month, locale = "uk-UA") {
  const firstDay = Temporal.PlainDate.from({
    year,
    month,
    day: 1,
  });

  const daysInMonth = firstDay.daysInMonth;

  // ISO: понеділок має номер 1, неділя — номер 7.
  const firstWeekday = firstDay.dayOfWeek;

  const formatter = new Intl.DateTimeFormat(locale, {
    weekday: "short",
    day: "numeric",
    month: "short",
  });

  const cells = [];

  // Додаємо порожні клітинки перед першим днем місяця.
  for (let index = 1; index < firstWeekday; index += 1) {
    cells.push(null);
  }

  for (let day = 1; day <= daysInMonth; day += 1) {
    const date = firstDay.with({ day });

    // PlainDate не можна напряму передати в Intl.DateTimeFormat.
    // Перетворюємо дату на UTC-момент лише для форматування назви.
    const instant = date
      .toPlainDateTime("12:00")
      .toZonedDateTime("UTC")
      .toInstant();

    cells.push({
      date: date.toString(),
      label: formatter.format(instant),
      weekday: date.dayOfWeek,
      isToday: Temporal.Now.plainDateISO().equals(date),
    });
  }

  return {
    month: firstDay.month,
    year: firstDay.year,
    cells,
  };
}

console.log(buildMonthGrid(2026, 3));

javascript

function isValidTimeZone(timeZone) {
  try {
    new Intl.DateTimeFormat("en", { timeZone }).format();
    return true;
  } catch {
    return false;
  }
}

console.log(isValidTimeZone("Europe/Kyiv"));
// true

console.log(isValidTimeZone("Invalid/Zone"));
// false

javascript

const event = {
  id: "event-42",
  title: "Розбір домашнього завдання",
  startsAt: "2026-03-29T09:00:00Z",
  durationMinutes: 90,
  createdInTimeZone: "Europe/Kyiv",
};

javascript

const testInstant = new Date("2026-03-29T00:30:00Z");

const zones = [
  "Europe/Kyiv",
  "America/New_York",
  "Asia/Tokyo",
];

for (const timeZone of zones) {
  const formatted = new Intl.DateTimeFormat("uk-UA", {
    dateStyle: "full",
    timeStyle: "short",
    timeZone,
  }).format(testInstant);

  console.log(`${timeZone}: ${formatted}`);
}

Практика: локалізований календар із часовими зонами

Мета уроку

Момент часу, локальна дата і часова зона

Часові зони та літній час

Форматування за допомогою `Intl.DateTimeFormat`

Основні параметри форматування

Важливість явного `timeZone`

Практичний приклад локалізованого календаря

Визначення локальних компонентів дати

Обчислення меж локального дня

API `Temporal`

Перетворення моменту в час у часовій зоні

Перехід між часовими зонами

Створення події з локальної дати і часу

Неоднозначні локальні часи

Побудова місячного календаря

Валідація часової зони

Проєктування даних календаря

Подія-момент

Подія в локальному часі

Календарна дата без часу

`Date` чи `Temporal`

Коли достатньо `Date`

Коли варто використовувати `Temporal`

Типові помилки

Парсинг неузгоджених рядків

Використання `toISOString()` для локального інтерфейсу

Ручне складання дати

Додавання 24 годин для переходу до наступного дня

Використання скорочення часового поясу як ідентифікатора

Припущення, що всі дні мають 24 години

Змішування локалі та часової зони

Перевірка календаря

Практичне завдання

Підсумок

Практика: локалізований календар із часовими зонами

Мета уроку

Момент часу, локальна дата і часова зона

Часові зони та літній час

Форматування за допомогою Intl.DateTimeFormat

Основні параметри форматування

Важливість явного timeZone

Практичний приклад локалізованого календаря

Визначення локальних компонентів дати

Обчислення меж локального дня

API Temporal

Перетворення моменту в час у часовій зоні

Перехід між часовими зонами

Створення події з локальної дати і часу

Неоднозначні локальні часи

Побудова місячного календаря

Валідація часової зони

Проєктування даних календаря

Подія-момент

Подія в локальному часі

Календарна дата без часу

Date чи Temporal

Коли достатньо Date

Коли варто використовувати Temporal

Типові помилки

Парсинг неузгоджених рядків

Використання toISOString() для локального інтерфейсу

Ручне складання дати

Додавання 24 годин для переходу до наступного дня

Використання скорочення часового поясу як ідентифікатора

Припущення, що всі дні мають 24 години

Змішування локалі та часової зони

Перевірка календаря

Практичне завдання

Підсумок

Форматування за допомогою `Intl.DateTimeFormat`

Важливість явного `timeZone`

API `Temporal`

`Date` чи `Temporal`

Коли достатньо `Date`

Коли варто використовувати `Temporal`

Використання `toISOString()` для локального інтерфейсу