Skip to page content

展开项

QExpansionItem 组件用于隐藏那些不需要立即展示给用户的内容。你可以把它理解为一个点击即可展开的手风琴元素,也常被称为折叠面板。

它们本质上是 QItem 组件的增强封装,因此可以放在 QList 中使用,并继承 QItem 的所有属性。

用法

基础用法

控制展开状态

样式

选项

关于缩进级别,有一个通用的经验法则:header-inset-level 为头部添加左侧内边距,但不影响内容区域;而 content-inset-level 则为内容区域添加左侧内边距。

行为

TIP

下面这个"仅通过展开图标切换"的行为在 QExpansionItem 头部绑定了路由的场景下特别有用。这样一来,点击头部会跳转路由,而点击展开图标则负责展开/折叠内容,两个操作互不干扰。显然,你无法把这两种行为同时绑定到整个头部上。

无障碍访问
v2.25+

头部遵循 WAI-ARIA 披露(disclosure)模式:它暴露 role="button" 并通过 aria-expanded 反映当前展开状态、aria-controls 指向内容容器,EnterSpace 可切换展开/收起。其无障碍名称是由 label 属性构建的本地化"展开"/"收起"标签(参见 Quasar 语言包);toggle-aria-label 属性可覆盖自动生成的标签。收起的内容对辅助技术是真正隐藏的,而非仅在视觉上隐藏。

当头部是一个链接时(to/href 属性——参见上文"仅通过展开图标切换"),头部保持为原生链接,切换相关的 ARIA 属性转移到展开图标上,该图标成为独立的 Tab 焦点——这样导航和展开操作可通过键盘分别到达。

请注意,丰富的自定义头部内容并不会被纳入生成的无障碍名称——屏幕阅读器用户仍然只能听到由 label 属性构建的"展开"/"收起"标签(或没有 label 时的通用标签)。当仅靠 label 属性无法完整表达含义时,请设置 toggle-aria-label