Komponentti ajanjakson 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.
DateRangePickerV2 korvaa tulevaisuudessa DateRangePicker-komponentin.
Esikatselu
<DateRangePickerV2 labelText="Lorem ipsum" />
Käyttötarkoitus
Ajanjakson valitsin (DateRangePickerV2) tarjoaa käyttäjälle alku- ja loppupäivämäärien syöttökentät ja kalenterinäkymän päivämäärävälin valitsemiseen.
Päivämäärän voi syöttää muodoissa pp.kk.vvvv, p.k.vvvv, ppkkvvvv sekä vvvv-kk-pp.
Tee näin
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. Myös erillisten
päivämääräkenttien käyttöä kannattaa harkita.
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
DateRangePickerV2:n 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.
Ajanjakson valinta
Ajanjakson valitseminen onnistuu joko syöttämällä alkamis- ja päättymispäivät tekstikenttiin tai valitsemalla ajanjakson kalenterista.
Oletusarvon voi antaa sekä alkamis- että päättymispäivälle, tai vain toiselle niistä. Oletusarvon voi antaa Date-objektina tai vvvv-kk-pp-muotoisena tekstiarvona.
<DateRangePickerV2
labelText="Ajanjakson valinta"
helpText="Ilmoita päivämäärät muodossa pp.kk.vvvv"
defaultValue={{ from: new Date(2023, 9, 2), to: "2023-10-27" }}
/>
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.
Ajanjaksoa ei pysty valitsemaan siten, että ajanjakson sisällä olisi estettyjä päiviä. Kalenteri estää ne vaihtoehdot, joita ei voi valita, kun käyttäjä valitsee ensimmäisen päivämäärän.
Päivämäärien validointi ja virheviestien asettaminen
Virhetilan asettaminen
Komponentin voi asettaa virhetilaan errorText ja invalid-proppien avulla.
<DateRangePickerV2
required
labelText="Ajanjakson valinta"
helpText="Ilmoita päivämäärät muodossa pp.kk.vvvv"
errorText="Virheellinen ajanjakso. Ilmoita päivämäärät muodossa pp.kk.vvvv."
invalid={{ from: true, to: true }}
/>
Komponentille voi asettaa useamman virheviestin antamalla errorText-propille listan virheviesteistä.
<DateRangePickerV2
labelText="Ajanjakson valinta"
helpText="Ilmoita päivämäärät muodossa pp.kk.vvvv"
required
errorText={[
{ type: "from", message: "Alkamispäivä on virheellinen." },
{ type: "to", message: "Päättymispäivä on virheellinen." },
{ type: "range", message: "Ajanjakso on virheellinen." },
]}
invalid={{ from: true, to: true }}
/>
Esimerkki virheenkäsittelyn toteuttamisesta
Komponentti palauttaa kaikkien tapahtumien (onChange, onSelect, onError, onBlur ja onCalendarClose) 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ä). Lisäksi palautetaan tieto, kumpaa kentistä käyttäjä on viimeksi käsitellyt.
Validoinnin mukana palautetaan aina tulokset molempien kenttien validoinnista. 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. Sovelluksen vastuulle jää virheilmoitusten tarkempi käsittely, esimerkiksi milloin
virheilmoitukset näytetään ja missä järjestyksessä.
Alta löytyy karkea esimerkki dynaamisen virheentarkistuksen toteuttamisesta:
Myös komponentin käyttämää getDateRangeValidator-funktiota voi hyödyntää validoinnin toteuttamiseen.
Funktiolle annetaan samat validointisäännöt (required, fromRequired, fromDate, toDate, disabledDates, disablePast), kuin komponentille.
Tätä voi hyödyntää esimerkiksi React Hook Formin validate-funktiossa. Oletusvirheilmoituksia voi päivittää
toErrorTexts, fromErrorTexts ja rangeErrorTexts-objektien kautta.
function DateRangePickerV2Example() {
const defaultValue = { from: new Date("2023-10-10"), to: "" };
const validationProps = {
fromDate: new Date("2023-01-01"),
toDate: new Date("2023-12-31"),
required: true,
};
const validationResult = getDateRangeValidator(validationProps).validate(defaultValue);
return (
<DateRangePickerV2
calendarDefaultMonth="2023-10"
defaultValue={defaultValue}
labelText="Ajanjakson valinta"
helpText="Ilmoita päivämäärät muodossa pp.kk.vvvv"
errorText={validationResult.from.error.message || validationResult.to.error.message}
invalid={{ from: !validationResult.from.isValid, to: !validationResult.to.isValid }}
{...validationProps}
/>
);
}
Validoinnin palauttamat arvot
Parametri
Kuvaus
field
Kertoo kumpaa input-kenttää käyttäjä on viimeksi käsitellyt (onChange, onBlur, onError). Arvoina from, to tai undefined. Voidaan käyttää esimerkiksi validointiviestien kohdistamiseen.
from.isValid to.isValid
Kertoo onko päivämäärä hyväksytty arvo (oikea päivämäärä ja läpäisee validoinnit).
from.valueAsDate to.valueAsDate
Päivämäärä Date-objektina, silloin kun input-kentän syötteestä pystytään muodostamaan päivämäärä.
from.valueAsISO to.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ä.
Kenttäkohtainen oletusvirheviesti, jota voi päivittää localization-propin kautta.
range.isValid
Kertoo ovatko molemmat arvot hyväksyttyjä (oikeat päivämäärät ja läpäisevät validoinnit).
range.error.type
Virheen tyyppi: invalidRange
range.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.
Tarvittaessa päivämääräarvon voi päivittää tai tyhjentää komponentin ulkopuolelta antamalla value-arvon.
Proppien fromRef ja toRef kautta pääsee käsiksi input-elementteihin, mikä mahdollistaa esimerkiksi kohdistuksen siirtämisen kenttään.
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ä.
<DateRangePickerV2
labelText="Date range"
helpText="Enter the dates as dd.mm.yyyy"
placeholder="dd.mm.yyyy"
fromDate="2020-01-01"
toDate="2040-12-31"
localization={{
ariaLabelRangeFrom: "Start date",
ariaLabelRangeTo: "End date",
ariaLabelWeekNumber: "Number of the week",
ariaStatusClearDate: "Selected time interval removed",
labelClearDate: "Clear date",
labelMonthDropdown: () => "Month",
labelYearDropdown: () => "Year",
labelNext: () => "Go to next month",
labelPrevious: () => "Go to previous month",
labelToggleCalendar: "Choose a date",
labelCloseCalendar: "Close the calendar",
labelSelected: "selected",
labelGoToCurrentDay: "Go to current day",
locale: enGB, // import { enGB } from "date-fns/locale/en-GB";
rangeErrorTexts: {
invalidRange: "Invalid time interval. Check the given dates.",
},
fromErrorTexts: {
dateDisabled: "The start date is not in the allowed date interval. Choose another date.",
invalidRelation: "The start date is incorrect. Check that the start date precedes the end date.",
invalidFormat: "The start date is incorrect. Enter the date as dd.mm.yyyy.",
notInRangeTo: "The start date is incorrect. Check that the date is within the allowed range.",
notInRangeFrom: "The start date is incorrect. Check that the date is within the allowed range.",
required: "The start date is mandatory information. Enter the date as dd.mm.yyyy.",
},
toErrorTexts: {
dateDisabled: "The end date is not in the allowed date interval. Choose another date.",
invalidRelation: "The end date is incorrect. Check that the start date precedes the end date.",
invalidFormat: "The end date is incorrect. Enter the date as dd.mm.yyyy.",
notInRangeTo: "The end date is incorrect. Check that the date is within the allowed range.",
notInRangeFrom: "The end date is incorrect. Check that the date is within the allowed range.",
required: "The end date is mandatory information. Enter the date as dd.mm.yyyy.",
},
}}
/>
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.
Toteuttajan vastuulle jää responsiivisen toiminnan ja saavutettavuuden varmistaminen.
Input-kentille voi renderInputs-propin avulla tulostaa myös kenttäkohtaiset nimilaput ja virheviestit.
Huom! Alla oleva esimerkki ei ole malli valmiista ulkoasusta, vaan tekninen esimerkki renderInputs-funktion käyttämisestä.