QtShadcn
组件

ShadcnScrollArea

滚动区域:shadcn 风格的 token 化滚动条。

滚动区域:一个 Flickable 容器 + 统一 token 化的滚动条。滚动条本身也单独导出为 ShadcnScrollBar,可以直接 attach 到任意 Flickable / TableView / ListView。

用法

ShadcnScrollArea {
    id: area
    width: 350
    height: 200

    Column {
        width: area.width - 12   // 给右侧滚动条留出位置
        Repeater { model: 20; delegate: ... }
    }
}

单独使用滚动条:

Flickable {
    ScrollBar.vertical: ShadcnScrollBar { policy: ScrollBar.AsNeeded }
}

子项宽度不要写 parent.width:内容的父项是内部的 host Item, 它的宽度来自 childrenRect,会形成 host ↔ 子项的回环。 用固定宽,或绑 ShadcnScrollArea 的 id。

API

属性默认说明
verticalPolicyScrollBar.AsNeeded竖向条策略,透传给内部 ShadcnScrollBar
horizontalPolicyScrollBar.AsNeeded横向条策略
contentWidth自动max(contentItem.childrenRect.width, width)
contentHeight自动contentItem.childrenRect.height

ShadcnScrollBar 自身就是 ScrollBar,额外支持 orientation / policy 等原生属性。

视觉

  • 轨道宽 10px(shadcn w-2.5),内含 1px padding(p-px)→ thumb 实际 8px
  • thumb 全圆角(rounded-full),颜色取 theme.border
  • 无轨道背景(shadcn 的 ScrollBar 只有 thumb)
  • 内容放得下时 thumb 隐藏;AlwaysOn 时即使不需要滚动也显示(撑满轨道)

需要注意

为什么基座是 Flickable 而不是 ScrollView:ScrollView 不会拉伸它 attached 的 ScrollBar 的几何。实测 ScrollView { ScrollBar.vertical: ScrollBar { } } 里 bar.height 停在 implicitHeight(10px)而不是视口高度,于是 thumb 高度 = size × 10, 内容再长也只有几像素,视觉上是个小圆点 —— 连 Qt 自带的 Basic ScrollBar 都是这样。 换成 Flickable 后 bar.height 才等于视口高,thumb 按比例显示。

内容尺寸:Flickable 不像 ScrollView 那样自动取单个内容根的 implicitWidth/Height, 本组件用 contentItem.childrenRect 推导。内容多时建议包一层 Column / ColumnLayout, childrenRect 不适合直接挂大量 delegate 的场景。

滚动条是叠加层:不挤占内容宽度,所以内容贴边时会被 thumb 遮住 10px,需要留白。

相关

  • ShadcnDialog 的 body、ShadcnTextarea、ShadcnTable 都已接入统一的滚动条样式
  • 与 ShadcnSeparator、ShadcnCard 组合做带边框的滚动列表
Copyright © 2026