MaskedTimeField

MaskedTimeField on tekstikenttä, jonka avulla käyttäjät voivat syöttää aikoja numeroin ja se muotoilee syötteen automaattisesti määritetyn maskin mukaan, kun kenttä menettää fokuksen. Maski määrittää odotetun aikamuodon ja ohjaa sekä syöttöä että näyttöä. Komponentti tukee joustavaa jäsentämistä, validoimista, lokalisointia ja arvon palauttamista johdonmukaiselle aikakäsittelylle.

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

MaskedTimeField on rakennettu pelkästään aikaa varten. Jos etsit komponenttia, joka käsittelee päiviä samankaltaisella maskipohjaisella muotoilulla, tutustu MaskedDateField.

MaskedTimeField voidaan luoda parametreilla tai ilman. Voit määrittää alkuaikavälin, etiketin, paikkamerkin ja tapahtumakuuntelijan arvomuutoksille.

Näytä koodi

MaskedTimeFieldView.java

Maskisäännöt

MaskedTimeField käyttää muotoilun indikaattoreita määritelläkseen, kuinka aika jäsennetään ja näytetään. Jokainen muotoilun indikaattori alkaa %-merkillä, jota seuraa kirjain, joka edustaa aikakomponenttia.

Maskin soveltaminen ohjelmallisesti

Jos haluat muotoilla tai jäsentää aikoja samalla maskisynneksellä 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öä:

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

Nämä mahdollistavat joustavan ja paikallisen aikamuotoilun.

Aikamuotojen lokalisointi

MaskedTimeField tukee lokalisointia määrittämällä sopivan paikallisen asetuksen. Tämä varmistaa, että aika syöttö ja ulosanti vastaavat alueellisia käytäntöjä.

field.setLocale(Locale.GERMANY);

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

Jäsentämislogiikka

MaskedTimeField jäsentää käyttäjän syötteen määritettyjen aikamaskien perusteella. Se hyväksyy sekä täydelliset että lyhennetyt numeeriset syötteet erottimilla tai ilman, sallien joustavan syötön samalla varmistaen voimassa olevat ajat. Jäsentämiskäyttäytyminen riippuu maskin määrittelemästä muotojärjestyksestä (esim. %Hz:%mz tunnille/minuutille). Tämä muoto määrittää, kuinka numerosekvenssejä tulkitaan.

Esimerkit jäsentämiskäytännöistä

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

Minimi/maximi-rajoitteiden asettaminen

Voit rajoittaa sallitun aikavälin MaskedTimeField-komponentissa käyttäen setMin() ja setMax() metodeja:

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

Molemmat metodit hyväksyvät java.time.LocalTime tyyppiset arvot. Syötteet, jotka ovat määritellyn alueen ulkopuolella, katsotaan virheellisiksi.

Arvon palauttaminen

MaskedTimeField sisältää palautusominaisuuden, joka palauttaa kentän arvon ennalta määritettyyn tai alkuperäiseen tilaan. Tämä voi olla hyödyllistä muutosten kumoamiseksi tai palauttamiseksi oletusaikaan.

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

Tavat palauttaa arvo

Ohjelmallisesti, kutsumalla restoreValue()
Näppäimistön avulla, painamalla ESC (tämä on oletuspalautusnäppäin, ellei tapahtumakuuntelija ohita sitä)

Näytä koodi

MaskedTimeFieldRestoreView.java

Validointimallit

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

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 noudatettava JavaScript RegExp -syntaksia, kuten on dokumentoitu tässä.

Huomautukset syötteen käsittelystä

Kenttä pyrkii jäsentämään ja muotoilemaan numeerisia aikasyötteitä nykyisen maskin perusteella. Käyttäjät voivat kuitenkin silti syöttää manuaalisesti arvoja, jotka eivät vastaa odotettua muotoa. Jos syöte on syntaktisesti voimassa, mutta semanttisesti virheellinen tai ei-jäsennettävä (esim. 99:99), se voi läpäistä mallin tarkistukset, mutta epäonnistua loogisessa validoinnissa. Sinun tulisi aina validoida syötearvo sovelluksesi logiikassa, vaikka säännöllinen lausekemalli on asetettu, varmistaaksesi, että aika on sekä oikein muotoiltu että merkityksellinen.

Aikavalitsin

MaskedTimeField sisältää sisäänrakennetun aikavalitsimen, joka mahdollistaa käyttäjien valita ajan 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öttö on tarpeen.

Näytä koodi

MaskedTimeFieldPickerView.java

Pääsy valitsimeen

Voit käyttää aikavalitsinta getPicker() metodilla:

TimePicker picker = field.getPicker();

Valitsinikoni näkyviin/piiloon

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

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

Automaattisesti avautuminen

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

picker.setAutoOpen(true);

Valinnan pakottaminen valitsimen kautta

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

field.getPicker().setAutoOpen(true); // Avaa valitsimen käyttäjän vuorovaikutuksessa
field.setAllowCustomValue(false);    // Estää manuaalisen tekstisyöttö

Tämä asetus takaa, että kaikki aikasyöte tulee valitsimen käyttöliittymän kautta, mikä on hyödyllistä, kun haluat tiukkaa muotoilun hallintaa ja poistaa jäsentämisongelmat kirjoitetusta syötteestä.

Valitsimen avaaminen manuaalisesti

Avaa aikavalitsin ohjelmallisesti:

picker.open();

Tai käytä aliasia:

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

Valitsimen asettamisen askel

Voit määrittää valitsimessa valittavien aikojen välin käyttäen setStep(). Tämä sallii sinulle hallita, kuinka valtavaa aikavaihtoehdot ovat - ihanteellinen aikataulutettaessa 15 minuutin välein.

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

Askelrajoitus

Askeleen on jaettava tasaisesti tunti tai kokonainen päivä. Muutoin heitetään poikkeus.

Tämä varmistaa, että alasvetoluettelo sisältää ennustettavia, tasaisesti aikavälein olevia arvoja kuten 09:00, 09:15, 09:30 jne.