Beta

DatePickerV2

Komponentti yksittäisen päivämäärän syöttämiseen tai valitsemiseen kalenterinäkymästä.

Julkaistu versiossa 13.3.0

Komponentti on edelleen kehityksessä, joten sen API ja ominaisuudet saattavat vielä muuttua.

DatePickerV2 korvaa tulevaisuudessa DatePicker-komponentin.

Esikatselu

Käyttötarkoitus

Päivämäärävalitsin (DatePickerV2) tarjoaa käyttäjälle päivämäärän syöttökentän ja kalenterinäkymän päivämäärän valitsemiseen.

Päivämäärän voi syöttää muodoissa pp.kk.vvvv, p.k.vvvv, ppkkvvvv sekä vvvv-kk-pp.

Tee näin

Estä päivät tai aikavälit, joita käyttäjä ei saa valita.
Jos käytät päivämäärävalitsinta tilanteessa, jossa on tarve syöttää päivämäärä usean vuoden päähän, aseta rajoitus päivämääräväliin. Tällöin käyttäjälle tulee kuukausi- ja vuosivalikot näkyviin.

Älä tee näin

Harkitse käytätkö päivämäärävalitsinta, jos on tarve syöttää päivämäärää usean vuoden päähän. Tällöin kannattaa useimmiten käyttää tavallista tekstikenttää (Input).
Jos käyttäjän tulee syöttää hänelle tuttu päivämäärä, esimerkiksi oma syntymäaika, kannattaa käyttää tavallista tekstikenttää (Input).

Saavutettavuus

Komponenttiin sisältyvä kalenteri tukee näppäimistönavigaatiota kohdistuksen ollessa kalenterinäkymän päivämäärävalinnoissa. Huom. ruudunlukijan käyttö saattaa vaikuttaa näppäimistönavigaation toimintatapaan.

Näppäin	Toiminto
`Nuoli vasemmalle`	Siirry edelliseen päivään.
`Nuoli oikealle`	Siirry seuraavaan päivään.
`Nuoli ylös`	Siirry edelliseen viikkoon.
`Nuoli alas`	Siirry seuraavaan viikkoon.
`Page Up`	Siirry edelliseen kuukauteen.
`Page Down`	Siirry seuraavaan kuukauteen.
`Shift + Page Up`	Siirry edelliseen vuoteen.
`Shift + Page Down`	Siirry seuraavaan vuoteen.
`Home`	Siirry viikon alkuun.
`End`	Siirry viikon loppuun.

Ruudunlukijalle tarkoitettuja tekstejä voi muokata komponentin localization-propin avulla. Saman propin avulla voi toteuttaa kalenterinäkymän lokalisointia mikäli käyttöliittymä näytetään jollain muulla kielellä kuin suomeksi. Tarkemmat ohjeet localization-propin käytöstä löydät kalenterin lokalisointi osiosta.

Päivämäärän valinta

Oletuksena päivämäärä on asettamatta ja kalenteri avautuu kuluvan kuukauden kohdalta.

Oletuspäivän asettaminen

Komponentille voi määrittää oletuksena valitun päivämäärän. Oletusarvon ollessa käytössä kalenteri avataan aina oletuksena annetun päivämäärän kuukauden kohdalta. Oletusarvon voi antaa Date-objektina tai vvvv-kk-pp-muotoisena tekstiarvona.

Valinnan estäminen tietyiltä päiviltä tai aikaväleiltä

Valinta voidaan estää tietyiltä päiviltä tai aikaväleiltä. Estettyä päivää ei pysty valitsemaan kalenterista ja jos sen syöttää käsin, tulee käyttäjälle esittää virheilmoitus.

Valinta voidaan estää:

yksittäisiltä päiviltä,
tietyltä aikaväliltä,
ennen tiettyä päivämäärää,
tietyn päivämäärän jälkeen, tai
tietyiltä viikonpäiviltä.

Päivämäärien validointi ja virheviestien asettaminen

Virhetilan asettaminen

Komponentin voi asettaa virhetilaan errorText ja invalid-proppien avulla.

Esimerkki virheenkäsittelyn toteuttamisesta

Komponentti palauttaa kaikkien tapahtumien (onChange, onSelect, onError ja onBlur) mukana validity-objektin, josta löytyy validoinnin tila, virheen tyyppi ja virheviesti, sekä päivämäärä ISO ja Date-muotoisena tietona (silloin kun input-kentän arvosta voidaan muodostaa päivämäärä). Sisäinen validointi kattaa komponentin tarjoamien proppien validoinnin.

Tarvittaessa sisäisen validoinnin voi jättää huomiotta, koska komponentti ei itse aseta itseään virhetilaan, vaan se tehdään errorText ja invalid-proppien avulla.

Alta löytyy karkea esimerkki dynaamisen virheentarkistuksen toteuttamisesta:

Päivämäärien validointi getDateValidator-funktiolla

Myös komponentin käyttämää getDateValidator-funktiota voi hyödyntää validoinnin toteuttamiseen. Funktiolle annetaan samat validointisäännöt (required, fromDate, toDate, disabledDates, disablePast), kuin komponentille. Tätä voi hyödyntää esimerkiksi React Hook Formin validate-funktiossa. Oletusvirheilmoituksia voi päivittää errorTexts-objektin kautta.

Validoinnin palauttamat arvot

Parametri	Kuvaus
`isValid`	Kertoo onko päivämäärä hyväksytty arvo (oikea päivämäärä ja läpäisee validoinnit).
`valueAsDate`	Päivämäärä `Date`-objektina, silloin kun input-kentän syötteestä pystytään muodostamaan päivämäärä.
`valueAsISO`	Päivämäärä ISO-muotoisena tekstinä (esim. 2023-10-30), silloin kun input-kentän syötteestä pystytään muodostamaan päivämäärä.
`error.type`	Virheen tyyppi: `dateDisabled`, `invalidFormat`, `notInRangeFrom`, `notInRangeTo`, `required`
`error.message`	Oletusvirheviesti, jota voi päivittää `localization`-propin kautta.

Vuosi- ja kuukausivalikon näyttäminen

Vuosi- ja kuukausivalikon saa näkyviin, kun valinnan rajoittaa tietylle aikavälille. Valittavia päivämääriä voidaan rajoittaa tietylle välille fromDate- ja toDate-proppien avulla. Vuosi- ja kuukausivalikkojen näyttämisen voi tarvittaessa estää asettamalla showDropdownNavigation-propin arvoksi false.

Viikkonumeroiden näyttäminen

Kalenteriin saa halutessa viikkonumerot näkyviin showWeekNumbers -propilla.

Päivämääräarvon näyttäminen ilman etunollia

Input-kentässä näytettävä päivämääräarvo voidaan tarvittaessa esittää ilman etunollia asettamalla showLeadingZeros-propin arvoksi false. Oletuksena etunollat näytetään.

Estetty kenttä

Kentän voi tarvittaessa asettaa estetyksi, eli disabloiduksi. Tällöin päivämäärää ei pääse syöttämään tekstinä, eikä kalenterin kautta.

Päivämääräarvon päivittäminen komponentin ulkopuolelta

Tarvittaessa päivämääräarvon voi päivittää tai tyhjentää komponentin ulkopuolelta antamalla value-arvon. Ref-propin kautta pääsee käsiksi input-elementtiin, joka mahdollistaa esimerkiksi kohdistuksen siirtämisen kenttään.

Kaksipalstainen asettelu

Kaksipalstaisessa asettelussa tulostetaan leftCol-propilla kentän nimilappu ja aputeksti Column-komponentin sisään.

Kalenterin lokalisointi

Lokalisointia tulee tehdä, jos käyttöliittymä näytetään jollain muulla kielellä kuin suomeksi tai jos suomenkielisiä ruudunlukijalle luettavia tekstejä halutaan muuttaa. Kalenterinäkymän lokalisointi onnistuu localization-propin avulla. Propin sallima lokalisaatio-objekti sisältää locale-arvon, joka on tyypiltään date-fns-kirjaston Locale. Lisäksi localization-objektin kautta pääsee muokkaamaan kalenteriin liittyvien toimintojen ruudunlukijoille annettavia label-tekstejä.

Funktio-muotoisten lokalisaatio-objektin labelien saama parametri riippuu käyttötapauksesta. Tarkempia tietoja labeleista ja niiden parametreista selviää tutkimalla omassa koodieditorissa komponentin saamia tyypityksiä.

Tekniset rajoitteet

Kontrolloituna komponenttina käytettäessä päivämääräarvo tulee antaa value-propille pp.kk.vvvv-muodossa (samassa muodossa kuin input-kentässä).