M

MLOG

Română

Un ghid detaliat despre API-ul Temporal JavaScript, o soluție modernă pentru gestionarea eficientă a datelor și orelor în diverse contexte internaționale.

API-ul Temporal JavaScript: Gestionarea Modernă a Datei și Orei pentru un Public Global

Obiectul `Date` din JavaScript a fost mult timp o sursă de frustrare pentru dezvoltatori. Mutabilitatea sa, API-ul inconsecvent și suportul slab pentru fusuri orare au dus la apariția a numeroase biblioteci precum Moment.js și date-fns pentru a umple golurile. Acum, cu API-ul Temporal, JavaScript oferă o soluție modernă, încorporată, pentru gestionarea datelor și orelor cu o claritate și precizie îmbunătățite. Acest articol oferă o imagine de ansamblu cuprinzătoare a API-ului Temporal, concentrându-se pe caracteristicile, beneficiile și utilizarea sa în diverse contexte internaționale.

Ce este API-ul Temporal?

API-ul Temporal este un obiect global nou în JavaScript, conceput pentru a remedia deficiențele obiectului `Date`. Acesta oferă un API curat și imuabil pentru lucrul cu date, ore, fusuri orare și sisteme de calendar. În mod crucial, își propune să reprezinte conceptele de dată și oră într-un mod care se aliniază mai strâns cu utilizarea și așteptările din lumea reală, făcând internaționalizarea mult mai simplă.

Caracteristici Cheie:

Obiecte Temporale de Bază

API-ul Temporal introduce câteva tipuri noi de obiecte. Iată câteva dintre cele de bază:

Lucrul cu Datele

Crearea unui `Temporal.PlainDate`

Pentru a crea un `Temporal.PlainDate`, puteți utiliza constructorul:

const plainDate = new Temporal.PlainDate(2024, 10, 27); // An, Lună (1-12), Zi
console.log(plainDate.toString()); // Rezultat: 2024-10-27

Puteți folosi și metoda `from`, care acceptă un șir de caractere în format ISO 8601:

const plainDateFromString = Temporal.PlainDate.from('2024-10-27');
console.log(plainDateFromString.toString()); // Rezultat: 2024-10-27

Obținerea Componentelor Datei

Puteți accesa componentele individuale ale datei folosind proprietăți precum `year`, `month` și `day`:

console.log(plainDate.year); // Rezultat: 2024
console.log(plainDate.month); // Rezultat: 10
console.log(plainDate.day); // Rezultat: 27

Aritmetica Datelor

Pentru a adăuga sau a scădea zile, săptămâni, luni sau ani, utilizați metodele `plus` și `minus`. Aceste metode returnează un nou obiect `Temporal.PlainDate`:

const nextWeek = plainDate.plus({ days: 7 });
console.log(nextWeek.toString()); // Rezultat: 2024-11-03

const lastMonth = plainDate.minus({ months: 1 });
console.log(lastMonth.toString()); // Rezultat: 2024-09-27

Compararea Datelor

Puteți compara datele folosind metoda `compare`:

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

console.log(Temporal.PlainDate.compare(date1, date2)); // Rezultat: -1 (date1 este anterioară lui date2)

Lucrul cu Orele

Crearea unui `Temporal.PlainTime`

Pentru a crea un `Temporal.PlainTime`, utilizați constructorul:

const plainTime = new Temporal.PlainTime(10, 30, 0); // Oră, Minut, Secundă
console.log(plainTime.toString()); // Rezultat: 10:30:00

Sau utilizați metoda `from` cu un șir de caractere de timp ISO 8601:

const plainTimeFromString = Temporal.PlainTime.from('10:30:00');
console.log(plainTimeFromString.toString()); // Rezultat: 10:30:00

Obținerea Componentelor Orei

console.log(plainTime.hour); // Rezultat: 10
console.log(plainTime.minute); // Rezultat: 30
console.log(plainTime.second); // Rezultat: 0

Aritmetica Orelor

const later = plainTime.plus({ minutes: 15 });
console.log(later.toString()); // Rezultat: 10:45:00

Lucrul cu Data și Ora Împreună

Crearea unui `Temporal.PlainDateTime`

Puteți crea un `Temporal.PlainDateTime` direct sau combinând un `Temporal.PlainDate` și un `Temporal.PlainTime`:

const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
console.log(plainDateTime.toString()); // Rezultat: 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()); // Rezultat: 2024-10-27T10:30:00

Fusuri Orare

Gestionarea corectă a fusurilor orare este crucială pentru aplicațiile care se adresează utilizatorilor din locații diferite. API-ul Temporal oferă suport robust pentru fusuri orare prin obiectele `Temporal.ZonedDateTime` și `Temporal.TimeZone`.

Crearea unui `Temporal.ZonedDateTime`

Pentru a crea un `Temporal.ZonedDateTime`, aveți nevoie de un `Temporal.PlainDateTime` și de un identificator de fus orar. Identificatorii de fus orar se bazează pe baza de date de fusuri orare IANA (de ex., `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()); // Rezultat: 2024-10-27T10:30:00-07:00[America/Los_Angeles] (Decalajul va depinde de regulile orei de vară)

Alternativ, creați un `Temporal.ZonedDateTime` dintr-un `Instant`.

const instant = Temporal.Instant.fromEpochSeconds(1666866600); // Exemplu de timestamp
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO(timeZone); // Fus orar precum 'America/Los_Angeles'
console.log(zonedDateTimeFromInstant.toString());

Conversia între Fusuri Orare

Puteți converti un `Temporal.ZonedDateTime` într-un alt fus orar folosind metoda `withTimeZone`:

const newTimeZone = 'Europe/London';
const zonedDateTimeInLondon = zonedDateTime.withTimeZone(newTimeZone);
console.log(zonedDateTimeInLondon.toString()); // Rezultat: 2024-10-27T18:30:00+01:00[Europe/London]

Lucrul cu Decalajele de Fus Orar

Metoda `getOffsetStringFor` a obiectului `Temporal.TimeZone` oferă șirul de decalaj pentru un `Temporal.Instant` dat:

const timeZoneObject = new Temporal.TimeZone(timeZone);
const offsetString = timeZoneObject.getOffsetStringFor(zonedDateTime.toInstant());
console.log(offsetString); // Rezultat: -07:00 (În funcție de regulile orei de vară)

Este esențial să utilizați identificatorii corecți de fus orar IANA pentru calcule precise. Acești identificatori sunt întreținuți și actualizați regulat pentru a reflecta schimbările în ora de vară și limitele fusurilor orare.

Durate

Obiectul `Temporal.Duration` reprezintă un interval de timp. Poate fi folosit pentru a adăuga sau a scădea din date și ore.

Crearea unei `Temporal.Duration`

Puteți crea o `Temporal.Duration` folosind constructorul, specificând anii, lunile, zilele, orele, minutele, secundele, milisecundele, microsecundele și nanosecundele:

const duration = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 8, 9); // Ani, Luni, Zile, Ore, Minute, Secunde, Milisecunde, Microsecunde, Nanosecunde
console.log(duration.toString()); // Rezultat: P1Y2M3DT4H5M6.007008009S

Sau folosind un șir de durată ISO 8601:

const durationFromString = Temporal.Duration.from('P1Y2M3DT4H5M6S');
console.log(durationFromString.toString()); // Rezultat: P1Y2M3DT4H5M6S

Adăugarea Duratelor la Date și Ore

const plainDate = new Temporal.PlainDate(2024, 10, 27);
const duration = new Temporal.Duration(0, 0, 7); // 7 zile
const newDate = plainDate.plus(duration);
console.log(newDate.toString()); // Rezultat: 2024-11-03

Rețineți că adăugarea duratelor care implică luni sau ani la date necesită o atenție deosebită, deoarece numărul de zile dintr-o lună sau an poate varia.

Sisteme de Calendar

API-ul Temporal suportă diferite sisteme de calendar pe lângă cel gregorian. Acest lucru este crucial pentru aplicațiile care trebuie să gestioneze date în diverse contexte culturale. Deși suportul este încă în evoluție, acesta oferă o fundație pentru extinderea viitoare.

Utilizarea Calendarelor Alternative

Pentru a utiliza un calendar specific, îl puteți specifica la crearea obiectelor Temporal:

const hebrewDate = new Temporal.PlainDate(5785, 1, 1, { calendar: 'hebrew' });
console.log(hebrewDate.toString()); // Rezultatul specific poate varia în funcție de implementare și formatare. La momentul scrierii acestui articol, necesită un polyfill în multe medii.

Important: Suportul pentru calendarele non-gregoriene ar putea necesita polyfill-uri sau suport specific din partea browserului/mediului de execuție. Verificați documentația API-ului Temporal și tabelele de compatibilitate ale browserelor pentru cele mai recente informații.

Formatarea Datelor și Orelor

Deși API-ul Temporal se concentrează pe manipularea datei și orei, formatarea este de obicei gestionată de obiectul `Intl.DateTimeFormat`, care face parte din API-ul de Internaționalizare. Obiectele Temporal funcționează perfect cu `Intl.DateTimeFormat`.

Utilizarea `Intl.DateTimeFormat`

Iată cum să formatați un `Temporal.PlainDate` folosind `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)); // Rezultat: October 27, 2024

const formatterGerman = new Intl.DateTimeFormat('de-DE', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatterGerman.format(plainDate)); // Rezultat: 27. Oktober 2024

Puteți personaliza opțiunile de formatare pentru a se potrivi nevoilor dumneavoastră. Primul argument pentru `Intl.DateTimeFormat` este localizarea (locale), care determină limba și convențiile regionale utilizate pentru formatare. Utilizarea unor localizări diferite (de ex., 'en-US', 'de-DE', 'fr-FR', 'ja-JP') produce formate de ieșire diferite.

Formatarea `Temporal.ZonedDateTime`

Formatarea `Temporal.ZonedDateTime` este similară, dar puteți include și informații despre fusul orar în rezultat:

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)); // Rezultat: October 27, 2024, 10:30 AM PDT (Abrevierea fusului orar depinde de regulile orei de vară)

Cele Mai Bune Practici de Internaționalizare

Când lucrați cu date și ore într-un context global, țineți cont de următoarele bune practici:

Comparație între API-ul Temporal și Obiectul `Date` Tradițional

Iată un tabel care evidențiază diferențele cheie și avantajele API-ului Temporal în comparație cu obiectul `Date` tradițional:

Caracteristică Obiectul `Date` Tradițional API Temporal
Mutabilitate Muabil (modifică obiectul original) Imuabil (returnează obiecte noi)
Suport Fus Orar Limitat și adesea problematic Robust și precis, bazat pe baza de date de fusuri orare IANA
API Inconsecvent și dificil de utilizat Clar, consecvent și intuitiv
Precizie Milisecundă Nanosecundă
Sisteme de Calendar Limitat la Gregorian Suportă sisteme de calendar alternative (cu suport în evoluție)
Internaționalizare Necesită biblioteci externe pentru o internaționalizare robustă Suport încorporat și integrare perfectă cu `Intl.DateTimeFormat`

Suport în Browsere și Polyfill-uri

Fiind un API relativ nou, suportul browserelor pentru API-ul Temporal este încă în evoluție. Verificați cele mai recente tabele de compatibilitate ale browserelor (de ex., pe MDN Web Docs) pentru a vedea ce browsere și medii îl suportă nativ. Pentru browsere mai vechi sau medii fără suport nativ, puteți utiliza polyfill-uri pentru a oferi funcționalitatea API-ului Temporal. Căutați pe web "Temporal API polyfill" pentru a găsi opțiuni potrivite.

Concluzie

API-ul Temporal JavaScript reprezintă un pas înainte semnificativ în gestionarea datelor și orelor în JavaScript. Imuabilitatea sa, API-ul clar, suportul robust pentru fusuri orare și capacitățile sistemelor de calendar îl fac un instrument puternic pentru dezvoltatorii care construiesc aplicații ce necesită să lucreze cu date și ore în mod precis și fiabil în diverse contexte internaționale. Deși suportul browserelor este încă în evoluție, beneficiile API-ului Temporal îl fac demn de învățat și adoptat pentru proiecte noi. Prin adoptarea API-ului Temporal și respectarea bunelor practici de internaționalizare, puteți crea aplicații care oferă o experiență de dată și oră fără cusur și precisă pentru utilizatorii din întreaga lume.

Resurse Suplimentare