Qt 5.15中Tumbler.displacement属性文档与实际行为不符及布局重叠问题咨询

1. Tumbler.displacement取值范围与文档不符的问题 #

是的，不少开发者都遇到过这个情况。Qt 5.15的Tumbler文档中描述Tumbler.displacement的取值范围是-visibleItemCount / 2至visibleItemCount / 2，但实际运行中，当你滚动Tumbler超出可见项的边界时，这个值会超出这个范围。

这是因为displacement的底层实现是基于项的实际滚动偏移量计算的，而非严格限制在可见项数量的一半。文档的描述更偏向于理想状态下的“可见范围内的偏移”，但实际滚动时，这个值会随着滚动操作持续变化，直到滚动停止并回弹到可见范围内。社区里也有不少开发者在讨论这个文档描述的不准确之处。

2. 关于示例透明度代码的合理性 #

完全认同你的观点！

文档中描述“非当前项时透明度为40%，成为当前项时过渡至100%不透明度”，但给出的示例代码：

0.4 + Math.max(0, 1 - Math.abs(Tumbler.displacement)) * 0.6

只有当Tumbler.displacement的绝对值≤1时，才能让当前项（displacement=0）达到100%透明度，边缘项达到40%。但结合displacement的实际取值逻辑，这个代码并不符合文档描述的效果。

而你提出的修正代码：

0.4 + Math.max(0, 1 - Math.abs(Tumbler.displacement)/(visibleItemCount/2.0)) * 0.6

通过将displacement除以visibleItemCount/2进行归一化，无论visibleItemCount设置为多少，当前项（displacement=0）的透明度都会是100%，最边缘的可见项（displacement=±visibleItemCount/2）透明度刚好是40%，完全匹配文档的文字描述。这明显是文档示例的疏漏。

3. 代理项重叠的问题 #

你遇到的“所有代理项打印在同一位置完全重叠”的问题，大概率和以下几个原因有关：

• 代理未正确绑定位置属性：Tumbler的代理项需要通过Tumbler.displacement附加属性来计算自身的位置，比如添加y: Tumbler.displacement * height这样的绑定，让项随着滚动偏移。如果缺少这个绑定，所有项都会默认在同一位置渲染。
• visibleItemCount或代理尺寸设置错误：如果visibleItemCount设置不合理，或者代理组件的高度没有正确定义，会导致布局计算出错。
• Qt 5.15.2的已知bug：Qt 5.15.2的Quick Controls 2中存在一些Tumbler的布局问题，尝试升级到Qt 5.15的后续补丁版本（比如5.15.8）可能会解决这个问题。

建议先检查代理组件是否正确实现了基于Tumbler.displacement的位置绑定，这是解决重叠问题的关键。

内容的提问来源于stack exchange，提问作者Nico