M

MLOG

Български

Подробно ръководство за JavaScript Temporal API – модерно решение за ефективно управление на дати и часове в разнообразни международни контексти.

JavaScript Temporal API: Модерно управление на дата и час за глобална аудитория

Обектът `Date` в JavaScript отдавна е източник на разочарование за разработчиците. Неговата изменяемост, непоследователен API и лоша поддръжка на часови зони доведоха до създаването на множество библиотеки като Moment.js и date-fns, които да запълнят празнините. Сега, с Temporal API, JavaScript предлага модерно, вградено решение за работа с дати и часове с подобрена яснота и прецизност. Тази статия предоставя подробен преглед на Temporal API, като се фокусира върху неговите характеристики, предимства и употреба в разнообразни международни контексти.

Какво е Temporal API?

Temporal API е нов, глобален обект в JavaScript, създаден да разреши недостатъците на обекта `Date`. Той предоставя изчистен, неизменяем API за работа с дати, часове, часови зони и календарни системи. От решаващо значение е, че той има за цел да представи концепциите за дата и час по начин, който е по-близък до реалната употреба и очаквания, правейки интернационализацията много по-лесна.

Ключови характеристики:

Основни Temporal обекти

Temporal API въвежда няколко нови типа обекти. Ето някои от основните:

Работа с дати

Създаване на `Temporal.PlainDate`

За да създадете `Temporal.PlainDate`, можете да използвате конструктора:

const plainDate = new Temporal.PlainDate(2024, 10, 27); // Година, месец (1-12), ден
console.log(plainDate.toString()); // Резултат: 2024-10-27

Можете също да използвате метода `from`, който приема низ във формат ISO 8601:

const plainDateFromString = Temporal.PlainDate.from('2024-10-27');
console.log(plainDateFromString.toString()); // Резултат: 2024-10-27

Получаване на компоненти на датата

Можете да достъпите отделни компоненти на датата чрез свойства като `year`, `month` и `day`:

console.log(plainDate.year); // Резултат: 2024
console.log(plainDate.month); // Резултат: 10
console.log(plainDate.day); // Резултат: 27

Аритметика с дати

За да добавите или извадите дни, седмици, месеци или години, използвайте методите `plus` и `minus`. Тези методи връщат нов обект `Temporal.PlainDate`:

const nextWeek = plainDate.plus({ days: 7 });
console.log(nextWeek.toString()); // Резултат: 2024-11-03

const lastMonth = plainDate.minus({ months: 1 });
console.log(lastMonth.toString()); // Резултат: 2024-09-27

Сравняване на дати

Можете да сравнявате дати с помощта на метода `compare`:

const date1 = new Temporal.PlainDate(2024, 10, 27);
const date2 = new Temporal.PlainDate(2024, 11, 15);

console.log(Temporal.PlainDate.compare(date1, date2)); // Резултат: -1 (date1 е по-рано от date2)

Работа с часове

Създаване на `Temporal.PlainTime`

За да създадете `Temporal.PlainTime`, използвайте конструктора:

const plainTime = new Temporal.PlainTime(10, 30, 0); // Час, минута, секунда
console.log(plainTime.toString()); // Резултат: 10:30:00

Или използвайте метода `from` с ISO 8601 низ за час:

const plainTimeFromString = Temporal.PlainTime.from('10:30:00');
console.log(plainTimeFromString.toString()); // Резултат: 10:30:00

Получаване на компоненти на часа

console.log(plainTime.hour); // Резултат: 10
console.log(plainTime.minute); // Резултат: 30
console.log(plainTime.second); // Резултат: 0

Аритметика с часове

const later = plainTime.plus({ minutes: 15 });
console.log(later.toString()); // Резултат: 10:45:00

Работа с дата и час заедно

Създаване на `Temporal.PlainDateTime`

Можете да създадете `Temporal.PlainDateTime` директно или като комбинирате `Temporal.PlainDate` и `Temporal.PlainTime`:

const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
console.log(plainDateTime.toString()); // Резултат: 2024-10-27T10:30:00

const date = new Temporal.PlainDate(2024, 10, 27);
const time = new Temporal.PlainTime(10, 30, 0);
const combinedDateTime = date.toPlainDateTime(time);
console.log(combinedDateTime.toString()); // Резултат: 2024-10-27T10:30:00

Часови зони

Правилната работа с часовите зони е от решаващо значение за приложения, които обслужват потребители на различни места. Temporal API предоставя стабилна поддръжка на часови зони чрез обектите `Temporal.ZonedDateTime` и `Temporal.TimeZone`.

Създаване на `Temporal.ZonedDateTime`

За да създадете `Temporal.ZonedDateTime`, ви трябват `Temporal.PlainDateTime` и идентификатор на часова зона. Идентификаторите на часови зони се основават на базата данни на IANA (напр. `America/Los_Angeles`, `Europe/London`, `Asia/Tokyo`).

const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);
console.log(zonedDateTime.toString()); // Резултат: 2024-10-27T10:30:00-07:00[America/Los_Angeles] (Отместването ще зависи от правилата за лятно часово време)

Алтернативно, създайте `Temporal.ZonedDateTime` от `Instant`.

const instant = Temporal.Instant.fromEpochSeconds(1666866600); // Примерно клеймо за време
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO(timeZone); // Часова зона като 'America/Los_Angeles'
console.log(zonedDateTimeFromInstant.toString());

Конвертиране между часови зони

Можете да конвертирате `Temporal.ZonedDateTime` в различна часова зона с помощта на метода `withTimeZone`:

const newTimeZone = 'Europe/London';
const zonedDateTimeInLondon = zonedDateTime.withTimeZone(newTimeZone);
console.log(zonedDateTimeInLondon.toString()); // Резултат: 2024-10-27T18:30:00+01:00[Europe/London]

Работа с отмествания на часови зони

Методът `getOffsetStringFor` на обекта `Temporal.TimeZone` предоставя низа на отместването за даден `Temporal.Instant`:

const timeZoneObject = new Temporal.TimeZone(timeZone);
const offsetString = timeZoneObject.getOffsetStringFor(zonedDateTime.toInstant());
console.log(offsetString); // Резултат: -07:00 (В зависимост от правилата за лятно часово време)

От съществено значение е да се използват правилните идентификатори на часови зони на IANA за точни изчисления. Тези идентификатори се поддържат и актуализират редовно, за да отразяват промените в лятното часово време и границите на часовите зони.

Продължителности (Durations)

Обектът `Temporal.Duration` представлява период от време. Той може да се използва за добавяне или изваждане от дати и часове.

Създаване на `Temporal.Duration`

Можете да създадете `Temporal.Duration` с помощта на конструктора, като посочите годините, месеците, дните, часовете, минутите, секундите, милисекундите, микросекундите и наносекундите:

const duration = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 8, 9); // Години, месеци, дни, часове, минути, секунди, милисекунди, микросекунди, наносекунди
console.log(duration.toString()); // Резултат: P1Y2M3DT4H5M6.007008009S

Или като използвате низ за продължителност по ISO 8601:

const durationFromString = Temporal.Duration.from('P1Y2M3DT4H5M6S');
console.log(durationFromString.toString()); // Резултат: P1Y2M3DT4H5M6S

Добавяне на продължителности към дати и часове

const plainDate = new Temporal.PlainDate(2024, 10, 27);
const duration = new Temporal.Duration(0, 0, 7); // 7 дни
const newDate = plainDate.plus(duration);
console.log(newDate.toString()); // Резултат: 2024-11-03

Имайте предвид, че добавянето на продължителности, които включват месеци или години към дати, изисква внимателно обмисляне, тъй като броят на дните в месеца или годината може да варира.

Календарни системи

Temporal API поддържа различни календарни системи освен григорианския календар. Това е от решаващо значение за приложения, които трябва да обработват дати в различни културни контексти. Въпреки че поддръжката все още се развива, тя предоставя основа за бъдещо разширяване.

Използване на алтернативни календари

За да използвате конкретен календар, можете да го посочите при създаване на Temporal обекти:

const hebrewDate = new Temporal.PlainDate(5785, 1, 1, { calendar: 'hebrew' });
console.log(hebrewDate.toString()); // Конкретният резултат може да варира в зависимост от имплементацията и форматирането. Изисква polyfill в много среди към момента на писане на тази статия.

Важно: Поддръжката на негригориански календари може да изисква polyfills или специфична поддръжка от браузъра/средата. Проверете документацията на Temporal API и таблиците за съвместимост на браузърите за най-новата информация.

Форматиране на дати и часове

Въпреки че Temporal API се фокусира върху манипулирането на дати и часове, форматирането обикновено се извършва от обекта `Intl.DateTimeFormat`, който е част от Internationalization API. Temporal обектите работят безпроблемно с `Intl.DateTimeFormat`.

Използване на `Intl.DateTimeFormat`

Ето как да форматирате `Temporal.PlainDate` с помощта на `Intl.DateTimeFormat`:

const plainDate = new Temporal.PlainDate(2024, 10, 27);
const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatter.format(plainDate)); // Резултат: October 27, 2024

const formatterGerman = new Intl.DateTimeFormat('de-DE', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatterGerman.format(plainDate)); // Резултат: 27. Oktober 2024

Можете да персонализирате опциите за форматиране според вашите нужди. Първият аргумент на `Intl.DateTimeFormat` е локалът (locale), който определя езика и регионалните конвенции, използвани за форматиране. Използването на различни локали (напр. 'en-US', 'de-DE', 'fr-FR', 'ja-JP') води до различни формати на изхода.

Форматиране на `Temporal.ZonedDateTime`

Форматирането на `Temporal.ZonedDateTime` е подобно, но можете да включите и информация за часовата зона в резултата:

const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);

const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric', timeZoneName: 'short' });
console.log(formatter.format(zonedDateTime)); // Резултат: October 27, 2024, 10:30 AM PDT (Абревиатурата на часовата зона зависи от правилата за лятно часово време)

Най-добри практики за интернационализация

Когато работите с дати и часове в глобален контекст, имайте предвид следните най-добри практики:

Сравнение на Temporal API със стария обект Date

Ето таблица, която подчертава основните разлики и предимства на Temporal API в сравнение със стария обект `Date`:

Характеристика Старият обект `Date` Temporal API
Изменност Изменяем (променя оригиналния обект) Неизменяем (връща нови обекти)
Поддръжка на часови зони Ограничена и често проблематична Стабилна и точна, базирана на базата данни за часови зони на IANA
API Непоследователен и труден за използване Ясен, последователен и интуитивен
Точност Милисекунда Наносекунда
Календарни системи Ограничена до григорианския Поддържа алтернативни календарни системи (с развиваща се поддръжка)
Интернационализация Изисква външни библиотеки за стабилна интернационализация Вградена поддръжка и безпроблемна интеграция с `Intl.DateTimeFormat`

Поддръжка от браузъри и Polyfills

Като сравнително нов API, поддръжката на Temporal API от браузърите все още се развива. Проверете най-новите таблици за съвместимост на браузърите (напр. в MDN Web Docs), за да видите кои браузъри и среди го поддържат нативно. За по-стари браузъри или среди без нативна поддръжка, можете да използвате polyfills, за да осигурите функционалността на Temporal API. Потърсете в интернет "Temporal API polyfill", за да намерите подходящи опции.

Заключение

JavaScript Temporal API представлява значителна стъпка напред в работата с дати и часове в JavaScript. Неговата неизменност, ясен API, стабилна поддръжка на часови зони и възможности за календарни системи го правят мощен инструмент за разработчици, създаващи приложения, които трябва да работят с дати и часове точно и надеждно в разнообразни международни контексти. Въпреки че поддръжката от браузърите все още се развива, предимствата на Temporal API го правят струващ си за научаване и внедряване в нови проекти. Като възприемете Temporal API и следвате най-добрите практики за интернационализация, можете да създадете приложения, които предоставят безпроблемно и точно изживяване с дати и часове за потребители по целия свят.

Допълнителни ресурси