MaskedDateField

MaskedDateField on tekstikenttä, joka antaa käyttäjille mahdollisuuden syöttää päivämääriä numeroina ja automaattisesti muotoilee syötteen määritellyn maskin perusteella, kun kenttä menettää fokuksen. Maski määrittelee odotetun päivämäärämuodon, ohjaten sekä syöttöä että esitystä. Komponentti tukee joustavaa analysointia, validointia, lokalisointia ja arvon palauttamista johdonmukaista, aluekohtaisesti tarkkaa päivämääräkäsittelyä varten.

Perusteet

Etsitkö aikasyöttöä?

MaskedDateField keskittyy pelkästään päivämääräarvoihin. Jos tarvitset vastaavan komponentin aikojen syöttämiseen ja muotoiluun, tutustu sen sijaan MaskedTimeField.

MaskedDateField voidaan alustaa parametreilla tai ilman. Voit määrittää alkuperäisen arvon, etiketin, paikkamerkin ja tapahtumakuuntelijan arvon muutoksille.

Näytä koodi

MaskedDateFieldView.java

Maskisäännöt

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

Päivä/Kuu/Vuosi (käytetään lähes koko Euroopassa)
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äiden muotojen sisällä paikalliset variaatiot sisältävät erotinmerkin valinnan (esim. -, / tai .), ovatko vuodet kaksinumeroisia vai nelinumeroisia, ja ovatko yksinumeroiset kuukaudet tai päivät täytettyjä nollilla.

Tämän monimuotoisuuden käsittelemiseksi MaskedDateField käyttää formaatti-indikaattoreita, jotka kaikki alkavat prosenttimerkillä %, jota seuraa kirjain, joka edustaa tiettyä päivämäärän osaa. Nämä indikaattorit määrittävät, miten syöte analysoidaan ja miten päivämäärä näytetään.

Maskien käyttäminen ohjelmallisesti

Muotoiltaessa tai analysoitaessa päivämääriä saman maskisynnnin avulla kentän ulkopuolella käytä MaskDecorator -työkaluluokkaa.

Päivämäärämuotoindikaattorit

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

Muokkaimet

Muokkaimet antavat enemmän kontrollia siitä, miten päivämäärän komponentit muotoillaan:

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

Näitä voidaan yhdistää, jotta voidaan luoda monenlaisia päivämäärämaskuja.

Päivämäärämuotojen lokalisointi

MaskedDateField mukautuu alueellisiin päivämäärämuotoihin asettamalla asianmukaisen kulttuurin. Tämä varmistaa, että päivämäärät esitetään ja analysoidaan tavalla, joka vastaa käyttäjien 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`

Lokalisoinnin soveltamiseksi käytä setLocale()-metodia. Se hyväksyy java.util.Locale ja säätää automaattisesti sekä muotoilua että analysointia:

dateField.setLocale(Locale.FRANCE);

Analysointilogiikka

MaskedDateField analysoi käyttäjän syötteen määritellyn päivämäärämaskin perusteella. Se hyväksyy sekä täydelliset että lyhennetyt numeromuotoiset syötteet erottimien kanssa tai ilman, mikä mahdollistaa joustavan syöttämisen samalla varmistaen, että päivämäärät ovat voimassa. Analysointikäyttäytyminen riippuu maskissa määritellystä muodosta (esim. %Mz/%Dz/%Yz kuukaudesta/päivästä/vuodesta). Tämä muoto määrittelee, miten numerojärjestykset tulkitaan.

Esimerkiksi, olettaen, että tänään on 15. syyskuuta 2012, näin erilaisia syötteitä analysoitaisiin:

Esimerkkianalysointiskenaariot

Syöte	YMD (ISO)	MDY (Yhdysvallat)	DMY (Eurooppa)
`1`	Yksi numero tulkitaan aina nykyisen kuukauden päivänä, joten tämä olisi 1. syyskuuta 2012.	Sama kuin YMD	Sama kuin YMD
`12`	Kaksi numeroa tulkitaan aina nykyisen kuukauden päivänä, joten tämä olisi 12. syyskuuta 2012.	Sama kuin YMD	Sama kuin YMD
`112`	Kolme numeroa tulkitaan 1-numeroisena kuukausina ja 2-numeroisena päivänä, joten tämä olisi 12. tammikuuta 2012.	Sama kuin YMD	Kolme numeroa tulkitaan 1-numeroisena päivänä ja 2-numeroisena kuukautena, joten tämä olisi 1. joulukuuta 2012.
`1004`	Neljä numeroa tulkitaan MMDD-muotoiseksi, joten tämä olisi 4. lokakuuta 2012.	Sama kuin YMD	Neljä numeroa tulkitaan DDMM-muotoiseksi, joten tämä olisi 10. huhtikuuta 2012.
`020304`	Kuusi numeroa tulkitaan YYMMDD-muotoiseksi, joten tämä olisi 4. maaliskuuta 2002.	Kuusi numeroa tulkitaan MMDDYY-muotoiseksi, joten tämä olisi 3. helmikuuta 2004.	Kuusi numeroa tulkitaan DDMMYY-muotoiseksi, joten tämä olisi 2. maaliskuuta 2004.
`8 numeroa`	Kahdeksan numeroa tulkitaan YYYYMMDD-muotoiseksi. Esimerkiksi, `20040612` on 12. kesäkuuta 2004.	Kahdeksan numeroa tulkitaan MMDDYYYY-muotoiseksi. Esimerkiksi, `06122004` on 12. kesäkuuta 2004.	Kahdeksan numeroa tulkitaan DDMMYYYY-muotoiseksi. Esimerkiksi, `06122004` on 6. joulukuuta 2004.
`12/6`	Kaksi numeroa, jotka on erotettu minkä tahansa voimassa olevan erottimen avulla, tulkitaan MM/DD-muotoiseksi, joten tämä olisi 6. joulukuuta 2012. Huom: Kaikki merkit, paitsi kirjaimet ja numerot, lasketaan voimassa oleviksi erottimiksi.	Sama kuin YMD	Kaksi numeroa, jotka on erotettu minkä tahansa erottimen avulla, tulkitaan DD/MM-muotoiseksi, joten tämä olisi 12. kesäkuuta 2012.
`3/4/5`	Huhtikuun 5, 2012	Maaliskuun 4, 2005	Huhtikuun 3, 2005

Tekstuaalinen päivämäärän analysointi 25.11

Oletusarvoisesti MaskedDateField hyväksyy vain numeerista syöttöä päivämäärille. Voit kuitenkin mahdollistaa tekstuaalisen päivämäärän analysoinnin salliaksesi käyttäjien syöttää kuukausi- ja päivämääränimet syötteessään. Tämä ominaisuus on erityisen hyödyllinen luonnollisen päivämäärän syöttämisen helpottamiseksi.

Ottaaksesi käyttöön tekstuaalisen analysoinnin, käytä setTextualDateParsing() -metodia:

dateField.setTextualDateParsing(true);

Kuukauden nimen korvaminen

Kun tekstuaalinen analysointi on käytössä, voit käyttää erityisiä muokkaimia maskissasi hyväksyäksesi kuukausinimiä numeeristen arvojen sijaan:

%Ms - Hyväksyy lyhyet kuukausinimet (Tam, Hel, Mar jne.)
%Ml - Hyväksyy pitkät kuukausinimet (Tammikuu, Helmikuu, Maaliskuu jne.)

Kuukauden nimet voivat esiintyä maskissa missä tahansa asemassa, ja kenttä hyväksyy edelleen numeerisen syötteen varalla.

Esimerkit

Maski	Syöte	Tulos
`%Ms/%Dz/%Yz`	`Sep/01/25`	Voimassa - Analysoidaan 1. syyskuuta 2025
`%Ml/%Dz/%Yz`	`September/01/25`	Voimassa - Analysoidaan 1. syyskuuta 2025
`%Dz/%Ml/%Yz`	`01/September/25`	Voimassa - Analysoidaan 1. syyskuuta 2025
`%Mz/%Dz/%Yz`	`09/01/25`	Voimassa - Numeerinen varalle on vielä käytössä

tiedot

Kaikki 12 kuukautta tukevat lyhyitä (Tam, Hel, Mar, Huht, Tou, Kes, Heinä, Elo, Syys, Loka, Marras, Joulukuu) ja pitkiä (Tammikuu, Helmikuu, jne.) muotoja.

Päivän nimen koristelu

Viikkopäivän nimet voidaan sisällyttää syötteeseen paremman luettavuuden vuoksi, mutta ne ovat koristeellisia vain ja poistetaan analysoinnin aikana. Ne eivät vaikuta varsinaiseen päivämääräarvoon.

%Ds - Hyväksyy lyhyet viikonpäivän nimet (Ma, Ti, Ke jne.)
%Dl - Hyväksyy pitkät viikonpäivän nimet (Maanantai, Tiistai, Keskiviikko jne.)

Viikonpäivän nimet vaativat numeerisen päivän

Käytettäessä viikonpäivän nimiä (%Ds tai %Dl), maskisi täytyy myös sisältää %Dz tai %Dd määrittämään varsinaisen päivän numero. Ilman numeerista päivämääräkomponenttia syöte on virheellinen.

Esimerkit

Maski	Syöte	Tulos
`%Ds %Mz/%Dz/%Yz`	`Ma 09/01/25`	Voimassa - Päivän nimi on koristeellinen
`%Dl %Mz/%Dz/%Yz`	`Maanantai 09/01/25`	Voimassa - Päivän nimi on koristeellinen
`%Mz/%Dz/%Yz %Ds`	`09/01/25 Ti`	Voimassa - Päivän nimi lopussa
`%Dl/%Mz/%Yz`	`Maanantai/09/25`	Virheellinen - Puuttuu `%Dz`
`%Mz/%Dl/%Yz`	`09/Maanantai/25`	Virheellinen - Puuttuu `%Dz`

Kaikki 7 viikonpäivää tukevat lyhyitä (Ma, Ti, Ke, To, Pe, La, Su) ja pitkiä (Maanantai, Tiistai jne.) muotoja.

Lisäanalysointisäännöt

Tekstuaalinen päivämäärän analysointi sisältää useita hyödyllisiä ominaisuuksia:

Ei-herkkä tapauksille: Syöte kuten MAANANTAI 09/01/25, maanantai 09/01/25, tai Maanantai 09/01/25 toimivat kaikki samalla tavalla.
Kulttuurintietoinen: Kuukauden ja päivän nimet on sovitettava kentän määriteltyyn kulttuuriin. Esimerkiksi ranskalaisella kulttuurilla käytetään septembre eikä September. Englanninkieliset nimet eivät tule tunnistetuksi, ellet kulttuuri ole asetettu englanniksi.
- Ranskalainen kulttuuri: septembre/01/25 tunnistetaan syyskuuna
- Saksalainen kulttuuri: Montag 09/01/25 tunnistetaan maanantaina viikonpäivänä

Min/Max-rajoitusten asettaminen

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

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

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

Arvon palauttaminen

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

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

Tavat palauttaa arvo

Ohjelmallisesti, kutsumalla restoreValue()
Näppäimistön kautta, painamalla ESC (tämä on oletusarvoinen palautusnäppäin, ellei tapahtumakuuntelijalla toisin määritellä)

Voit asettaa palautettavan arvon käyttämällä setRestoreValue(), jossa on LocalDate -instanssi.

Näytä koodi

MaskedDateFieldRestoreView.java

Validointikaaviot

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

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

Tämä kaavio varmistaa, että vain arvot, jotka vastaavat MM/DD/YYYY -muotoa (kaksi numeroa, vinoviiva, kaksi numeroa, vinoviiva, neljä numeroa) ovat voimassa.

Säännöllisen lausekkeen muoto

Kaavion on noudatettava JavaScript RegExp -syntaksia, kuten asiakirjoissa on kuvattu tässä.

Huomautuksia syötteen käsittelystä

Kenttä yrittää analysoida ja muotoilla numeerisia päivämääräsyötteitä nykyisen maskin perusteella. Käyttäjät voivat silti kuitenkin syöttää manuaalisesti arvoja, jotka eivät vastaa odotettua muotoa. Jos syöte on syntaktisesti voimassa, mutta semantisesti virheellinen tai ei-analysoitavissa (esim. 99/99/9999), se saattaa läpäistä kaaviotarkistukset, mutta epäonnistua loogisessa validoinnissa. Sinun tulisi aina validoida syöttöarvo sovelluksesi logiikassa, vaikka säännöllinen lauseke olisi asetettu, varmistaaksesi, että päivämäärä on sekä oikein muotoiltu että merkityksellinen.

Päivämäärävalitsin

MaskedDateField sisältää sisäänrakennetun kalenterivalitsimen, joka antaa käyttäjille mahdollisuuden valita päivämäärä visuaalisesti sen sijaan, että tyyppisi sen. Tämä parantaa käytettävyyttä vähemmän teknisille käyttäjille tai kun tarkkaa syöttöä tarvitaan.

Näytä koodi

MaskedDateFieldPickerView.java

Pääsy valitsimelle

Voit käyttää päivämäärävalitsinta kutsumalla getPicker():

DatePicker picker = dateField.getPicker();

Valitsimen ikonin näyttäminen/piilottaminen

Käytä setIconVisible() -metodia näyttääksesi tai piilottaaksesi kalenterikuvakkeen kentän vieressä:

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

Automaattinen avauskäyttäytyminen

Voit määrittää valitsimen avautumaan automaattisesti, kun käyttäjä käyttää kenttää (esim. klikkaa, painaa Enter tai nuolinäppäimiä):

picker.setAutoOpen(true);

Pakota valitseminen valitsimen kautta

Varmistaaksesi, että käyttäjät voivat valita päivämäärän vain kalenterivalitsimella (eikä voi kirjoittaa manuaalisesti), yhdistä seuraavat kaksi asetusta:

dateField.getPicker().setAutoOpen(true); // Avaa valitsimen käyttäjän vuorovaikutuksessa
dateField.setAllowCustomValue(false);    // Poistaa manuaalisen tekstisyötön käytöstä

Tämä asetus varmistaa, että kaikki päivämääräsyötteet tulevat valitsin käyttöliittymän kautta, mikä on hyödyllistä, kun haluat tiukkaa muotoilun hallintaa ja poistaa tyypitysyksilöinnistä syntyvät ongelmat.

Avaa kalenteri manuaalisesti

Avaa kalenteri ohjelmallisesti:

picker.open();

Tai käytä aliasia:

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

Näytä viikot kalenterissa

Valitsin voi valinnaisesti näyttää viikon numerot kalenterinäkymässä:

picker.setShowWeeks(true);