Vitral 0.2
Formulário

AutoComplete

Um campo que sugere enquanto você digita, com sugestões vindas da sua aplicação, um ou vários valores como chips e um botão para a lista inteira.

Importação

main.ts
import { AutoComplete } from '@vitral/vue';

Básico

Value: null
<script setup lang="ts">import { AutoComplete, FilterService, Label, StackPanel } from '@vitral/vue';import { ref } from 'vue'; interface Country {    name: string;    code: string;    region: string;} const countries: Country[] = [    { name: 'Angola', code: 'AO', region: 'Africa' },    { name: 'Argentina', code: 'AR', region: 'Americas' },    { name: 'Brazil', code: 'BR', region: 'Americas' },    { name: 'Cabo Verde', code: 'CV', region: 'Africa' },    { name: 'Canada', code: 'CA', region: 'Americas' },    { name: 'Chile', code: 'CL', region: 'Americas' },    { name: 'Colombia', code: 'CO', region: 'Americas' },    { name: 'France', code: 'FR', region: 'Europe' },    { name: 'Germany', code: 'DE', region: 'Europe' },    { name: 'Moçambique', code: 'MZ', region: 'Africa' },    { name: 'Peru', code: 'PE', region: 'Americas' },    { name: 'Portugal', code: 'PT', region: 'Europe' },    { name: 'Spain', code: 'ES', region: 'Europe' },    { name: 'São Tomé and Príncipe', code: 'ST', region: 'Africa' },    { name: 'Uruguay', code: 'UY', region: 'Americas' }]; const match = (query: string) => countries.filter((c) => FilterService.matches(c.name, query, 'contains')); const single = ref<Country | string | null>(null);const suggestions = ref<Country[]>([]);</script> <template>    <StackPanel spacing="0.375rem" style="min-width: 16rem">        <Label for="ac-country">Country</Label>        <AutoComplete            id="ac-country"            v-model="single"            :suggestions="suggestions"            option-label="name"            placeholder="Type a country"            @complete="suggestions = match($event.query)"        />        <small style="color: var(--vt-text-muted-color)">Value: {{ typeof single === 'string' ? `"${single}"` : (single?.code ?? 'null') }}</small>    </StackPanel></template>

Múltiplo

<script setup lang="ts">import { AutoComplete, FilterService, Label, StackPanel } from '@vitral/vue';import { ref } from 'vue'; interface Country {    name: string;    code: string;    region: string;} const countries: Country[] = [    { name: 'Angola', code: 'AO', region: 'Africa' },    { name: 'Argentina', code: 'AR', region: 'Americas' },    { name: 'Brazil', code: 'BR', region: 'Americas' },    { name: 'Cabo Verde', code: 'CV', region: 'Africa' },    { name: 'Canada', code: 'CA', region: 'Americas' },    { name: 'Chile', code: 'CL', region: 'Americas' },    { name: 'Colombia', code: 'CO', region: 'Americas' },    { name: 'France', code: 'FR', region: 'Europe' },    { name: 'Germany', code: 'DE', region: 'Europe' },    { name: 'Moçambique', code: 'MZ', region: 'Africa' },    { name: 'Peru', code: 'PE', region: 'Americas' },    { name: 'Portugal', code: 'PT', region: 'Europe' },    { name: 'Spain', code: 'ES', region: 'Europe' },    { name: 'São Tomé and Príncipe', code: 'ST', region: 'Africa' },    { name: 'Uruguay', code: 'UY', region: 'Americas' }]; const match = (query: string) => countries.filter((c) => FilterService.matches(c.name, query, 'contains')); const many = ref<Country[]>([]);const suggestions = ref<Country[]>([]);</script> <template>    <StackPanel spacing="0.375rem" style="min-width: 22rem">        <Label for="ac-many">Countries</Label>        <AutoComplete id="ac-many" v-model="many" :suggestions="suggestions" option-label="name" multiple fluid @complete="suggestions = match($event.query)" />    </StackPanel></template>

Grupos e templates

<script setup lang="ts">import { AutoComplete, FilterService, Label, StackPanel } from '@vitral/vue';import { ref } from 'vue'; interface Country {    name: string;    code: string;    region: string;} const countries: Country[] = [    { name: 'Angola', code: 'AO', region: 'Africa' },    { name: 'Argentina', code: 'AR', region: 'Americas' },    { name: 'Brazil', code: 'BR', region: 'Americas' },    { name: 'Cabo Verde', code: 'CV', region: 'Africa' },    { name: 'Canada', code: 'CA', region: 'Americas' },    { name: 'Chile', code: 'CL', region: 'Americas' },    { name: 'Colombia', code: 'CO', region: 'Americas' },    { name: 'France', code: 'FR', region: 'Europe' },    { name: 'Germany', code: 'DE', region: 'Europe' },    { name: 'Moçambique', code: 'MZ', region: 'Africa' },    { name: 'Peru', code: 'PE', region: 'Americas' },    { name: 'Portugal', code: 'PT', region: 'Europe' },    { name: 'Spain', code: 'ES', region: 'Europe' },    { name: 'São Tomé and Príncipe', code: 'ST', region: 'Africa' },    { name: 'Uruguay', code: 'UY', region: 'Americas' }]; const match = (query: string) => countries.filter((c) => FilterService.matches(c.name, query, 'contains')); const grouped = ref<Country | null>(null);const groupedSuggestions = ref<{ region: string; items: Country[] }[]>([]);function searchGrouped(query: string) {    const hits = match(query);    groupedSuggestions.value = ['Africa', 'Americas', 'Europe']        .map((region) => ({ region, items: hits.filter((c) => c.region === region) }))        .filter((g) => g.items.length);}</script> <template>    <StackPanel spacing="0.375rem" style="min-width: 16rem">        <Label for="ac-grouped">Country by region</Label>        <AutoComplete            id="ac-grouped"            v-model="grouped"            :suggestions="groupedSuggestions"            option-label="name"            option-group-label="region"            auto-option-focus            @complete="searchGrouped($event.query)"        >            <template #option="{ option }">                <span style="flex: 1">{{ (option as Country).name }}</span>                <small style="color: var(--vt-text-muted-color)">{{ (option as Country).code }}</small>            </template>        </AutoComplete>    </StackPanel></template>

Strings simples, tamanhos e estados

<script setup lang="ts">import { AutoComplete } from '@vitral/vue';import { ref } from 'vue'; const words = ref<string | null>(null);const wordSuggestions = ref<string[]>([]);</script> <template>    <AutoComplete        v-model="words"        :suggestions="wordSuggestions"        aria-label="Word"        size="small"        @complete="wordSuggestions = ['alpha', 'beta', 'gamma', 'delta'].filter((w) => w.includes($event.query))"    />    <AutoComplete :suggestions="[]" aria-label="Filled" variant="filled" />    <AutoComplete :suggestions="[]" aria-label="Loading" loading />    <AutoComplete :suggestions="[]" aria-label="Invalid" invalid />    <AutoComplete :suggestions="[]" aria-label="Disabled" disabled model-value="Disabled" dropdown /></template>

API

Lido de packages/vue/src/components/AutoComplete/types.ts, então diz o que o componente aceita de fato.

Props

NomeTipoDescrição
suggestionsany[]O que a lista oferece para a consulta atual; a aplicação o define em resposta a `complete`.
optionLabelstringCampo (caminho com pontos) com o texto de uma sugestão. Sem ele, as sugestões são mostradas como estão.
optionDisabledstring—
optionGroupLabelstringTransforma `suggestions` em grupos: este campo é o rótulo de cada grupo…
optionGroupChildrenstring…e este, as suas sugestões. O padrão é `items`.
dataKeystringCompara valores de objeto por este campo em vez de pela estrutura.
multiplebooleanO v-model passa a ser um array, mostrado como chips no campo.
dropdownbooleanAdiciona um botão que pede a lista inteira.
dropdownMode'blank' | 'current'O que o botão pede: todas as sugestões (`'blank'`, o padrão) ou as que combinam com o texto atual.
forceSelectionbooleanSó uma sugestão escolhida pode ficar na caixa; outro texto é apagado quando ela perde o foco.
delaynumberMilissegundos a esperar depois da digitação antes de pedir. O padrão é 300.
minLengthnumberCaracteres a digitar antes de pedir. O padrão é 1.
completeOnFocusbooleanPede assim que a caixa recebe o foco.
autoOptionFocusbooleanPõe o foco na primeira sugestão quando a lista abre, para que Enter a escolha.
showClearbooleanMostra um botão de limpar enquanto houver valor.
loadingbooleanMostra um spinner, para enquanto a aplicação busca.
showEmptyMessagebooleanAvisa quando nada combina, em vez de manter a lista fechada. O padrão é true.
emptySearchMessagestring—
sizeSize—
variantInputVariantO padrão é o `inputVariant` do plugin.
invalidboolean—
disabledboolean—
readonlyboolean—
fluidboolean—
placementOverlayPlacement—
appendTostring`'body'` (o padrão), `'self'` para renderizar no lugar, ou um seletor.

Mais pt, dt e unstyled de BaseProps; veja pass-through e modo sem estilo.

Emits

EventoPayloadDescrição
completeevent: AutoCompleteCompleteEventPede à aplicação as sugestões que combinam com `query`.
option-selectevent: AutoCompleteOptionEvent—
option-unselectevent: AutoCompleteOptionEvent—
dropdown-clickevent: AutoCompleteCompleteEvent—
clear——
show——
hide——
focusevent: FocusEvent—
blurevent: FocusEvent—

Slots

NomeProps do slotDescrição
option(props: { option: unknown; index: number; selected: boolean; focused: boolean })—
optiongroup(props: { group: unknown })—
chip(props: { value: unknown; label: string; remove: (event: Event) => void })O conteúdo de um chip no modo múltiplo.
header——
footer——
empty——
dropdownicon——