PathView QML Type

将模型提供的项沿路径排列。更多...

• 所有成员的列表，包括继承的成员

属性

• cacheItemCount : int
• count : int
• currentIndex : int
• currentItem : Item
• delegate : Component
• dragMargin : real
• dragging : bool
• flickDeceleration : real
• flicking : bool
• highlight : Component
• highlightItem : Item
• highlightMoveDuration : int
• highlightRangeMode : enumeration
• interactive : bool
• maximumFlickVelocity : real
• model : model
• movementDirection : enumeration
• moving : bool
• offset : real
• path : Path
• pathItemCount : int
• preferredHighlightBegin : real
• preferredHighlightEnd : real
• snapMode : enumeration

关联属性

• isCurrentItem : bool
• onPath : bool
• view : PathView

信号

• dragEnded()
• dragStarted()
• flickEnded()
• flickStarted()
• movementEnded()
• movementStarted()

方法

• void decrementCurrentIndex()
• void incrementCurrentIndex()
• int indexAt(real x, real y)
• Item itemAt(real x, real y)
• Item itemAtIndex(int index)
• void positionViewAtIndex(int index, PositionMode mode)

详细说明

PathView 用于显示来自内置 QML 类型（如ListModel 和XmlListModel ）所创建的模型数据，或来自 C++ 中定义的、继承自QAbstractListModel 的自定义模型类的数据。

该视图包含一个 `model`，用于定义待显示的数据；以及一个 `delegate`，用于定义数据的显示方式。对于 `path` 上的每个项目，都会实例化一个 `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: true`，才能使超出视图范围的项目被妥善裁剪。

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

属性文档

cacheItemCount : int

该属性指定了路径外缓存项的最大数量。

例如，一个模型包含 20 个项的 `PathView `，其 `pathItemCount ` 值为 10，且 `cacheItemCount` 值为 4，将最多创建 14 个项，其中 10 个在路径上可见，4 个不可见的缓存项。

缓存的委托是异步创建的，允许在多个帧中进行创建，从而降低了跳帧的可能性。

另请参阅 pathItemCount 。

count : int [read-only]

该属性存储模型中的项目数量。

currentIndex : int

该属性保存当前项的索引。

currentItem : Item [read-only]

该属性保存视图中的当前项。

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 [read-only]

该属性表示视图是否因用户拖动而正在移动。

flickDeceleration : real

该属性控制轻扫动作的减速速率。

默认值为 100。

flicking : bool [read-only]

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

highlight : Component

该属性用于指定用作高亮效果的组件。

每个视图都会创建一个高亮组件的实例。生成的组件实例的几何图形将由视图进行管理，以确保其始终与当前项目保持同步。

下面的示例演示了如何制作一个简单的高亮效果。请注意使用PathView.onPath 附加属性，以确保当项目被滑出路径时，高亮效果会被隐藏。

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

另请参阅 highlightItem 和highlightRangeMode 。

highlightItem : Item [read-only]

highlightItem 包含由highlight 组件生成的高亮项。

另请参阅 highlight 。

highlightMoveDuration : int

该属性存储高亮委托的移动动画持续时间。

如果“highlightRangeMode ”属性设置为“StrictlyEnforceRange”，则该属性将决定项目沿路径移动的速度。

该持续时间的默认值为 300 毫秒。

这些属性用于设置视图中突出显示项（当前项）的首选范围。首选值必须在0 到1 之间。

highlightRangeMode 的有效值如下：

默认值为PathView.StrictlyEnforceRange。

定义高亮范围是影响视图移动时当前项目最终位置的正确方法。例如，如果您希望当前选中的项目位于路径中间，则将高亮范围设置为 0.5,0.5，并将highlightRangeMode 设置为PathView.StrictlyEnforceRange。 这样，当路径滚动时，当前选中的项将是位于该位置的项。这同样适用于当前选中项发生变化时——它将滚动到首选高亮范围之内。此外，无论是否存在高亮，当前项索引的行为都会发生。

interactive : bool

用户无法拖动或轻扫非交互式的PathView 。

此属性可用于临时禁用轻扫操作。这使得可以与PathView 的子元素进行特殊的交互。

maximumFlickVelocity : real

该属性存储用户可对视图进行轻扫操作的近似最大速度，单位为像素/秒。

默认值取决于平台。

model : model

该属性保存为视图提供数据的模型。

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

另请参阅 “数据模型”。

movementDirection : enumeration

该属性用于确定设置当前索引时项的移动方向。可能的取值包括：

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

• 当Positive 的移动方向为 时，结果顺序为：0, 1, 2
• 当移动方向为Negative 时，将产生以下顺序：0, 5, 4, 3, 2
• Shortest 的移动方向将产生与Positive 相同的顺序。

moving : bool [read-only]

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

offset : real

偏移量指定了项目相对于其初始位置在路径上偏移的距离。这是一个实数，取值范围从0 到模型中项目的总数。

path : Path

该属性保存用于布局项目的路径。有关详细信息，请参阅Path 文档。

pathItemCount : int

该属性存储路径上任何时候可见的项目数量。

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

snapMode : enumeration

此属性决定了项目在拖动或轻扫后如何定位。可能的取值包括：

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

另请参阅 highlightRangeMode 。

附加属性文档

PathView.isCurrentItem : bool [read-only attached]

如果该委托是当前项，则此附加属性为 true；否则为 false。

它附属于该委托的每个实例。

该属性可用于调整当前项的外观。

    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 [read-only attached]

此附加属性用于标识该项目当前是否位于路径上。

如果已设置pathItemCount ，则可能存在某些项已被实例化，但未被视为当前位于路径上的情况。通常，这些项会被设置为不可见，例如：

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

该属性附加在每个委托实例上。

PathView.view : PathView [read-only attached]

此附加属性保存着管理该委托实例的视图。

它附加在每个委托实例上。

Signal 文档

dragEnded()

当用户停止拖动视图时，会触发此信号。

如果在释放触摸或鼠标按钮时拖动速度足够大，则会触发轻扫操作。

dragStarted()

当视图因用户交互而被拖动时，会发出此信号。

flickEnded()

当视图因轻扫操作而停止移动时，会触发此信号。

flickStarted()

当视图被轻扫时，会触发此信号。轻扫动作始于鼠标或触摸释放的瞬间，此时指针或触控点仍在移动中。

movementEnded()

当视图因用户交互而停止移动时，会触发此信号。如果产生了轻扫操作，则在轻扫停止后会触发此信号；如果未产生轻扫操作，则在用户停止拖动时（即释放鼠标或触摸）会触发此信号。

movementStarted()

当视图因用户交互而开始移动时，会发出此信号。

方法文档

void decrementCurrentIndex()

将当前索引减1。

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

void incrementCurrentIndex()

将当前索引递增。

注意：仅应在组件完成加载后才调用这些方法。

int indexAt(real x, real y)

返回包含坐标x 、y （内容坐标系）的项的索引。如果指定位置不存在该项，则返回-1。

注意：这些方法应在组件完成加载后才调用。

Item itemAt(real x, real y)

返回包含坐标x 、y （以内容坐标系计）的项。如果指定坐标处不存在该项，则返回 null。

注意：仅应在组件完成创建后才调用这些方法。

Item itemAtIndex(int index)

返回index 对应的项。如果该索引下没有对应的项（例如，因为该项尚未创建，或者因平移操作已超出可见范围并从缓存中移除），则返回null。

注意：此方法仅应在组件完成初始化后调用。此外，不应存储返回值，因为一旦控件超出调用范围，如果视图释放了该项，返回值可能会立即变为 null。

void positionViewAtIndex(int index, PositionMode mode)

将视图定位，使index 位于mode 指定的位置：

注意：仅应在组件完成加载后调用这些方法。若要在启动时定位视图，应通过 Component.onCompleted 调用此方法。例如，若要将视图定位在路径末端：

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