MaskedDateField

MaskedDateField on teksti-input, joka sallii käyttäjien syöttää päivämäärät numeroina ja automaattisesti muotoilla syötteen määritellyn maskin perusteella, kun kenttä menettää fokus. Maski määrittelee odotetun päivämäärämuodon, ohjaten sekä syöttöä että näyttöä. Komponentti tukee joustavaa jäsentämistä, validoimista, lokalisointia ja arvon palauttamista johdonmukaiselle, aluekohtaiselle päivämäärä käsittelylle.

Perusteet

Etsitkö aikasyöttöä?

MaskedDateField keskittyy ainoastaan päivämäärä arvoihin. Jos tarvitset samanlaista komponenttia aikojen syöttämiseen ja muotoiluun, katso MaskedTimeField.

MaskedDateField voidaan luoda parametrista riippumatta. Voit määrittää alkusarjan, etiketin, paikkamerkin ja tapahtumakuuntelijan arvojen muutoksille.

Näytä koodi

Java

Maskisäännöt

MaskedDateField tukee useita päivämäärämuotoja, jotka vaihtelevat ympäri maailmaa päivä-, kuukausi- ja vuosijärjestyksen mukaan. Yleisimmät kaavat sisältävät:

Päivä/Kuukausi/Vuosi (käytössä suurimmassa osassa Eurooppaa)
Kuukausi/Päivä/Vuosi (käytössä Yhdysvalloissa)
Vuosi/Kuukausi/Päivä (käytössä Kiinassa, Japanissa ja Koreassa; myös ISO-standardi: YYYY-MM-DD)

Näiden muotojen sisällä paikalliset vaihtelut sisältävät erotinmerkin valinnan (esim. -, / tai .), ovatko vuodet kahta tai neljää numeroa, ja ovatko yksinumeroiset kuukaudet tai päivät esitäytettyjä nollilla.

Tämän monimuotoisuuden käsittelemiseksi MaskedDateField käyttää formaatti-indikaattoreita, jotka alkavat %, jota seuraa kirjain, joka edustaa tiettyä osaa päivämäärästä. Nämä indikaattorit määrittelevät, kuinka syöttö jäsennetään ja kuinka päivämäärä näytetään.

Päivämäärämuotoindikaattorit

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

Modifikaattorit

Modifikaattorit antavat enemmän hallintaa päivämäärän osien muotoilussa:

Modifikaattori	Kuvaus
`z`	Nollatäyte
`s`	Lyhyt tekstiesitys
`l`	Pitkä tekstiesitys
`p`	Pakattu numero
`d`	Desimaalimuoto (oletus)

Näitä voidaan yhdistää luomaan monenlaisia päivämäärämaskeja.

Päivämäärän muotoilu lokalisoinnin mukaan

MaskedDateField mukautuu alueellisiin päivämäärämuotoihin asettamalla asianmukaisen lokalisoinnin. 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`

Lokalisoinnin soveltamiseksi käytä setLocale() -metodia. Se hyväksyy java.util.Locale -olion ja säätää automaattisesti sekä muotoilun että jäsentämisen:

dateField.setLocale(Locale.FRANCE);

Jäsentämislogiikka

MaskedDateField jäsentää käyttäjän syöttöä määritellyn päivämäärämaskin perusteella. Se hyväksyy sekä täydelliset että lyhennetyt numeeriset syötteet erotinmerkkien kanssa tai ilman, jolloin joustava syöttäminen varmistaa kelvolliset päivämäärät.

Jäsentämisen käytäntö riippuu maskin määrittämästä järjestyksestä (esim. %Mz/%Dz/%Yz kuukausi/päivä/vuosi). Tämä muoto määrää, miten numeeriset sekvenssit tulkitaan.

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

Esimerkit jäsentämisestä

Syöte	YMD (ISO)	MDY (US)	DMY (EU)
`1`	Yksi numero tulkitaan aina päivänumeroksi voimassa olevassa kuukaudessa, joten tämä olisi 1. syyskuuta 2012.	Sama kuin YMD	Sama kuin YMD
`12`	Kaksi numeroa tulkitaan aina päivänumeroksi voimassa olevassa kuukaudessa, joten tämä olisi 12. syyskuuta 2012.	Sama kuin YMD	Sama kuin YMD
`112`	Kolme numeroa tulkitaan yhden numeron kuukausinumeroksi ja kahden numeron päivänumeroksi, joten tämä olisi 12. tammikuuta 2012.	Sama kuin YMD	Kolme numeroa tulkitaan yhden numeron päivänumeroksi ja kahden numeron kuukausinumeroksi, joten tämä olisi 1. joulukuuta 2012.
`1004`	Neljä numeroa tulkitaan muodossa MMDD, joten tämä olisi 4. lokakuuta 2012.	Sama kuin YMD	Neljä numeroa tulkitaan muodossa DDMM, joten tämä olisi 10. huhtikuuta 2012.
`020304`	Kuusi numeroa tulkitaan muodossa YYMMDD, joten tämä olisi 4. maaliskuuta 2002.	Kuusi numeroa tulkitaan muodossa MMDDYY, joten tämä olisi 3. helmikuuta 2004.	Kuusi numeroa tulkitaan muodossa DDMMYY, joten tämä olisi 2. maaliskuuta 2004.
`8 numeroa`	Kahdeksan numeroa tulkitaan muodossa YYYYMMDD. Esimerkiksi `20040612` on 12. kesäkuuta 2004.	Kahdeksan numeroa tulkitaan muodossa MMDDYYYY. Esimerkiksi `06122004` on 12. kesäkuuta 2004.	Kahdeksan numeroa tulkitaan muodossa DDMMYYYY. Esimerkiksi `06122004` on 6. joulukuuta 2004.
`12/6`	Kaksi numeroa, jotka on erotettu millä tahansa voimassa olevalla erottimella tulkitaan muotoon MM/DD, joten tämä olisi 6. joulukuuta 2012. Huom: Kaikki merkit, paitsi kirjaimet ja numerot, on voimassa olevia erotinmerkkejä.	Sama kuin YMD	Kaksi numeroa, jotka on erotettu millä tahansa erotinmerkillä tulkitaan muotoon DD/MM, joten tämä olisi 12. kesäkuuta 2012.
`3/4/5`	5. huhtikuuta 2012	4. maaliskuuta 2005	3. huhtikuuta 2005

Tekstuaalinen päivämääräjäsentäminen 25.11

Oletuksena MaskedDateField hyväksyy vain numeeriset syötteet päivämäärille. Voit kuitenkin ottaa käyttöön tekstuaalisen päivämääräjäsentämisen sallimalla käyttäjien syöttää kuukausi- ja päivätietoja syötteeseensä. Tämä toiminto on erityisen hyödyllinen luotaessa luonnollisempaa päivämääräsyöttöä.

Ota tekstuaalinen jäsentäminen käyttöön käyttämällä setTextualDateParsing() -metodia:

dateField.setTextualDateParsing(true);

Kuukauden nimen korvaaminen

Kun tekstuaalinen jäsentäminen on käytössä, voit käyttää erityisiä modifikaattoreita maskissasi hyväksyäksesi kuukausinimiä numeeristen arvojen sijaan:

%Ms - Hyväksyy lyhyitä kuukausinimiä (Tammi, Helmi, Maa, jne.)
%Ml - Hyväksyy pitkiä kuukausinimiä (Tammikuu, Helmikuu, Maaliskuu, jne.)

Kuukauden nimet voivat esiintyä missä tahansa sijainnissa maskissa, ja kenttä hyväksyy silti numeerisia syötteitä varasyötteenä.

Esimerkit

Maski	Syöte	Tulos
`%Ms/%Dz/%Yz`	`Sep/01/25`	Kelvollinen - Jäsentää 1. syyskuuta 2025
`%Ml/%Dz/%Yz`	`September/01/25`	Kelvollinen - Jäsentää 1. syyskuuta 2025
`%Dz/%Ml/%Yz`	`01/September/25`	Kelvollinen - Jäsentää 1. syyskuuta 2025
`%Mz/%Dz/%Yz`	`09/01/25`	Kelvollinen - Numero varasyöttö toimii silti

tiedot

Kaikkia 12 kuukautta tuetaan sekä lyhyinä (Tammi, Helmi, Maa, Huhti, Touko, Kesä, Heinä, Elo, Syys, Loka, Marras, Joulu) että pitkinä (Tammikuu, Helmikuu, jne.) muotoina.

Päivän nimen koristeellinen käyttö

Viikonpäivän nimiä voidaan sisällyttää syötteeseen paremman luettavuuden vuoksi, mutta ne ovat koristeellisia vain ja poistetaan jäsentämisen aikana. Ne eivät vaikuta varsinaiseen päivämääräarvoon.

%Ds - Hyväksyy lyhyitä päivän nimiä (Ma, Ti, Ke, jne.)
%Dl - Hyväksyy pitkiä päivän nimiä (Maanantai, Tiistai, Keskiviikko, jne.)

Päivän nimet tarvitsevat numeerisen päivän

Kun käytät viikonpäivän nimiä (%Ds tai %Dl), maskisi täytyy myös sisältää %Dz tai %Dd määrittämään varsinainen päivännumero. Ilman numeerista päivän osaa syöte on kelpaamaton.

Esimerkit

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

Kaikki 7 viikonpäivää tuetaan sekä lyhyinä (Ma, Ti, Ke, To, Pe, La, Su) että pitkinä (Maanantai, Tiistai, jne.) muotoina.

Lisäjäsentämissäännöt

Tekstuaalinen päivämääräjäsentäminen sisältää useita hyödyllisiä ominaisuuksia:

Kokonaissensitiivinen: Syöte kuten MAANANTAI 09/01/25, maanantai 09/01/25 tai Maanantai 09/01/25 toimivat kaikki samalla tavalla.
Paikkakunnasta riippuvainen: Kuukausi- ja päivän nimet on sovittava kentän määritettyyn lokalisointiin. Esimerkiksi, ranskalaisella lokalisoinnilla käytä septembre etkä September. Englanninkielisiä nimiä ei tunnisteta, ellei lokalisointi ole asetettu englanniksi.
- Ranskalainen lokalisointi: septembre/01/25 tunnistetaan syyskuuksi
- Saksalainen lokalisointi: Montag 09/01/25 tunnistetaan maanantaina nimipäivänä

Min/Max-rajojen 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 menetelmät hyväksyvät java.time.LocalDate -tyyppisiä arvoja. Määriteltyjen rajojen ulkopuoliset syötteet katsotaan kelpaamattomiksi.

Arvon palauttaminen

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

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

Tapoja palauttaa arvo

Ohjelmallisesti, kutsumalla restoreValue()
Näppäimistön kautta, painamalla ESC (tämä on oletusarvoinen palautusavain, ellei sitä ylikirjoiteta tapahtumakuuntelijan toimesta)

Voit asettaa palautettavan arvon käyttämällä setRestoreValue(), antaen LocalDate (https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/LocalDate.html) -instanssin.

Näytä koodi

Java

Varmennuskuviot

Voit soveltaa asiakaspään validoimisääntöjä käyttämällä säännöllisiä lausekkeita setPattern() -metodilla:

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

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

Säännöllinen lausekemuoto

Kuvion on noudatettava JavaScript RegExp -syntaksia, kuten on dokumentoitu täällä.

Huomautuksia syötteen käsittelyyn

Kenttä yrittää jäsentää ja formatoida numeeriset päivämääräsyötteet nykyisen maskin mukaan. Käyttäjät voivat silti syöttää manuaalisesti arvoja, jotka eivät vastaa odotettua muotoa. Jos syöte on syntaktisesti kelvollinen mutta semanttisesti virheellinen tai ei-jäsennettävä (esim. 99/99/9999), se voi läpäistä kuvio tarkastukset, mutta epäonnistua loogisessa validoimisessa. Sinun tulisi aina validoida syötearvo sovelluksen logiikassa, vaikka säännöllinen lauseke olisi asetettu, varmistaaksesi, että päivämäärä on sekä oikeassa muodossa että merkityksellinen.

Päivämäärävalitsin

MaskedDateField sisältää sisäänrakennetun kalenterivalitsimen, joka mahdollistaa käyttäjien valita päivämäärän visuaalisesti, sen sijaan että kirjoitetaan se. Tämä parantaa käytettävyyttä vähemmän teknisten käyttäjien tai silloin, kun tarkka syöttö on tarpeen.

Näytä koodi

Java

Valitsimen käyttöönotto

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

DatePicker picker = dateField.getPicker();

Valitsimen ikonin näyttäminen/piilottaminen

Käytä setIconVisible() -metodia näytääksesi tai piilottaaksesi kalenteri-ikoni kentän vieressä:

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

Automaattinen avaustoiminta

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

picker.setAutoOpen(true);

Pakota valinta valitsimen kautta

Varmistaaksesi, että käyttäjät voivat valita vain päivämäärän kalenteri-valitsimella (eivätkä kirjoittaa manuaalisesti), yhdistä seuraavat kaksi asetusta:

dateField.getPicker().setAutoOpen(true); // Avaa valitsimen käyttäjän vuorovaikutuksen myötä
dateField.setAllowCustomValue(false);    // Estää manuaalisen tekstisyötön

Tämä asetus varmistaa, että kaikki päivämääräsyöte tulee valitsimen käyttöliittymän kautta, mikä on hyödyllistä tiukkaa muotoilun hallintaa varten ja eliminoi jäsentämisongelmat kirjoitetuista syötteistä.

Kalenterin avaaminen manuaalisesti

Avaa kalenteri ohjelmallisesti:

picker.open();

Tai käytä aliasia:

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

Viikkojen näyttäminen kalenterissa

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

picker.setShowWeeks(true);