级联选择

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

导入#


import { CascadeSelect } from 'primereact/cascadeselect';

基础#

级联选择作为受控组件使用，具有value和onChange属性以及options集合。要定义组的标签，需要optionGroupLabel属性，并且需要optionGroupChildren来定义引用组子项的属性。请注意，optionGroupChildren 的顺序很重要，因为它应与数据层次结构相对应。

选择一个城市


<CascadeSelect value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={countries} 
    optionLabel="cname" optionGroupLabel="name" optionGroupChildren={['states', 'cities']}
    className="w-full md:w-14rem" breakpoint="767px" placeholder="Select a City" style={{ minWidth: '14rem' }}  />

加载状态#

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

正在加载...


<CascadeSelect loading placeholder="Loading..." className="w-full md:w-14rem" breakpoint="767px" style={{ minWidth: '14rem' }} />

模板#

可以使用接受选项作为参数的 itemTemplate 属性来自定义项目的内容。

选择一个城市


<CascadeSelect value={selectedCity} onChange={e => setSelectedCity(e.value)} options={countries} 
    optionLabel="cname" optionGroupLabel="name" optionGroupChildren={['states', 'cities']} 
    className="w-full md:w-14rem" breakpoint="767px" placeholder="Select a City" itemTemplate={countryOptionTemplate} style={{ minWidth: '14rem' }} />

浮动标签#

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

p-emptylabel

城市


<FloatLabel>
    <CascadeSelect inputId="cs-city" value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={countries}
        optionLabel="cname" optionGroupLabel="name" optionGroupChildren={['states', 'cities']}
        className="w-full md:w-14rem" breakpoint="767px" style={{ minWidth: '14rem' }} />
    <label htmlFor="cs-city">City</label>
</FloatLabel>

填充#

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

选择一个城市


<CascadeSelect variant="filled" value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={countries} 
    optionLabel="cname" optionGroupLabel="name" optionGroupChildren={['states', 'cities']}
    className="w-full md:w-14rem" breakpoint="767px" placeholder="Select a City" style={{ minWidth: '14rem' }}  />

无效#

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

选择一个城市


<CascadeSelect invalid value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={countries} 
    optionLabel="cname" optionGroupLabel="name" optionGroupChildren={['states', 'cities']}
    className="w-full md:w-14rem" breakpoint="767px" placeholder="Select a City" style={{ minWidth: '14rem' }} />

已禁用#

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

已禁用


<CascadeSelect disabled placeholder="Disabled" style={{ minWidth: '14rem' }} />

辅助功能#

屏幕阅读器

可以使用 aria-labelledby 或 aria-label 属性提供描述组件的值。除了 aria-haspopup 和 aria-expanded 之外，级联选择元素还具有 combobox 角色属性。使用 aria-controls 创建组合框和弹出窗口之间的关系，该属性引用弹出窗口的 id。

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

如果启用了过滤，则可以定义 filterInputProps 以向过滤输入元素提供 aria-* 属性。


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

<CascadeSelect aria-label="Options" />

关闭状态的键盘支持

键	功能
tab	将焦点移至级联选择元素。
空格键	打开弹出窗口并将视觉焦点移至选定的选项，如果没有选项，则第一个选项获得焦点。
向下箭头	打开弹出窗口并将视觉焦点移至选定的选项，如果没有选项，则第一个选项获得焦点。

弹出窗口键盘支持

键	功能
tab	隐藏弹出窗口并将焦点移至下一个可选项。
shift + tab	隐藏弹出窗口并将焦点移至上一个可选项。
回车键	选择聚焦的选项并关闭弹出窗口。
空格键	选择聚焦的选项并关闭弹出窗口。
Esc 键	关闭弹出窗口，将焦点移至级联选择元素。
向下箭头	将焦点移至下一个选项。
向上箭头	将焦点移至上一个选项。
向右箭头	如果选项已关闭，则打开该选项，否则将焦点移至第一个子选项。
向左箭头	如果选项已打开，则关闭该选项，否则将焦点移至父选项。