MaskedDateField

MaskedDateField on tekstiinputtiohjaus, joka on suunniteltu jäsenneltyyn päivämäärien syöttämiseen. Se sallii käyttäjien syöttää päivämääriä numeroina ja automaattisesti muotoilee syötteen määritellyn maskin perusteella, kun kenttä menettää fokuksen. Maski on merkkijono, joka määrittää odotetun päivämäärämuodon, ohjaten sekä syötettä että näyttöä.

Tämä komponentti tukee joustavaa jäsentämistä, validoimista, lokalisointia ja arvon palauttamista. Se on erityisen hyödyllinen lomakkeissa, kuten rekisteröinneissä, varauksissa ja aikataulutuksessa, joissa vaaditaan johdonmukaisia ja aluekohtaisia päivämäärämuotoja.

Etsitkö aikasyöttöä?

MaskedDateField keskittyy pelkästään päivämäärä arvoihin. Jos tarvitset vastaavaa komponenttia ajan syöttämiseen ja muotoiluun, katso MaskedTimeField.

Perusteet

MaskedDateField voidaan instansioida joko parametreilla tai ilman. Voit määrittää alkusarjan, etiketin, paikkamerkin ja tapahtumakuuntelijan arvojen muutoksiin.

Näytä koodi

Java

Maskisäännöt

MaskedDateField tukee useita päivämäärämuotoja, joita käytetään eri puolilla maailmaa, jotka vaihtelevat päivän, kuukauden ja vuoden järjestyksen mukaan. Yleisiä kuvioita ovat:

Päivä/Kuu/Vuosi (käytetään useimmissa Euroopan maissa)
Kuu/Päivä/Vuosi (käytetään Yhdysvalloissa)
Vuosi/Kuu/Päivä (käytetään Kiinassa, Japanissa ja Koreassa; myös ISO-standardi: YYYY-MM-DD)

Näissä muodoissa paikalliset variaatiot sisältävät erottimen valinnan (esim. -, / tai .), onko vuosia kaksi vai neljä numeroa, ja ovatko yksinumeroiset kuukaudet tai päivät täytetty etunollilla.

Käsitelläkseen tätä monimuotoisuutta MaskedDateField käyttää formaatti-indikaattoreita, jotka alkavat aina %:llä ja joita seuraa kirjain, joka edustaa jokaisen osan päivämäärästä. Nämä indikaattorit määrittävät, miten syöte jäsennetään ja miten päivämäärä näytetään.

Päivämääräformaatti-indikaattorit

Muoto	Kuvaus
`%Y`	Vuosi
`%M`	Kuukausi
`%D`	Päivä

Muokkaimet

Muokkaimet mahdollistavat enemmän hallintaa sen suhteen, miten päivämäärän osia muotoillaan:

Muokkain	Kuvaus
`z`	Nollatäyttö
`s`	Lyhyt tekstiesitys
`l`	Pitkä tekstiesitys
`p`	Pakattu numero
`d`	Desimaalimuoto (oletusmuoto)

Nämä voidaan yhdistää rakentamaan laaja valikoima päivämäärämaskeja.

Päivämäärämuodon lokalisointi

MaskedDateField mukautuu alueellisiin päivämäärämuotoihin asettamalla asianmukaisen kielitunnuksen. Tämä varmistaa, että päivämäärät näytetään ja jäsennetään tavalla, joka vastaa käyttäjän odotuksia.

Alue	Muoto	Esimerkki
Yhdysvallat	MM/DD/YYYY	`07/04/2023`
Eurooppa	DD/MM/YYYY	`04/07/2023`
ISO-standardi	YYYY-MM-DD	`2023-07-04`

Käytä lokalisointia varten setLocale() -metodia. Se hyväksyy java.util.Locale ja säätää automaattisesti sekä muotoilua että jäsentämistä:

dateField.setLocale(Locale.FRANCE);

Jäsentämislogiikka

MaskedDateField jäsentää käyttäjän syötteen määritellyn päivämäärämaskin perusteella. Se hyväksyy sekä täydelliset että lyhennetyt numeeriset syötteet erottimilla tai ilman, mikä mahdollistaa joustavan syötteen, samalla kun varmistetaan, että päivämäärät ovat voimassa. Jäsentämiskäyttäytyminen riippuu maskissa määritellystä muototilasta (esim. %Mz/%Dz/%Yz kuukaudelle/päivälle/vuodelle). Tämä muoto määräytyy sen mukaan, miten numeeriset merkkijonot tulkitaan.

Esimerkiksi, olettaen, että tänään on 15. syyskuuta 2012, näin erilaiset syötteet tulkitaan:

Esimerkit jäsentämisestä

Syöttö	YMD (ISO)	MDY (US)	DMY (EU)
`1`	Yksi numero tulkitaan aina kuukauden nykyisen päivän numerona, joten tämä olisi 1. syyskuuta 2012.	Sama kuin YMD	Sama kuin YMD
`12`	Kaksi numeroa tulkitaan aina kuukauden nykyisen päivän numerona, joten tämä olisi 12. syyskuuta 2012.	Sama kuin YMD	Sama kuin YMD
`112`	Kolme numeroa tulkitaan 1-numeroisena kuukauden numerona, jota seuraa 2-numeroisesti päivänumero, joten tämä olisi 12. tammikuuta 2012.	Sama kuin YMD	Kolme numeroa tulkitaan 1-numeroisena päivän numerona, jota seuraa 2-numeroisen kuukauden numero, joten tämä olisi 1. joulukuuta 2012.
`1004`	Neljä numeroa tulkitaan MMDD-muodossa, joten tämä olisi 4. lokakuuta 2012.	Sama kuin YMD	Neljä numeroa tulkitaan DDMM-muodossa, joten tämä olisi 10. huhtikuuta 2012.
`020304`	Kuusi numeroa tulkitaan YYMMDD-muodossa, joten tämä olisi 4. maaliskuuta 2002.	Kuusi numeroa tulkitaan MMDDYY-muodossa, joten tämä olisi 3. helmikuuta 2004.	Kuusi numeroa tulkitaan DDMMYY-muodossa, joten tämä olisi 2. maaliskuuta 2004.
`8 numeroa`	Kahdeksan numeroa tulkitaan YYYYMMDD-muodossa. Esimerkiksi `20040612` on 12. kesäkuuta 2004.	Kahdeksan numeroa tulkitaan MMDDYYYY-muodossa. Esimerkiksi `06122004` on 12. kesäkuuta 2004.	Kahdeksan numeroa tulkitaan DDMMYYYY-muodossa. Esimerkiksi `06122004` on 6. joulukuuta 2004.
`12/6`	Kaksi numeroa, jotka on erotettu mistä tahansa voimassa olevasta erottimesta, tulkitaan muodossa MM/DD, joten tämä olisi 6. joulukuuta 2012. Huom: Kaikki merkit, paitsi kirjaimet ja numerot, katsotaan voimassa oleviksi erottimiksi.	Sama kuin YMD	Kaksi numeroa, jotka on erotettu mistä tahansa erottimesta, tulkitaan muodossa DD/MM, joten tämä olisi 12. kesäkuuta 2012.
`3/4/5`	5. huhtikuuta 2012	4. maaliskuuta 2005	3. huhtikuuta 2005

Min/max-rajoitusten asettaminen

Voit rajoittaa sallitun päivämääräalueen MaskedDateField-komponentissa käyttämällä setMin() ja setMax() -menetelmiä:

dateField.setMin(LocalDate.of(2020, 1, 1));
dateField.setMax(LocalDate.of(2030, 12, 31));

Molemmat metodit hyväksyvät arvoja tyyppiä java.time.LocalDate. Syöttö, joka on määritellyn alueen ulkopuolella, katsotaan virheelliseksi.

Arvon palauttaminen

MaskedDateField sisältää palautusominaisuuden, joka palauttaa kentän arvon ennalta määriteltyyn tai alkuperäiseen tilaan. Tämä on hyödyllistä käyttäjän syötteen palauttamiseksi tai palauttamiseksi oletuspäivämäärään.

dateField.setRestoreValue(LocalDate.of(2025, 1, 1));
dateField.restoreValue();

Tapoja palauttaa arvo

Ohjelmallisesti, kutsumalla restoreValue()
Näyttönäppäimistön avulla, painamalla ESC (tämä on oletusarvoinen palautusavain, ellei tapahtumakuuntelijalla ole toisin määritelty)

Voit asettaa palautettavan arvon setRestoreValue()-metodilla, välittämällä LocalDate instanssin.

Näytä koodi

Java

Validointikuviot

Voit soveltaa asiakassivujen validointisääntöjä käyttämällä säännöllisiä lausekkeita setPattern()-menetelmällä:

dateField.setPattern("^\\d{2}/\\d{2}/\\d{4}$");

Tämä kuvio varmistaa, että vain arvot, jotka vastaavat MM/DD/YYYY muotoa (kaksi numeroa, vinoviiva, kaksi numeroa, vinoviiva, neljä numeroa) katsotaan voimassa oleviksi.

Säännöllinen lauseke -muoto

Kuvion on noudatettava JavaScriptin RegExp-synteesiä, kuten on asiakirjoitettu täällä.

Huomautuksia syötteen käsittelyyn

Kenttä yrittää jäsentää ja muotoilla numeeriset päivämääräsyötteet nykyisen maskin perusteella. Kuitenkin, käyttäjät voivat silti syöttää manuaalisesti arvoja, jotka eivät vastaa odotettua muotoa. Jos syöttö on syntaktisesti voimassa, mutta semanttisesti virheellinen tai jäsentämätön (esim. 99/99/9999), se voi ohittaa kuvion tarkat, mutta epäonnistua loogisessa validoinnissa. Sinun tulisi aina validoida syötearvo sovelluksen logiikassasi, vaikka säännöllinen lauseke olisi asetettu, varmistaaksesi, että päivämäärä on sekä oikein muotoiltu että mielekäs.

Päivämäärävalitsin

MaskedDateField sisältää sisäänrakennetun kalenterivalitsimen, joka sallii käyttäjien valita päivämäärän visuaalisesti sen sijaan, että he kirjoittaisivat sen. Tämä parantaa käytettävyyttä vähemmän teknisille käyttäjille tai kun tarkka syöttö on tarpeen.

Näytä koodi

Java

Pipetön valitsimen käyttö

Voit käyttää päivämäärävalitsinta getPicker()-menetelmällä:

DatePicker picker = dateField.getPicker();

Näytä/piilota valitsimen ikoni

Käytä setIconVisible()-menetelmää näyttääksesi tai piilottaaksesi kalenteri-ikonin kentän vieressä:

picker.setIconVisible(true); // näyttää ikonin

Automaattinen avautuminen

Voit määrittää valitsimen avautumaan automaattisesti, kun käyttäjä toimii kentän kanssa (esim. napsauttaa, painaa Enter tai nuolinäppäimiä):

picker.setAutoOpen(true);

Vaatimus vain valitsimen kautta

Varmistaaksesi, että käyttäjät voivat valita päivämäärän vain kalenterivalitsimen avulla (eivätkä syöttäen sitä manuaalisesti), yhdistä seuraavat kaksi asetusta:

dateField.getPicker().setAutoOpen(true); // avaa valitsimen käyttäjän toiminnan yhteydessä
dateField.setAllowCustomValue(false);    // estää manuaalisen tekstisyötön

Tämä asetus takaa, että kaikki päivämääräsyötteet tulevat valitsimen käyttöliittymästä, mikä on hyödyllistä, kun haluat tiukan muotoilun hallinnan ja estää jäsentämisongelmia kirjoitettavasta syötteestä.

Avaa kalenteri manuaalisesti

Avaa kalenteri ohjelmallisesti:

picker.open();

Tai käytä aliasia:

picker.show(); // sama kuin open()

Näytä viikot kalenterissa

Valitsija voi valinnaisesti näyttää viikkonumerot kalenterinäkymässä:

picker.setShowWeeks(true);