组件/FilterChips 筛选胶囊

FilterChips 筛选胶囊

带圆点与计数的单选筛选条

Verified自 0.3.9

用法

基础

items 为每个 chip 提供 label、dot 与 count。

Loading demo...

与表格组合

筛选条只表达选中项;宿主过滤行数据,计数与表格共用同一份数据。

Loading demo...

最佳实践

  • 计数用 computed 从行数据推导,不写死字面量。
  • 过滤放在宿主:被筛掉的行从数据中移除,不要用 CSS 隐藏——隐藏的行仍在无障碍树与 Tab 序列里。
  • 列表筛选保持默认的 role="toolbar";只有存在成组的互斥面板时才用 tablist。
  • chip 多于两三个时给每个配 iconClass;只有图标本身可辨认时才开 iconOnly。
  • 只有宿主动效会整体重排 chip 时才关 indicator;减少动态效果由系统设置处理。

API 参考

属性

属性名类型默认值说明
modelValuestring | number-当前选中的 chip。
itemsFilterChipItem[][]chip 列表。
disabledbooleanfalse禁用整条筛选条。
role'toolbar' | 'tablist''toolbar'决定 chip 按开关还是标签页呈现。
indicatorbooleantrue选中底色作为一个滑块在 chip 间平移;关闭后逐 chip 上色。
iconOnlybooleanfalse只画 iconClass,label 转为 aria-label 与 title;无图标的 chip 仍显示文字。
ariaLabelstring'Filters'筛选条的可访问名称。

事件

事件名参数说明
update:modelValue(value)选中变化。
change(value)与 update:modelValue 同时触发。

插槽

名称说明
chip替换 chip 内部内容;接收 { item, active },按钮外壳与键盘行为保留。

FilterChipItem

字段类型说明
valuestring | numberchip 唯一标识。
labelstringchip 文案。
iconClassstring前置图标 class,画在圆点与文案之前。
dotstring前置圆点颜色。
countnumber尾部计数徽标,应从数据推导。
disabledboolean单独禁用该 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