JavaScript Temporal API: Sodobno upravljanje datumov in časov za globalno občinstvo

Objekt `Date` v JavaScriptu je že dolgo vir frustracij za razvijalce. Njegova spremenljivost, nedosleden API in slaba podpora za časovne pasove so vodili do številnih knjižnic, kot sta Moment.js in date-fns, ki so zapolnile vrzeli. Zdaj JavaScript s Temporal API ponuja sodobno, vgrajeno rešitev za upravljanje datumov in časov z izboljšano jasnostjo in natančnostjo. Ta članek ponuja celovit pregled Temporal API, s poudarkom na njegovih značilnostih, prednostih in uporabi v različnih mednarodnih kontekstih.

Kaj je Temporal API?

Temporal API je nov, globalni objekt v JavaScriptu, zasnovan za odpravljanje pomanjkljivosti objekta `Date`. Ponuja čist, nespremenljiv API za delo z datumi, časi, časovnimi pasovi in koledarskimi sistemi. Ključno je, da si prizadeva predstaviti koncepte datuma in časa na način, ki se bolj ujema z resnično uporabo in pričakovanji, kar bistveno olajša internacionalizacijo.

Ključne značilnosti:

Nespremenljivost: Temporal objekti so nespremenljivi, kar pomeni, da operacije, kot je dodajanje dni ali mesecev, vrnejo nove objekte, namesto da bi spremenile izvirnega. To odpravlja pogost vir napak in olajša razumevanje kode.
Jasen API: Temporal ponuja dosleden in intuitiven API za pogoste operacije z datumi in časi.
Podpora za časovne pasove: Temporal vključuje robustno podporo za časovne pasove, kar vam omogoča delo z datumi in časi na različnih lokacijah brez zapletenosti starega objekta `Date`. Uporablja IANA bazo podatkov časovnih pasov, kar zagotavlja točne in posodobljene informacije.
Koledarski sistemi: Poleg gregorijanskega koledarja Temporal podpira tudi alternativne koledarske sisteme, kar ustreza potrebam različnih kultur in regij.
Izboljšana natančnost: Temporal ponuja nanosekundno natančnost, kar odpravlja omejitve milisekundnega objekta `Date`.

Osnovni Temporal objekti

Temporal API uvaja več novih vrst objektov. Tukaj je nekaj osrednjih:

`Temporal.PlainDate`: Predstavlja datum (leto, mesec, dan) brez časovnega pasu.
`Temporal.PlainTime`: Predstavlja čas (ura, minuta, sekunda, milisekunda, mikrosekunda, nanosekunda) brez datuma ali časovnega pasu.
`Temporal.PlainDateTime`: Predstavlja datum in čas brez časovnega pasu.
`Temporal.ZonedDateTime`: Predstavlja datum in čas z določenim časovnim pasom.
`Temporal.Instant`: Predstavlja določen trenutek v času, merjen v nanosekundah od Unix epohe (1. januar 1970 UTC).
`Temporal.TimeZone`: Predstavlja časovni pas.
`Temporal.Duration`: Predstavlja časovno obdobje (npr. 2 uri, 30 minut).
`Temporal.YearMonth`: Predstavlja leto in mesec.
`Temporal.MonthDay`: Predstavlja mesec in dan.

Delo z datumi

Ustvarjanje `Temporal.PlainDate`

Za ustvarjanje `Temporal.PlainDate` lahko uporabite konstruktor:

const plainDate = new Temporal.PlainDate(2024, 10, 27); // Leto, mesec (1-12), dan
console.log(plainDate.toString()); // Izhod: 2024-10-27

Uporabite lahko tudi metodo `from`, ki sprejme niz v formatu ISO 8601:

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

Pridobivanje komponent datuma

Do posameznih komponent datuma lahko dostopate z lastnostmi, kot so `year`, `month` in `day`:

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

Aritmetika datumov

Za dodajanje ali odštevanje dni, tednov, mesecev ali let uporabite metodi `plus` in `minus`. Ti metodi vrneta nov objekt `Temporal.PlainDate`:

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

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

Primerjanje datumov

Datume lahko primerjate z metodo `compare`:

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

console.log(Temporal.PlainDate.compare(date1, date2)); // Izhod: -1 (date1 je zgodnejši od date2)

Delo s časi

Ustvarjanje `Temporal.PlainTime`

Za ustvarjanje `Temporal.PlainTime` uporabite konstruktor:

const plainTime = new Temporal.PlainTime(10, 30, 0); // Ura, minuta, sekunda
console.log(plainTime.toString()); // Izhod: 10:30:00

Ali pa uporabite metodo `from` z nizom časa v formatu ISO 8601:

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

Pridobivanje komponent časa

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

Aritmetika časov

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

Skupno delo z datumom in časom

Ustvarjanje `Temporal.PlainDateTime`

`Temporal.PlainDateTime` lahko ustvarite neposredno ali z združevanjem `Temporal.PlainDate` in `Temporal.PlainTime`:

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

Časovni pasovi

Pravilno upravljanje časovnih pasov je ključnega pomena za aplikacije, ki delajo z uporabniki na različnih lokacijah. Temporal API zagotavlja robustno podporo za časovne pasove preko objektov `Temporal.ZonedDateTime` in `Temporal.TimeZone`.

Ustvarjanje `Temporal.ZonedDateTime`

Za ustvarjanje `Temporal.ZonedDateTime` potrebujete `Temporal.PlainDateTime` in identifikator časovnega pasu. Identifikatorji časovnih pasov temeljijo na IANA bazi podatkov časovnih pasov (npr. `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()); // Izhod: 2024-10-27T10:30:00-07:00[America/Los_Angeles] (Odklon bo odvisen od pravil poletnega časa)

Alternativno lahko `Temporal.ZonedDateTime` ustvarite iz objekta `Instant`.

const instant = Temporal.Instant.fromEpochSeconds(1666866600); // Primer časovnega žiga
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO(timeZone); // Časovni pas, kot je 'America/Los_Angeles'
console.log(zonedDateTimeFromInstant.toString());

Pretvarjanje med časovnimi pasovi

`Temporal.ZonedDateTime` lahko pretvorite v drug časovni pas z metodo `withTimeZone`:

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

Delo z odkloni časovnih pasov

Metoda `getOffsetStringFor` objekta `Temporal.TimeZone` vrne niz odklona za dani `Temporal.Instant`:

const timeZoneObject = new Temporal.TimeZone(timeZone);
const offsetString = timeZoneObject.getOffsetStringFor(zonedDateTime.toInstant());
console.log(offsetString); // Izhod: -07:00 (Odvisno od pravil poletnega časa)

Ključnega pomena je uporaba pravilnih identifikatorjev časovnih pasov IANA za natančne izračune. Ti identifikatorji se redno vzdržujejo in posodabljajo, da odražajo spremembe v poletnem času in mejah časovnih pasov.

Trajanja

Objekt `Temporal.Duration` predstavlja časovno obdobje. Uporablja se lahko za dodajanje ali odštevanje od datumov in časov.

Ustvarjanje `Temporal.Duration`

`Temporal.Duration` lahko ustvarite s konstruktorjem, kjer določite leta, mesece, dni, ure, minute, sekunde, milisekunde, mikrosekunde in nanosekunde:

const duration = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 8, 9); // Leta, meseci, dnevi, ure, minute, sekunde, milisekunde, mikrosekunde, nanosekunde
console.log(duration.toString()); // Izhod: P1Y2M3DT4H5M6.007008009S

Ali z uporabo niza trajanja v formatu ISO 8601:

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

Dodajanje trajanj datumom in časom

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

Upoštevajte, da dodajanje trajanj, ki vključujejo mesece ali leta, datumom zahteva previdnost, saj se število dni v mesecu ali letu lahko razlikuje.

Koledarski sistemi

Temporal API podpira različne koledarske sisteme poleg gregorijanskega. To je ključnega pomena za aplikacije, ki morajo obravnavati datume v različnih kulturnih kontekstih. Čeprav se podpora še razvija, ponuja osnovo za prihodnjo širitev.

Uporaba alternativnih koledarjev

Za uporabo določenega koledarja ga lahko navedete pri ustvarjanju Temporal objektov:

const hebrewDate = new Temporal.PlainDate(5785, 1, 1, { calendar: 'hebrew' });
console.log(hebrewDate.toString()); // Konkreten izhod se lahko razlikuje glede na implementacijo in formatiranje. V času pisanja tega članka v mnogih okoljih zahteva polyfill.

Pomembno: Podpora za ne-gregorijanske koledarje lahko zahteva polyfille ali specifično podporo brskalnika/okolja. Preverite najnovejše tabele združljivosti brskalnikov in dokumentacijo Temporal API za najnovejše informacije.

Formatiranje datumov in časov

Medtem ko se Temporal API osredotoča na manipulacijo z datumi in časi, se formatiranje običajno izvaja z objektom `Intl.DateTimeFormat`, ki je del Internationalization API. Temporal objekti se brezhibno integrirajo z `Intl.DateTimeFormat`.

Uporaba `Intl.DateTimeFormat`

Tako formatirate `Temporal.PlainDate` z uporabo `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)); // Izhod: October 27, 2024

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

Možnosti formata lahko prilagodite svojim potrebam. Prvi argument za `Intl.DateTimeFormat` je lokalizacija (locale), ki določa jezik in regionalne konvencije, uporabljene za formatiranje. Uporaba različnih lokalizacij (npr. 'en-US', 'de-DE', 'fr-FR', 'ja-JP') ustvari različne izhodne formate.

Formatiranje `Temporal.ZonedDateTime`

Formatiranje `Temporal.ZonedDateTime` je podobno, vendar lahko v izhod vključite tudi informacije o časovnem pasu:

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)); // Izhod: October 27, 2024, 10:30 AM PDT (Okrajšava časovnega pasu je odvisna od pravil poletnega časa)

Najboljše prakse za internacionalizacijo

Pri delu z datumi in časi v globalnem kontekstu upoštevajte naslednje najboljše prakse:

Uporabljajte identifikatorje časovnih pasov IANA: Za natančno upravljanje časovnih pasov vedno uporabljajte identifikatorje časovnih pasov IANA (npr. `America/Los_Angeles`, `Europe/London`).
Bodite pozorni na poletni čas: Poletni čas (DST) lahko vpliva na odklone časovnih pasov. Temporal API samodejno obravnava prehode na poletni čas.
Za formatiranje uporabljajte `Intl.DateTimeFormat`: Za formatiranje datumov in časov glede na uporabnikovo lokalizacijo uporabljajte objekt `Intl.DateTimeFormat`.
Upoštevajte koledarske sisteme: Če mora vaša aplikacija podpirati uporabnike v različnih kulturnih kontekstih, razmislite o uporabi alternativnih koledarskih sistemov.
Shranjujte datume in čase v UTC: Pri shranjevanju datumov in časov v bazi podatkov je najboljša praksa, da jih shranjujete v UTC (univerzalni koordinirani čas), da se izognete težavam s časovnimi pasovi. Nato jih za prikaz pretvorite v lokalni čas. Temporal ponuja metode za pretvorbo v in iz UTC.
Temeljito testirajte: Testirajte svojo aplikacijo z različnimi časovnimi pasovi, lokalizacijami in koledarskimi sistemi, da zagotovite pravilno delovanje za vse uporabnike.

Primerjava Temporal API z zastarelim objektom Date

Tukaj je tabela, ki poudarja ključne razlike in prednosti Temporal API v primerjavi z zastarelim objektom `Date`:

Značilnost	Zastarel objekt `Date`	Temporal API
Spremenljivost	Spremenljiv (spreminja izvirni objekt)	Nespremenljiv (vrača nove objekte)
Podpora za časovne pasove	Omejena in pogosto problematična	Robustna in natančna, temelji na IANA bazi podatkov časovnih pasov
API	Nedosleden in težaven za uporabo	Jasen, dosleden in intuitiven
Natančnost	Milisekunda	Nanosekunda
Koledarski sistemi	Omejen na gregorijanskega	Podpira alternativne koledarske sisteme (z razvijajočo se podporo)
Internacionalizacija	Zahteva zunanje knjižnice za robustno internacionalizacijo	Vgrajena podpora in brezhibna integracija z `Intl.DateTimeFormat`

Podpora brskalnikov in polyfilli

Ker gre za razmeroma nov API, se podpora brskalnikov za Temporal API še vedno razvija. Preverite najnovejše tabele združljivosti brskalnikov (npr. na MDN Web Docs), da vidite, kateri brskalniki in okolja ga podpirajo izvorno. Za starejše brskalnike ali okolja brez izvorne podpore lahko uporabite polyfille, ki zagotavljajo funkcionalnost Temporal API. Na spletu poiščite "Temporal API polyfill", da najdete ustrezne možnosti.

Zaključek

JavaScript Temporal API predstavlja pomemben korak naprej pri upravljanju datumov in časov v JavaScriptu. Njegova nespremenljivost, jasen API, robustna podpora za časovne pasove in zmožnosti koledarskih sistemov ga delajo za močno orodje za razvijalce, ki gradijo aplikacije, ki morajo natančno in zanesljivo delati z datumi in časi v različnih mednarodnih kontekstih. Medtem ko se podpora brskalnikov še razvija, so prednosti Temporal API vredne učenja in uporabe v novih projektih. Z uporabo Temporal API in upoštevanjem najboljših praks internacionalizacije lahko ustvarite aplikacije, ki uporabnikom po vsem svetu zagotavljajo brezhibno in natančno izkušnjo z datumi in časi.

MLOG