MaskedTimeField

MaskedTimeField on tekstikenttä, joka antaa käyttäjien syöttää aikoja numeroina ja muotoilee syötteen automaattisesti määritellyn maskin mukaan, kun kenttä menettää fokuksen. Maski määrittää odotettavan aikamuodon, ohjaten sekä syöttöä että näyttöä. Komponentti tukee joustavaa analysointia, validointia, lokalisointia sekä arvon palauttamista johdonmukaista aikakäsittelyä varten.

Perusteet

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

MaskedTimeField on rakennettu vain ajan syöttöön. Jos etsit komponenttia, joka käsittelee päivämääriä vastaavalla maskipohjaisella muotoilulla, katso MaskedDateField.

MaskedTimeField voidaan instansioida parametreilla tai ilman. Voit määrittää alkuarvon, etiketti, paikkamerkin ja tapahtumakuuntelijan arvojen muutoksille.

Näytä koodi

MaskedTimeFieldView.java

Maskisäännöt

MaskedTimeField käyttää formaatti-indikaattoreita määrittämään, miten aikaa analysoidaan ja näytetään. Jokainen formaatti-indikaattori alkaa %-merkillä, jota seuraa kirjain, joka edustaa aikaosaa.

Maskien soveltaminen ohjelmallisesti

Jos haluat muotoilla tai analysoida aikoja samalla maskisynteksillä kentän ulkopuolella, käytä MaskDecorator hyötyluokkaa.

Aikamuotoindikaattorit

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

Muokkaimet

Muokkaimet tarkentavat aikakomponenttien näyttöä:

Muokain	Kuvaus
`z`	Nollalla täyttö
`s`	Lyhyt tekstiesitys
`l`	Pitkä tekstiesitys
`p`	Pakattu numero
`d`	Desimaali (oletusmuoto)

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

Aikamuodon lokalisointi

MaskedTimeField tukee lokalisointia asettamalla sopivan paikallisen asetuksen. Tämä varmistaa, että aikasyöttö ja -tulo vastaavat aluetasoisia käytäntöjä.

field.setLocale(Locale.GERMANY);

Tämä vaikuttaa siihen, miten AM/PM-indikaattorit näytetään, miten erottimia käsitellään ja miten arvot analysoidaan.

Analysointilogiikka

MaskedTimeField analysoi käyttäjän syötteen määritetyn aikamaskin perusteella. Se hyväksyy sekä täydelliset että lyhennetyt numeeriset syötteet, joissa on tai ei ole erottimia, mahdollistaen joustavan syötön samalla varmistaen voimassa olevat ajat. Analysointikäyttäytyminen riippuu maskin määrittämästä formaattijärjestyksestä (esim. %Hz:%mz tunti/minuutti). Tämä formaatti määrää, miten numeerisia sekvenssejä tulkitaan.

Esimerkit analysointitilanteista

Syöte	Maski	Tulkitsee Muuna
`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-rajoitusten asettaminen

Voit rajoittaa sallitun aikavälin MaskedTimeField-komponentissa käyttäen 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 aikavälin ulkopuoliset syötteet katsotaan virheellisiksi.

Arvon palauttaminen

MaskedTimeField sisältää palautusominaisuuden, joka nollaa kentän arvon ennalta määrättyyn tai alkuperäiseen tilaan. Tämä voi olla hyödyllistä muutosten peruuttamiseen tai takaisin oletusaikaan.

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

Tapoja palauttaa arvo

Ohjelmallisesti, kutsumalla restoreValue()
Näppäimistön kautta, painamalla ESC (tämä on oletuspalautusavain, ellei tapahtumakuuntelijalla määritellä toisin)

Näytä koodi

MaskedTimeFieldRestoreView.java

Validointikaavat

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

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

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

Säännöllisen lausekkeen muoto

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

Huomautuksia syötteen käsittelystä

Kenttä yrittää analysoida ja muotoilla numeerisia aikasyötteitä nykyisen maskin perusteella. Kuitenkin käyttäjät voivat silti syöttää arvoja, jotka eivät vastaa odotettua muotoa. Jos syöte on syntaktisesti validi mutta semanttisesti virheellinen tai analysoimaton (esim. 99:99), se voi läpäistä kaavavalvonnan mutta epäonnistua loogisessa validoinnissa. Sinun tulisi aina validoida syötearvo sovelluksen logiikassasi, vaikka säännöllinen lauseke on asetettu, jotta voit varmistaa, että aika on sekä kunnolla muotoiltu että merkityksellinen.

Aikavalitsin

MaskedTimeField sisältää sisäänrakennetun aikavalitsimen, joka antaa 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

Aikavalitsimen käyttö

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

TimePicker picker = field.getPicker();

Valitsimen ikonin näyttäminen/piilottaminen

Käytä setIconVisible()-menetelmää näyttääksesi tai piilottaaksesi kellon ikonin kentän vieressä:

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

Automaattisesti avautuva käyttäytyminen

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

picker.setAutoOpen(true);

Pakota valinta aikavalitsimen kautta

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

field.getPicker().setAutoOpen(true); // Avataan valitsin käyttäjän vuorovaikutuksessa
field.setAllowCustomValue(false);    // Poistaa manuaalisen tekstisyötön

Tämä asettelu varmistaa, että kaikki aikasyöte tulee valitsimen käyttöliittymän kautta, mikä on hyödyllistä, kun haluat tiukan muotoilun hallinnan ja poistaa opiskeluprosesseista kirjoitettuja syötteitä.

Aikavalitsimen avaaminen manuaalisesti

Avaa aikavalitsin ohjelmallisesti:

picker.open();

Tai käytä aliasia:

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

Valitsimen askeleen määrittäminen

Voit määrittää valittavien aikojen välin valitsimessa käyttäen setStep(). Tämä mahdollistaa aikavaihtoehtojen kontrolloinnin—ihanteellinen skenaarioissa kuten aikataulutuksissa 15 minuutin välein.

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

Askelrajoitus

Askel täytyy jakaa tasan tunnille tai koko päivälle. Muuten poikkeus heitetään.

Tämä varmistaa, että alasvetoluettelossa on ennustettavia, tasaisesti jaettuja arvoja kuten 09:00, 09:15, 09:30 jne.