AutoComplete

AutoComplete 是一个输入组件，在输入时提供实时建议。

导入 # 


import AutoComplete from 'primevue/autocomplete';

基础 #

AutoComplete 与 v-model 属性一起使用以实现双向值绑定。此外，还需要 suggestions 属性和 complete 方法来查询结果。

No results found

<AutoComplete v-model="value" :suggestions="items" @complete="search" />

对象 #

AutoComplete 可以使用 optionLabel 属性与对象一起工作，该属性定义要显示为建议的标签。传递给模型的值仍然是建议的对象实例。这是一个 Country 对象的示例，它具有 name 和 code 字段，如 {name: "United States", code:"USA"}。

No results found

<AutoComplete v-model="selectedCountry" optionLabel="name" :suggestions="filteredCountries" @complete="search" />

表单 #

AutoComplete 与 PrimeVue Forms 库无缝集成。

No results found

<Form v-slot="$form" :resolver="resolver" :initialValues="initialValues" @submit="onFormSubmit" class="flex justify-center flex-col gap-4 w-full md:w-56">
    <div class="flex flex-col gap-1">
        <AutoComplete name="country.name" optionLabel="name" :suggestions="filteredCountries" @complete="search" />
        <Message v-if="$form.country?.name?.invalid" severity="error" size="small" variant="simple">{{ $form.country.name.error?.message }}</Message>
    </div>
    <Button type="submit" severity="secondary" label="Submit" />
</Form>

下拉框 #

启用 dropdown 属性会在输入字段旁边显示一个按钮，按钮的点击行为通过 dropdownMode 属性定义，该属性可以取 blank 或 current 作为可能的值。 blank 是默认模式，发送带有空字符串的查询，而 current 设置发送带有输入框当前值的查询。

No results found

<AutoComplete v-model="value" dropdown :suggestions="items" @complete="search" />

模板 #

AutoComplete 通过模板提供多个插槽用于自定义。

No results found

<AutoComplete v-model="selectedCountry" optionLabel="name" :suggestions="filteredCountries" @complete="search">
    <template #option="slotProps">
        <div class="flex items-center">
            <img :alt="slotProps.option.name" src="https://primefaces.org/cdn/primevue/images/flag/flag_placeholder.png" :class="`flag flag-${slotProps.option.code.toLowerCase()} mr-2`" style="width: 18px" />
            <div>{{ slotProps.option.name }}</div>
        </div>
    </template>
    <template #header>
        <div class="font-medium px-3 py-2">Available Countries</div>
    </template>
    <template #footer>
        <div class="px-3 py-3">
            <Button label="Add New" fluid severity="secondary" text size="small" icon="pi pi-plus" />
        </div>
    </template>
</AutoComplete>

分组 #

选项组通过 optionGroupLabel 和 optionGroupChildren 属性指定。

No results found

<AutoComplete v-model="selectedCity" :suggestions="filteredCities" @complete="search" optionLabel="label" optionGroupLabel="label" optionGroupChildren="items" placeholder="Hint: type 'a'">
    <template #optiongroup="slotProps">
        <div class="flex items-center country-item">
            <img :alt="slotProps.option.label" src="https://primefaces.org/cdn/primevue/images/flag/flag_placeholder.png" :class="`flag flag-${slotProps.option.code.toLowerCase()} mr-2`" style="width: 18px" />
            <div>{{ slotProps.option.label }}</div>
        </div>
    </template>
</AutoComplete>

强制选择 #

ForceSelection 模式验证手动输入以检查它是否也存在于建议列表中，如果不存在，则清除输入值以确保传递给模型的值始终是建议之一。只需启用 forceSelection 即可强制输入始终来自建议列表。

No results found

<AutoComplete v-model="selectedCountry" forceSelection optionLabel="name" :suggestions="filteredCountries" @complete="search" />

虚拟滚动 #

虚拟滚动是渲染大型列表的高性能方式。滚动行为的配置通过 virtualScrollerOptions 定义，需要 itemSize 作为必需值来设置项目的高度。访问 VirtualScroller 文档了解更多配置 API 信息。

No results found

<AutoComplete v-model="selectedItem" :suggestions="filteredItems" @complete="searchItems"
    :virtualScrollerOptions="{ itemSize: 38 }" optionLabel="label" dropdown />

填充 #

将 variant 属性指定为 filled 以显示比默认 outlined 样式具有更高视觉强调的组件。

No results found

<AutoComplete v-model="value" :suggestions="items" @complete="search" variant="filled" />

浮动标签 #

聚焦时，浮动标签会出现在输入字段的顶部。访问 FloatLabel 文档了解更多信息。

No results found
No results found
No results found

<FloatLabel>
    <AutoComplete v-model="value1" inputId="over_label" :suggestions="items" @complete="search" />
    <label for="over_label">Over Label</label>
</FloatLabel>

<FloatLabel variant="in">
    <AutoComplete v-model="value2" inputId="in_label" :suggestions="items" @complete="search" variant="filled" />
    <label for="in_label">In Label</label>
</FloatLabel>

<FloatLabel variant="on">
    <AutoComplete v-model="value3" inputId="on_label" :suggestions="items" @complete="search" />
    <label for="on_label">On Label</label>
</FloatLabel>

Ifta 标签 #

IftaLabel 用于创建字段内顶部对齐的标签。访问 IftaLabel 文档了解更多信息。

No results found

<IftaLabel>
    <AutoComplete v-model="value" inputId="ac" :suggestions="items" @complete="search" variant="filled" />
    <label for="ac">Identifier</label>
</IftaLabel>

尺寸 #

AutoComplete 提供 small 和 large 尺寸作为基础尺寸的替代选择。

No results found
No results found
No results found

<AutoComplete v-model="value1" :suggestions="items" @complete="search" size="small" placeholder="Small" dropdown />
<AutoComplete v-model="value2" :suggestions="items" @complete="search" placeholder="Normal" dropdown />
<AutoComplete v-model="value3" :suggestions="items" @complete="search" size="large" placeholder="Large" dropdown />

多选 #

使用 multiple 属性启用多选模式，用于从自动完成中选择多个值。在这种情况下，值引用应该是一个数组。

No results found

<label for="multiple-ac-1" class="font-bold mb-2 block">With Typeahead</label>
<AutoComplete v-model="value1" inputId="multiple-ac-1" multiple fluid :suggestions="items" @complete="search" />

<label for="multiple-ac-2" class="font-bold mt-8 mb-2 block">Without Typeahead</label>
<AutoComplete v-model="value2" inputId="multiple-ac-2" multiple fluid @complete="search" :typeahead="false" />

无效 #

使用 invalid 属性显示无效状态以指示验证失败。在与表单验证库集成时可以使用此样式。

No results found
No results found

<AutoComplete v-model="value1" :suggestions="items" @complete="search" :invalid="!value1" placeholder="Code" />
<AutoComplete v-model="value2" :suggestions="items" @complete="search" :invalid="!value2" variant="filled" placeholder="Code" />

禁用 #

当存在 disabled 时，元素无法编辑和聚焦。

No results found

<AutoComplete disabled placeholder="Disabled" />

无障碍 #

屏幕阅读器

用于描述组件的值可以通过 label 标签结合 inputId 属性提供，或者使用 aria-labelledby、aria-label 属性。输入元素除了具有 combobox 角色外，还具有 aria-autocomplete、aria-haspopup 和 aria-expanded 属性。输入框和弹出框之间的关系通过 aria-controls 创建，aria-activedescendant 属性用于指示屏幕 阅读器在弹出列表中进行键盘导航时应读取哪个选项。

在多选模式下，chip 列表使用 listbox 角色，aria-orientation 设置为水平方向，而每个 chip 具有 option 角色，aria-label 设置为 chip 的标签。

弹出列表有一个 id，它引用输入元素的 aria-controls 属性，并使用 listbox 作为角色。每个列表项都有 option 角色和一个 id，以匹配输入 元素的 aria-activedescendant。 


<label for="ac1">;Username</label>
<AutoComplete inputId="ac1" />

<span id="ac2">Email</span>
<AutoComplete aria-labelledby="ac2" />

<AutoComplete aria-label="City" />

关闭状态键盘支持

按键功能
tab将焦点移动到自动完成元素。
任何可打印字符打开弹出框并将焦点移动到第一个选项。

弹出框键盘支持

按键功能
tab将焦点移动到弹出框中的下一个可聚焦元素。如果没有，则选择可聚焦选项并关闭覆盖层，然后将焦点移动到页面中的下一个元素。
shift + tab将焦点移动到弹出框中的上一个可聚焦元素。如果没有，则选择可聚焦选项并关闭覆盖层，然后将焦点移动到页面中的下一个元素。
enter选择聚焦的选项并关闭弹出框，然后将焦点移动到自动完成元素。
space选择聚焦的选项并关闭弹出框，然后将焦点移动到自动完成元素。
escape关闭弹出框，然后将焦点移动到自动完成元素。
down arrow将焦点移动到下一个选项，如果没有则视觉焦点不变。
up arrow将焦点移动到上一个选项，如果没有则视觉焦点不变。
alt + up arrow选择聚焦的选项并关闭弹出框，然后将焦点移动到自动完成元素。
left arrow从当前选项移除视觉焦点并将输入光标向左移动一个字符。
right arrow从当前选项移除视觉焦点并将输入光标向右移动一个字符。
home将输入光标移动到末尾，如果不是则将焦点移动到第一个选项。
end将输入光标移动到开头，如果不是则将焦点移动到最后一个选项。
pageUp将视觉焦点跳转到第一个选项。
pageDown将视觉焦点跳转到最后一个选项。
shift + down arrow将焦点移动到下一个选项并切换选择状态。
shift + up arrow将焦点移动到上一个选项并切换选择状态。
shift + space选择最近选择的选项和聚焦选项之间的项目。
control + shift + home选择聚焦的选项和直到第一个选项的所有选项。
control + shift + end选择聚焦的选项和直到最后一个选项的所有选项。

Chips 输入键盘支持

按键功能
backspace如果输入字段为空，则删除上一个 chip。
left arrow如果可用且输入字段为空，则将焦点移动到上一个 chip。

Chip 键盘支持

按键功能
left arrow如果可用，将焦点移动到上一个 chip。
right arrow将焦点移动到下一个 chip，如果没有则输入字段获得焦点。
backspace删除 chip 并将焦点添加到输入字段。
Build Faster Design Better
490+ ready to use UI blocks crafted with PrimeVue and Tailwind CSS.
Learn More
Theme Designer
PrimeVue 4.3.5 on Vue 3 by PrimeTek