组件
ShadcnAccordion
手风琴:Accordion / Item / Trigger / Content 组合,单选·多选·collapsible 三档语义 + 高度展开动画。

手风琴(shadcn/ui v4 base-nova 口径,对齐 Base UI Accordion)。四个组件组合:
Accordion flex w-full flex-col(纵向列,零自绘样式)
└── AccordionItem not-last:border-b(除末行外 1px theme.border 底边线)
├── AccordionTrigger 行头按钮(包在 Header flex 里)
└── AccordionContent 内容区(高度 0 ↔ 自然高动画 + overflow-hidden)
用法
ShadcnAccordion {
width: 460
multiple: false // true = 多开,value 为 string[]
collapsible: false // 单选时点已展开项是否可收起
value: "" // 受控:单选 string / 多选 string[]
onToggled: (value, opened) => console.log(value, opened)
ShadcnAccordionItem {
value: "faq1"
ShadcnAccordionTrigger { text: qsTr("QtShadcn 是什么?") }
ShadcnAccordionContent {
Text {
Layout.fillWidth: true
wrapMode: Text.WordWrap
color: theme.mutedForeground // 官方 text-muted-foreground
text: qsTr("一套 shadcn/ui 风格的 Qt Quick 组件库。")
}
}
}
ShadcnAccordionItem {
value: "faq2"
ShadcnAccordionTrigger { text: qsTr("支持暗色吗?") }
ShadcnAccordionContent { /* …… */ }
}
}
一行 = 一个 Trigger + 一个 Content(官方 Panel 也是单个)。内容子项在
ShadcnAccordionContent 内部的 ColumnLayout 里,需要铺宽时写 Layout.fillWidth: true。
API
ShadcnAccordion
| 属性 / 信号 | 默认 | 说明 |
|---|---|---|
multiple | false | 单选 / 多选。多选时点一项不影响其它项 |
collapsible | false | 单选时点已展开项能否收起。Base UI 默认 false = 至少保持一项展开 |
value | "" | 受控值:单选 string、多选 string[];"" / [] = 全收起。宿主写入即生效,用户点击同样回写 |
content | — | 默认属性,收 ShadcnAccordionItem 进内部 Column |
toggled(value, opened) | — | 用户开合时发出(opened = 开 / 关) |
ShadcnAccordionItem
| 属性 | 默认 | 说明 |
|---|---|---|
value | "" | 行标识,根的 value 用它比对;留空 = 该行不可开合 |
expanded | 只读 | 展开态,由根的 value 派生(勿覆盖) |
localExpanded | false | 仅「单独摆一个 Item、没有 Accordion 根」时生效的本地态 |
ShadcnAccordionTrigger(基于 QQC Button)
| 属性 | 默认 | 说明 |
|---|---|---|
text | "" | 行标题(沿用 Button.text,Qt 6.8 起该属性 FINAL,不再自行声明) |
expanded | 只读 | 跟所属 Item |
enabled | true | false = 官方 aria-disabled:点不动 + opacity-50 |
键盘:Tab 可聚焦,Enter / Space 切换(两档都接管,跨 Qt 版本行为一致)。
ShadcnAccordionContent
| 属性 | 默认 | 说明 |
|---|---|---|
expanded | 只读 | 跟所属 Item |
textColor | theme.mutedForeground | 官方 text-muted-foreground 是 CSS 继承,QML 的 Text 不吃继承,宿主侧显式取这个值 |
content | — | 默认属性,收子项进内部 ColumnLayout |
视觉(base-nova 对照)
| 官方类 | Qt 侧 |
|---|---|
flex w-full flex-col | Column(positioner),宽度由宿主给 |
not-last:border-b | 行底 Rectangle 1px theme.border,末行 visible: false |
Trigger py-2.5 | verticalPadding: round(spacingXs × 2.5) = 10px |
Trigger text-sm font-medium | 14px / Font.Medium |
Trigger rounded-lg | theme.radiusLg |
Trigger hover:underline | font.underline: hovered |
focus-visible:border-ring + ring-3 ring-ring/50 | 1px theme.ring 描边 + 外扩 3px 半透明 ring(activeFocus) |
aria-disabled:opacity-50 | opacity: enabled ? 1 : 0.5 |
图标 size-4 text-muted-foreground ml-auto | ShadcnIcon 16px / theme.mutedForeground / RowLayout 贴右 |
Content overflow-hidden | clip: true |
Content pb-2.5 | 底部留白 10px(无顶部留白) |
duration-200 展开动画 | theme.motionDuration(theme.durationSlow) + theme.easingOut |
chevron 是「双图标切换」不是旋转
官方 Trigger 里放两个图标:ChevronDownIcon 常态显示、展开时 hidden;
ChevronUpIcon 常态 hidden、展开时显示(group-aria-expanded/accordion-trigger:hidden /
:inline)。Qt 侧照做:两个 ShadcnIcon(chevron-down / chevron-up)按 expanded
互斥 visible,没有旋转动画。
高度动画:Qt 没有 grid-rows
官方用 grid-template-rows: 0fr → 1fr + animate-in/out 做展开。Qt 的等价实现是
「外层裁剪 + 动画外层自己的高度」:
Item { // 外层:动画自己的 height + clip
clip: true
height: expanded ? host.height : 0
Behavior on height { NumberAnimation { duration: theme.motionDuration(theme.durationSlow) } }
Item { // 内容宿主:固定自然高,独立于外层动画高度
id: host
visible: root.height > 0
height: column.implicitHeight + padBottom
ColumnLayout { id: column; height: column.implicitHeight }
}
}
三个必须避开的坑(仓库历史实测):
clip容器里直接读子项implicitHeight会塌缩(同ShadcnDialogContent/ShadcnScrollArea)。所以内容高度由独立的host固定成一条自己的算式,外层只读它, 依赖单向不成环。- 不用
childrenRect:它会被子项的 anchors / 尺寸反向影响,内容里放Flickable/ScrollView时给出的是视口高而不是内容高。 - 收起状态内容不可交互:
clip不参与命中测试,光靠裁剪「看不见」的内容照样吃掉 点击,必须host.visible = height > 0显式收掉可见性。
另外整条链不用 ColumnLayout 排行:Layout 会在布局 pass 里接管子项 height,动画中间值
直接被覆盖(ShadcnTabsList 那类「自包含尺寸要显式写」的问题同源)。用 Column
positioner 只写子项 y,height 归子项自己管。
已知偏差
- 官方
w-full在 Qt 没有级联宽度:给ShadcnAccordion显式宽度;放进ColumnLayout时用Layout.fillWidth/Layout.preferredWidth。 Item内不要用Repeater:异步创建会打乱视觉顺序。动态行在宿主侧声明或用Loader。- 动态移除已展开的行后,请把
value写回不含该值的集合(根不监听子项增删,避免读子项 属性形成依赖环)。
相关
- 单块开合区用
ShadcnCollapsible ShadcnSeparator是独立分隔线,行内分隔线由 Item 自己画(官方not-last:border-b)
