Siirry sisältöön

14.5.0

Luonnos

ComboboxV2

Tekstikentän ja valintalistan yhdistelmä, joka ehdottaa käyttäjälle valintoja.

Julkaistu versiossa 14.1.0

ComboboxV2 korvaa aiemman Combobox-komponentin versiossa 16.0.0.

Esikatselu

Käyttötarkoitus

ComboboxV2 on tekstikentän ja valintalistan yhdistelmä, joka ehdottaa asiakkaalle listasta löytyviä vaihtoehtoja sen perustella, mitä asiakas tekstikenttään kirjoittaa. Automaattinen täydennys ehdottaa sopivia vaihtoehtoja reaaliaikaisesti samalla, kun asiakas kirjoittaa tekstikenttään merkkejä.

Sopivat vaihtoehdot näytetään valintalistassa. Automaattinen täydennys nopeuttaa oikean vaihtoehdon löytämistä tilanteissa, joissa valittavia vaihtoehtoja on paljon ja niiden selaaminen valintalistasta olisi työlästä.

Automaattinen täydennys voi aloittaa haun heti ensimmäisestä kirjoitetusta merkistä tai tietyn merkkimäärän jälkeen. Jos esimerkiksi haetaan suomalaisella IBAN-tilinumerolla, haku kannattaa aloittaa vasta kolmannesta merkistä, koska kaikki tilinumerot alkavat samalla FI-etuliitteellä.

Kirjoitetun merkkijonon ei kuitenkaan tarvitse löytyä heti sanan alusta, vaan asiakas voi hakea myös sanan loppuosalla.

Tarvittaessa komponentin voi asettaa näyttämään vain ehdotuksia, jotka alkavat annetulla merkkijonolla.

Tee näin
  • Käytä komponenttia, kun valintalistassa on paljon arvoja, ja asiakas tietää selkeästi, minkä vaihtoehdon hän haluaa valita (esimerkiksi luettelo valtioista tai diagnooseista).
  • Käytä komponenttia, kun haluat ehdottaa asiakkaalle sopivia vaihtoehtoja isosta joukosta (esim. hakukenttä).
  • Ohjeista tarvittaessa asiakasta komponentin käyttöön.
  • Luettele vaihtoehdot loogisessa järjestyksessä, esimerkiksi valinnan yleisyyden mukaan tai aakkosjärjestyksessä.
  • Nimeä vaihtoehdot selkeästi ja ymmärrettävästi, mutta mahdollisimman napakasti.
Älä tee näin

Saavutettavuus

Komponentti toteuttaa teknisesti saavutettavan combobox-käyttöliittymäelementin.

NäppäinToiminto
EnterJos valikko on piilossa, ei tee mitään.
Jos valikko on auki, valitsee korostetun valinnan ja sulkee valikon.
EscJos valikko on auki, ja sulkee valikon.
Jos valikko on piilossa, tyhjentää kentän sisällön.
TabJos valikko on auki, sulkee valikon kohdistuksen poistuessa komponentista.
Jos valikko on auki, korostaa seuraavan valinnan (focus trap).
Jos valikko on piilossa ja käytössä on vain tekstikenttä, ei tee mitään.
Jos valikko on piilossa ja käytössä on pudotusvalikko, avaa valikon ja korostaa ensimmäisen vaihtoehdon.
Jos valikko on auki, korostaa edellisen valinnan (focus trap).
Jos valikko on piilossa ja käytössä on vain tekstikenttä, ei tee mitään.
Jos valikko on piilossa ja käytössä on pudotusvalikko, avaa valikon ja korostaa viimeisen vaihtoehdon.

Komponentille voidaan asettaa seuraavat arvot ruudunlukijaa varten:

AvainKuvausOletusarvo
resultsNotFoundTeksti, joka luetaan kun valintavaihtoehtoja ei löydy.Valintavaihtoehtoja ei löytynyt
resultsFoundTeksti, joka luetaan kun valintavaihtoehtoja löytyy. Funktio, jolla count-parametri.Valintavaihtoehtoja löytyi 1 kappale
Valintavaihtoehtoja löytyi 2 kappaletta
resultsDelayAfterTypeAika millisekunteina, jonka jälkeen valintojen lukumäärä ilmoitetaan.2000
resultsEnabledMäärittää luetaanko valintojen lukumäärä.true
selectedLabelTeksti, joka lisätään valinnan nimen eteen, kun vaihtoehto valitaan valikosta.Valittu
nothingIsSelectedLabelTeksti, joka luetaan kun valinta poistetaan.Valinta poistettu
loadingTextTeksti, joka luetaan valikkoa avatessa, kun asynkroninen Combobox hakee vaihtoehtoja.Ladataan valintavaihtoehtoja

Tekstikenttä

Käytä automaattisella täydennyksellä varustettua tekstikenttää silloin, kun haluat helpottaa asiakkaan työtä tarjoamalla sopivia ehdotuksia (esim. hakukenttä). Käytä komponenttia kuten mitä tahansa tekstikenttää. Asiakas voi valita komponentin ehdottamista vaihtoehdoista sopivan tai kirjoittaa kenttään oman arvon. Kenttään syötetyn tekstin validointi jää lomakkeen kehittäjän tehtäväksi.

Tekstikentän ja valikon yhdistelmä

Käytä tekstikentän ja valikon yhdistelmää, jos asiakkaalla voi olla tarve etsiä sopivaa vaihtoehtoa tietystä joukosta käyttäen automaattista täydennystä tai valitsemalla se valikosta. Älä tarjoa avattavaa valikkoa, jos valittavia vaihtoehtoja on niin paljon, että niiden selaaminen on todella hankalaa.

Salli vain valikossa olevat arvot

Komponentin saa toimimaan Select-komponentin kaltaisesti propilla allowOnlyListedValues, joka sallii kenttään vain ne arvot, jotka löytyvät komponentille annetuista vaihtoehdoista (ComboboxV2MenuOption).

TapausToiminto
Syötettä vastaavia ehdotuksia 0 kplKentän sisältö tyhjennetään, kun kohdistus poistuu kentästä. OnSelect palauttaa tyhjän arvon.
Syötettä vastaavia ehdotuksia 1 kplEhdotettu arvo valitaan, kun kohdistus poistuu kentästä. OnSelect palauttaa valitun arvon.
Syötettä vastaavia ehdotuksia > 1 kplKentän sisältö tyhjennetään, kun kohdistus poistuu kentästä. OnSelect palauttaa tyhjän arvon.

Valikon muokkaus

Valintalistan sisältöä ja ulkoasua voi muokata käyttämällä ComboboxV2MenuOption-komponentin render-propia. Voit esimerkiksi lisätä vaihtoehtoihin liittyviä lisätietoja, jos se auttaa asiakasta löytämään tai valitsemaan vaihtoehdon.

Huomaa, että kenttä ei suodata valintoja esitettyjen lisätietojen perusteella. Mahdolliset lisätiedot tulee erottaa visuaalisesti varsinaisista valinnoista.

Virheilmoitus

Estetty

Lukutila

Oletusvalinta

Oletusvalinta voidaan antaa merkkijonona tai ComboboxV2OptionValue-tyyppisenä objektina. Anna oletusvalinta value-propin kautta silloin, kun komponenttia käytetään kontrolloituna komponenttina.

Valikon renderöinti Portalin avulla

Valikko voidaan renderöidä Portal-komponentilla usePortal-proppia käyttäen. Tämä on tarpeellista silloin, kun ympäröivä elementti ei salli sisällön näyttämistä sen ulkopuolella.

Painikkeiden tai lisätietojen yhdistäminen input-kenttään

Tarvittaessa addonBefore ja addonAfter -propeilla voi yhdistää lisätietoja tai painikkeita komponentin input-kenttään.

Arvojen päivittäminen komponentin ulkopuolelta

Muu-vaihtoehto

Muu-vaihtoehtoa voi käyttää, kun halutaan tarjota valintavaihtoehto silloin kun muita vaihtoehtoja ei löydy. Muu-vaihtoehto voi myös olla näkyvissä jatkuvasti ja se on myös osa suodatusvaihtoehtoja.

Valintojen hakeminen asynkronisesti

Valinnat voi noutaa asynkronisesti, kun komponentti renderöidään. Käytä ComboboxV2Async-komponenttia, jos valintoja on tarve täydentää input-kentän syötteen perusteella.

Valintojen täydentäminen käyttäjän syötteen perusteella

Voit käyttää ComboboxV2Async-komponentin loadOptions-proppia valintavaihtoehtojen hakemiseen ja suodattamiseen asynkronisesti, kun asiakas kirjoittaa input-kenttään. Tämä on suositeltavaa silloin kun valintavaihtoehtoja on erittäin paljon.

Kannattaa muodostaa loadOptions-funktio komponentin ulkopuolella tai kääriä se useCallback(Avautuu uuteen välilehteen)-hookkiin, jolloin se ei päivittyessään renderöi komponenttia turhaan uudelleen.

Oletusvalinnat voi antaa tavallisen Comboboxin tapaan lapsielementteinä. Jos oletusvalintoja ei ole annettu, haetaan ne loadOptions-funktiolla. Aseta startsWith ja threshold -propit samalla tavalla kuin suodatusfunktiolle, jotta hakutulokset korostetaan oikein.

Esimerkki valintoja ehdottavasta syöttökentästä

Valintojen hakeminen valikon avautuessa

Oletuksena valikossa näytetään edelliset hakutulokset. Asetuksella loadOptionsOnToggle voidaan valinnat hakea loadOptions-funktiolla, joka mahdollistaa räätälöidyt vaihtoehdot, kun valikko avataan.

Muu-vaihtoehto

Muu-vaihtoehtoa käytettäessä ei tuloksia -ilmoitusta ei näytetä.