QScrollerProperties Class
QScrollerProperties 类用于存储QScroller 的设置。更多内容...
| 头文件： | #include <QScrollerProperties> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
公共类型
| enum | FrameRates { Fps60, Fps30, Fps20, Standard } |
| enum | OvershootPolicy { OvershootWhenScrollable, OvershootAlwaysOff, OvershootAlwaysOn } |
| enum | ScrollMetric { MousePressEventDelay, DragStartDistance, DragVelocitySmoothingFactor, AxisLockThreshold, ScrollingCurve, …, ScrollMetricCount } |
公共函数
| QScrollerProperties() | |
| QScrollerProperties(const QScrollerProperties &sp) | |
| virtual | ~QScrollerProperties() |
| QVariant | scrollMetric(QScrollerProperties::ScrollMetric metric) const |
| void | setScrollMetric(QScrollerProperties::ScrollMetric metric, const QVariant &value) |
| bool | operator!=(const QScrollerProperties &sp) const |
| QScrollerProperties & | operator=(const QScrollerProperties &sp) |
| bool | operator==(const QScrollerProperties &sp) const |
静态公共成员
| void | setDefaultScrollerProperties(const QScrollerProperties &sp) |
| void | unsetDefaultScrollerProperties() |
详细说明
QScrollerProperties 类存储了QScroller 所使用的参数。
默认设置取决于平台，因此 Qt 会模拟平台对动能滚动的行为。
按照惯例，QScrollerProperties 采用物理单位（米、秒），并由QScroller 根据当前 DPI 进行转换。
另请参阅 QScroller 。
成员类型文档
enum QScrollerProperties::FrameRates
此枚举描述了拖动或滚动时可用的帧率。
| 常量 | 值 | 描述 |
|---|---|---|
QScrollerProperties::Fps60 | 1 | 每秒 60 帧 |
QScrollerProperties::Fps30 | 2 | 每秒 30 帧 |
QScrollerProperties::Fps20 | 3 | 每秒 20 帧 |
QScrollerProperties::Standard | 0 | 默认值为每秒60帧（相当于QAbstractAnimation ）。 |
enum QScrollerProperties::OvershootPolicy
该枚举描述了各种超调模式。
| 常量 | 值 | 描述 |
|---|---|---|
QScrollerProperties::OvershootWhenScrollable | 0 | 当内容可滚动时，可能发生超调。这是默认设置。 |
QScrollerProperties::OvershootAlwaysOff | 1 | 即使内容可滚动，超调也永远不会被启用。 |
QScrollerProperties::OvershootAlwaysOn | 2 | 始终启用超调，即使内容不可滚动时也是如此。 |
enum QScrollerProperties::ScrollMetric
该枚举包含不同的滚动度量类型。除非另有说明，否则setScrollMetric 函数期望接收一个类型为qreal的QVariant 。
有关不同值背后概念的更多细节，请参阅QScroller 的文档。
| 常量 | 值 | 描述 |
|---|---|---|
QScrollerProperties::MousePressEventDelay | 0 | 这是在[s] 中启动轻扫手势时，鼠标按下事件被延迟的时间。如果手势在此时间范围内被触发，则不会向滚动对象发送任何鼠标按下或释放事件。 如果该手势在延迟后触发，则会发送延迟的鼠标按下事件以及在全局位置QPoint(-QWIDGETSIZE_MAX, -QWIDGETSIZE_MAX) 处模拟的释放事件。如果手势被取消，则会同时发送延迟的鼠标按下事件和真实的释放事件。 |
QScrollerProperties::DragStartDistance | 1 | 这是在m 中触发轻扫手势前，触摸点或鼠标指针需要移动的最小距离。 |
QScrollerProperties::DragVelocitySmoothingFactor | 2 | 该值描述了新拖拽速度在多大程度上会被纳入最终滚动速度。该值应在0 到1 之间。数值越低，对拖拽速度的平滑处理就越强。 |
QScrollerProperties::AxisLockThreshold | 3 | 如果移动角度在该轴周围的范围内，则将移动限制在该轴上。阈值必须在0 到1 之间。 |
QScrollerProperties::ScrollingCurve | 4 | 用户发起轻扫操作后，用于减速滚动速度的QEasingCurve 。请注意，这是位置的缓动曲线，而非速度的缓动曲线：默认值为QEasingCurve::OutQuad ，这将导致速度（一阶导数）线性减小，且减速率（二阶导数）保持恒定。 |
QScrollerProperties::DecelerationFactor | 5 | 该因子影响滚动条减速至零速度所需的时间。实际数值取决于所选的 ScrollingCurve。对于大多数类型，该值应在0.1 到2.0 |
QScrollerProperties::MinimumVelocity | 6 | 在m/s 中，结束触摸或释放鼠标后开始滚动所需的最小速度。 |
QScrollerProperties::MaximumVelocity | 7 | 这是在m/s 中可达到的最大速度。 |
QScrollerProperties::MaximumClickThroughVelocity | 8 | 这是在m/s 中点击穿透操作允许的最大滚动速度。这意味着，当点击当前正在（缓慢）滚动的对象时，不仅会停止滚动，点击事件还会传递给UI控件。这在使用指数型滚动曲线时非常有用。 |
QScrollerProperties::AcceleratingFlickMaximumTime | 9 | 这是在seconds 中，轻扫手势被识别为“加速轻扫”所需的最长时长。若设置为零，则不会检测到此类手势。 “加速轻扫”是指在已经开始滚动的对象上执行的轻扫手势。在此情况下，滚动速度将乘以 AcceleratingFlickSpeedupFactor 以实现加速。 |
QScrollerProperties::AcceleratingFlickSpeedupFactor | 10 | 若检测到加速轻扫，当前速度将乘以该数值。应设置为>= 1 。 |
QScrollerProperties::SnapPositionRatio | 11 | 这是用户必须拖动区域在两个对齐点之间移动的距离，才能使其对齐到下一个位置。0.33 表示滚动只需达到两个对齐点之间距离的三分之一即可对齐到下一个位置。该比率必须在0 到1 之间。 |
QScrollerProperties::SnapTime | 12 | 这是滚动曲线的时间因子。数值越小，滚动所需时间越长。滚动距离与该数值无关。 |
QScrollerProperties::OvershootDragResistanceFactor | 13 | 该值是鼠标拖动与实际滚动区域移动（在过冲期间）之间的倍数。该倍数必须在0 到1 之间。 |
QScrollerProperties::OvershootDragDistanceFactor | 14 | 这是拖动时超调移动的最大距离。实际超调距离通过将此值乘以被滚动对象的视口大小来计算。该系数必须在0 和1 之间。 |
QScrollerProperties::OvershootScrollDistanceFactor | 15 | 这是滚动时超调移动的最大距离。实际超调距离通过将此值与被滚动对象的视口大小相乘来计算。该系数必须在0 到1 之间。 |
QScrollerProperties::OvershootScrollTime | 16 | 这是以seconds 为单位的时间，用于播放完整的超调动画。 |
QScrollerProperties::HorizontalOvershootPolicy | 17 | 这是水平超调策略（参见OvershootPolicy ）。 |
QScrollerProperties::VerticalOvershootPolicy | 18 | 这是水平超调策略（参见OvershootPolicy ）。 |
QScrollerProperties::FrameRate | 19 | 这是拖拽或滚动时应使用的帧率。QScroller 在内部使用QAbstractAnimation 计时器，将所有滚动操作与可能同时激活的其他动画进行同步。 如果每秒 60 帧的标准值过快，可以通过此设置将其降低，同时仍与QAbstractAnimation 保持同步。请注意，此处仅允许使用FrameRates 枚举中的值。 |
QScrollerProperties::ScrollMetricCount | 20 | 此项始终为最后一个条目。 |
成员函数文档
QScrollerProperties::QScrollerProperties()
创建新的滚动条属性。
QScrollerProperties::QScrollerProperties(const QScrollerProperties &sp)
创建sp 的副本。
[virtual noexcept] QScrollerProperties::~QScrollerProperties()
清除滚动条的属性。
QVariant QScrollerProperties::scrollMetric(QScrollerProperties::ScrollMetric metric) const
查询滚动条属性的metric 值。
另请参阅 setScrollMetric() 和ScrollMetric 。
[static] void QScrollerProperties::setDefaultScrollerProperties(const QScrollerProperties &sp)
将所有新创建的QScrollerProperties 对象的滚动条属性设置为sp 。
使用此函数可覆盖默认构造函数返回的平台默认属性。若仅需更改单个滚动条的属性，请使用QScroller::setScrollerProperties()
注意：调用 此函数不会更改已存在的QScrollerProperties 对象的内容。
另请参阅 unsetDefaultScrollerProperties()。
void QScrollerProperties::setScrollMetric(QScrollerProperties::ScrollMetric metric, const QVariant &value)
将metric 的ScrollerMetric属性设置为value 。
另请参阅 scrollMetric() 和ScrollMetric 。
[static] void QScrollerProperties::unsetDefaultScrollerProperties()
将默认构造函数返回的滚动条属性重置为平台的默认属性。
另请参阅 setDefaultScrollerProperties()。
bool QScrollerProperties::operator!=(const QScrollerProperties &sp) const
如果这些滚动条属性与sp 不同，则返回true ；否则返回false 。
QScrollerProperties &QScrollerProperties::operator=(const QScrollerProperties &sp)
将sp 赋值给这些滚动条属性，并返回对这些滚动条属性的引用。
bool QScrollerProperties::operator==(const QScrollerProperties &sp) const
如果这些滚动条属性等于 `sp`，则返回 `true `；否则返回 `false`。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
