MaskedTimeField

MaskedTimeField on tekstikenttä, joka on suunniteltu tarkkaa ja jäsenneltyä aikasyöttöä varten. Se antaa käyttäjille mahdollisuuden syöttää aikoja numeroina ja muotoilee syötteen automaattisesti määritetyn maskin perusteella, kun kenttä menettää fokuksen. Maski on merkkijono, joka määrittelee odotetun aikamuodon, ohjaten sekä syöttöä että näyttöä.

Tämä komponentti tukee joustavaa jäsentämistä, validoimista, lokalisointia ja arvon palauttamista. Se on erityisen hyödyllinen aikaherkkissä lomakkeissa, kuten aikatauluissa, työaikapapereissa ja varauksissa.

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

MaskedTimeField on rakennettu vain aika syöttöä varten. Jos etsit komponenttia, joka käsittelee päivämääriä vastaavalla maskiperusteisella muotoilulla, tutustu MaskedDateField.

Perusteet

MaskedTimeField voidaan alustaa parametreilla tai ilman. Voit määrittää alkusarvoa, etiketin, paikkaohjaimen ja tapahtumakuuntelijan arvon muutoksille.

Näytä Koodi

Java

Maskisäännöt

MaskedTimeField käyttää formaattinäyttöjä määrittääkseen, kuinka aikaa jäsennetään ja näytetään. Jokainen formaattinäyttö alkaa prosenttimerkillä % ja sitä seuraa kirjain, joka edustaa aikakomponenttia.

Aikamuotoilunäyttöjä

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

Modifierit

Modifierit hienosäätävät aikakomponenttien näyttämistä:

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

Nämä mahdollistavat joustavan ja paikallisystävällisen aikamuotoilun.

Aikamuodon lokalisointi

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

field.setLocale(Locale.GERMANY);

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

Jäsentämislogiikka

MaskedTimeField jäsentää käyttäjän syötteen määritetyn aikamaskin perusteella. Se hyväksyy sekä täydellisiä että lyhennettyjä numeerisia syötteitä erottimilla tai ilman, mahdollistaen joustavan syötön varmistaen samalla, että ajat ovat voimassa. Jäsentäminen riippuu maskin määrittämästä formaattijärjestyksestä (esim. %Hz:%mz tunnille/minuutille). Tämä formaatti määrittää, kuinka numeerisia sekvenssejä tulkitaan.

Esimerkit jäsentämisestä

Syöte	Maski	Tulkitaan
`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-komponentissa 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 arvoja. Määritellyn alueen ulkopuoliset syötteet katsotaan virheellisiksi.

Arvon palauttaminen

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

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

Tavat palauttaa arvo

Ohjelmallisesti kutsumalla restoreValue()
Näppäimistön kautta, painamalla ESC (tämä on oletuspalausnäppäin, ellei sitä ohitettaisi tapahtumakuuntelijalla)

Näytä Koodi

Java

Validointikaaviot

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

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

Tämä kaavio varmistaa, että vain HH:mm -muotoiset arvot (kaksi numeroa, päällekkäin, kaksi numeroa) katsotaan voimassa oleviksi.

Säännöllisen lausekkeen muoto

Kaavan on noudatettava JavaScriptin RegExp-syntaksia, kuten on dokumentoitu tässä.

Huomautuksia syötteen käsittelystä

Kenttä yrittää jäsentää ja muotoilla numeerisia aikasyötteitä nykyisen maskin mukaan. Kuitenkin käyttäjät voivat 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ä kaaviotarkastukset, mutta epäonnistua loogisessa validoinnissa. Sinun tulee 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 antaa käyttäjille mahdollisuuden valita aikansa visuaalisesti sen sijaan, että kirjoittaisivat sen. Tämä parantaa käytettävyyttä vähemmän teknisille käyttäjille tai kun tarkkaa syöttöä tarvitaan.

Näytä Koodi

Java

Pääsy valitsimeen

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

TimePicker picker = field.getPicker();

Valitsimen ikonin näyttäminen/piilottaminen

Käytä setIconVisible() -menetelmää valitsemaan, näytetäänkö vai piilotetaanko kelloikoni kentän vieressä:

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

Automaattinen avauskäyttäytyminen

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

picker.setAutoOpen(true);

Vahvista valinta valitsimella

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

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

Tämä asetelma varmistaa, että kaikki aikasyöttö tulee valitsin-käyttäjäliittymän kautta, mikä on hyödyllistä tiukan formaattikontrollin ja syöttövirheiden poistamisen käsittelyssä.

Valitsimen avaaminen manuaalisesti

Aukaisemaan aikavalitsin ohjelmallisesti:

picker.open();

Tai käytä aliasia:

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

Valitsimen välin asettaminen

Voit määrittää valitsimessa valittavien aikavälisten aikojen välin käyttämällä setStep(). Tämä mahdollistaa sen, että voit hallita, kuinka suuria aikavalinnan vaihtoehdot ovat—ihanteellinen tilanteisiin, joissa aikataulutetaan 15 minuutin välein.

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

Askeleen rajoite

Askeleen on jaettava täsmällisesti tunti tai koko päivä. Muuten poikkeus heitetään.

Tämä varmistaa, että alasvetoluettelossa on ennakoitavia ja tasaisesti sijoitettuja arvoja kuten 09:00, 09:15, 09:30 jne.