多选器
@astryxdesign/core v0.7.1 · MultiSelector
使用方法
MultiSelector 从固定列表里选多项。触发器在没有搜索框时是 combobox，列表是 aria-multiselectable 的 listbox。选中一项不会关闭列表。
选项可以是字符串、带说明的对象、分隔线，或带标题的分组。selectAll 在列表顶部加一行全选，禁用项不会被全选带上。searchable 会在列表里显示搜索框，只过滤当前列表，不请求远程数据。
triggerDisplay 决定关闭后怎么展示已选项：count 显示「已选 N 项」，labels 拼接文字，badges 用标签。maxBadges 限制露出的个数，放不下时末尾显示 +N。宽度更窄时还会再收一次。
只读时已选值还在，可以聚焦并提交，但打不开列表，也没有清除和展开箭头，外观不会变暗。加载时触发器显示旋转指示，这时不提供创建行，也不说没有选项。disabledMessage 用来解释为什么禁用：悬停和键盘聚焦时弹出提示，触发器靠 aria-disabled 保持可聚焦，菜单仍然打不开。
关闭后的文字可以用函数改写，只对数量和标签两种展示生效，标签模式会忽略它。没有任何选中项时不调用，继续显示占位符。
和搜索一起打开创建后，输入的文字和任何选项标签都不相同（忽略大小写）时，列表第一行是创建。选中后，变更事件会多带一段描述，里面是创建和当时的文字。调用方要在同一次更新里把这个选项加进列表。没有搜索时不会出现创建行。
从外面开关列表时，在脚本里把句柄对象本身传进去。模板会把 ref 自动拆开，所以模板里要传一个接收句柄的函数。只读和禁用时，打开不会生效。
方向键移动高亮项，Enter 和空格切换选中。搜索框里的空格仍用于输入。没有高亮项时，Enter 会创建当前文字。Escape 关闭列表。关闭且没有在搜索时，Backspace 清空已选项。
解剖
| 部分 | 说明 |
|---|---|
| 字段 | 提供标签和可选辅助内容的独立 Field 外壳。放在 InputGroup 里时不画这一层。 |
| 触发器 | 着色控件，显示当前选择或占位。可编辑时打开选择表面。 |
| 图标渲染的起始图标 | 可选的前导语义图标或图标组件，通过 Icon 绘制。 |
| 使用方渲染的起始内容 | 直接画在触发器开头的可选任意插槽内容。 |
| 触发器清除按钮 | 共用的清除操作。clearable 打开时，一次去掉所有已选值。 |
| 状态图标 | 状态以附着或提示方式呈现时，用来代替展开指示的状态符号。 |
| 指示图标 | 状态呈现没有把它换掉时显示的尾部箭头，反映收起或展开。 |
| 搜索行 | 面板头部，带无边框搜索框和可选的清除操作。 |
| 搜索图标 | 搜索行里通过 Icon 画出的前导放大镜。 |
| 搜索清除按钮 | 已经有查询词时，搜索行里的共用清除操作。 |
| 选项行 | 一个选项，或可选的全选，所在的可选择行。 |
| 选项复选指示 | CheckboxInput 指示，呈现每一行的已选、未选或不确定。 |
| 选项分隔线 | 公开选项数据里用来分开相邻选项组的分隔线。 |
| 分区标题 | 一组带标签的选项行的可见标题。 |
| 空状态 | 共用面板里没有选项，或搜索没有匹配时的消息。 |
| 指针弹层 | 浮层呈现方式里，承载共用面板内容的锚定着色表面。 |
| 触摸面板标题 | 底部面板呈现方式里，共用面板内容上方的标题。 |
| 触摸面板 | 底部面板呈现方式里，承载同一套面板内容的 BottomSheet 表面。 |
最佳实践
| 指引 | 实践 |
|---|---|
| 推荐 | 选项不多、用户需要对照着勾选时用多选器。 |
| 推荐 | 已选项要在触发器里认出来时，用 badges 并加上 +N。 |
| 避免 | 用多选器搜索远程数据。那种场景用标签输入框。 |
示例
底部弹层
在底部弹层里勾选，列表保持打开。
列可见性
隐藏标签，可搜索、可全选，触发器显示已选数量。
表单组合
表单里两个多选器，分别标成必填和可选，另有一个禁用的在悬停或键盘聚焦时说明原因。
幽灵工具栏
无边框变体，和幽灵按钮排在同一条工具栏里。
可搜索
可搜索，并带全选。
分组权限
选项按标题分成几组。
创建和只读
输入现有列表里没有的名字可以创建。关闭后的文字可以改成自己的句子。只读保留已选值。