MaskedTimeField

MaskedTimeField on tekstikenttä, joka sallii käyttäjien syöttää aikoja numeroina ja automaattisesti muotoilee syötteen määritellyn maskin perusteella, kun kenttä menettää fokuksen. Maski määrittelee odotetun aikamuodon, ohjaten sekä syöttöä että näyttöä. Komponentti tukee joustavaa jäsentämistä, validointia, lokalisaatiota ja arvon palauttamista johdonmukaiselle aikakäsittelylle.

Perustiedot

Etsitkö päivämääräsyöttöä?

MaskedTimeField on rakennettu vain aikoja varten. Jos etsit komponenttia, joka käsittelee päiviä samanlaisen maskiperusteisen muotoilun avulla, tutustu MaskedDateField.

MaskedTimeField voidaan alustaa parametreilla tai ilman. Voit määrittää alkupäivämäärän, etiketin, paikkamerkin ja tapahtumakuuntelijan arvojen muutoksille.

Näytä koodi

MaskedTimeFieldView.java

Maskisäännöt

MaskedTimeField käyttää muotoilun indikaattoreita määrittämään, miten aikaa jäsennetään ja näytetään. Jokainen muotoilun indikaattori alkaa prosenttimerkistä %, jonka jälkeen tulee kirjain, joka edustaa aikakomponenttia.

Maskien soveltaminen ohjelmallisesti

Jos haluat muotoilla tai jäsentää aikoja samalla maskisyntaksilla kentän ulkopuolella, käytä MaskDecorator -apuluokkaa.

Aikamuotoilun indikaattorit

Muoto	Kuvaus
`%H`	Tunti (24-tuntinen)
`%h`	Tunti (12-tuntinen)
`%m`	Minuutti
`%s`	Sekunti
`%p`	AM/PM

Muokkaimet

Muokkaimet tarkentavat aikakomponenttien näyttöä:

Muokkain	Kuvaus
`z`	Nollasijoitus
`s`	Lyhyt tekstiesitys
`l`	Pitkä tekstiesitys
`p`	Pakattu number
`d`	Desimaaliluku (oletusmuoto)

Nämä mahdollistavat joustavan ja paikallisesti mukautuvan aikamuotoilun.

Aikamuotojen lokalisaatio

MaskedTimeField tukee lokalisaatiota oikean alueen määrittämisellä. Tämä varmistaa, että aikasyöte ja -tulos vastaavat alueellisia käytäntöjä.

field.setLocale(Locale.GERMANY);

Tämä vaikuttaa siihen, miten AM/PM -indikaattorit näytetään, miten erottimet käsitellään ja miten arvot jäsennetään.

Jäsentämislogiikka

MaskedTimeField jäsentää käyttäjän syöttämän tiedon määritellyn aikamaskin perusteella. Se hyväksyy sekä täydelliset että lyhennetyt numeeriset syötteet erottimilla tai ilman, mikä mahdollistaa joustavan syötteen ilman, että voimassa olevat ajat vaarantuvat. Jäsentäminen riippuu maskissa määritellystä muotojärjestyksestä (esim. %Hz:%mz tunnin/minuutin osalta). Tämä muoto määrää, miten numeeriset sekvenssit tulkitaan.

Esimerkit jäsentämistapauksista

Syöte	Mask	Tulkinta
`900`	`%Hz:%mz`	`09:00`
`1345`	`%Hz:%mz`	`13:45`
`0230`	`%hz:%mz %p`	`02:30 AM`
`1830`	`%hz:%mz %p`	`06:30 PM`

Min/max-rajojen asettaminen

Voit rajoittaa sallitun aikavälin MaskedTimeField-kentässä käyttämällä setMin() ja setMax() -menetelmiä:

field.setMin(LocalTime.of(8, 0));
field.setMax(LocalTime.of(18, 0));

Molemmat menetelmät hyväksyvät java.time.LocalTime -tyypin arvot. Määritelmien ulkopuolisia syötteitä pidetään voimassa olevina.

Arvon palauttaminen

MaskedTimeField sisältää palautusominaisuuden, joka palauttaa kentän arvon ennalta määrättyyn tai alkuperäiseen tilaan. Tämä voi olla hyödyllistä muutosten kumoamisen tai oletusaikaan palaamisen kannalta.

field.setRestoreValue(LocalTime.of(12, 0));
field.restoreValue();

Tavat palauttaa arvo

Ohjelmallisesti, kutsumalla restoreValue()
Näppäimistön kautta, painamalla ESC (tämä on oletuspalautusavain, ellei tapahtumakuuntelija ylikirjoita sitä)

Näytä koodi

MaskedTimeFieldRestoreView.java

Validointimallit

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

field.setPattern("^\\d{2}:\\d{2}$");

Tämä malli varmistaa, että vain arvot, jotka vastaavat HH:mm -muotoa (kaksi numeroa, kaksoispiste, kaksi numeroa), katsotaan voimassa oleviksi.

Säännöllisen lausekkeen muoto

Mallin on seurattava JavaScriptin RegExp-syntaksia, kuten on dokumentoitu täällä.

Huomautuksia syötteen käsittelystä

Kenttä yrittää jäsentää ja muotoilla numeerisia aikasyötteitä nykyisen maskin perusteella. Kuitenkin, käyttäjät voivat silti manuaalisesti syöttää arvoja, jotka eivät vastaa odotettua muotoa. Jos syöte on syntaktisesti voimassa, mutta semanttisesti virheellinen tai jäsentämättömä (esim. 99:99), se saattaa läpäistä mallintarkastukset mutta epäonnistua loogisessa validoinnissa. Sinun tulisi aina validoida syötearvo sovelluksesi logiikassa, vaikka säännöllinen lauseke olisi asetettu, varmistaaksesi, että aika on sekä oikein muotoiltu että merkityksellinen.

Aikavalitsin

MaskedTimeField sisältää sisäänrakennetun aikavalitsimen, joka sallii käyttäjien valita ajan muuttamalla sitä visuaalisesti sen sijaan, että he kirjoittaisivat sen. Tämä parantaa käytettävyyttä vähemmän teknisille käyttäjille tai silloin, kun tarkka syöte on tarpeen.

Näytä koodi

MaskedTimeFieldPickerView.java

Valitsimen käyttö

Voit käyttää aikavalitsinta käyttämällä getPicker():

TimePicker picker = field.getPicker();

Valitsimen kuvakkeen näyttäminen/piilottaminen

Käytä setIconVisible() -menetelmää näyttämään tai piilottamaan kelloikoni kentän vieressä:

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

Automaattinen avautumiskäyttäytyminen

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

picker.setAutoOpen(true);

Valitsimen kautta valinnan pakottaminen

Varmistaaksesi, että käyttäjät voivat valita ajan vain valitsimen kautta (eivätkä manuaalisesti kirjoittamalla), yhdistä seuraavat kaksi asetusta:

field.getPicker().setAutoOpen(true); // Avautuu valitsimella vuorovaikuttaessa
field.setAllowCustomValue(false);    // Poistaa manuaalisen tekstisyötteen mahdollisuuden

Tämä asetus takaa, että kaikki aikasyöte tulee valitsimen käyttöliittymästä, mikä on hyödyllistä, kun haluat tiukkaa muotoilua ja poistaa jäsentämiseen liittyvät ongelmat kirjoitetuista syötteistä.

Avaa valitsin manuaalisesti

Avaa aikavalitsin ohjelmallisesti:

picker.open();

Tai käytä alias-nimeä:

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

Valitsimen askeleen asettaminen

Voit määrittää valitsimen valittavien aikojen välin käyttäen setStep(). Tämä mahdollistaa sen, että voit hallita, kuinka tarkasti aikavaihtoehdot asetetaan – ihanteellinen aikataulutustilanteissa, joissa käytetään 15 minuutin välejä.

field.getPicker().setStep(Duration.ofMinutes(15));

Askeleen rajoitus

Askeleen on jaettava tasan tunti tai koko päivä. Muussa tapauksessa poikkeus heitetään.

Tämä varmistaa, että avattavassa luettelossa on ennakoitavia, tasaisesti jakautuvia arvoja kuten 09:00, 09:15, 09:30 jne.