QList 和 QItem 是一组组件,它们协同工作,将多个行项目垂直排列为一个连续的整体。它们最适合以信息行的形式展示相似类型的数据,例如联系人列表、播放列表或菜单。每一行称为一个 Item(项目)。QItem 也可以在 QList 之外独立使用。
列表可以封装 Item 或类似 Item 的组件,例如 QExpansionItem 或 QSlideItem。在需要时,还可以使用 QSeparator 来分隔不同的区块。
列表项有以下预构建的子组件:
- QItemSection - 用于放置特定内容的区块。通过
avatar、thumbnail和side属性来控制显示方式。不设置任何属性时,它会渲染 QItem 的主内容区域(会占据所有可用空间)。 - QItemLabel - 用于在 QItemSection 中显示预定义类型的文本内容,也可以作为 QList 本身的标题内容。
用法
基础
QItemSection
当列表项有多行内容时,可以使用 QItemSection 的 top 属性将各区块对齐到顶部,覆盖默认的垂直居中对齐方式。
激活状态
QItemLabel
注意,您可以使用 lines 属性来处理标签文本溢出,指定它最多可以占据多少行。但是,此功能使用了 Webkit 特有的 CSS,在 IE/Edge 中无法正常工作。
更多示例
在下面的示例中,出于演示目的,我们使用 active 属性代替 QItem 的路由属性(to、exact)。UMD 模式下没有 Vue Router,因此您无法在 Codepen/jsFiddle 中使用路由功能。
对于更复杂的菜单,建议同时使用 QExpansionItem。
连接到 Vue Router
您可以通过绑定 <router-link> 的属性来将 QItem 与 Vue Router 结合使用。这样可以监听当前的应用路由,并在点击/轻触时触发路由导航。
<q-item to="/inbox" exact>
<q-item-section avatar>
<q-icon name="inbox" />
</q-item-section>
<q-item-section> Inbox </q-item-section>
</q-item>您还可以延迟、取消或重定向导航,如下所示。关于下面使用的 @click 事件的详细说明,请参阅页面顶部的 QItem API 卡片。
无障碍访问 v2.25+
QList 默认暴露 WAI-ARIA list role(当通过 tag 属性渲染为 ul/ol 时是隐式的),role 属性可覆盖该默认值。每个 QItem 的默认 role 由包裹它的 QList 决定:
| QItem | 在默认 QList 内 | 在 role="menu"/"menubar" 的 QList 内 | 在 QList 外部 / 其他 QList role |
|---|---|---|---|
带 clickable 或链接 | button / 原生链接 | menuitem | button / 原生链接 |
| 非交互式 | listitem | 无 | 无 |
这确保了生成的标记是有效的:ARIA 的 list 只能拥有 listitem 子元素(反过来 listitem 也需要一个列表父元素,所以独立的 QItem 不声明任何 role),而 menu/menubar 只能拥有 menuitem 类型的条目——只需在 QList 上声明一次 role 即可,如 QMenu 无障碍访问章节 的"基础"示例所示。QItem 上的 role 属性可为单个条目覆盖派生的 role(例如 menuitemcheckbox/menuitemradio 用于切换条目——此时管理 aria-checked 就是你的责任了)。
如果一个列表全部由交互式条目组成,那么它对 list role 没有有效的声明依据——这样的容器不拥有 listitem 子元素。请声明它的实际用途:如果它作为一组命令弹出,使用 role="menu";或使用 role="none" 来保留条目(作为按钮/链接播报)但不带列表语义。