组件
组合框 Combobox
Combobox:组合框。输入框沿用控件样式,匹配列表淡入展开为纸质浮层,选中行使用墨色平铺填充。部件:Root、Label、Control、Input、Trigger、ClearTrigger、Positioner、Content、List、Empty、Item、ItemText、ItemIndicator、ItemGroup、ItemGroupLabel。
#基础用法
<script setup lang="ts">
import { useListCollection } from "@ark-ui/vue/combobox";
import { useFilter } from "@ark-ui/vue/locale";
import { check, chevron_down, x } from "@bysages/icons";
import { Combobox, Icon } from "@bysages/vue";
const filters = useFilter({ sensitivity: "base" });
const { collection, filter } = useListCollection({
initialItems: [
{ label: "Apple", value: "apple" },
{ label: "Banana", value: "banana" },
{ label: "Cherry", value: "cherry" },
{ label: "Date", value: "date" },
{ label: "Elderberry", value: "elderberry" },
{ label: "Fig", value: "fig" },
],
filter: (item: string, inputValue: string) => filters.value.contains(item, inputValue),
});
</script>
<template>
<Combobox.Root :collection="collection" @input-value-change="(e) => filter(e.inputValue)">
<Combobox.Label>Fruit</Combobox.Label>
<Combobox.Control>
<Combobox.Input placeholder="e.g. Apple" />
<Combobox.ClearTrigger>
<Icon :glyph="x" />
</Combobox.ClearTrigger>
<Combobox.Trigger>
<Icon :glyph="chevron_down" />
</Combobox.Trigger>
</Combobox.Control>
<Teleport to="body">
<Combobox.Positioner>
<Combobox.Content>
<Combobox.Empty>No results found</Combobox.Empty>
<Combobox.Item v-for="item in collection.items" :key="item.value" :item="item">
<Combobox.ItemText>{{ item.label }}</Combobox.ItemText>
<Combobox.ItemIndicator>
<Icon :glyph="check" />
</Combobox.ItemIndicator>
</Combobox.Item>
</Combobox.Content>
</Combobox.Positioner>
</Teleport>
</Combobox.Root>
</template>
#属性
#ClearTrigger
纯造型的部件——自身没有属性,沿用部件结构的共享样式。
#Content
纯造型的部件——自身没有属性,沿用部件结构的共享样式。
#Control
纯造型的部件——自身没有属性,沿用部件结构的共享样式。
#Empty
纯造型的部件——自身没有属性,沿用部件结构的共享样式。
#Input
纯造型的部件——自身没有属性,沿用部件结构的共享样式。
#ItemContext
纯造型的部件——自身没有属性,沿用部件结构的共享样式。
#ItemGroupLabel
纯造型的部件——自身没有属性,沿用部件结构的共享样式。
#ItemGroup
纯造型的部件——自身没有属性,沿用部件结构的共享样式。
#ItemIndicator
纯造型的部件——自身没有属性,沿用部件结构的共享样式。
#ItemText
纯造型的部件——自身没有属性,沿用部件结构的共享样式。
#Item
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
item | CollectionItem | 要渲染的条目 | |
persistFocus | boolean | undefined | 悬停移出后是否清除高亮 |
#Label
纯造型的部件——自身没有属性,沿用部件结构的共享样式。
#List
纯造型的部件——自身没有属性,沿用部件结构的共享样式。
#Positioner
纯造型的部件——自身没有属性,沿用部件结构的共享样式。
#Root
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
size | String as PropType<"sm" | "md" | "lg"> | "md" | 字段行高度,可为 sm、md 或 lg |
allowCustomValue | boolean | 是否允许在输入框中输入自定义值 | |
alwaysSubmitOnEnter | boolean | 是否跳过默认两步行为(先按 Enter 关闭组合框,再按 Enter 提交表单),让 Enter 直接提交表单;适合单字段自动补全表单 | |
autoFocus | boolean | 挂载时是否自动聚焦输入框 | |
closeOnSelect | boolean | 选中条目后是否关闭组合框 | |
collection | ListCollection<T> | 条目集合 | |
composite | boolean | true | 组合框是否与标签页等复合组件组合使用 |
defaultHighlightedValue | string | 组合框初始高亮值;无需控制高亮值时使用 | |
defaultInputValue | string | "" | 组合框输入框初始值;无需控制输入值时使用 |
defaultOpen | boolean | 组合框初始是否展开;无需控制展开状态时使用 | |
defaultValue | string[] | [] | 组合框已选项初始值;无需控制已选值时使用 |
disabled | boolean | 组合框是否禁用 | |
disableLayer | boolean | 是否禁止把该组件注册为可关闭层 | |
form | string | 组合框关联的表单 | |
highlightedValue | string | 组合框的受控高亮值 | |
id | string | 组件内部状态机的唯一标识 | |
ids | Partial<{ root: string; label: string; control: string; input: string; content: string; trigger: string; clearTrigger: string; item(id: string, index?: number): string; positioner: string; itemGroup(id: string | number): string; itemGroupLabel(id: string | number): string; }> | 组合框内各元素的 id;便于组合使用 | |
inputBehavior | 'autohighlight' | 'autocomplete' | 'none' | "none" | 组合框的自动补全行为:autohighlight 表示输入时高亮第一个获得焦点的条目;autocomplete 表示用方向键在列表框中导航时选中条目并更新输入框 |
inputValue | string | 组合框输入框的受控值 | |
invalid | boolean | 组合框是否无效 | |
loopFocus | boolean | true | 键盘导航是否在条目间循环 |
modelValue | string[] | 组合框的 v-model 值 | |
multiple | boolean | 是否允许多选;multiple 为 true 时,selectionBehavior 会自动设为 clear,建议把已选项放在单独容器中渲染 | |
name | string | 组合框输入框的 name 属性,用于表单提交 | |
navigate | (details: combobox.NavigateDetails) => void | 用于导航到已选项的函数 | |
open | boolean | 组合框的受控展开状态 | |
openOnChange | boolean | ((details: combobox.InputValueChangeDetails) => boolean) | true | 输入值变化时是否显示组合框弹层 |
openOnClick | boolean | false | 首次点击输入框时是否打开组合框弹层 |
openOnKeyPress | boolean | true | 按下方向键时是否打开组合框弹层 |
placeholder | string | 组合框输入框的占位文本 | |
positioning | combobox.PositioningOptions | { placement: "bottom-start" } | 组合框弹层的动态定位选项 |
readOnly | boolean | 组合框是否只读;只读时输入框不可编辑,但仍可交互 | |
required | boolean | 组合框是否必填 | |
scrollToIndexFn | (details: combobox.ScrollToIndexDetails) => void | 滚动到指定索引的函数 | |
selectionBehavior | 'clear' | 'replace' | 'preserve' | "replace" | 选中条目后输入框的处理方式:replace 表示把选中项文本设为输入值;clear 表示清空输入值;preserve 表示保留输入值 |
translations | combobox.IntlTranslations | 无障碍元素及其状态的本地化文案 |
#Trigger
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
focusable | boolean | undefined | 触发器是否可聚焦 |