前端UI组件跨平台【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址https://gitcode.com/gh_mirrors/qu/quasar点击查看免费下载QList 与 QItem 是 Quasar Framework 中一组协同工作的列表组件用于将多条数据以单行single line item的形式垂直排列成一个连续的整体是构建联系人列表、播放列表、菜单、设置页等场景的基础组件。本文以 list-and-list-items.md 官方文档为主体骨架结合 QList.js、QItem.js 等源码实现系统讲解四个组件QList、QItem、QItemSection、QItemLabel的完整用法、属性细节、路由集成与无障碍Accessibility语义帮助你写出结构清晰、可访问、可维护的列表界面。组件家族概览QList 与 QItem 的官方文档位于 docs/src/pages/vue-components/list-and-list-items.md文档中定义的组件关键字为QList、QItem、QItemSection、QItemLabel它们共同构成了 Quasar 的列表体系组件作用源码位置QList列表容器垂直排列多个 ItemQList.jsQItem列表中的每一行Item也可脱离 QList 单独使用QItem.jsQItemSectionItem 内部的区块用于放置头像、缩略图、侧边内容等QItemSection.jsQItemLabelItem 内部的文本标签支持 overline/caption/header 等文本样式QItemLabel.js每个组件的 API 定义props、slots、events可在对应 JSON 中查看QList.json、QItem.json、QItemSection.json、QItemLabel.json。组合关系与使用场景QList 与 QItem 最适合展示相似数据类型的成行信息例如联系人列表每行一个联系人包含头像、姓名、邮箱播放列表每行一首歌曲包含序号、歌名、时长菜单每行一个菜单项带图标与文字设置页每行一个设置项含标题与说明文字。QItem 也可以脱离 QList 单独使用。而 QList 不仅能封装 QItem还可以封装Item 类的组件例如 QExpansionItem展开项、QSlideItem滑动项需要分段时可以用 QSeparator 将列表拆分为多个区块。内置子组件每个 Item 都内置了以下预构建子组件QItemSection一个区块可以有多种用途通过avatar、thumbnail、side三个 prop 控制。不带任何 prop 时它渲染为 QItem 的主体区块main section自动占满可用空间。QItemLabel在 QItemSection 内部提供预定义样式的文本内容也可以用作 QList 自身的类标题header内容。QList 列表容器QList 是列表的容器组件负责整体布局与视觉样式。其 props 定义在 QList.jsprops: { ...useDarkProps, // 含 dark 布尔 prop bordered: Boolean, // 是否显示边框 dense: Boolean, // 紧凑模式 separator: Boolean, // 在条目之间显示分隔线 padding: Boolean, // 上下应用 Material Design 风格的留白 role: String, // 覆盖默认 ARIA role tag: { type: String, default: div } // 渲染的 HTML 标签 }常用属性说明bordered为列表添加边框视觉上更突出常用于卡片式布局dense紧凑模式减小行高与间距适合数据密度高的场景separator在相邻条目之间绘制分隔线效果等同于在每个 QItem 之间插入分隔元素padding在列表上下应用类似 Material Design 的留白适合独立成块的菜单/卡片dark深色模式适配继承自useDarkPropstag指定渲染的 HTML 标签默认为div也可设为ul/ol以使用原生列表语义见下文无障碍章节role覆盖默认的listARIA rolev2.25详见无障碍章节。从源码可以看到QList 的 class 会按 prop 组合生成q-list (props.bordered ? q-list--bordered : ) (props.dense ? q-list--dense : ) (props.separator ? q-list--separator : ) (isDark() ? q-list--dark : ) (props.padding ? q-list--padding : )这些视觉样式在 QList.sass 中定义。QList 默认渲染为div无多余嵌套slot 内容直接落入容器。QItem 列表行QItem 是列表中的每一行是最核心的交互单元。其 props 定义在 QItem.js包含active、clickable、dense、insetLevel、tabindex、focused、manualFocus、tag、role以及路由相关 propsto、exact、replace等来自useRouterLinkProps。关键属性解析clickable是否可点击。true时添加悬停效果并触发click事件不设置默认null时只要绑定了click监听器QItem 就自动可点击v2.29clickablefalse显式禁用。从源码可以看出判定逻辑QItem.jsconst isActionable computed( () (props.clickable null ? props.onClick ! void 0 // 有 click 监听器则视为可点击 : props.clickable) || hasLink.value || // 绑定了路由链接 props.tag label // label 标签 )[!TIP] QItem 绑定click监听器即可点击v2.29自动获得悬停效果、键盘激活能力以及click事件无需显式clickableprop。仅在没有监听器例如仅有一个v-close-popup指令入口或需要通过布尔值切换行为时才显式设置clickable显式的clickablefalse优先于监听器。active是否处于激活状态。true时添加q-item--activeclass 与可选的自定义激活样式类与路由链接结合时可配合active-class定制激活样式见下方菜单示例。dense紧凑模式减小内边距。inset-level缩进级别Number。当条目缺少左侧头像/侧边时可用它让内容与其他带左侧的条目对齐也常用于构建菜单。源码中缩进计算为16 insetLevel * 56像素QItem.js并会根据 RTL 语言方向自动切换 padding 方向。tabindex可聚焦元素的 tab 顺序可点击条目默认tabindex0。manual-focus/focused手动管理焦点状态。开启manual-focus后由focusedprop 决定是否聚焦而非依赖原生 hover/focus 状态适用于自定义键盘导航场景。tag渲染的 HTML 标签默认为div。官方建议当用 QItem 包裹 QCheckbox/QRadio/QToggle 时使用label标签这样用户点击整行即可触发组件模型变更设为a则渲染为原生链接。disable继承自通用 prop禁用条目非交互状态下渲染aria-disabledtrue。键盘交互与焦点管理源码中实现了完整的键盘可达性可点击条目绑定onKeyup与onKeydown当按下 Enter键码 13或 Space键码 32时会构造一个MouseEvent(click)派发到根元素以触发点击并为水波纹效果标记qKeyEventQItem.js。Space 键在按下时会阻止默认滚动行为避免页面误滚动。此外还会在条目前插入一个q-focus-helper元素用于键盘焦点指示QItem.js样式定义在 QItem.sass 中。[!NOTE] 这些键盘行为由组件源码保证无需开发者额外编写。相关行为在 QItem.test.js 与 QItem.hydration.test.js 中有对应测试覆盖。QItemSection 区块QItemSection 负责把 Item 的内容划分为多个区块其 props 定义在 QItemSection.jsprops: { avatar: Boolean, // 头像侧区块 thumbnail: Boolean, // 缩略图侧区块 side: Boolean, // 侧边区块 top: Boolean, // 顶部对齐 noWrap: Boolean // 不换行 }三种预置区块主区块main不带任何 prop默认渲染占满可用空间是 Item 的主体内容区avatar头像设置avatar后渲染为头像侧区块通常放置 QAvatar 或小图标不需要额外设置sidethumbnail缩略图设置thumbnail后渲染为缩略图侧区块通常放置大一点的图片同样不需要设置sideside侧边渲染为 Item 的侧边区块通常放置图标、开关、操作按钮等次要内容通常靠右显示。源码中区块类型的 class 生成逻辑如下QItemSection.jsq-item__section column q-item__section--${props.avatar || props.side || props.thumbnail ? side : main} (props.top ? q-item__section--top justify-start : justify-center) (props.avatar ? q-item__section--avatar : ) (props.thumbnail ? q-item__section--thumbnail : ) (props.noWrap ? q-item__section--nowrap : )从代码可见avatar/thumbnail/side任一为真即渲染为 side 类区块默认垂直居中justify-centertop则改为顶部对齐justify-start。[!TIP] 当条目是多行文本时可以在 side/avatar 区块上使用top属性将其与首行对齐覆盖默认的垂直居中对齐视觉更协调。no-wrap不换行适合主内容过长但希望单行显示的场景。QItemLabel 文本标签QItemLabel 提供预定义样式的文本内容其 props 定义在 QItemLabel.jsprops: { overline: Boolean, // 上划线样式的标题小号大写字母 caption: Boolean, // 说明文字样式次要文本 header: Boolean, // 列表头部标题样式 lines: [Number, String] // 最多显示的行数超出省略 }四种文本样式overline渲染上划线标签text-overline样式适合作为条目内的分组小标题例如日期、分类caption渲染说明文字text-caption样式适合作为主标题下的次要描述如邮箱地址、歌曲时长header渲染列表头部标签典型用法是作为 QList 内部的分区标题例如联系人列表中的 Offline 分区默认无任何样式 prop常规正文文本适合作为条目主标题。lines 属性与文本溢出控制lines用于控制标签最多占用的行数超出部分自动省略。源码中的实现QItemLabel.jslines1时添加ellipsisclass使用标准的单行省略lines1时通过display: -webkit-box配合-webkit-line-clamp实现多行截断省略lines未设置时不做任何处理。[!WARNING] 多行省略lines 1依赖 Webkit 专有的-webkit-line-clampCSS 特性在 IE/Edge 旧版本中无法工作。若需兼容这些浏览器请使用lines1或自行实现截断逻辑。组合示例一个典型的两行条目主标题 说明文字q-item clickable v-ripple q-item-section q-item-labelItem with caption/q-item-label q-item-label captionCaption/q-item-label /q-item-section /q-item基础用法实战最基础的列表以下是最简单的列表写法对应文档 Basic 示例完整代码见 Basic.vuediv classq-pa-md stylemax-width: 350px q-list bordered separator q-item clickable v-ripple q-item-sectionSingle line item/q-item-section /q-item q-item clickable v-ripple q-item-section q-item-labelItem with caption/q-item-label q-item-label captionCaption/q-item-label /q-item-section /q-item q-item clickable v-ripple q-item-section q-item-label overlineOVERLINE/q-item-label q-item-labelItem with overline/q-item-label /q-item-section /q-item /q-list /div要点bordered separator同时启用边框与条目分隔线clickable v-ripple让条目可点击并带水波纹反馈条目内可自由组合多个 QItemLabel 实现标题 说明结构。强制深色模式Dark设置 QList 的dark属性即可强制列表以深色模式渲染对应文档 Force dark mode 示例见 Dark.vue。该属性来自useDarkProps与 Quasar 全局的深色模式联动适合在亮色页面中嵌入深色列表块。紧凑模式DenseQList 与 QItem 都支持dense属性启用后行高与内边距收紧适合需要高密度展示的场景对应文档 Dense 示例见 Dense.vue。QItemSection 进阶布局左侧头像 / 缩略图头部区块放置头像的写法对应文档 Left avatar/thumbnail QItemSection 示例见 AvatarLeft.vueq-item clickable v-ripple q-item-section avatar q-avatar colorprimary text-colorwhite R /q-avatar /q-item-section q-item-section q-item-labelContacts/q-item-label q-item-label caption5 min ago/q-item-label /q-item-section /q-itemavatar区块配合 QAvatar 使用若使用更大的图片则改用thumbnail区块。两者的区别仅在于视觉尺寸与圆角处理见 QItem.sass。右侧头像 / 缩略图将带avatar/thumbnail的 QItemSection 放在后面即渲染在右侧对应文档 Right avatar/thumbnail QItemSection 示例见 AvatarRight.vue。这类布局常见于消息通知等场景主文本在左头像在右。侧边区块Sideside区块通常承载图标、开关、角标等次要内容对应文档 Side QItemSection 示例见 SideSection.vueq-item-section side q-icon namechat_bubble colorgreen / /q-item-section激活状态与菜单样式active属性让条目进入激活视觉状态常与菜单高亮联动对应文档 Active prop 示例见 ActiveState.vue。可结合active-class自定义激活样式。一个完整的菜单示例对应文档 Menu 示例完整代码见 ExampleMenu.vueq-list bordered padding classrounded-borders text-primary q-item v-ripple :activelink inbox clicklink inbox active-classmy-menu-link q-item-section avatar q-icon nameinbox / /q-item-section q-item-sectionInbox/q-item-section /q-item !-- 更多菜单项outbox / trash / settings / help ... -- q-separator spaced / /q-listimport { ref } from vue const link ref(inbox).my-menu-link color: white background: #F2C037要点用:activelink xxx根据当前选中项动态切换激活态active-class指定激活时的自定义样式类q-separator spaced在分组之间插入带间距的分隔线官方提示示例中用active代替路由 propsto、exact是因为 UMD 构建不包含 Vue Router无法在 Codepen/jsFiddle 中演示路由跳转更复杂的菜单建议同时参考 QExpansionItem子菜单展开。更多实战示例文档还提供了四类贴近真实业务的完整示例全部位于 docs/src/examples/QItem 目录示例文件核心技巧联系人列表Contact listExampleContacts.vueavatar头像 side图标 q-item-label header分区标题 lines1单行省略设置页SettingsExampleSettings.vueside区块放置 QToggle/QSelect 等表单控件taglabel整行可点邮件列表EmailsExampleEmails.vue多行文本 top顶部对齐 复杂侧边操作文件夹列表Folder listingExampleFolders.vuethumbnail缩略图 inset-level缩进对齐以联系人列表为例ExampleContacts.vue它展示了头像、双行文本、侧边图标与分区标题的完整组合q-list bordered q-item v-forcontact in contacts :keycontact.id clickable v-ripple q-item-section avatar q-avatar colorprimary text-colorwhite {{ contact.letter }} /q-avatar /q-item-section q-item-section q-item-label{{ contact.name }}/q-item-label q-item-label caption lines1{{ contact.email }}/q-item-label /q-item-section q-item-section side q-icon namechat_bubble colorgreen / /q-item-section /q-item q-separator / q-item-label headerOffline/q-item-label !-- 离线联系人列表头像使用 img 加载真实图片 -- /q-list与 Vue Router 集成QItem 可以直接绑定 Vue Router 的router-link相关属性to、exact等实现监听当前路由 点击跳转的能力。文档给出的最小示例q-item to/inbox exact q-item-section avatar q-icon nameinbox / /q-item-section q-item-section Inbox /q-item-section /q-itemto目标路由路径或路由对象QItem 底层通过useRouterLink组合式函数use-router-link.js渲染为router-linkexact路由精确匹配时激活带路由链接的 QItem 自动成为可点击项源码中hasLink.value直接参与isActionable判定。延迟、取消或重定向导航文档示例 LinksWithGo.vue只读展示no-edit演示了如何通过click事件延迟、取消或重定向导航q-item clickable v-ripple clickgoTo(/inbox) q-item-section avatar q-icon nameinbox / /q-item-section q-item-sectionInbox/q-item-section /q-item在事件处理器中你可以取消return false或调用event.preventDefault()阻止默认导航延迟先执行异步逻辑如鉴权、埋点完成后再调用路由跳转重定向根据业务条件改为跳转到其他路由。关于click事件触发时机与可取消性的完整说明请参考本文开头的 QItem API 定义QItem.json 中click事件扩展自navigation-click。无障碍Accessibility语义v2.25QList 在无障碍方面做了精细的语义设计文档 Accessibility 章节v2.25 引入。QList 的默认 role默认tagdiv时QList 显式暴露 WAI-ARIAlistrole当tagul或tagol时利用原生列表的隐式语义不再重复声明role源码 QList.js 中的roleAttrExceptions数组通过roleprop 可覆盖默认行为。QItem 的派生 role每个 QItem 的默认 role 由其所在的 QList 推导而来源码通过provide/inject的listKey传递列表语义见 QList.js 与 QItem.jsQItem 状态默认 QList 内rolemenu/menubar的 QList 内QList 外 / 其他 role 的 QList 内可点击clickable、有click监听器或链接button/ 原生链接menuitembutton/ 原生链接非交互listitem无无这套推导规则保证了产出的 DOM 语义合法ARIA 规范要求list只能包含listitem子元素而listitem又必须有 list 父级因此脱离 QList 独立使用的 QItem 不声明任何 rolemenu/menubar只能包含menuitem类条目——只需在 QList 上声明一次rolemenu其中的可点击条目自动获得menuitemrole正如 QMenu 的无障碍章节 中 Basic 示例的做法QItem 的roleprop 可针对单个条目覆盖派生 role例如开关型菜单项可设为menuitemcheckbox/menuitemradio此时aria-checked状态需自行管理。交互项列表的 role 选择[!WARNING] 如果列表全部由交互项组成没有listitem子元素则该容器没有资格声明listrole。此时应如实声明其真实语义若它作为命令列表弹出使用rolemenu若希望保留条目的按钮/链接语义而不带列表语义使用rolenone。从源码实现看QItem.jsQItem 在roleprop 未设置时依次判断显式 role → menu/menubar 上下文中的可交互项menuitem→ 原生链接不设 role利用a隐式语义→ 可点击项button→ 默认 QList 内的非交互项listitem→ 其他情况不声明。这套逻辑使列表在屏幕阅读器中呈现正确的语义树是 Quasar 组件无障碍设计的重要体现。测试与验证Quasar 仓库为列表组件提供了完善的测试覆盖可作为你理解组件行为的参考QList.test.js验证 QList 的渲染、class 生成与 role 推导QItem.test.js验证 QItem 的可点击性、键盘交互、role 派生QItem.hydration.test.js 与 QItem.hydration.fixtures.js验证 SSR 水合场景下的行为一致性。总结QList、QItem、QItemSection、QItemLabel 四个组件构成了 Quasar 的完整列表体系QList负责容器与整体样式边框、分隔、留白、深色、denseQItem负责行单元与交互点击、激活、路由、键盘焦点、禁用QItemSection负责区块划分主区、头像、缩略图、侧边、对齐方式QItemLabel负责文本样式与溢出控制overline/caption/header/lines。在实战中请记住几个关键点click监听器使 QItem 自动可点击v2.29多行内容用top对齐侧边区块文本溢出用lines控制行数注意 Webkit 兼容性与路由集成直接用to/exact无障碍场景按本文的 role 推导规则声明语义。结合 docs/src/examples/QItem 下的真实示例与 ui/src/components/item 下的源码你可以快速搭建出结构清晰、体验完整、可访问性良好的列表界面。赞分享前端UI组件跨平台【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址https://gitcode.com/gh_mirrors/qu/quasar点击查看免费下载相关推荐Quasar 的 QToolbar 与 QToolbarTitle 组件完全指南从基础用法到无障碍实践Quasar 的 QToolbar 与 QToolbarTitle 组件完全指南从基础用法到无障碍实践 QToolbar 是 Quasar Framework前端UI组件跨平台reka-ui Dialog 组件完全指南从基础用法到无障碍与自定义 APIreka ui Dialog 组件完全指南从基础用法到无障碍与自定义 API 本文基于 radix vue 仓库即 reka ui 的前身的 Dialog前端UI组件设计系统Quasar QDate 组件完全指南从基础用法到波斯日历、无障碍与表单集成的实战手册Quasar QDate 组件完全指南从基础用法到波斯日历、无障碍与表单集成的实战手册 导读 本文以 Quasar Framework 官方文档 QDate前端UI组件跨平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考