ShadcnScrollArea

滚动区域:一个 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
| 属性 | 默认 | 说明 |
|---|---|---|
verticalPolicy | ScrollBar.AsNeeded | 竖向条策略,透传给内部 ShadcnScrollBar |
horizontalPolicy | ScrollBar.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组合做带边框的滚动列表
