PathView QML 类型

在路径上布局模型提供的项。 更多...

导入语句import QtQuick
继承

Item

属性

附加属性

信号

方法

详细描述

PathView显示从内置QML类型（如ListModel和XmlListModel）或从继承自QAbstractListModel的自定义模型类中创建的模型的数据。

视图有一个model，它定义了要显示的数据，以及一个delegate，它定义了数据应如何显示。对于路径上的每个项目，都会实例化delegate。可以通过沿路径滑动项目来移动这些项目。

例如，在一个名为ContactModel.qml的文件中定义了一个简单的列表模型如下：

import QtQuick

ListModel {
    ListElement {
        name: "Bill Jones"
        icon: "pics/qtlogo.png"
    }
    ListElement {
        name: "Jane Doe"
        icon: "pics/qtlogo.png"
    }
    ListElement {
        name: "John Smith"
        icon: "pics/qtlogo.png"
    }
}

可以将这些数据表示为一个PathView，如下所示：

import QtQuick

Rectangle {
    width: 240; height: 200

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

    PathView {
        anchors.fill: parent
        model: ContactModel {}
        delegate: delegate
        path: Path {
            startX: 120; startY: 100
            PathQuad { x: 120; y: 25; controlX: 260; controlY: 75 }
            PathQuad { x: 120; y: 100; controlX: -20; controlY: 75 }
        }
    }
}

(注意上述示例使用PathAttribute来缩放并修改项目在旋转时的不透明度。此附加代码可以在PathAttribute文档中看到。）

PathView不会自动处理键盘导航。这是因为用于导航的键将取决于路径的形状。可以通过将focus设置为true并调用decrementCurrentIndex()或incrementCurrentIndex()，例如使用左右箭头键进行导航，非常简单地将导航添加到其中。

PathView {
    // ...
    focus: true
    Keys.onLeftPressed: decrementCurrentIndex()
    Keys.onRightPressed: incrementCurrentIndex()
}

路径视图本身是一个焦点范围（有关详细信息，请参见Qt Quick中的键盘焦点）。

代理按需实例化，随时可能被销毁。不应在代理中存储任何状态。

PathView将一些属性附加到代理的根项目上，例如PathView.isCurrentItem。在以下示例中，根代理项目可以直接访问此附加属性作为PathView.isCurrentItem，而子nameText对象必须引用此属性作为wrapper.PathView.isCurrentItem。

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

注意视图不会自动启用clip。如果视图没有被其他项或屏幕剪辑，则必须将clip: true设置为使超出视图的项目被适当剪辑。

另请参阅Path，QML数据模型，ListView，GridView以及Qt Quick示例 - 视图。

属性文档

highlightRangeMode : 枚举

preferredHighlightBegin : real

preferredHighlightEnd : real

这些属性设置视图内高亮（当前项）的预选范围。预选值必须在从0到1的范围内。

highlightRangeMode的有效值包括：

常量描述
PathView.NoHighlightRange不应用任何范围：高亮可以在视图中自由移动。
PathView.ApplyRange视图将尝试在范围内保持高亮，但高亮可能由于路径两端的路径或鼠标交互而移出范围。
PathView.StrictlyEnforceRange高亮永远不会移动到范围之外。这意味着如果键盘或鼠标操作会导致高亮超出范围，当前项目将会改变。

默认值是 PathView.StrictlyEnforceRange。

定义高亮范围是正确的方式来影响当前项目在视图移动后结束的位置。例如，如果您想当前选中项位于路径中间，则将高亮范围设置为 0.5,0.5，并将 highlightRangeMode 设置为 PathView.StrictlyEnforceRange。然后，当路径滚动时，当前选中的项目将是该位置的项目。这也适用于当前选中的项目发生变化时 - 它将滚动到首选高亮范围内的任何位置。此外，当前项目索引的行为将发生，无论是否存在高亮。

注意：一个有效的范围要求 preferredHighlightEnd 的值大于或等于 preferredHighlightBegin。


cacheItemCount : int

这个属性包含缓存在路径之外的最大条目数。

例如，一个包含 20 个项目的 PathView，具有 10 的 pathItemCount 和 4 的 cacheItemCount 将创建多达 14 个项目，其中 10 个在路径上可见，4 个不可见的缓存项目。

缓存的代理异步创建，允许跨多个框架进行创建，从而减少跳帧的可能性。

注意：设置此属性不能替代创建高效的代理。它可以提高滚动行为的平滑性，但代价是额外的内存使用。代理中的对象和绑定越少，视图滚动得越快。重要的是要认识到设置 cacheItemCount 只会推迟由缓慢加载的代理引起的问题，并不是解决这种情况的方案。

另请参阅：pathItemCount。


count : int [只读]

这个属性包含模型中的条目数。


currentIndex : int

这个属性包含当前项的索引。


currentItem : Item [只读]

这个属性包含视图中的当前项。


delegate : Component

代理提供了一个模板，定义了视图所实例化的每个项目。索引作为可访问的 index 属性公开。根据 数据模型 的类型，模型属性也是可用的。

在指定了 pathItemCount 时，代理中的对象和绑定的数量对视图的滑动性能有直接影响。如果可能，将不需要用于正常显示代理的功能放置在可以按需加载附加组件的 Loader 中。

请注意，PathView 将基于委托中的根项的大小来布局项。

以下是一个示例代理

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

dragMargin : real

这个属性包含启动鼠标拖动的路径最大距离。

默认情况下，路径只能通过点击项来拖动。如果 dragMargin 大于零，则可以点击路径的dragMargin像素内来启动拖动。


dragging : bool [只读]

此属性表示视图当前是否由于用户拖拽视图而移动。


flickDeceleration : real

此属性表示快速轻扫时的减速率。

默认值为100。


flicking : bool [只读]

此属性表示视图当前是否由于用户滑动视图而移动。


highlight : 组件

此属性表示用作高亮的组件。

对于每个视图将创建一个高亮组件的实例。生成的组件实例的几何形状将由视图管理，以便与当前项保持一致。

以下示例演示了如何创建简单的高亮。注意在使用PathView.onPath附加属性确保高亮在从路径滑动离开时被隐藏。

Component {
    Rectangle {
        visible: PathView.onPath
        // ...
    }
}

另请参见highlightItem和highlightRangeMode。


highlightItem : 项目 [只读]

highlightItem持有高亮项目，该项目由highlight组件创建。

另请参见highlight。


highlightMoveDuration : int

此属性表示高亮代理的移动动画持续时间。

如果highlightRangeMode是StrictlyEnforceRange，则此属性确定项目沿路径移动的速度。

默认持续时间是300ms。


interactive : bool

用户无法拖拽或滑动非交互式的PathView。

此属性对于临时禁用滑动很有用。这允许对PathView的子项进行特殊交互。


maximumFlickVelocity : real

此属性持有用户可以在像素/秒中大约能达到的最大滑动速度。

默认值取决于平台。


model : model

此属性表示为视图提供数据的模型。

模型提供一组数据，用于创建视图中的项目。对于大型或动态数据集，模型通常由C++模型对象提供。也可以在QML中直接创建模型，使用ListModel类型。

注意：更改模型将重置偏移量和currentIndex为0。

另请参见数据模型。


movementDirection : 枚举

此属性确定设置当前索引时项目移动的方向。可能的值有

常量描述
PathView.Shortest（默认）项目将移动到最短距离的方向，这可能既是Negative也是Positive。
PathView.Negative项目向目标方向移动，向后移动。
PathView.Positive项目向前移动，向目标方向移动。

例如，假设模型中有5个项，且 currentIndex 为 0。如果将 currentIndex 设置为 2，则

  • Positive 运动方向将导致以下顺序：0，1，2
  • Negative 运动方向将导致以下顺序：0，5，4，3，2
  • Shortest 运动方向与 Positive 相同的顺序。

注意：此属性不影响 incrementCurrentIndex() 和 decrementCurrentIndex() 的移动。


moving ： bool [只读]

该属性指示视图是否因用户拖动或轻扫视图而正在移动。


offset ： real

偏移量指定项目与初始位置之间的路径长度。这是一个从 0 到模型中项数的实数。


path ： Path

该属性用于保存用于布局项目的路径。更多信息请参阅 Path 文档。


pathItemCount ： int

该属性持有时在任何时候路径上可见的项目数量。

将 pathItemCount 设置为未定义将显示路径上的所有项目。


snapMode ： enumeration

此属性确定拖动或轻扫后项目如何停靠。可能的值有

常量描述
PathView.NoSnap(默认值) 项目可以在路径上的任何位置停止。
PathView.SnapToItem项目与 preferredHighlightBegin 对齐的项目停靠。
PathView.SnapOneItem当触压释放时，项目将在与 preferredHighlightBegin 最近的项附近停靠，不超出一个项目。此模式特别适用于逐页移动。

snapMode 不会影响 currentIndex。要随视图的移动更新 currentIndex，请将 highlightRangeMode 设置为 PathView.StrictlyEnforceRange（默认值 PathView）。

另请参阅 highlightRangeMode。


附加属性文档

PathView.isCurrentItem ： bool [只读]

如果此代理是当前项目，则此附加属性为真；否则为假。

它附加到每个代理实例。

可以使用此属性调整当前项的外观。

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

PathView.onPath ： bool [只读]

此附加属性指示项目是否当前在路径上。

如果已设置 pathItemCount，则可能某些项目已实例化，但尚未视为当前在路径上。通常，这些项将被设置为不可见，例如

Component {
    Rectangle {
        visible: PathView.onPath
        // ...
    }
}

它附加到每个代理实例。


PathView.view ： PathView [只读]

此附加属性指示管理此代理实例的视图。

它附加到每个代理实例。


信号文档

dragEnded()

当用户停止拖动视图时发出此信号。

如果在触摸/鼠标按钮释放时拖动速度足够快，则将开始一个快照。

注意：相应的处理程序是 onDragEnded。


dragStarted()

当用户交互引起视图开始拖动时发出此信号。

注意：相应的处理程序是 onDragStarted。


flickEnded()

当由于快照而使视图停止移动时发出此信号。

注意：相应的处理程序是 onFlickEnded。


flickStarted()

当视图被快照时发出此信号。快照从鼠标或触摸释放的点开始，同时仍在移动。

注意：相应的处理程序是 onFlickStarted。


movementEnded()

当由于用户交互使视图停止移动时发出此信号。如果生成了一个快照，则此信号将在快照停止时发出。如果没有生成快照，则当用户停止拖动时（即鼠标或触摸释放）发出此信号。

注意：相应的处理程序是 onMovementEnded。


movementStarted()

当由于用户交互使视图开始移动时发出此信号。

注意：相应的处理程序是 onMovementStarted。


方法文档

decrementCurrentIndex()

递减当前索引。

注意：方法应在组件完成之后调用。


incrementCurrentIndex()

递增当前索引。

注意：方法应在组件完成之后调用。


int indexAt(real xi, real yi)

返回包含内容坐标中点 xi, yi 的项目的索引。如果没有项目位于指定的点上，则返回 -1。

注意：方法应在组件完成之后调用。


Item itemAt(real xi, real yi)

返回包含内容坐标中点 xi, yi 的项目。如果没有项目位于指定的点上，则返回 null。

注意：方法应在组件完成之后调用。


Item itemAtIndex(int index)

返回 index 的项目。如果没有该项目，例如，因为它尚未创建，或者因为它已从可见区域中滚动并从缓存中删除，则返回 null。

注意：此方法应在组件完成后调用。返回的值也不应存储，因为它可以在控制退出调用作用域后立即变为 null，如果视图释放该项目。


positionViewAtIndex(int index, PositionMode mode)

调整视图位置，使得 index 位于由 mode 指定位置。

常量描述
PathView.Beginning将项目定位在路径的起始位置。
PathView.Center将项目定位在路径的中心。
PathView.End将项目定位在路径的末尾。
PathView.Contain确保项目定位在路径上。
PathView.SnapPosition将项目定位在 preferredHighlightBegin。此模式仅在 highlightRangeMode 为 StrictlyEnforceRange 或通过 snapMode 启用吸附模式时有效。

注意：方法应在组件完成后调用。为了在启动时定位视图，应通过 Component.onCompleted 调用此方法。例如，为了定位视图末尾，

Component.onCompleted: positionViewAtIndex(count - 1, PathView.End)

© 2024 The Qt Company Ltd. 本文档中包含的贡献文档均属于各自所有者的版权。提供的文档根据由自由软件开发基金会发布的GNU自由文档许可证版本1.3的条件许可。Qt及其标志是芬兰以及世界其他国家的The Qt Company Ltd.的商标。所有其他商标均为其各自所有者的财产。