Komponentti päivämäärän tai ajanjakson syöttämiseen tai valitsemiseen kalenterinäkymästä.
Julkaistu versiossa 9.1.0
DatePicker- ja DateRangePicker-komponentit poistuvat käytöstä tulevaisuudessa, eikä niihin lisätä enää uusia ominaisuuksia.
Tutustu uusiin DatePickerV2 ja DateRangePickerV2-komponentteihin, jotka tarjoavat joustavamman virheenkäsittelyn ja muuten samat ominaisuudet.
Käyttötarkoitus
Päivämäärävalitsin (DatePicker) 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
DatePickeriin 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.
Päivämäärän valinta
Oletuksena päivämäärä on asettamatta ja kalenteri avautuu kuluvan kuukauden kohdalta.
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-MM-DD-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 virheilmoitus. Valinta voidaan estää
Komponentille voi asettaa virheviestit eri virhetilanteita varten errorText-propin avulla. Mikäli errorText-arvoa ei anneta, komponentti näyttää virheviestien oletusarvot. Arvolla null ei komponentin sisäisesti asettamia virheviestejä tulosteta lainkaan, mutta komponentti näyttää virheellisen kentän korostuksen.
Virhetilanteita voidaan hallita komponentin ulkopuolella onError -callback-funktiolla.
<DatePicker
labelText="Päivämäärä"
helpText="Ilmoita päivämäärä muodossa pp.kk.vvvv"
errorText={{
invalidFormat: "Virheellinen päivämäärä",
dateDisabled: "Estetty päivämäärä",
notInRange: "Päivämäärä ei ole sallitulta väliltä",
defaultError: "Tarkista annettu päivämäärä",
}}
onError={(isInvalid, errorType) => console.log(isInvalid, errorType)}
disabledDates={[{ dayOfWeek: [0, 6] }]}
onChange={(date) => console.log(date)}
fromDate="2022-09"
toDate="2024-10-15"
/>
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 halutessa estää asettamalla showDropdownNavigation-propin arvoksi false.
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.
Tarvittaessa päivämääräarvon voi päivittää tai tyhjentää komponentin ulkopuolelta hyödyntämällä ref-objektin mukana palautuvia reset- ja setValue-funktioita.
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ä.
Ajanjakson valitsemiseen on tarjolla oma DateRangePicker-komponentti. Ajanjakson valitseminen onnistuu joko syöttämällä alkamis- ja päättymispäivät tekstikenttiin tai valitsemalla ajanjakso kalenterista.
Myös ajanjaksolle pystyy antamaan oletusarvon. Oletusarvon voi antaa sekä alkamis- että päättymispäivälle tai vain toiselle niistä. Oletusarvo sallii päivämäärien antamisen Date-objektina tai VVVV-MM-DD-muotoisena tekstiarvona.
Komponentin näyttämiä virheviestejä voi hallita hyödyntämällä errorText-proppia. Mikäli errorText-arvoa ei anneta, komponentti näyttää virheviestien oletusarvot. Arvolla null ei komponentin sisäisesti asettamia virheviestejä tulosteta lainkaan, mutta komponentti näyttää virheellisen kentän korostuksen.
Virhetilanteita voidaan hallita komponentin ulkopuolella onError -callback-funktiolla.
Input-elementtien tulostukseen voi vaikuttaa hyödyntämällä renderInputs-proppia, jolloin voidaan mm. muuttaa kenttien esitystapaa ja välittää input-elementeille haluttuja attribuutteja. Input-kentät eivät saa maksimileveyttä renderInputs-propin ollessa käytössä, joten kenttien leveyttä voi tarvittaessa rajoittaa omilla css-määrityksillä, tai hyödyntämällä palstakomponentteja.
Input-kentille voi renderInputs-propin avulla tulostaa myös kenttäkohtaiset nimilaput ja virheviestit. Ruudunlukijan lukemiin kenttäkohtaisiin aria-label-teksteihin voi asettaa halutut arvot myös localization-propin avulla.