JavaScript Temporal API: Nykyaikainen päivämäärän ja ajan käsittely

JavaScriptin Date-objekti on pitkään ollut kehittäjien turhautumisen lähde. Sen muuttuvuus, sisäänrakennetun aikavyöhyketuen puute ja kömpelö API ovat johtaneet lukemattomiin kirjastoihin ja kiertoteihin. Onneksi Temporal API pyrkii korjaamaan nämä puutteet tarjoamalla modernin, intuitiivisen ja aikavyöhyketietoisen ratkaisun päivämäärän ja ajan käsittelyyn JavaScriptissä.

Mikä on Temporal API?

Temporal API on uusi globaali objekti, Temporal, joka tarjoaa modernin ja standardoidun tavan käsitellä päivämääriä ja aikoja JavaScriptissä. Se on suunniteltu korvaamaan vanha Date-objekti ja tarjoaa merkittäviä parannuksia API-suunnittelun, muuttumattomuuden, aikavyöhyketuen ja yleisen käytettävyyden osalta. Se on osa ECMAScript-ehdotusta ja sitä ollaan toteuttamassa suurimmissa JavaScript-moottoreissa.

Temporal API:n tärkeimmät edut:

• Muuttumattomuus: Temporal-objektit ovat muuttumattomia, mikä tarkoittaa, että niihin kohdistuvat toiminnot palauttavat uusia objekteja alkuperäisen muokkaamisen sijaan. Tämä auttaa estämään odottamattomia sivuvaikutuksia ja tekee koodista helpommin ymmärrettävää.
• Selkeä API: API on suunniteltu intuitiivisemmaksi ja johdonmukaisemmaksi kuin vanha Date-objekti.
• Aikavyöhyketuki: Temporal tarjoaa vahvan tuen aikavyöhykkeille, jonka avulla voit käsitellä päivämääriä ja aikoja eri puolilla maailmaa.
• Kalenterituki: Gregoriaanisen kalenterin lisäksi API mahdollistaa muiden kalenterijärjestelmien käytön, mikä helpottaa globaaleja sovelluksia.
• Karkaussekuntien käsittely: Temporal API ottaa huomioon karkaussekunnit ja tarjoaa tarkempia aika-laskelmia.

Pääsy Temporal-käyttöön

Vaikka Temporal API on vielä kehitteillä, eikä sitä vielä täysin tueta kaikissa selaimissa ja Node.js-ympäristöissä, voit käyttää polyfilliä aloittaaksesi sen kokeilemisen jo tänään. Voit asentaa polyfillin npm:n kautta:

            npm install @js-temporal/polyfill
            

              
                Copy
              
            
          

Tuo sitten polyfill JavaScript-koodiisi:

            import { Temporal } from '@js-temporal/polyfill';
            

              
                Copy
              
            
          

Kun polyfill on asennettu, voit alkaa käyttää Temporal-objektia ja sen eri luokkia.

Temporal-luokat

Temporal API tarjoaa useita keskeisiä luokkia päivämäärien ja aikojen käsittelyyn:

• Temporal.PlainDate: Edustaa kalenteripäivämäärää (vuosi, kuukausi ja päivä) ilman aikavyöhyke- tai kellonaikatiedot.
• Temporal.PlainTime: Edustaa kellonaikaa (tunti, minuutti, sekunti ja sekunnin osa) ilman päivämäärä- tai aikavyöhyketietoja.
• Temporal.PlainDateTime: Edustaa päivämäärää ja aikaa ilman aikavyöhyketietoja.
• Temporal.ZonedDateTime: Edustaa päivämäärää ja aikaa tietyllä aikavyöhykkeellä.
• Temporal.Instant: Edustaa tiettyä hetkeä ajassa, mitattuna nanosekunneissa Unix-epookista (1. tammikuuta 1970 klo 00:00:00 Coordinated Universal Time (UTC)).
• Temporal.TimeZone: Edustaa aikavyöhykettä.
• Temporal.Duration: Edustaa aikaväliä, kuten tunteja, minuutteja tai sekunteja.
• Temporal.Now: Tarjoaa pääsyn nykyiseen päivämäärään ja aikaan.

PlainDaten käyttö

Temporal.PlainDate-luokka edustaa päivämäärää ilman aikavyöhyke- tai kellonaikatiedot. Se on hyödyllinen syntymäpäivien, vuosipäivien tai muiden päivämääräpohjaisten tapahtumien edustamiseen.

PlainDate-objektin luominen:

            const plainDate = Temporal.PlainDate.from({ year: 2024, month: 10, day: 26 });
console.log(plainDate.toString()); // Tuloste: 2024-10-26
            

              
                Copy
              
            
          

Voit myös luoda PlainDate-objektin merkkijonosta ISO 8601 -muodossa:

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

              
                Copy
              
            
          

Päivämäärän osien käyttäminen:

            const year = plainDate.year; // 2024
const month = plainDate.month; // 10
const day = plainDate.day;   // 26
const dayOfWeek = plainDate.dayOfWeek; // Viikonpäivä (1-7, maanantai-sunnuntai)
const dayOfYear = plainDate.dayOfYear; // Vuoden päivä (1-366)
const daysInMonth = plainDate.daysInMonth; // Kuukauden päivien lukumäärä
const isLeapYear = plainDate.isLeapYear;   // Boolean, joka osoittaa, onko vuosi karkausvuosi
            

              
                Copy
              
            
          

Päivien lisääminen ja vähentäminen:

            const nextDay = plainDate.add({ days: 1 });
console.log(nextDay.toString()); // Tuloste: 2024-10-27

const previousWeek = plainDate.subtract({ weeks: 1 });
console.log(previousWeek.toString()); // Tuloste: 2024-10-19
            

              
                Copy
              
            
          

Päivämäärien vertailu:

            const anotherDate = Temporal.PlainDate.from({ year: 2024, month: 11, day: 15 });

if (plainDate.equals(anotherDate)) {
  console.log('Päivämäärät ovat samat');
} else if (plainDate.lessThan(anotherDate)) {
  console.log('plainDate on aiemmin kuin anotherDate');
} else {
  console.log('plainDate on myöhemmin kuin anotherDate');
}
// Tuloste: plainDate on aiemmin kuin anotherDate
            

              
                Copy
              
            
          

PlainTimen käyttö

Temporal.PlainTime-luokka edustaa kellonaikaa ilman päivämäärä- tai aikavyöhyketietoja. Se on hyödyllinen aukioloaikojen, kokousaikojen tai muiden aikaan perustuvien tapahtumien edustamiseen.

PlainTime-objektin luominen:

            const plainTime = Temporal.PlainTime.from({ hour: 14, minute: 30, second: 0 });
console.log(plainTime.toString()); // Tuloste: 14:30:00
            

              
                Copy
              
            
          

Voit myös luoda PlainTime-objektin merkkijonosta ISO 8601 -muodossa:

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

              
                Copy
              
            
          

Ajan osien käyttäminen:

            const hour = plainTime.hour;   // 14
const minute = plainTime.minute; // 30
const second = plainTime.second; // 0
const millisecond = plainTime.millisecond; // 0
const microsecond = plainTime.microsecond; // 0
const nanosecond = plainTime.nanosecond;   // 0
            

              
                Copy
              
            
          

Ajan lisääminen ja vähentäminen:

            const laterTime = plainTime.add({ minutes: 15 });
console.log(laterTime.toString()); // Tuloste: 14:45:00

const earlierTime = plainTime.subtract({ hours: 1 });
console.log(earlierTime.toString()); // Tuloste: 13:30:00
            

              
                Copy
              
            
          

Aikojen vertailu:

            const anotherTime = Temporal.PlainTime.from({ hour: 15, minute: 0, second: 0 });

if (plainTime.equals(anotherTime)) {
  console.log('Ajat ovat samat');
} else if (plainTime.lessThan(anotherTime)) {
  console.log('plainTime on aiemmin kuin anotherTime');
} else {
  console.log('plainTime on myöhemmin kuin anotherTime');
}
// Tuloste: plainTime on aiemmin kuin anotherTime
            

              
                Copy
              
            
          

PlainDateTime-objektin käyttö

Temporal.PlainDateTime-luokka edustaa päivämäärää ja aikaa ilman aikavyöhyketietoja. Se yhdistää PlainDate- ja PlainTime-luokkien toiminnallisuuden.

PlainDateTime-objektin luominen:

            const plainDateTime = Temporal.PlainDateTime.from({ year: 2024, month: 10, day: 26, hour: 14, minute: 30, second: 0 });
console.log(plainDateTime.toString()); // Tuloste: 2024-10-26T14:30:00
            

              
                Copy
              
            
          

Voit myös luoda PlainDateTime-objektin merkkijonosta ISO 8601 -muodossa:

            const plainDateTimeFromString = Temporal.PlainDateTime.from('2024-12-25T09:00:00');
console.log(plainDateTimeFromString.toString()); // Tuloste: 2024-12-25T09:00:00
            

              
                Copy
              
            
          

Päivämäärän ja ajan osien käyttäminen:

            const year = plainDateTime.year;   // 2024
const month = plainDateTime.month; // 10
const day = plainDateTime.day;     // 26
const hour = plainDateTime.hour;   // 14
const minute = plainDateTime.minute; // 30
const second = plainDateTime.second; // 0
            

              
                Copy
              
            
          

Päivämäärien ja aikojen lisääminen ja vähentäminen:

            const nextDayAndTime = plainDateTime.add({ days: 1, hours: 2 });
console.log(nextDayAndTime.toString()); // Tuloste: 2024-10-27T16:30:00

const previousWeekAndTime = plainDateTime.subtract({ weeks: 1, minutes: 30 });
console.log(previousWeekAndTime.toString()); // Tuloste: 2024-10-19T14:00:00
            

              
                Copy
              
            
          

Muuntaminen PlainDate- ja PlainTime-objekteiksi:

            const plainDateFromDateTime = plainDateTime.toPlainDate();
console.log(plainDateFromDateTime.toString()); // Tuloste: 2024-10-26

const plainTimeFromDateTime = plainDateTime.toPlainTime();
console.log(plainTimeFromDateTime.toString()); // Tuloste: 14:30:00
            

              
                Copy
              
            
          

ZonedDateTime-objektin käyttö

Temporal.ZonedDateTime-luokka edustaa päivämäärää ja aikaa tietyllä aikavyöhykkeellä. Tämä on ratkaisevan tärkeää sovelluksissa, jotka haluavat käsitellä päivämääriä ja aikoja eri puolilla maailmaa. Toisin kuin vanha Date-objekti, Temporal tarjoaa sisäänrakennetun aikavyöhyketuen.

ZonedDateTime-objektin luominen:

            const zonedDateTime = Temporal.ZonedDateTime.from({ year: 2024, month: 10, day: 26, hour: 14, minute: 30, second: 0, timeZone: 'America/Los_Angeles' });
console.log(zonedDateTime.toString()); // Tuloste: 2024-10-26T14:30:00-07:00[America/Los_Angeles]
            

              
                Copy
              
            
          

Voit myös luoda ZonedDateTime-objektin Instant-objektista ja aikavyöhykkeestä:

            const instant = Temporal.Instant.fromEpochSeconds(1666785000); // Esimerkki aikaleimasta
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO('Europe/London');
console.log(zonedDateTimeFromInstant.toString()); // Tuloste vaihtelee todellisen hetken mukaan, mutta heijastaa päivämäärän/ajan Euroopassa/Lontoossa
            

              
                Copy
              
            
          

Päivämäärän ja ajan osien käyttäminen:

            const year = zonedDateTime.year;   // 2024
const month = zonedDateTime.month; // 10
const day = zonedDateTime.day;     // 26
const hour = zonedDateTime.hour;   // 14
const minute = zonedDateTime.minute; // 30
const second = zonedDateTime.second; // 0
const timeZone = zonedDateTime.timeZone; // Temporal.TimeZone -objekti
            

              
                Copy
              
            
          

Aikavyöhykkeiden välillä muuntaminen:

            const newYorkDateTime = zonedDateTime.withTimeZone('America/New_York');
console.log(newYorkDateTime.toString()); // Tuloste: 2024-10-26T17:30:00-04:00[America/New_York]
            

              
                Copy
              
            
          

Kesäaika (DST) -käsittely:

Temporal käsittelee automaattisesti kesäajan siirtymät. Kun lisäät tai vähennät aikaa, se ottaa DST:n huomioon ja varmistaa tarkat tulokset. Harkitse esimerkiksi kokousta, joka on ajoitettu DST-siirtymän yli Saksassa:

            const meetingStart = Temporal.ZonedDateTime.from({ year: 2024, month: 3, day: 31, hour: 2, minute: 30, timeZone: 'Europe/Berlin' });
const meetingEnd = meetingStart.add({ hours: 1 }); // Lisätään 1 tunti
console.log(meetingEnd.toString()); // Tuloste: 2024-03-31T03:30:00+02:00[Europe/Berlin]. Huomaa, että offset muuttuu DST:n vuoksi
            

              
                Copy
              
            
          

Instant-objektin käyttö

Temporal.Instant-luokka edustaa tiettyä hetkeä ajassa, mitattuna nanosekunneissa Unix-epookista. Se on hyödyllinen tarkkojen hetkien tallentamiseen ja vertailuun.

Instant-objektin luominen:

            const instant = Temporal.Instant.fromEpochSeconds(1666785000); // Esimerkki Unix-aikaleimasta sekunteina
console.log(instant.toString()); // Tuloste on ISO-merkkijonojen esitys kyseisestä hetkestä
            

              
                Copy
              
            
          

Muuntaminen ZonedDateTime-objektiksi:

            const zonedDateTimeFromInstant = instant.toZonedDateTimeISO('America/Los_Angeles');
console.log(zonedDateTimeFromInstant.toString()); // Tuloste: Päivämäärä ja aika Amerikassa/Los Angelesissa vastaa hetkeä
            

              
                Copy
              
            
          

Instant-objektien vertailu:

            const anotherInstant = Temporal.Instant.fromEpochSeconds(1666790000);

if (instant.equals(anotherInstant)) {
  console.log('Instant-objektit ovat yhtä suuria');
} else if (instant.lessThan(anotherInstant)) {
  console.log('instant on aiemmin kuin anotherInstant');
} else {
  console.log('instant on myöhemmin kuin anotherInstant');
}
// Tuloste: instant on aiemmin kuin anotherInstant
            

              
                Copy
              
            
          

Duration-objektin käyttö

Temporal.Duration-luokka edustaa aikaväliä, kuten tunteja, minuutteja tai sekunteja. Se on hyödyllinen kahden päivämäärän tai ajan välisen eron laskemiseen.

Duration-objektin luominen:

            const duration = Temporal.Duration.from({ hours: 2, minutes: 30 });
console.log(duration.toString()); // Tuloste: PT2H30M
            

              
                Copy
              
            
          

Päivämäärien/aikojen välisten erojen laskeminen:

            const startDate = Temporal.PlainDateTime.from({ year: 2024, month: 1, day: 1, hour: 0, minute: 0, second: 0 });
const endDate = Temporal.PlainDateTime.from({ year: 2024, month: 1, day: 3, hour: 12, minute: 30, second: 0 });
const difference = endDate.since(startDate);
console.log(difference.toString()); // Tuloste: P2DT12H30M

// Durationin osien käyttäminen
console.log(difference.days);    // 2
console.log(difference.hours);   // 12
console.log(difference.minutes); // 30
            

              
                Copy
              
            
          

Durationin lisääminen päivämääriin/aikoihin:

            const newDate = startDate.add(duration);
console.log(newDate.toString()); // Tuloste: 2024-01-03T02:30:00
            

              
                Copy
              
            
          

Kalentereiden käyttö

Temporal API tukee eri kalenterijärjestelmiä gregoriaanisen kalenterin lisäksi. Vaikka niitä ei vielä ole täysin toteutettu kaikissa polyfilleissä ja moottoreissa, tarkoituksena on antaa sovelluksille mahdollisuus käsitellä päivämääriä eri kulttuureille ominaisissa kalentereissa. Esimerkiksi japanilaisen kalenterin käyttäminen (hypoteettisesti, koska toteutus on vielä kehitteillä):

            // Tämä on käsitteellinen esimerkki, koska kalenterituki on edelleen kehitteillä
// const japaneseDate = Temporal.PlainDate.from({ year: 2024, month: 10, day: 26, calendar: 'japanese' });
// console.log(japaneseDate.toString()); // Odotettu: Tuloste muotoiltuna japanilaisen kalenterin mukaan
            

              
                Copy
              
            
          

Huomautus: Kalenterituki on Temporal API:n kehittyvä ominaisuus, ja täysi toiminnallisuus ei ole vielä yleisesti saatavilla.

Käytännön esimerkkejä ja käyttötapauksia

Temporal API tarjoaa laajan valikoiman mahdollisuuksia päivämäärien ja aikojen käsittelyyn JavaScriptissä. Tässä on joitain käytännön esimerkkejä ja käyttötapauksia:

• Ajanvaraaminen: Luo ajanvaraussovellus, jonka avulla käyttäjät voivat varata aikoja omalla aikavyöhykkeellään. Temporal.ZonedDateTime helpottaa aikavyöhykkeiden välillä muuntamista ja DST-siirtymien käsittelyä. Berliinissä sijaitsevalle klinikalle, joka varaa aikoja globaalisti:

            const appointmentTimeBerlin = Temporal.ZonedDateTime.from({ year: 2024, month: 11, day: 5, hour: 10, minute: 0, timeZone: 'Europe/Berlin' });
const appointmentTimeLA = appointmentTimeBerlin.withTimeZone('America/Los_Angeles');
console.log(`Aika Berliinissä: ${appointmentTimeBerlin.toString()}`);
console.log(`Aika Los Angelesissa: ${appointmentTimeLA.toString()}`);
            

              
                Copy
              
            
          

• Iän laskeminen: Määritä käyttäjän ikä syntymäajan perusteella. PlainDate antaa sinun edustaa syntymäaikaa ilman aikavyöhyketietoja.

            const birthDate = Temporal.PlainDate.from({ year: 1990, month: 5, day: 15 });
const today = Temporal.Now.plainDateISO();
const age = today.year - birthDate.year - (today.month < birthDate.month || (today.month === birthDate.month && today.day < birthDate.day) ? 1 : 0);
console.log(`Ikä: ${age}`);
            

              
                Copy
              
            
          

• Päivämäärien ja aikojen näyttäminen eri muodoissa: Muotoile päivämäärät ja ajat käyttäjän aluekohtaisella asetuksella. Vaikka kansainvälistymisominaisuudet (Intl) ovat erillisiä, Temporal-objektit voidaan helposti muotoilla toLocaleString()- tai vastaavilla menetelmillä yhdistettynä Intl API -ominaisuuksiin.

            const zonedDateTimeNow = Temporal.Now.zonedDateTimeISO('en-GB');
console.log(zonedDateTimeNow.toLocaleString('en-GB'));
console.log(zonedDateTimeNow.toLocaleString('de-DE'));
            

              
                Copy
              
            
          

• Tapahtuman keston seuranta: Laske tapahtuman kesto ja näytä se ihmisluettavassa muodossa. Duration antaa sinun edustaa aikaeroa kahden päivämäärän tai ajan välillä.

            const eventStart = Temporal.Instant.fromEpochSeconds(1700000000); // Esimerkki aloitusaikaleimasta
const eventEnd = Temporal.Instant.fromEpochSeconds(1700005000);   // Esimerkki lopetusaikaleimasta
const durationOfEvent = eventEnd.since(eventStart);
console.log(`Tapahtuman kesto: ${durationOfEvent.minutes} minuuttia`);
            

              
                Copy
              
            
          

Parhaat käytännöt Temporal API:n käytössä

Tässä on joitain parhaita käytäntöjä, jotka on pidettävä mielessä Temporal API:tä käytettäessä:

• Käytä muuttumattomuutta: Hyväksy Temporal-objektien muuttumattomuus. Vältä objektien suoraa muokkaamista. Sen sijaan luo uusia objekteja käyttämällä menetelmiä, kuten add, subtract ja with.
• Käsittele aikavyöhykkeitä huolellisesti: Ole tietoinen aikavyöhykkeistä, kun käsittelet päivämääriä ja aikoja. Käytä ZonedDateTime-objektia, kun haluat esittää päivämääriä ja aikoja tietyllä aikavyöhykkeellä.
• Käytä selkeitä muuttujien nimiä: Käytä kuvaavia muuttujien nimiä, jotka osoittavat selvästi käytetyn Temporal-objektin tyypin (esim. plainDate, zonedDateTime, duration).
• Harkitse polyfillejä: Koska Temporal on vielä suhteellisen uusi, varmista riittävä tuki käyttämällä polyfill-kirjastoa tarvittaessa.
• Tarkista syöte: Tarkista aina käyttäjän syöte varmistaaksesi, että päivämäärät ja ajat ovat oikeassa muodossa.

Siirtyminen vanhasta Date-objektista

Siirtyminen vanhasta Date-objektista voi olla asteittainen prosessi. Harkitse näitä strategioita:

• Lisääminen asteittain: Aloita käyttämällä Temporalia uudessa koodissa säilyttäen samalla Date-objektin sovelluksesi aiemmissa osissa.
• Wrapper-funktiot: Luo wrapper-funktioita, jotka muuntavat Date- ja Temporal-objektien välillä helpottaaksesi yhteentoimivuutta siirtymisen aikana.
• Perusteellinen testaus: Testaa siirtyminen laajasti varmistaaksesi, että kaikki päivämäärä- ja aikayksiköt ovat tarkkoja.

Temporal API vs. Moment.js

Moment.js oli suosittu kirjasto päivämäärän ja ajan käsittelyyn JavaScriptissä, mutta sitä pidetään nyt vanhentuneena projektina ja se on ylläpitotilassa. Temporal API tarjoaa modernimman ja standardoidun ratkaisun, joka korjaa monia Moment.js:n puutteita. Moment.js on muuttuva ja siinä ei ole natiivia aikavyöhyketukea. Temporal API on muuttumaton ja siinä on natiivi aikavyöhyketuki.

Johtopäätös

JavaScript Temporal API edustaa merkittävää parannusta vanhaan Date-objektiin verrattuna. Sen muuttumattomuus, selkeä API, aikavyöhyketuki ja kalenterituki tekevät siitä tehokkaan työkalun päivämäärien ja aikojen käsittelyyn nykyaikaisissa JavaScript-sovelluksissa. Vaikka käyttöönotto on edelleen kasvussa, polyfillin käyttäminen mahdollistaa sen hyötyjen hyödyntämisen jo tänään. Kun API saa enemmän tukea, sen odotetaan tulevan standardiksi tavaksi käsitellä päivämääriä ja aikoja JavaScriptissä.

Omaksu Temporal API ja avaa tehokkaampi ja luotettavampi tapa hallita päivämääriä ja aikoja projekteissasi varmistaen, että sovelluksesi käsittelee globaalit aikavyöhykkeet ja laskelmat tarkasti.