FilterChips 筛选胶囊
带圆点与计数的单选筛选条
用法
基础
items 为每个 chip 提供 label、dot 与 count。
Loading demo...
与表格组合
筛选条只表达选中项;宿主过滤行数据,计数与表格共用同一份数据。
Loading demo...
最佳实践
- 计数用
computed从行数据推导,不写死字面量。 - 过滤放在宿主:被筛掉的行从数据中移除,不要用 CSS 隐藏——隐藏的行仍在无障碍树与 Tab 序列里。
- 列表筛选保持默认的
role="toolbar";只有存在成组的互斥面板时才用tablist。 - chip 多于两三个时给每个配
iconClass;只有图标本身可辨认时才开iconOnly。 - 只有宿主动效会整体重排 chip 时才关
indicator;减少动态效果由系统设置处理。
API 参考
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue | string | number | - | 当前选中的 chip。 |
items | FilterChipItem[] | [] | chip 列表。 |
disabled | boolean | false | 禁用整条筛选条。 |
role | 'toolbar' | 'tablist' | 'toolbar' | 决定 chip 按开关还是标签页呈现。 |
indicator | boolean | true | 选中底色作为一个滑块在 chip 间平移;关闭后逐 chip 上色。 |
iconOnly | boolean | false | 只画 iconClass,label 转为 aria-label 与 title;无图标的 chip 仍显示文字。 |
ariaLabel | string | 'Filters' | 筛选条的可访问名称。 |
事件
| 事件名 | 参数 | 说明 |
|---|---|---|
update:modelValue | (value) | 选中变化。 |
change | (value) | 与 update:modelValue 同时触发。 |
插槽
| 名称 | 说明 |
|---|---|
chip | 替换 chip 内部内容;接收 { item, active },按钮外壳与键盘行为保留。 |
FilterChipItem
| 字段 | 类型 | 说明 |
|---|---|---|
value | string | number | chip 唯一标识。 |
label | string | chip 文案。 |
iconClass | string | 前置图标 class,画在圆点与文案之前。 |
dot | string | 前置圆点颜色。 |
count | number | 尾部计数徽标,应从数据推导。 |
disabled | boolean | 单独禁用该 chip。 |
概述
- 整条只占一个 Tab 停靠点:焦点落在选中的 chip(无选中时为第一个可用 chip);方向键绕回并跳过禁用项,
Home/End直达首尾。 toolbar下 chip 是aria-pressed开关,移动焦点不改变筛选。tablist下 chip 为role="tab"加aria-selected,选中跟随焦点;宿主需渲染对应的role="tabpanel"。- 点击已选中的 chip 不触发事件。
- 首帧、chip 列表重建、尺寸变化及减少动态效果时,滑块直接落位;无选中项时不绘制。
技术实现
- 滑块是滚动行的绝对定位子元素,按 chip 的
offsetLeft/offsetTop定位,因此随 chip 一起滚动。 - 源码:
packages/tuffex/packages/components/src/filter-chips/。 - 移植自 Beautiful UI(© 2026 Shane Levine,MIT);上游只有
aria-pressed,此处补上键盘导航与tablist语义。
查看源码
packages/tuffex/packages/components/src/filter-chips/index.ts