MaskedTimeField

MaskedTimeField on tekstikenttä, joka sallii käyttäjien syöttää aikoja numeroina ja muotoilee sisäänsyötön automaattisesti määritetyn maskin perusteella, kun kenttä menettää fokuksen. Maski määrittelee odotetun aikamuotoilun, ohjaten sekä syöttöä että näyttöä. Komponentti tukee joustavaa jäsentämistä, validoimista, lokalisointia ja arvojen palauttamista yhtenäisen ajan käsittelyn varmistamiseksi.

Perusteet

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

MaskedTimeField on rakennettu vain-aikasyötteelle. Jos etsit komponenttia, joka käsittelee päiviä samankaltaisella maskiperusteisella muotoilulla, katso MaskedDateField.

MaskedTimeField voidaan luoda parametreilla tai ilman. Voit määrittää alkuperäisen arvon, etiketin, paikkamerkin ja tapahtumakuuntelijan arvojen muutoksille.

Näytä koodi

Java

Maskisäännöt

MaskedTimeField käyttää muotoilun osoittimia määrittääkseen, miten aika jäsennetään ja näytetään. Jokainen muotoilun osoitin alkaa %-merkillä, jota seuraa kirjain, joka edustaa aikakomponenttia.

Aikamuotoilun osoittimet

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

Modifioijat

Modifioijat tarkentavat aikakomponenttien näyttöä:

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

Nämä mahdollistavat joustavan ja paikallisten aikamuotoilu.

Aikamuotoilun lokalisointi

MaskedTimeField tukee lokalisointia asettamalla sopivan lokalisoinnin. Tämä varmistaa, että aikasyöttö ja -tuloste vastaavat alueellisia käytäntöjä.

field.setLocale(Locale.GERMANY);

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

Jäsentämislogiikka

MaskedTimeField jäsentää käyttäjän syötteen perusteella määritetyn aikamaskin. Se hyväksyy sekä täydelliset että lyhennetyt numeeriset syötteet, joissa on tai ei ole erotinmerkkejä, mikä mahdollistaa joustavan syötön samalla varmistaen kelvolliset ajat. Jäsentämiskäyttäytyminen riippuu maskin määrittelemästä muotojärjestyksestä (esim. %Hz:%mz tunnin/minuutin jaoks). Tämä muoto määrittää, miten numeeriset sekvenssit tulkitaan.

Esimerkkijäsentämisskenaariot

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`

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-tyyppisiä arvoja. Määritetyn aikarajan ulkopuoliset syötteet katsotaan kelvottomiksi.

Arvon palauttaminen

MaskedTimeField sisältää palautustoiminnon, joka nollaa kentän arvon ennalta määriteltyyn tai alkuperäiseen tilaan. Tämä voi olla hyödyllistä muutosten peruuttamiseen tai oletusaikaan paluuseen.

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

Tapoja palauttaa arvo

Ohjelmallisesti, kutsumalla restoreValue()
Avaimen kautta, painamalla ESC (tämä on oletuspalautusavain, ellei tapahtumakuuntelijalla ole muuta määritelty)

Näytä koodi

Java

Validointimallit

Voit soveltaa asiakaspään validointisää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 HH:mm- muodossa (kaksi numeroa, kaksoispiste, kaksi numeroa) olevat arvot katsotaan kelvollisiksi.

Säännöllisen lausekkeen muoto

Mallin on noudatettava JavaScript RegExp -syntaksia, kuten asiakirjoissa täällä.

Huomautuksia syöttökäsittelystä

Kenttä yrittää jäsentää ja muotoilla numeeriset aikasyötteet 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 jäsentämätön (esim. 99:99), se voi läpäistä kaavamallit mutta epäonnistua loogisessa validoinnissa. Sinun tulisi aina validoida syötearvo sovelluksen logiikassa, vaikka säännöllinen lausekemalli olisi asetettu, varmistaaksesi, että aika on sekä oikein muotoiltu että merkityksellinen.

Aikavalitsin

MaskedTimeField sisältää sisäänrakennetun aikavalitsimen, joka antaa käyttäjien valita ajan visuaalisesti sen sijaan, että 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

Java

Valitsimen käyttö

Voit käyttää aikavalitsinta getPicker()-menetelmällä:

TimePicker picker = field.getPicker();

Valitsimen kuvakkeen näyttäminen/pittämättä jättäminen

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

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

Automaattinen avautuminen

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);

Valinnan pakottaminen valitsimen kautta

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

field.getPicker().setAutoOpen(true); // Avautuu valitsimeen käyttäjän vuorovaikutuksen myötä
field.setAllowCustomValue(false);    // Estää manuaalisen tekstisyötteen

Tämä asetustapa takaa, että kaikki aikasyöttö tulee valitsimen käyttöliittymän kautta, mikä on hyödyllistä, kun haluat tiukan muotoilusäätelyn ja poistaa erityiskirjoitukseen liittyvät jäsentämisongelmat.

Aikavalitsimen avaaminen manuaalisesti

Avaa aikavalitsin ohjelmallisesti:

picker.open();

Tai käytä alias-komentoa:

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

Valitsimen askeleen määrittäminen

Voit määrittää valitsimen valittavien aikojen välin käyttämällä setStep(). Tämä antaa sinulle mahdollisuuden hallita, kuinka hienojakoisia aikavaihtoehdot ovat—ihanteellinen esimerkiksi aikatauluttamiseen 15 minuutin välein.

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

Askelrajoitus

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

Tämä varmistaa, että pudotuslistassa on ennakoitavissa olevia, tasaisesti jaettavia arvoja kuten 09:00, 09:15, 09:30 jne.