Quasar QChip 组件完全指南基础用法、交互状态与无障碍实践【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasarQChip 是 Quasar 框架中一个轻量的 UI 区块组件用于以紧凑的方式表达底层更复杂的数据实体例如联系人、标签、筛选条件。本文以 chip.md 文档为骨架结合 QChip.js、QChip.json、QChip.sass 源码与 QChip 示例集 逐个示例完整讲解 QChip 的用法、全部配置项、交互状态机以及 v2.25 的可访问性实现读完你可以在实际项目中自如地构建标签、筛选条件、联系人卡等交互型 Chip。QChip 是什么QChip 本质上是一个简单的 UI 区块实体用来以紧凑的形式代表某种更复杂的底层数据——例如一个联系人。Chip 内部可以承载多种内容实体头像QAvatar、文本或图标可选地带一个指针指向性图标如果配置了removable它还可以被关闭或移除。它经常与以下组件搭配使用QAvatar作为 Chip 的前置头像QIcon作为 Chip 的左侧/右侧/移除/选中图标QBadge当需要一个更强调数量或状态的徽标时使用Chip 与 Badge 视觉相似但语义不同Chip 代表数据实体Badge 代表状态提示。基础用法图标、label 与头像QChip 的内容有三种注入方式默认插槽slots.default、label属性、以及icon/icon-right属性。其中label会覆盖默认插槽见 QChip.json 中label的描述Chips content as string; overrides default slot if specified。参考官方示例 Basic.vue最基础的使用方式如下q-chip iconeventAdd to calendar/q-chip q-chip iconbookmarkBookmark/q-chip q-chip iconalarm labelSet alarm / q-chip classglossy icondirectionsGet directions/q-chip加上颜色与文本颜色后Chip 会呈现出 Quasar 典型的彩色胶囊外观q-chip colorprimary text-colorwhite iconevent Add to calendar /q-chip q-chip colorteal text-colorwhite iconbookmark Bookmark /q-chip q-chip classglossy colororange text-colorwhite icon-rightstar Star /q-chip也可以把 QAvatar 放进默认插槽组成头像 文本的信息实体q-chip q-avatar iconbookmark colorred text-colorwhite / Bookmark /q-chip q-chip q-avatar colorred text-colorwhite50/q-avatar Emails /q-chip q-chip q-avatar img altUser avatar srchttps://cdn.quasar.dev/img/avatar5.jpg / /q-avatar John /q-chip基础样式与配色原理从 QChip.sass 可以看到默认视觉参数border-radius: 16px、height: $chip-height、默认灰底background: #e0e0e0、文字色rgba(0,0,0,.87)内边距padding: .5em .9emChip 之间默认margin: 4px。传入color时会追加bg-{color}类text-color则追加text-{color}类同时加上q-chip--colored修饰类使内部图标继承文本颜色见 QChip.js 的 class 计算逻辑。密度与尺寸dense 与 sizeDense 紧凑模式dense属性让 Chip 以更紧凑的尺寸渲染适合空间受限的工具栏、筛选栏等场景。官方示例 Dense.vue 展示了 dense 与头像、图标的组合q-chip dense iconeventAdd to calendar/q-chip q-chip dense colorprimary text-colorwhite iconevent Add to calendar /q-chip q-chip dense q-avatar colorred text-colorwhite50/q-avatar Emails /q-chip样式上dense 模式将border-radius降为12px、内边距收窄为0 .4em、高度切换为$chip-dense-height头像与图标的字体也相应缩小见 QChip.sass。自定义尺寸 sizesize属性接受两种取值命名尺寸xs、sm、md、lg、xl任意 CSS 单位如25px、2rem、18px。官方示例 Sizes.vue 演示了两者的混用q-chip size18px iconbookmark Bookmark /q-chip q-chip sizexs iconbookmark Bookmark /q-chip q-chip sizesm iconbookmark Bookmark /q-chip q-chip sizemd iconbookmark Bookmark /q-chip q-chip sizelg iconbookmark Bookmark /q-chip q-chip sizexl iconbookmark Bookmark /q-chip q-chip dense sizexs iconbookmark Bookmark /q-chip !-- ... --命名尺寸的换算由源码中的defaultSizes表定义QChip.jsexport const defaultSizes { xs: 8, sm: 10, md: 14, lg: 20, xl: 24 }即sizemd等价于字号基准 14pxxl为 24px。传入 CSS 单位时会原样写入内联样式data.style getSizeStyle(props.size)因此size2rem这类写法完全可用。dense 与 size 可以叠加使用。形状与风格square 与 outlineSquare 直角样式默认 Chip 是圆角胶囊16pxsquare属性将其改为接近直角的低圆角。示例 Square.vue 中可与颜色、glossy、头像任意组合q-chip square iconeventAdd to calendar/q-chip q-chip classglossy square colorteal text-colorwhite iconbookmark Bookmark /q-chip q-chip square colororange text-colorwhite icon-rightstar Star /q-chip源码中square会把border-radius改为$generic-border-radius通用圆角变量头像则使用($generic-border-radius - 1px)以贴合边框QChip.sass。Outline 描边风格outline属性让 Chip 采用透明底 描边的设计颜色来自color或text-color。示例 Outline.vueq-chip outline colorprimary text-colorwhite iconevent Add to calendar /q-chip q-chip outline colororange text-colorwhite icon-rightstar Star /q-chip q-chip outline square colorred text-colorwhite iconalarm labelSet alarm /outline 可以与square叠加。样式上outline 强制背景透明并绘制1px solid currentColor边框由于多出了 1px 边框头像的负边距会被微调以保持对齐QChip.sass。交互状态点击、选中与移除Clickable可点击 Chipv2.29 行为自 v2.29 起QChip 的可点击判断变得更加智能只要挂载了click监听器Chip 默认就是可点击的——会自动获得 hover 效果、键盘激活能力与click事件无需显式设置clickable属性。何时需要显式clickable当 Chip 上没有点击监听器却仍需要点击效果时或需要用一个布尔值动态切换点击行为时。注意显式的clickablefalse优先级高于监听器——即使挂了click只要clickablefalse就不会进入可点击状态。示例 Clickable.vueq-chip clickonClick colorprimary text-colorwhite iconevent Add to calendar /q-chip q-chip clickonClick iconbookmark Bookmark /q-chip !-- ... -- script setup function onClick() { console.log(Clicked on a QChip) } /script源码中可点击性的判定集中在isActionable计算属性QChip.jsconst isActionable computed( () (props.clickable null ? props.onClick ! void 0 : props.clickable) || props.selected ! null )即clickable未设置null时以是否存在onClickprop由click监听器注入为准设置了则以显式值为准另外只要selected模式被启用Chip 一定可点击。clickable之所以在源码中被声明为 prop 而非 emits正是为了让监听器是否存在这一信息可被组件内部观察到见 QChip.js 的注释。最终isClickable !disable isActionable可点击时才会挂载onClick/键盘事件并追加q-chip--clickable cursor-pointer non-selectable q-hoverable类QChip.js。Ripple 水波纹默认开启ripple默认true禁用状态下自动关闭QChip.js。Selected选中态模型selected是 QChip 的开关型状态模型通过v-model:selected双向绑定。当传入selected时Chip 自动变为可点击并展示左侧选中图标默认来自图标集的chip.selectedMaterial 图标集下为勾选符号此外.q-chip--selected样式会隐藏头像见 QChip.sass。示例 Selected.vue 用一组甜品选择器演示了多选效果q-chip v-model:selecteddesert.Icecream colorprimary text-colorwhite iconcake Ice cream /q-chip q-chip v-model:selecteddesert.Eclair colorteal text-colorwhite iconcake Eclair /q-chip script setup import { computed, reactive } from vue const desert reactive({ Icecream: false, Eclair: true, Cupcake: false, Gingerbread: false }) const selection computed(() Object.keys(desert) .filter(type desert[type]) .join(, ) ) /script选中态触发时会同时发出update:selected与click两个事件见 QChip.js 的onClick实现。selected的默认值是null表示未启用选中模式selected为false也是合法值表示处于未选中的开关状态。Removable可移除 Chipremovable属性在 Chip 右侧渲染一个移除图标默认来自图标集的chip.removeMaterial 图标集下为cancel。点击移除图标会发出remove事件并把modelValue置为false从而将整个 Chip 从 DOM 中移除——modelValue在此处扮演是否渲染的角色而不是是否选中。示例 Removable.vueq-chip removable v-modelicecream removelog(Icecream) colorprimary text-colorwhite iconcake Ice cream /q-chip q-chip disable removable v-modelgingerbread removelog(Icecream) colorred text-colorwhite iconcake Gingerbread (disable) /q-chip script setup import { ref } from vue const icecream ref(true) // ... function onResetClick() { icecream.value true // ... } /script注意示例中最后一只 Chip 同时使用了disable禁用状态下移除图标不可操作但v-model仍然控制其渲染与否。源码中onRemove处理了键盘与鼠标两种触发路径QChip.jsfunction onRemove(e) { if (e.keyCode void 0 || [13, 32].includes(e.keyCode)) { stopAndPrevent(e) if (!props.disable) { emit(update:modelValue, false) emit(remove) } } }移除图标本身是独立的可聚焦控件带有rolebutton、aria-hiddenfalse与可访问名称禁用时tabindex-1并被标注aria-disabledQChip.js。可点击、选中、可移除的状态关系速览场景需要的属性/事件触发后行为纯动作点击后跳转/执行click或显式clickable发出click开关选择多选/单选标签v-model:selected切换选中态发出update:selected与click删除标签removablev-modelremove移除图标点击后发出update:modelValue(false)与removeChip 消失禁止交互disable无 click/选中/移除退出 Tab 键序长文本截断Long label truncation当 Chip 承载很长的文本时可以配合 CSS 的ellipsis类进行单行省略并用q-tooltip或原生title属性展示完整内容。官方示例 LongLabel.vue 给出了三种典型做法!-- 方式一label title 属性 -- q-chip removable v-modelvanilla colorprimary text-colorwhite iconcake :labelvanillaLabel :titlevanillaLabel / !-- 方式二默认插槽 q-tooltip -- q-chip removable v-modelchocolate colorteal text-colorwhite iconcake :labelchocolateLabel q-tooltip{{ chocolateLabel }}/q-tooltip /q-chip !-- 方式三ellipsis 包裹 q-tooltip含头像时推荐 -- q-chip removable v-modelstrawberry colororange text-colorwhite iconcake div classellipsis {{ strawberryLabel }} q-tooltip{{ strawberryLabel }}/q-tooltip /div /q-chip其中通过label属性传入文本时QChip 内部会自动为文本包上一层ellipsis类见 QChip.js无需手动处理通过默认插槽自定义内容时需要自行在外层元素上添加ellipsis类外层容器需要约束宽度示例中通过 scoped 样式max-width: 140px限制.q-chip的最大宽度才能触发截断ellipsis是 Quasar 全局工具类效果为overflow: hidden; text-overflow: ellipsis; white-space: nowrap与 Chip 内容区white-space: nowrap的默认样式QChip.sass配合实现单行省略。可访问性v2.25QChip 的可访问性语义在 v2.25 起被明确定义涵盖可点击 Chip、选中 Chip 与移除图标三个层面可点击 Chip 的语义当 Chip 通过clickableprop、click监听器或selected模型进入可点击状态时它以rolebutton暴露给辅助技术并支持Enter或Space键激活。源码中键盘处理在onKeyup中完成QChip.js同时onKeydown会拦截空格键防止页面滚动。aria-pressed 只属于开关型 Chip只有由selected模型驱动的 Chip 才会额外暴露aria-pressed值为true/false纯动作型actionChip 不会声明按下/未按下这种切换语义避免误导屏幕阅读器。源码中的实现是条件展开aria-pressedQChip.js。禁用态禁用 Chip 保持rolebutton仍可被感知并通过aria-disabledtrue宣告为置灰但tabindex-1使其退出 Tab 键序。移除图标removableChip 的移除图标是独立的、可键盘操作的控件其可访问名称来自 Quasar 语言包中的本地化 Remove 文本见 ui/lang 目录下的语言包文件例如 zh-CN.js 中label.remove的本地化文案。由于通用名称移除无法表达移除的是什么建议为每个 Chip 通过remove-aria-label提供上下文信息例如remove-aria-labelRemove tag: Vue使屏幕阅读器用户明确知道操作对象。q-chip removable remove-aria-labelRemove tag: Vue v-modeltagVisible Vue /q-chipremove-aria-label是 QChip.json 中定义的 accessibility 类属性传入后会直接作为移除图标的aria-label替代语言包中的默认 Remove 文案QChip.js。API 速查Props、Slots 与 Events以下内容依据 QChip.json 整理可在实际项目中快速查阅。Props属性类型默认值说明denseBooleanfalse紧凑模式sizeStringmd由defaultSizes决定命名尺寸xs/sm/md/lg/xl或 CSS 单位如25px、2remdarkBooleanfalse深色模式iconString—左侧图标未选中时显示icon-rightString—右侧图标icon-removeString图标集chip.remove自定义移除图标icon-selectedString图标集chip.selected选中态时替换左侧图标labelString | Number—Chip 文本内容设置后覆盖默认插槽colorString—背景颜色Quasar 调色板色名text-colorString—文本颜色outline 模式下兼作描边色model-valueBooleantrue控制 Chip 是否渲染false时整体移除selectedBoolean | nullnull选中态模型配合v-model:selected非null时强制可点击squareBooleanfalse低圆角近直角outlineBooleanfalse透明底 1px 描边clickableBoolean | nullnull显式控制可点击null时按是否存在click或selected自动推断显式false优先级最高removableBooleanfalse显示移除图标rippleBoolean | Objecttrue水波纹效果配置remove-aria-labelString语言包label.remove移除图标的无障碍名称tabindexString | Number0可点击时的 Tab 键序disableBooleanfalse禁用保留角色语义但退出 Tab 键序Slots插槽说明defaultChip 内容区未使用label属性时生效可放置 QAvatar、文本、QTooltip 等Events事件参数说明clickevt可点击 Chip 被点击鼠标或键盘时发出update:model-valuevalue: Boolean渲染状态变化配合v-modelupdate:selectedstate: Boolean选中状态变化配合v-model:selectedremovestate: Boolean点击移除图标、Chip 被移除时发出小结QChip 虽是一个小巧的组件却覆盖了数据实体展示这一高频场景的全部能力头像/图标/文本的任意组合icon、icon-right、label、默认插槽、QAvatar、细腻的视觉变体dense、size、square、outline、color、三种互不冲突的交互模型click动作型、v-model:selected开关型、removablev-model删除型以及从 v2.25 起完整对齐 WAI-ARIA 按钮语义的无障碍实现。在具体使用中建议牢记三点label会覆盖插槽、clickablefalse优先于监听器、selected一旦使用即宣告切换语义。你可以在 QChip 示例目录 中查看全部 9 个可运行示例并结合 QChip.test.js 与 QChip.hydration.test.js 了解框架层面的行为验证。【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Quasar QChip 组件完全指南：基础用法、交互状态与无障碍实践
Quasar QChip 组件完全指南基础用法、交互状态与无障碍实践【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasarQChip 是 Quasar 框架中一个轻量的 UI 区块组件用于以紧凑的方式表达底层更复杂的数据实体例如联系人、标签、筛选条件。本文以 chip.md 文档为骨架结合 QChip.js、QChip.json、QChip.sass 源码与 QChip 示例集 逐个示例完整讲解 QChip 的用法、全部配置项、交互状态机以及 v2.25 的可访问性实现读完你可以在实际项目中自如地构建标签、筛选条件、联系人卡等交互型 Chip。QChip 是什么QChip 本质上是一个简单的 UI 区块实体用来以紧凑的形式代表某种更复杂的底层数据——例如一个联系人。Chip 内部可以承载多种内容实体头像QAvatar、文本或图标可选地带一个指针指向性图标如果配置了removable它还可以被关闭或移除。它经常与以下组件搭配使用QAvatar作为 Chip 的前置头像QIcon作为 Chip 的左侧/右侧/移除/选中图标QBadge当需要一个更强调数量或状态的徽标时使用Chip 与 Badge 视觉相似但语义不同Chip 代表数据实体Badge 代表状态提示。基础用法图标、label 与头像QChip 的内容有三种注入方式默认插槽slots.default、label属性、以及icon/icon-right属性。其中label会覆盖默认插槽见 QChip.json 中label的描述Chips content as string; overrides default slot if specified。参考官方示例 Basic.vue最基础的使用方式如下q-chip iconeventAdd to calendar/q-chip q-chip iconbookmarkBookmark/q-chip q-chip iconalarm labelSet alarm / q-chip classglossy icondirectionsGet directions/q-chip加上颜色与文本颜色后Chip 会呈现出 Quasar 典型的彩色胶囊外观q-chip colorprimary text-colorwhite iconevent Add to calendar /q-chip q-chip colorteal text-colorwhite iconbookmark Bookmark /q-chip q-chip classglossy colororange text-colorwhite icon-rightstar Star /q-chip也可以把 QAvatar 放进默认插槽组成头像 文本的信息实体q-chip q-avatar iconbookmark colorred text-colorwhite / Bookmark /q-chip q-chip q-avatar colorred text-colorwhite50/q-avatar Emails /q-chip q-chip q-avatar img altUser avatar srchttps://cdn.quasar.dev/img/avatar5.jpg / /q-avatar John /q-chip基础样式与配色原理从 QChip.sass 可以看到默认视觉参数border-radius: 16px、height: $chip-height、默认灰底background: #e0e0e0、文字色rgba(0,0,0,.87)内边距padding: .5em .9emChip 之间默认margin: 4px。传入color时会追加bg-{color}类text-color则追加text-{color}类同时加上q-chip--colored修饰类使内部图标继承文本颜色见 QChip.js 的 class 计算逻辑。密度与尺寸dense 与 sizeDense 紧凑模式dense属性让 Chip 以更紧凑的尺寸渲染适合空间受限的工具栏、筛选栏等场景。官方示例 Dense.vue 展示了 dense 与头像、图标的组合q-chip dense iconeventAdd to calendar/q-chip q-chip dense colorprimary text-colorwhite iconevent Add to calendar /q-chip q-chip dense q-avatar colorred text-colorwhite50/q-avatar Emails /q-chip样式上dense 模式将border-radius降为12px、内边距收窄为0 .4em、高度切换为$chip-dense-height头像与图标的字体也相应缩小见 QChip.sass。自定义尺寸 sizesize属性接受两种取值命名尺寸xs、sm、md、lg、xl任意 CSS 单位如25px、2rem、18px。官方示例 Sizes.vue 演示了两者的混用q-chip size18px iconbookmark Bookmark /q-chip q-chip sizexs iconbookmark Bookmark /q-chip q-chip sizesm iconbookmark Bookmark /q-chip q-chip sizemd iconbookmark Bookmark /q-chip q-chip sizelg iconbookmark Bookmark /q-chip q-chip sizexl iconbookmark Bookmark /q-chip q-chip dense sizexs iconbookmark Bookmark /q-chip !-- ... --命名尺寸的换算由源码中的defaultSizes表定义QChip.jsexport const defaultSizes { xs: 8, sm: 10, md: 14, lg: 20, xl: 24 }即sizemd等价于字号基准 14pxxl为 24px。传入 CSS 单位时会原样写入内联样式data.style getSizeStyle(props.size)因此size2rem这类写法完全可用。dense 与 size 可以叠加使用。形状与风格square 与 outlineSquare 直角样式默认 Chip 是圆角胶囊16pxsquare属性将其改为接近直角的低圆角。示例 Square.vue 中可与颜色、glossy、头像任意组合q-chip square iconeventAdd to calendar/q-chip q-chip classglossy square colorteal text-colorwhite iconbookmark Bookmark /q-chip q-chip square colororange text-colorwhite icon-rightstar Star /q-chip源码中square会把border-radius改为$generic-border-radius通用圆角变量头像则使用($generic-border-radius - 1px)以贴合边框QChip.sass。Outline 描边风格outline属性让 Chip 采用透明底 描边的设计颜色来自color或text-color。示例 Outline.vueq-chip outline colorprimary text-colorwhite iconevent Add to calendar /q-chip q-chip outline colororange text-colorwhite icon-rightstar Star /q-chip q-chip outline square colorred text-colorwhite iconalarm labelSet alarm /outline 可以与square叠加。样式上outline 强制背景透明并绘制1px solid currentColor边框由于多出了 1px 边框头像的负边距会被微调以保持对齐QChip.sass。交互状态点击、选中与移除Clickable可点击 Chipv2.29 行为自 v2.29 起QChip 的可点击判断变得更加智能只要挂载了click监听器Chip 默认就是可点击的——会自动获得 hover 效果、键盘激活能力与click事件无需显式设置clickable属性。何时需要显式clickable当 Chip 上没有点击监听器却仍需要点击效果时或需要用一个布尔值动态切换点击行为时。注意显式的clickablefalse优先级高于监听器——即使挂了click只要clickablefalse就不会进入可点击状态。示例 Clickable.vueq-chip clickonClick colorprimary text-colorwhite iconevent Add to calendar /q-chip q-chip clickonClick iconbookmark Bookmark /q-chip !-- ... -- script setup function onClick() { console.log(Clicked on a QChip) } /script源码中可点击性的判定集中在isActionable计算属性QChip.jsconst isActionable computed( () (props.clickable null ? props.onClick ! void 0 : props.clickable) || props.selected ! null )即clickable未设置null时以是否存在onClickprop由click监听器注入为准设置了则以显式值为准另外只要selected模式被启用Chip 一定可点击。clickable之所以在源码中被声明为 prop 而非 emits正是为了让监听器是否存在这一信息可被组件内部观察到见 QChip.js 的注释。最终isClickable !disable isActionable可点击时才会挂载onClick/键盘事件并追加q-chip--clickable cursor-pointer non-selectable q-hoverable类QChip.js。Ripple 水波纹默认开启ripple默认true禁用状态下自动关闭QChip.js。Selected选中态模型selected是 QChip 的开关型状态模型通过v-model:selected双向绑定。当传入selected时Chip 自动变为可点击并展示左侧选中图标默认来自图标集的chip.selectedMaterial 图标集下为勾选符号此外.q-chip--selected样式会隐藏头像见 QChip.sass。示例 Selected.vue 用一组甜品选择器演示了多选效果q-chip v-model:selecteddesert.Icecream colorprimary text-colorwhite iconcake Ice cream /q-chip q-chip v-model:selecteddesert.Eclair colorteal text-colorwhite iconcake Eclair /q-chip script setup import { computed, reactive } from vue const desert reactive({ Icecream: false, Eclair: true, Cupcake: false, Gingerbread: false }) const selection computed(() Object.keys(desert) .filter(type desert[type]) .join(, ) ) /script选中态触发时会同时发出update:selected与click两个事件见 QChip.js 的onClick实现。selected的默认值是null表示未启用选中模式selected为false也是合法值表示处于未选中的开关状态。Removable可移除 Chipremovable属性在 Chip 右侧渲染一个移除图标默认来自图标集的chip.removeMaterial 图标集下为cancel。点击移除图标会发出remove事件并把modelValue置为false从而将整个 Chip 从 DOM 中移除——modelValue在此处扮演是否渲染的角色而不是是否选中。示例 Removable.vueq-chip removable v-modelicecream removelog(Icecream) colorprimary text-colorwhite iconcake Ice cream /q-chip q-chip disable removable v-modelgingerbread removelog(Icecream) colorred text-colorwhite iconcake Gingerbread (disable) /q-chip script setup import { ref } from vue const icecream ref(true) // ... function onResetClick() { icecream.value true // ... } /script注意示例中最后一只 Chip 同时使用了disable禁用状态下移除图标不可操作但v-model仍然控制其渲染与否。源码中onRemove处理了键盘与鼠标两种触发路径QChip.jsfunction onRemove(e) { if (e.keyCode void 0 || [13, 32].includes(e.keyCode)) { stopAndPrevent(e) if (!props.disable) { emit(update:modelValue, false) emit(remove) } } }移除图标本身是独立的可聚焦控件带有rolebutton、aria-hiddenfalse与可访问名称禁用时tabindex-1并被标注aria-disabledQChip.js。可点击、选中、可移除的状态关系速览场景需要的属性/事件触发后行为纯动作点击后跳转/执行click或显式clickable发出click开关选择多选/单选标签v-model:selected切换选中态发出update:selected与click删除标签removablev-modelremove移除图标点击后发出update:modelValue(false)与removeChip 消失禁止交互disable无 click/选中/移除退出 Tab 键序长文本截断Long label truncation当 Chip 承载很长的文本时可以配合 CSS 的ellipsis类进行单行省略并用q-tooltip或原生title属性展示完整内容。官方示例 LongLabel.vue 给出了三种典型做法!-- 方式一label title 属性 -- q-chip removable v-modelvanilla colorprimary text-colorwhite iconcake :labelvanillaLabel :titlevanillaLabel / !-- 方式二默认插槽 q-tooltip -- q-chip removable v-modelchocolate colorteal text-colorwhite iconcake :labelchocolateLabel q-tooltip{{ chocolateLabel }}/q-tooltip /q-chip !-- 方式三ellipsis 包裹 q-tooltip含头像时推荐 -- q-chip removable v-modelstrawberry colororange text-colorwhite iconcake div classellipsis {{ strawberryLabel }} q-tooltip{{ strawberryLabel }}/q-tooltip /div /q-chip其中通过label属性传入文本时QChip 内部会自动为文本包上一层ellipsis类见 QChip.js无需手动处理通过默认插槽自定义内容时需要自行在外层元素上添加ellipsis类外层容器需要约束宽度示例中通过 scoped 样式max-width: 140px限制.q-chip的最大宽度才能触发截断ellipsis是 Quasar 全局工具类效果为overflow: hidden; text-overflow: ellipsis; white-space: nowrap与 Chip 内容区white-space: nowrap的默认样式QChip.sass配合实现单行省略。可访问性v2.25QChip 的可访问性语义在 v2.25 起被明确定义涵盖可点击 Chip、选中 Chip 与移除图标三个层面可点击 Chip 的语义当 Chip 通过clickableprop、click监听器或selected模型进入可点击状态时它以rolebutton暴露给辅助技术并支持Enter或Space键激活。源码中键盘处理在onKeyup中完成QChip.js同时onKeydown会拦截空格键防止页面滚动。aria-pressed 只属于开关型 Chip只有由selected模型驱动的 Chip 才会额外暴露aria-pressed值为true/false纯动作型actionChip 不会声明按下/未按下这种切换语义避免误导屏幕阅读器。源码中的实现是条件展开aria-pressedQChip.js。禁用态禁用 Chip 保持rolebutton仍可被感知并通过aria-disabledtrue宣告为置灰但tabindex-1使其退出 Tab 键序。移除图标removableChip 的移除图标是独立的、可键盘操作的控件其可访问名称来自 Quasar 语言包中的本地化 Remove 文本见 ui/lang 目录下的语言包文件例如 zh-CN.js 中label.remove的本地化文案。由于通用名称移除无法表达移除的是什么建议为每个 Chip 通过remove-aria-label提供上下文信息例如remove-aria-labelRemove tag: Vue使屏幕阅读器用户明确知道操作对象。q-chip removable remove-aria-labelRemove tag: Vue v-modeltagVisible Vue /q-chipremove-aria-label是 QChip.json 中定义的 accessibility 类属性传入后会直接作为移除图标的aria-label替代语言包中的默认 Remove 文案QChip.js。API 速查Props、Slots 与 Events以下内容依据 QChip.json 整理可在实际项目中快速查阅。Props属性类型默认值说明denseBooleanfalse紧凑模式sizeStringmd由defaultSizes决定命名尺寸xs/sm/md/lg/xl或 CSS 单位如25px、2remdarkBooleanfalse深色模式iconString—左侧图标未选中时显示icon-rightString—右侧图标icon-removeString图标集chip.remove自定义移除图标icon-selectedString图标集chip.selected选中态时替换左侧图标labelString | Number—Chip 文本内容设置后覆盖默认插槽colorString—背景颜色Quasar 调色板色名text-colorString—文本颜色outline 模式下兼作描边色model-valueBooleantrue控制 Chip 是否渲染false时整体移除selectedBoolean | nullnull选中态模型配合v-model:selected非null时强制可点击squareBooleanfalse低圆角近直角outlineBooleanfalse透明底 1px 描边clickableBoolean | nullnull显式控制可点击null时按是否存在click或selected自动推断显式false优先级最高removableBooleanfalse显示移除图标rippleBoolean | Objecttrue水波纹效果配置remove-aria-labelString语言包label.remove移除图标的无障碍名称tabindexString | Number0可点击时的 Tab 键序disableBooleanfalse禁用保留角色语义但退出 Tab 键序Slots插槽说明defaultChip 内容区未使用label属性时生效可放置 QAvatar、文本、QTooltip 等Events事件参数说明clickevt可点击 Chip 被点击鼠标或键盘时发出update:model-valuevalue: Boolean渲染状态变化配合v-modelupdate:selectedstate: Boolean选中状态变化配合v-model:selectedremovestate: Boolean点击移除图标、Chip 被移除时发出小结QChip 虽是一个小巧的组件却覆盖了数据实体展示这一高频场景的全部能力头像/图标/文本的任意组合icon、icon-right、label、默认插槽、QAvatar、细腻的视觉变体dense、size、square、outline、color、三种互不冲突的交互模型click动作型、v-model:selected开关型、removablev-model删除型以及从 v2.25 起完整对齐 WAI-ARIA 按钮语义的无障碍实现。在具体使用中建议牢记三点label会覆盖插槽、clickablefalse优先于监听器、selected一旦使用即宣告切换语义。你可以在 QChip 示例目录 中查看全部 9 个可运行示例并结合 QChip.test.js 与 QChip.hydration.test.js 了解框架层面的行为验证。【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考