M

MLOG

Suomi

Syväluotaava opas JavaScriptin Temporal API:in, joka on moderni ratkaisu päivämäärien ja aikojen tehokkaaseen käsittelyyn moninaisissa kansainvälisissä ympäristöissä.

JavaScript Temporal API: Nykyaikainen päivämäärien ja aikojen käsittely globaalille yleisölle

JavaScriptin `Date`-olio on pitkään ollut kehittäjien turhautumisen lähde. Sen muuttuvuus (mutability), epäjohdonmukainen API ja heikko aikavyöhyketuki ovat johtaneet lukuisten kirjastojen, kuten Moment.js:n ja date-fns:n, syntyyn paikkaamaan puutteita. Nyt Temporal API:n myötä JavaScript tarjoaa modernin, sisäänrakennetun ratkaisun päivämäärien ja aikojen käsittelyyn selkeämmin ja tarkemmin. Tämä artikkeli tarjoaa kattavan yleiskatsauksen Temporal API:sta keskittyen sen ominaisuuksiin, hyötyihin ja käyttöön erilaisissa kansainvälisissä ympäristöissä.

Mikä on Temporal API?

Temporal API on uusi, globaali olio JavaScriptissä, joka on suunniteltu korjaamaan `Date`-olion puutteet. Se tarjoaa selkeän, muuttumattoman (immutable) API:n päivämäärien, aikojen, aikavyöhykkeiden ja kalenterijärjestelmien käsittelyyn. Keskeistä on, että se pyrkii esittämään päivämäärä- ja aikakäsitteet tavalla, joka vastaa paremmin todellista käyttöä ja odotuksia, tehden kansainvälistämisestä huomattavasti suoraviivaisempaa.

Tärkeimmät ominaisuudet:

Temporalin perusoliot

Temporal API esittelee useita uusia oliotyyppejä. Tässä on joitakin keskeisimmistä:

Päivämäärien käsittely

`Temporal.PlainDate`-olion luominen

Voit luoda `Temporal.PlainDate`-olion konstruktorilla:

const plainDate = new Temporal.PlainDate(2024, 10, 27); // Vuosi, Kuukausi (1-12), Päivä
console.log(plainDate.toString()); // Tuloste: 2024-10-27

Voit myös käyttää `from`-metodia, joka hyväksyy merkkijonon ISO 8601 -muodossa:

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

Päivämäärän osien hakeminen

Yksittäisiin päivämäärän osiin pääsee käsiksi ominaisuuksilla, kuten `year`, `month` ja `day`:

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

Päivämääräaritmetiikka

Päivien, viikkojen, kuukausien tai vuosien lisäämiseen ja vähentämiseen käytetään `plus`- ja `minus`-metodeja. Nämä metodit palauttavat uuden `Temporal.PlainDate`-olion:

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

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

Päivämäärien vertailu

Päivämääriä voi verrata `compare`-metodilla:

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

console.log(Temporal.PlainDate.compare(date1, date2)); // Tuloste: -1 (date1 on aiemmin kuin date2)

Aikojen käsittely

`Temporal.PlainTime`-olion luominen

Voit luoda `Temporal.PlainTime`-olion konstruktorilla:

const plainTime = new Temporal.PlainTime(10, 30, 0); // Tunti, Minuutti, Sekunti
console.log(plainTime.toString()); // Tuloste: 10:30:00

Tai käytä `from`-metodia ISO 8601 -aikamerkkijonolla:

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

Ajan osien hakeminen

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

Aika-aritmetiikka

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

Päivämäärän ja ajan yhteiskäsittely

`Temporal.PlainDateTime`-olion luominen

Voit luoda `Temporal.PlainDateTime`-olion suoraan tai yhdistämällä `Temporal.PlainDate`- ja `Temporal.PlainTime`-oliot:

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

Aikavyöhykkeet

Aikavyöhykkeiden oikea käsittely on ratkaisevan tärkeää sovelluksille, jotka palvelevat käyttäjiä eri paikoissa. Temporal API tarjoaa vankan aikavyöhyketuen `Temporal.ZonedDateTime`- ja `Temporal.TimeZone`-olioiden kautta.

`Temporal.ZonedDateTime`-olion luominen

`Temporal.ZonedDateTime`-olion luomiseen tarvitaan `Temporal.PlainDateTime` ja aikavyöhyketunniste. Aikavyöhyketunnisteet perustuvat IANA-aikavyöhyketietokantaan (esim. `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()); // Tuloste: 2024-10-27T10:30:00-07:00[America/Los_Angeles] (Poikkeama riippuu kesäaikasäännöistä)

Vaihtoehtoisesti `Temporal.ZonedDateTime` voidaan luoda `Instant`-oliosta.

const instant = Temporal.Instant.fromEpochSeconds(1666866600); // Esimerkkileima
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO(timeZone); // Aikavyöhyke kuten 'America/Los_Angeles'
console.log(zonedDateTimeFromInstant.toString());

Muuntaminen aikavyöhykkeiden välillä

Voit muuntaa `Temporal.ZonedDateTime`-olion toiselle aikavyöhykkeelle `withTimeZone`-metodilla:

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

Aikavyöhykepoikkeamien käsittely

`Temporal.TimeZone`-olion `getOffsetStringFor`-metodi antaa poikkeamamerkkijonon tietylle `Temporal.Instant`-oliolle:

const timeZoneObject = new Temporal.TimeZone(timeZone);
const offsetString = timeZoneObject.getOffsetStringFor(zonedDateTime.toInstant());
console.log(offsetString); // Tuloste: -07:00 (Riippuen kesäaikasäännöistä)

On olennaista käyttää oikeita IANA-aikavyöhyketunnisteita tarkkojen laskelmien varmistamiseksi. Näitä tunnisteita ylläpidetään ja päivitetään säännöllisesti vastaamaan kesäajan ja aikavyöhykerajojen muutoksia.

Kestot (Durations)

`Temporal.Duration`-olio edustaa ajanjaksoa. Sitä voidaan käyttää ajan lisäämiseen tai vähentämiseen päivämääristä ja ajoista.

`Temporal.Duration`-olion luominen

Voit luoda `Temporal.Duration`-olion konstruktorilla, määrittäen vuodet, kuukaudet, päivät, tunnit, minuutit, sekunnit, millisekunnit, mikrosekunnit ja nanosekunnit:

const duration = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 8, 9); // Vuodet, Kuukaudet, Päivät, Tunnit, Minuutit, Sekunnit, Millisekunnit, Mikrosekunnit, Nanosekunnit
console.log(duration.toString()); // Tuloste: P1Y2M3DT4H5M6.007008009S

Tai käyttämällä ISO 8601 -kestomerkkijonoa:

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

Kestojen lisääminen päivämääriin ja aikoihin

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

Huomaa, että kuukausia tai vuosia sisältävien kestojen lisääminen päivämääriin vaatii tarkkaa harkintaa, koska päivien määrä kuukaudessa tai vuodessa voi vaihdella.

Kalenterijärjestelmät

Temporal API tukee eri kalenterijärjestelmiä gregoriaanisen kalenterin lisäksi. Tämä on ratkaisevan tärkeää sovelluksille, joiden on käsiteltävä päivämääriä erilaisissa kulttuurikonteksteissa. Vaikka tuki on vielä kehittymässä, se tarjoaa perustan tulevalle laajennukselle.

Vaihtoehtoisten kalenterien käyttäminen

Voit käyttää tiettyä kalenteria määrittämällä sen Temporal-olioita luodessasi:

const hebrewDate = new Temporal.PlainDate(5785, 1, 1, { calendar: 'hebrew' });
console.log(hebrewDate.toString()); // Tarkka tuloste voi vaihdella toteutuksesta ja muotoilusta riippuen. Vaatii polyfillin monissa ympäristöissä tätä kirjoitettaessa.

Tärkeää: Tuki muille kuin gregoriaanisille kalentereille saattaa vaatia polyfillejä tai erityistä selain-/ympäristötukea. Tarkista ajantasaisimmat tiedot Temporal API:n dokumentaatiosta ja selainten yhteensopivuustaulukoista.

Päivämäärien ja aikojen muotoilu

Vaikka Temporal API keskittyy päivämäärä- ja aikamanipulaatioon, muotoilun hoitaa tyypillisesti `Intl.DateTimeFormat`-olio, joka on osa kansainvälistämisen API:ta (Internationalization API). Temporal-oliot toimivat saumattomasti `Intl.DateTimeFormat`:n kanssa.

`Intl.DateTimeFormat`:n käyttäminen

Näin muotoilet `Temporal.PlainDate`-olion `Intl.DateTimeFormat`:n avulla:

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)); // Tuloste: October 27, 2024

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

Voit mukauttaa muotoiluasetuksia tarpeidesi mukaan. `Intl.DateTimeFormat`:n ensimmäinen argumentti on lokaali, joka määrittää muotoilussa käytettävän kielen ja alueelliset käytännöt. Eri lokaalien (esim. 'en-US', 'de-DE', 'fr-FR', 'ja-JP') käyttäminen tuottaa erilaisia tulostusmuotoja.

`Temporal.ZonedDateTime`-olion muotoilu

`Temporal.ZonedDateTime`-olion muotoilu on samanlaista, mutta voit sisällyttää tulosteeseen myös aikavyöhyketietoja:

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)); // Tuloste: October 27, 2024, 10:30 AM PDT (Aikavyöhykkeen lyhenne riippuu kesäaikasäännöistä)

Kansainvälistämisen parhaat käytännöt

Kun käsittelet päivämääriä ja aikoja globaalissa kontekstissa, pidä mielessä seuraavat parhaat käytännöt:

Temporal API:n vertailu vanhaan Date-olioon

Tässä taulukossa korostetaan Temporal API:n keskeisiä eroja ja etuja verrattuna vanhaan `Date`-olioon:

Ominaisuus Vanha `Date`-olio Temporal API
Muuttuvuus Muuttuva (muokkaa alkuperäistä oliota) Muuttumaton (palauttaa uusia olioita)
Aikavyöhyketuki Rajoitettu ja usein ongelmallinen Vankka ja tarkka, perustuu IANA-aikavyöhyketietokantaan
API Epäjohdonmukainen ja vaikeakäyttöinen Selkeä, johdonmukainen ja intuitiivinen
Tarkkuus Millisekunti Nanosekunti
Kalenterijärjestelmät Rajoittuu gregoriaaniseen Tukee vaihtoehtoisia kalenterijärjestelmiä (kehittyvällä tuella)
Kansainvälistäminen Vaatii ulkoisia kirjastoja vankkaan kansainvälistämiseen Sisäänrakennettu tuki ja saumaton integraatio `Intl.DateTimeFormat`:n kanssa

Selaintuki ja polyfillit

Koska kyseessä on suhteellisen uusi API, Temporal API:n selaintuki kehittyy edelleen. Tarkista uusimmat selainten yhteensopivuustaulukot (esim. MDN Web Docsista) nähdäksesi, mitkä selaimet ja ympäristöt tukevat sitä natiivisti. Vanhemmille selaimille tai ympäristöille ilman natiivitukea voit käyttää polyfillejä tarjoamaan Temporal API:n toiminnallisuuden. Hae verkosta "Temporal API polyfill" löytääksesi sopivia vaihtoehtoja.

Yhteenveto

JavaScriptin Temporal API on merkittävä edistysaskel päivämäärien ja aikojen käsittelyssä JavaScriptissä. Sen muuttumattomuus, selkeä API, vankka aikavyöhyketuki ja kalenterijärjestelmäominaisuudet tekevät siitä tehokkaan työkalun kehittäjille, jotka rakentavat sovelluksia, joiden on käsiteltävä päivämääriä ja aikoja tarkasti ja luotettavasti erilaisissa kansainvälisissä ympäristöissä. Vaikka selaintuki on vielä kehittymässä, Temporal API:n hyödyt tekevät siitä oppimisen ja käyttöönoton arvoisen uusissa projekteissa. Ottamalla Temporal API:n käyttöön ja noudattamalla kansainvälistämisen parhaita käytäntöjä voit luoda sovelluksia, jotka tarjoavat saumattoman ja tarkan päivämäärä- ja aikakokemuksen käyttäjille ympäri maailmaa.

Lisätietoa