级联选择

级联选择是一个表单组件，用于从嵌套的选项结构中选择一个值。

导入 #


import CascadeSelect from 'primevue/cascadeselect';

基本 #

级联选择与 v-model 属性一起使用，用于双向值绑定，以及 options 集合。要定义组的标签，需要 optionGroupLabel 属性，并且还需要 optionGroupChildren 来定义引用组子级的属性。请注意，optionGroupChildren 的顺序很重要，因为它应与数据层次结构相对应。

选择一个城市有 3 个结果可用


<CascadeSelect v-model="selectedCity" :options="countries" optionLabel="cname" optionGroupLabel="name"
    :optionGroupChildren="['states', 'cities']" class="w-56" placeholder="Select a City" />

表单 #

级联选择与 PrimeVue 表单库无缝集成。


<Form v-slot="$form" :resolver="resolver" :initialValues="initialValues" @submit="onFormSubmit" class="flex justify-center flex-col gap-4">
    <div class="flex flex-col gap-1">
        <CascadeSelect name="city" :options="countries" optionLabel="cname" optionGroupLabel="name" :optionGroupChildren="['states', 'cities']" class="w-56" placeholder="Select a City" />
        <Message v-if="$form.city?.invalid" severity="error" size="small" variant="simple">{{ $form.city.error?.message }}</Message>
    </div>
    <Button type="submit" severity="secondary" label="Submit" />
</Form>

模板 #

级联选择通过模板提供多个自定义槽。

选择一个城市有 3 个结果可用


<CascadeSelect v-model="selectedCity" :options="countries" optionLabel="cname" optionGroupLabel="name"
    :optionGroupChildren="['states', 'cities']" class="w-56" placeholder="Select a City">
    <template #option="slotProps">
        <div class="flex items-center">
            <img v-if="slotProps.option.states" :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"  />
            <i v-if="slotProps.option.cities" class="pi pi-compass mr-2"></i>
            <i v-if="slotProps.option.cname" class="pi pi-map-marker mr-2"></i>
            <span>{{ slotProps.option.cname || slotProps.option.name }}</span>
        </div>
    </template>
    <template #dropdownicon>
        <i class="pi pi-map" />
    </template>
    <template #header>
        <div class="font-medium px-3 py-2">Available Countries</div>
    </template>
    <template #footer>
        <div class="px-3 py-1">
            <Button label="Add New" fluid severity="secondary" text size="small" icon="pi pi-plus" />
        </div>
    </template>
</CascadeSelect>

加载状态 #

可以使用 loading 属性来设置加载状态。

加载中...未找到结果


<CascadeSelect loading placeholder="Loading..." class="w-56" />

清除图标 #

启用 showClear 后，会添加一个清除图标以重置级联选择。

选择一个城市有 3 个结果可用


<CascadeSelect v-model="selectedCity" :options="countries" optionLabel="cname" optionGroupLabel="name"
    :optionGroupChildren="['states', 'cities']" class="w-56" placeholder="Select a City" />

已填充 #

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

选择一个城市有 3 个结果可用


<CascadeSelect v-model="selectedCity" variant="filled" :options="countries" optionLabel="cname" optionGroupLabel="name"
    :optionGroupChildren="['states', 'cities']" class="w-56" placeholder="Select a City" />

浮动标签 #

当获得焦点时，浮动标签会出现在输入字段的顶部。有关更多信息，请访问浮动标签文档。

p-emptylabel有 3 个结果可用

上方标签

p-emptylabel有 3 个结果可用

内部标签

p-emptylabel有 3 个结果可用

活动标签


<FloatLabel class="w-full md:w-56">
    <CascadeSelect v-model="value1" inputId="over_label" :options="countries" optionLabel="cname" optionGroupLabel="name" :optionGroupChildren="['states', 'cities']" class="w-full" />
    <label for="over_label">Over Label</label>
</FloatLabel>

<FloatLabel class="w-full md:w-56">
    <CascadeSelect v-model="value2" inputId="in_label" :options="countries" optionLabel="cname" optionGroupLabel="name" :optionGroupChildren="['states', 'cities']" class="w-full" variant="filled" />
    <label for="in_label">In Label</label>
</FloatLabel>

<FloatLabel class="w-full md:w-56">
    <CascadeSelect v-model="value3" inputId="on_label" :options="countries" optionLabel="cname" optionGroupLabel="name" :optionGroupChildren="['states', 'cities']" class="w-full" />
    <label for="on_label">On Label</label>
</FloatLabel>

Ifta 标签 #

IftaLabel 用于创建内部顶部对齐标签。有关更多信息，请访问 IftaLabel 文档。

p-emptylabel有 3 个结果可用

城市


<IftaLabel class="w-full md:w-56">
    <CascadeSelect v-model="selectedCity" inputId="cs_city" :options="countries" optionLabel="cname" optionGroupLabel="name" :optionGroupChildren="['states', 'cities']" class="w-full" variant="filled" />
    <label for="cs_city">City</label>
</IftaLabel>

尺寸 #

级联选择提供了 small 和 large 尺寸作为基本尺寸的替代方案。

小有 3 个结果可用

正常有 3 个结果可用

大有 3 个结果可用


<CascadeSelect v-model="value1" :options="countries" optionLabel="cname" optionGroupLabel="name" :optionGroupChildren="['states', 'cities']" 
    class="w-56" size="small" placeholder="Small" />
<CascadeSelect v-model="value2" :options="countries" optionLabel="cname" optionGroupLabel="name" :optionGroupChildren="['states', 'cities']" 
    class="w-56" placeholder="Normal" />
<CascadeSelect v-model="value3" :options="countries" optionLabel="cname" optionGroupLabel="name" :optionGroupChildren="['states', 'cities']" 
    class="w-56" size="large" placeholder="Large" />

无效 #

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

选择一个城市有 3 个结果可用


<div class="card flex flex-wrap justify-center gap-4">
    <CascadeSelect v-model="selectedCity1" :invalid="!selectedCity1" :options="countries" optionLabel="cname" optionGroupLabel="name" 
        :optionGroupChildren="['states', 'cities']" class="w-full sm:w-56" placeholder="Select a City" />
    <CascadeSelect v-model="selectedCity2" :invalid="!selectedCity2" :options="countries" optionLabel="cname" optionGroupLabel="name" 
        :optionGroupChildren="['states', 'cities']" class="w-full sm:w-56" placeholder="Select a City" variant="filled" />
</div>

已禁用 #

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

已禁用未找到结果


<CascadeSelect disabled placeholder="Disabled" class="w-56" />

可访问性 #

屏幕阅读器

可以使用 aria-labelledby 或 aria-label 属性来描述组件的值。级联选择 (cascadeselect) 元素除了具有 aria-haspopup 和 aria-expanded 属性外，还具有 combobox 角色。组合框 (combobox) 和弹出窗口之间的关系通过 aria-controls 创建，它指向弹出窗口的 id。

弹出列表的 id 指向 combobox 元素的 aria-controls 属性，并使用 tree 作为角色。每个列表项都具有 treeitem 角色，以及 aria-label、aria-selected 和 aria-expanded 属性。树节点 (treenode) 的容器元素具有 group 角色。aria-setsize、aria-posinset 和 aria-level 属性是隐式计算并添加到每个 treeitem 中的。


<span id="dd1"></span>Options</span>
<CascadeSelect aria-labelledby="dd1" />

<CascadeSelect aria-label="Options" />

关闭状态下的键盘支持

按键	功能
tab	将焦点移动到级联选择元素。
空格键	打开弹出窗口并将视觉焦点移动到选定的选项；如果没有任何选定项，则第一个选项获得焦点。
回车键	打开弹出窗口并将视觉焦点移动到选定的选项；如果没有任何选定项，则第一个选项获得焦点。
向下箭头	打开弹出窗口并将视觉焦点移动到选定的选项；如果没有任何选定项，则第一个选项获得焦点。
向上箭头	打开弹出窗口并将视觉焦点移动到选定的选项；如果没有任何选定项，则最后一个选项获得焦点。
任何可打印字符	打开弹出窗口并将焦点移动到标签以键入字符开头的选项；如果没有任何匹配项，则第一个选项获得焦点。

弹出窗口的键盘支持

按键	功能
tab	隐藏弹出窗口并将焦点移动到下一个可聚焦的元素。如果没有，则选择可聚焦的选项，关闭覆盖层，然后将焦点移动到页面中的下一个元素。
shift + tab	隐藏弹出窗口并将焦点移动到上一个可聚焦的元素。
回车键	选择焦点选项并关闭弹出窗口。
空格键	选择焦点选项并关闭弹出窗口。
Esc 键	关闭弹出窗口，并将焦点移动到级联选择元素。
向下箭头	将焦点移动到下一个选项。
向上箭头	将焦点移动到上一个选项。
alt + 向上箭头	选择焦点选项并关闭弹出窗口，然后将焦点移动到级联选择元素。
向右箭头	如果选项已关闭，则打开该选项；否则将焦点移动到第一个子选项。
向左箭头	如果选项已打开，则关闭该选项；否则将焦点移动到父选项。
Home 键	将输入光标移动到末尾；如果不是，则将焦点移动到第一个选项。
End 键	将输入光标移动到开头；如果不是，则将焦点移动到最后一个选项。
任何可打印字符	将焦点移动到标签以键入字符开头的选项。

级联选择

导入 #

基本 #

表单 #

模板 #

加载状态 #

清除图标 #

已填充 #

浮动标签 #

Ifta 标签 #

尺寸 #

无效 #

已禁用 #

可访问性 #

屏幕阅读器

关闭状态下的键盘支持

弹出窗口的键盘支持

CascadeSelect API