QtShadcn
组件

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

属性 / 信号默认说明
multiplefalse单选 / 多选。多选时点一项不影响其它项
collapsiblefalse单选时点已展开项能否收起。Base UI 默认 false = 至少保持一项展开
value""受控值:单选 string、多选 string[];"" / [] = 全收起。宿主写入即生效,用户点击同样回写
content—默认属性,收 ShadcnAccordionItem 进内部 Column
toggled(value, opened)—用户开合时发出(opened = 开 / 关)

ShadcnAccordionItem

属性默认说明
value""行标识,根的 value 用它比对;留空 = 该行不可开合
expanded只读展开态,由根的 value 派生(勿覆盖)
localExpandedfalse仅「单独摆一个 Item、没有 Accordion 根」时生效的本地态

ShadcnAccordionTrigger(基于 QQC Button)

属性默认说明
text""行标题(沿用 Button.text,Qt 6.8 起该属性 FINAL,不再自行声明)
expanded只读跟所属 Item
enabledtruefalse = 官方 aria-disabled:点不动 + opacity-50

键盘:Tab 可聚焦,Enter / Space 切换(两档都接管,跨 Qt 版本行为一致)。

ShadcnAccordionContent

属性默认说明
expanded只读跟所属 Item
textColortheme.mutedForeground官方 text-muted-foreground 是 CSS 继承,QML 的 Text 不吃继承,宿主侧显式取这个值
content—默认属性,收子项进内部 ColumnLayout

视觉(base-nova 对照)

官方类Qt 侧
flex w-full flex-colColumn(positioner),宽度由宿主给
not-last:border-b行底 Rectangle 1px theme.border,末行 visible: false
Trigger py-2.5verticalPadding: round(spacingXs × 2.5) = 10px
Trigger text-sm font-medium14px / Font.Medium
Trigger rounded-lgtheme.radiusLg
Trigger hover:underlinefont.underline: hovered
focus-visible:border-ring + ring-3 ring-ring/501px theme.ring 描边 + 外扩 3px 半透明 ring(activeFocus)
aria-disabled:opacity-50opacity: enabled ? 1 : 0.5
图标 size-4 text-muted-foreground ml-autoShadcnIcon 16px / theme.mutedForeground / RowLayout 贴右
Content overflow-hiddenclip: 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 }
    }
}

三个必须避开的坑(仓库历史实测):

  1. clip 容器里直接读子项 implicitHeight 会塌缩(同 ShadcnDialogContent / ShadcnScrollArea)。所以内容高度由独立的 host 固定成一条自己的算式,外层只读它, 依赖单向不成环。
  2. 不用 childrenRect:它会被子项的 anchors / 尺寸反向影响,内容里放 Flickable / ScrollView 时给出的是视口高而不是内容高。
  3. 收起状态内容不可交互: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)
Copyright © 2026