PathView 是 QML 中用于沿自定义路径布局项目的视图组件，常用于实现轮播图、弧形菜单等效果。继承自 Flickable。
qml
import QtQuick 2.15
PathView {
model: 5 // 数据模型
delegate: Rectangle { width: 50; height: 50; color: "lightblue" }
path: Path { startX: 0; startY: 0; PathLine { x: 200; y: 200 } }
}属性
| 属性 | 类型 | 描述 | 默认值 | 示例 |
|---|---|---|---|---|
model |
variant |
数据模型（数字/ListModel/JS数组） | - | model: myModel |
delegate |
Component |
定义每个项目的显示组件 | - | delegate: MyItem {} |
path |
Path |
定义项目移动路径（必需） | - | path: Path { ... } |
currentIndex |
int |
当前选中项的索引 | 0 |
currentIndex: 1 |
offset |
real |
路径上的偏移量（0.0-1.0） | 0 |
offset: 0.5 |
pathItemCount |
int |
同时可见的项目数量 | - | pathItemCount: 5 |
interactive |
bool |
是否允许用户拖动 | true |
interactive: false |
snapMode |
enum |
吸附模式（NoSnap/SnapToItem） |
NoSnap |
snapMode: SnapToItem |
flickDeceleration |
real |
拖动减速系数（越大减速越快） | 100 |
flickDeceleration: 200 |
方法
| 方法 | 参数 | 返回值 | 描述 | 示例 |
|---|---|---|---|---|
positionViewAtIndex(index, mode) |
index: int, mode: PositionMode |
- | 定位视图到指定索引 | positionViewAtIndex(3, PathView.Center) |
incrementCurrentIndex() |
- | - | 增加当前索引 | onClicked: view.incrementCurrentIndex() |
decrementCurrentIndex() |
- | - | 减少当前索引 | onClicked: view.decrementCurrentIndex() |
forceLayout() |
- | - | 强制重新布局 | onModelChanged: view.forceLayout() |
信号
| 信号 | 参数 | 描述 | 示例 |
|---|---|---|---|
currentIndexChanged() |
- | 当前索引变化时触发 | onCurrentIndexChanged: console.log(index) |
movementStarted() |
- | 开始拖动时触发 | onMovementStarted: animateIn() |
movementEnded() |
- | 拖动结束时触发 | onMovementEnded: animateOut() |
完整示例
qml
import QtQuick 2.15
import QtQuick.Controls 2.15
ApplicationWindow {
width: 600; height: 400
visible: true
ListModel {
id: myModel
ListElement { name: "A"; color: "red" }
ListElement { name: "B"; color: "green" }
ListElement { name: "C"; color: "blue" }
}
PathView {
id: pathView
anchors.fill: parent
model: myModel
pathItemCount: 3 // 显示3个项目
path: Path {
startX: 100; startY: 200
PathQuad { x: 300; y: 200; controlX: 200; controlY: 50 }
}
delegate: Rectangle {
width: 80; height: 80
color: model.color
opacity: PathView.isCurrentItem ? 1 : 0.5
Text { text: model.name; anchors.centerIn: parent }
MouseArea {
anchors.fill: parent
onClicked: pathView.currentIndex = index
}
}
highlight: Rectangle {
width: 80; height: 80
border.color: "yellow"; border.width: 3
}
}
Button {
text: "Next"
onClicked: pathView.incrementCurrentIndex()
}
}关键注意事项
路径定义：
必须包含
Path元素（如PathLine、PathQuad、PathArc）。使用
PathAttribute可为路径添加自定义属性（如缩放/透明度）。
性能优化：
大数据量时设置
cacheItemCount缓存项目。避免在
delegate中使用复杂组件。
交互控制：
禁用拖动：
interactive: false精准定位：
positionViewAtIndex(index, PathView.Center)
动态效果：
结合
PathView.onPath和PathView.angle实现 3D 旋转：qml
Rotation { origin.x: 40; origin.y: 40 axis { x: 0; y: 1; z: 0 } angle: PathView.angle * 45 }