Design systém gov.cz4.6.4

Autocomplete

Komponenta Autocomplete je Input, který usnadňuje uživatelům výběr hodnoty z rozsáhlého seznamu možností. Našeptávač zvyšuje efektivitu a pohodlí při zadávání hodnoty.

Katastrální území v Praze

Použití ​

Kdy používat ​

  • Při vyhledávání nebo výběru, kdy existuje rozsáhlý seznam možností.
  • V situacích, kdy je důležité zúžit výběr na základě částečného vstupu uživatele.

Kdy nepoužívat ​

  • Pro jednoduché seznamy s malým počtem položek, kde je výhodnější použít běžný Select nebo Checkboxy.
  • Kde není potřeba dynamické vyhledávání ze seznamu možností.
  • Kde uživatelé mají přehled o všech dostupných možnostech.

Backend search & debouncing ​

Funkci předanou přes setSearchCallback(callback) volá komponenta interně s vestavěným debouncerem — po každém zadrženém zápisu počká throttleTime ms (default 200) a teprve potom callback zavolá. Pro pomalejší backendy (nebo pro snížení počtu requestů) zvyšte throttleTime (např. 400–600 ms).

Callback musí vracet Promise<GovFormAutocompleteItem[]>. Neobalujte ho vlastním debounce z lodash / RxJS — typický debounce wrapper vrací undefined (dokud neuplyne čas) místo Promise a komponenta pak nemá co await-ovat. Místo toho použijte vestavěný throttleTime.

html
<gov-form-autocomplete throttle-time="400"></gov-form-autocomplete>
ts
autocompleteRef.value.setSearchCallback((query) => {
    return fetch(`/api/search?q=${encodeURIComponent(query)}`).then(r => r.json())
})

Zdroj dat ​

Komponenta podporuje dva způsoby plnění položek. Který zvolit:

RežimKdy ho použít
Statický seznam (options)Středně velký, lokálně dostupný seznam (desítky až nižší stovky položek) — číselník krajů, úřadů, kategorií. Filtrování řeší komponenta sama.
Asynchronní vyhledávání (setSearchCallback)Rozsáhlý, vzdálený nebo výpočetně drahý zdroj, kde se dotazuje na server — adresy (RÚIAN), firmy (ARES), obce. Dotaz se spouští od minlength znaků (výchozí 3).

Statický seznam (options) ​

Pole položek lze předat přímo přes atribut/prop options. Filtrování (substring, bez ohledu na velikost písmen a diakritiku) i limit počtu zobrazených položek (max-options, výchozí 10) zajišťuje komponenta sama. Klik do inputu zobrazí všechny položky (do limitu), psaní je filtruje.

Klíč pro zobrazení — name-key ​

Komponenta u každé položky potřebuje vědět, ze kterého klíče objektu má vzít text, který zobrazí a podle kterého vyhledává. Tento klíč určuje prop name-key (výchozí name).

  • Pokud položky mají klíč name, funguje to bez konfigurace:

    ts
    options = [{ name: 'Praha' }, { name: 'Brno' }];   // name-key není potřeba

  • Pokud položky používají jiný klíč (časté { id, value }), musíš komponentě říct, který to je — jinak se zobrazí prázdné řádky a vyhledávání nic nenajde:

    ts
    options = [{ id: 1, value: 'Praha' }, { id: 2, value: 'Brno' }];
    html
    <gov-form-autocomplete [options]="options" name-key="value"></gov-form-autocomplete>

Asynchronní vyhledávání (setSearchCallback) ​

Pro vzdálené zdroje zaregistruj callback, který vrací Promise s vyfiltrovanými položkami — viz ukázka výše. Vyhledávání se spouští od minlength znaků (výchozí 3).

Angular ​

ts
// app.component.ts
options = [
  { id: 1, value: 'Praha' },
  { id: 2, value: 'Brno' },
  { id: 3, value: 'Olomouc' },
];
html
<!-- app.component.html -->
<gov-form-autocomplete
  [options]="options"
  name-key="value"
  max-options="10"
  (gov-select)="onSelect($event)">
</gov-form-autocomplete>