astryx-vue

选择器

@astryxdesign/core v0.7.1 · Selector

使用方法 ​

Selector 是一个下拉选择器组件，用户点击后展开选项列表，选择一项后收起。它支持搜索过滤、清除选择、禁用选项等功能。

基本用法只需要传入选项数组和绑定值：

vue
<script setup lang="ts">
import { Selector } from '@astryx-vue/core/Selector'
import { ref } from 'vue'

const selected = ref(null)
const options = [
  { value: 'apple', label: '苹果' },
  { value: 'banana', label: '香蕉' },
  { value: 'cherry', label: '樱桃' },
]
</script>

<template>
  <Selector v-model="selected" :options="options" placeholder="选择水果" />
</template>

每个选项对象包含 value（唯一标识）和 label（显示文本）。可选的 disabled 属性可以禁用特定选项，description 可以添加辅助说明。

开启 searchable 属性后，选择器会显示搜索框，用户可以输入文字过滤选项。开启 hasClear 后，已选中的值旁边会出现清除按钮；clearable 是旧名字。

只读时当前值还在，可以聚焦，也会随表单提交，但打不开列表，也没有清除和展开箭头，外观不会变暗。同时禁用时按禁用处理。加载时触发器里是旋转指示，列表在选项到达之前不说「没有结果」。没有任何选项，和搜索之后没有命中，是两句不同的话。选中标记默认画在行尾，也可以改到行首；没选中时标记不占位。disabledMessage 用来解释为什么禁用：悬停和键盘聚焦时弹出提示，触发器靠 aria-disabled 保持可聚焦，但列表仍然打不开。

方向键上下移动高亮项，Home 和 End 跳到首尾，Enter 选中当前项，Escape 关闭列表。搜索框打开后，方向键和回车作用在搜索框上，空格仍用于输入。

菜单至少和触发器一样宽，选项更长时会跟着变宽。组件自带文案默认是英文，调用 provideAstryxLocale('zh-CN') 后改为中文。文档页会按当前语言自动提供。

解剖

部分说明
字段提供标签和可选辅助内容的独立 Field 外壳。放在 InputGroup 里时不画这一层。
触发器着色控件，显示当前选择或占位。可编辑时打开选择表面。
图标渲染的起始图标可选的前导语义图标或图标组件，通过 Icon 绘制。
使用方渲染的起始内容直接画在触发器开头的可选任意插槽内容。
触发器清除按钮共用的清除操作。clearable 打开时去掉已选值。
状态图标状态以附着或提示方式呈现时，用来代替展开指示的状态符号。
指示图标状态呈现没有把它换掉时显示的尾部箭头，反映收起或展开。
搜索行面板头部，带无边框搜索框和可选的清除操作。
搜索图标搜索行里通过 Icon 画出的前导放大镜。
搜索清除按钮已经有查询词时，搜索行里的共用清除操作。
选项行一个选项所在的可选择行。
默认选项内容没有提供 option 插槽时，从选项数据画出的标签、说明和图标。
选项插槽内容通过 option 插槽提供的内容，用来代替默认的标签和说明。
选项选中指示每个选项在已选或未选状态下画出的选中标记。解析后的指示什么都不画时，它占的布局空间会收起来。
选项分隔线公开选项数据里用来分开相邻选项组的分隔线。
分区标题一组带标签的选项行的可见标题。
空状态共用面板里没有选项，或搜索没有匹配时的消息。
指针弹层浮层呈现方式里，承载共用面板内容的锚定着色表面。
触摸面板标题底部面板呈现方式里，共用面板内容上方的标题。
触摸面板底部面板呈现方式里，承载同一套面板内容的 BottomSheet 表面。

最佳实践 ​

指引实践
推荐选项数量超过 10 项时开启搜索功能，帮助用户快速定位。
推荐为非必填字段提供清除按钮，让用户可以取消选择。
推荐使用简洁清晰的选项标签，避免过长的文本。
避免在选择器中放置超过 100 项选项，考虑分页或异步加载。
避免使用选择器做多选，应使用专门的多选组件。

示例 ​

底部弹层

Team

在底部弹层里展示单选列表，适合紧凑的触控界面。

可清除

清除按钮可以把已选的值重置掉。

幽灵工具栏

This setting affects all users

无边框的选择器和幽灵按钮一起放在工具栏里。

次要样式

次要样式和次要按钮同一套静止外观：没有边框，铺一层中性底。

选项操作

选项可以带一个操作。点操作不会改当前选择。只要有一项带了操作，列表就变成两列。

分组

选项按带标题的分组排列。

选项说明

Default trigger: one line at the size token.
A stacked value: the description gets its own line, and the trigger grows by exactly one line.

选项带说明时，菜单画成两行。单行的值保持控件高度，两行的值正好高出一行。放进输入组后，值仍保持一行。

校验状态

Please select a role
Viewer has limited access

错误、警告和成功三种校验状态。

只读、禁用、加载和搜索

只读
Only the owner of this list can change it

只读保留当前值，加载时不声称没有选项。必填标在标签旁。禁用的字段在悬停或键盘聚焦时用气泡说明原因，并且仍可聚焦。搜索没有命中时用另一句文案，选中标记可以画在行首。