1. 界面基础元素
- Rectangle:矩形形状元素,用于布局和绘制。
- Text:显示文本。
- Button:按钮元素,允许用户点击。
- TextField:文本输入框。
- ComboBox:下拉菜单,用于选择多个选项中的一个。
- Slider:滑动条,用于调整数值。
- ProgressBar:进度条,用于显示进度。
- Switch:开关,用于二选一的选择。
- CheckBox:复选框。
- RadioButton:单选按钮,通常用于选择一个选项。
- Label:标签,用于显示简单文本。
示例:
Rectangle {width: 200height: 100color: "lightblue"Text {anchors.centerIn: parenttext: "Hello, Qt!"}
}
2. 布局相关
- Grid:网格布局,按行列排布子元素。
- Column:列布局,将子元素垂直排列。
- Row:行布局,将子元素水平排列。
- StackLayout:堆叠布局,子元素堆叠显示。
- GridLayout:更灵活的网格布局,可以指定每个子项的位置。
示例:
Column {spacing: 10Rectangle { width: 100; height: 50; color: "red" }Rectangle { width: 100; height: 50; color: "green" }Rectangle { width: 100; height: 50; color: "blue" }
}
3. 交互元素
- MouseArea:定义可交互区域,通过鼠标事件触发动作。
- KeyEvent:键盘事件,用于响应键盘按键。
- GestureArea:手势识别区域,用于响应触摸手势。
示例:
Rectangle {width: 200height: 200color: "lightgreen"MouseArea {anchors.fill: parentonClicked: {console.log("Rectangle clicked")}}
}
4. 高级组件
- ListView:列表视图,用于显示可滚动的项目列表。
- Repeater:重复某个元素,用于生成动态内容。
- StackView:堆叠视图,类似于页面切换,支持历史记录。
- Loader:动态加载组件,支持延迟加载。
- Popup:弹出窗口。
- Dialog:对话框,通常用于与用户进行交互。
- Menu:菜单,通常用于显示一系列选项。
- ToolBar:工具栏,通常包含一些按钮和其他控件。
示例:
ListView {width: 200; height: 400model: ListModel {ListElement { name: "Alice" }ListElement { name: "Bob" }ListElement { name: "Charlie" }}delegate: Item {width: parent.widthheight: 50Rectangle {width: parent.widthheight: 50color: "lightblue"Text {anchors.centerIn: parenttext: model.name}}}
}
5. 动画与效果
- Animation:动画效果,用于属性的过渡。
- Opacity:控制透明度的变化。
- DropShadowEffect:阴影效果,用于添加阴影。
- ShaderEffect:着色器效果,可以自定义渲染效果。
- PropertyAnimation:属性动画,用于平滑过渡。
- ParallelAnimation:并行动画,可以同时执行多个动画。
- SequentialAnimation:顺序动画,多个动画按顺序执行。
示例:
Rectangle {width: 100; height: 100color: "blue"MouseArea {anchors.fill: parentonClicked: {var anim = Qt.createQmlObject('import QtQuick 2.15; PropertyAnimation { target: parent; property: "width"; to: 200; duration: 1000 }', parent)anim.start()}}
}
6. 自定义形状与路径
- Path:定义路径,用于绘制复杂图形。
- Shape:绘制简单的几何形状(圆形、矩形等)。
- Circle、Line、Ellipse:基本几何图形。
- Polygon:多边形形状。
示例:
Shape {width: 200; height: 200ShapePath {strokeColor: "black"strokeWidth: 2path: Path {moveTo(100, 10)lineTo(190, 190)lineTo(10, 190)closeSubpath()}}
}
7. 媒体与图片
- Image:显示图像。
- ImageButton:图像按钮。
- ImageView:图像查看器,用于显示可缩放的图像。
- SoundEffect:播放声音效果。
- Video:视频播放组件。
示例:
Image {source: "image.png"width: 200height: 200
}
8. 其他有用组件
- Timer:定时器,定时触发某个动作。
- TextArea:多行文本框。
- FileDialog:文件对话框,用于选择文件。
- DatePicker、TimePicker:日期和时间选择器。
示例:
Timer {interval: 1000running: truerepeat: trueonTriggered: {console.log("One second passed")}
}
9. 视图与地图
- Map:地图组件,展示地图视图。
- ChartView、PieSeries、BarSeries:用于绘制图表。
示例:
ChartView {width: 400; height: 400BarSeries {BarSet { label: "Set 1"; values: [1, 2, 3, 4, 5] }}
}
10. 高级交互组件
- MouseArea:用于检测鼠标点击、拖动等操作,通常与其他控件结合使用来响应用户的交互。
- MultiPointTouchArea:多点触摸区域,用于处理多个触摸点。
- GestureArea:手势识别区域,用于捕捉和响应触摸屏手势,如滑动、捏合等。
- KeyEvent:捕捉键盘事件,可用来处理用户按下键盘的操作。
示例:
Rectangle {width: 200; height: 200color: "yellow"MouseArea {anchors.fill: parentonReleased: {console.log("Mouse clicked on the rectangle")}}
}
11. 菜单和弹窗组件
- Menu:菜单组件,允许在弹出菜单中显示多个项。
- MenuItem:菜单项,用于显示在
Menu
中,每个项都可以触发动作。 - ContextMenu:右键菜单,通常用于右键点击时显示操作选项。
- Popup:弹出窗口,用于显示浮动的内容,如提示框或子窗口。
- Dialog:对话框,通常用于获取用户输入或显示信息。
- PopupMenu:弹出式菜单,类似于
Menu
,但它可以在任何地方显示。
示例:
Menu {id: menuMenuItem {text: "Open"onTriggered: console.log("Open selected")}MenuItem {text: "Save"onTriggered: console.log("Save selected")}
}
12. 动画与视觉效果
- ShaderEffect:着色器效果,允许开发者通过自定义着色器来实现图像的复杂效果,如模糊、阴影等。
- DropShadowEffect:阴影效果,用于为任何可视元素添加阴影,使其更具立体感。
- Opacity:透明度控制,可以使元素变得透明或不透明。
- Transition:过渡效果,用于在元素的状态变化时添加动画。
- Animation:属性动画,支持各种动画效果,如平移、缩放、旋转等。
- SequentialAnimation:顺序动画,多个动画按顺序执行。
- ParallelAnimation:并行动画,多个动画同时执行。
示例:
Rectangle {width: 200; height: 200color: "blue"MouseArea {anchors.fill: parentonClicked: {var anim = Qt.createQmlObject('import QtQuick 2.15; PropertyAnimation { target: parent; property: "width"; to: 400; duration: 500 }', parent)anim.start()}}
}
13. 视图和模型
- ListView:列表视图,用于显示具有相似结构的数据项。
- GridView:网格视图,类似于
ListView
,但数据项呈现为网格。 - Repeater:用于动态生成元素的组件。
- Loader:延迟加载其他QML组件,用于提高性能。
- ListModel:定义数据模型,用于与
ListView
等视图组件绑定。 - GridModel:网格模型,类似于
ListModel
,用于网格布局。
示例:
ListView {width: 200; height: 400model: ListModel {ListElement { name: "Alice" }ListElement { name: "Bob" }ListElement { name: "Charlie" }}delegate: Item {width: parent.widthheight: 50Rectangle {width: parent.widthheight: 50color: "lightblue"Text {anchors.centerIn: parenttext: model.name}}}
}
14. 图形与路径
- Path:自定义路径,用于绘制线条、曲线等。
- PathLine:路径中的直线。
- PathCurve:路径中的曲线。
- Shape:自定义形状,使用路径绘制不同的图形,如矩形、圆形、多边形等。
- Polygon:绘制多边形。
- Circle、Line、Ellipse:基本形状,如圆形、直线和椭圆。
示例:
Shape {width: 200; height: 200ShapePath {strokeColor: "black"strokeWidth: 2path: Path {moveTo(100, 10)lineTo(190, 190)lineTo(10, 190)closeSubpath()}}
}
15. 输入与日期时间
- TextField:用于输入单行文本。
- TextArea:多行文本输入框。
- SpinBox:数字输入框,用户可以通过点击箭头增减数值。
- DatePicker:日期选择器。
- TimePicker:时间选择器。
- DateTimeEdit:日期和时间输入控件。
示例:
SpinBox {width: 100from: 0to: 100value: 50
}
16. 图像与媒体处理
- Image:显示静态图片。
- ImageView:可缩放的图像视图,支持显示、缩放和旋转图片。
- ImageButton:图像按钮,结合图片和点击操作。
- SoundEffect:播放声音。
- Video:播放视频。
示例:
Image {source: "image.png"width: 100height: 100
}
17. 3D图形
- Context3D:3D上下文,用于在Qt Quick应用中呈现3D图形。
- GraphicsEffect:为元素添加视觉效果,如模糊、阴影等。
- Camera:用于3D视图的相机。
- Light:为3D场景添加光照。
- Lens:3D场景中的透镜,用于模拟不同的相机视角。
示例:
Camera {position: Qt.vector3d(0, 0, -500)lookAt: Qt.vector3d(0, 0, 0)
}
18. 控件与交互设计
- FocusScope:聚焦范围,用于限制控件的焦点范围。
- FocusIndicator:焦点指示器,显示哪个控件当前拥有焦点。
- DropArea:拖放区域,用于接收拖动的内容。
- DragArea:拖动区域,允许控件被拖动。
- DropShadowEffect:阴影效果,增强视觉效果。
示例:
DropArea {anchors.fill: parentonReleased: {console.log("Item dropped!")}
}
19. 实用工具
- Timer:定时器,用于定期执行任务。
- FileDialog:文件选择对话框,用于打开或保存文件。
- ProgressBar:进度条,用于显示任务的执行进度。
- TextMetrics:文本度量,获取文本的尺寸和位置。
示例:
Timer {interval: 1000running: truerepeat: trueonTriggered: {console.log("One second has passed.")}
}
20. 视图控制与导航
- StackView:堆叠视图,用于实现类似于页面导航的功能,支持推送、弹出页面,并维护一个历史堆栈。
- NavigationDrawer:导航抽屉,常用于展示可滑动的侧边栏菜单。
- TabView:标签视图,用于管理多个选项卡,每个选项卡展示不同的内容。
- TabBar:标签栏,通常与
TabView
搭配使用,用于切换不同的标签页。 - StackLayout:堆叠布局,允许子项按照层次叠加。
示例:
StackView {id: stackwidth: parent.widthheight: parent.heightinitialItem: page1
}Component {id: page1Rectangle {width: 200; height: 200color: "lightblue"Text {anchors.centerIn: parenttext: "Page 1"}MouseArea {anchors.fill: parentonClicked: stack.push(page2)}}
}Component {id: page2Rectangle {width: 200; height: 200color: "lightgreen"Text {anchors.centerIn: parenttext: "Page 2"}}
}
21. 动态加载与数据处理
- Loader:用于延迟加载组件,提升应用启动速度,尤其是对于大组件或复杂的QML对象。
- ListModel:数据模型,用于存储和操作动态数据,通常与
ListView
或GridView
结合使用。 - Repeater:通过重复某个项生成多个子项,通常与数据模型一起工作。
- SimpleListModel:一个简化的
ListModel
,适用于不需要复杂数据结构的场景。
示例:
ListView {width: 200; height: 400model: ListModel {ListElement { name: "Alice" }ListElement { name: "Bob" }ListElement { name: "Charlie" }}delegate: Item {width: parent.widthheight: 50Rectangle {width: parent.widthheight: 50color: "lightblue"Text {anchors.centerIn: parenttext: model.name}}}
}
22. 图表和数据可视化
- ChartView:用于绘制各种图表,如柱状图、折线图、饼图等。
- PieSeries:饼图系列,常用于展示百分比数据。
- BarSeries:柱状图系列,用于展示类别数据。
- LineSeries:折线图系列,用于展示随时间变化的数据。
- ScatterSeries:散点图系列,用于显示离散数据点。
- HeatMap:热力图,用于显示二维数据的热度分布。
示例:
ChartView {width: 400; height: 400BarSeries {BarSet { label: "Set 1"; values: [1, 2, 3, 4, 5] }}
}
23. 图像处理与滤镜
- ImageFilter:图像滤镜,允许开发者对图片进行多种处理,例如模糊、锐化等效果。
- DropShadowEffect:为元素添加阴影效果,增强视觉层次感。
- Gradient:渐变,用于背景或元素的颜色过渡。
- RadialGradient:径向渐变,颜色从中心点向外扩展。
- LinearGradient:线性渐变,颜色沿一条直线过渡。
示例:
Rectangle {width: 200; height: 200gradient: Gradient {GradientStop { position: 0.0; color: "red" }GradientStop { position: 1.0; color: "yellow" }}
}
24. 交互式控件和动态输入
- TextField:单行文本输入框,适用于用户输入。
- TextArea:多行文本输入框,适用于较长的文本输入。
- SpinBox:允许用户通过上下按钮选择一个数值。
- Slider:滑动条,允许用户通过滑动来选择数值。
- ComboBox:下拉框,允许用户从下拉列表中选择一个项。
- ProgressBar:进度条,用于显示任务进度。
示例:
TextField {width: 200placeholderText: "Enter text"
}ComboBox {width: 200model: ListModel {ListElement { name: "Option 1" }ListElement { name: "Option 2" }ListElement { name: "Option 3" }}delegate: Item {width: parent.widthheight: 50Rectangle {width: parent.widthheight: 50color: "lightgray"Text {anchors.centerIn: parenttext: model.name}}}
}
25. 文件与资源管理
- FileDialog:文件对话框,用于选择文件或目录,支持打开、保存等操作。
- ColorDialog:颜色选择对话框,允许用户选择颜色。
- FileSelector:文件选择器,用于选择文件或路径。
- ImageProvider:图像提供者,用于动态加载图像,支持本地和网络路径。
- ContextMenu:右键菜单,用于展示常用操作。
示例:
FileDialog {id: fileDialogtitle: "Open File"onAccepted: {console.log("File selected:", fileDialog.fileUrl)}
}Button {text: "Open File Dialog"onClicked: fileDialog.open()
}
26. 图形与几何
- Path:定义路径,用于绘制复杂图形(如曲线、直线等)。
- Shape:自定义形状,用路径定义几何形状。
- Polygon、Circle、Line:分别用于绘制多边形、圆形和直线。
- Ellipse:绘制椭圆形状。
- Arc:绘制弧形。
示例:
Shape {width: 200; height: 200ShapePath {strokeColor: "blue"path: Path {moveTo(10, 10)arcTo(100, 100, 0, 0, 1, 150, 150)}}
}
27. 焦点与输入管理
- FocusScope:设置焦点范围,限制哪些控件可以获取焦点。
- FocusHandler:处理控件的焦点切换,管理多个控件的焦点。
- FocusIndicator:焦点指示器,用于显示当前焦点所在的控件。
- FocusArea:焦点区域,帮助管理焦点的分配。
示例:
FocusScope {TextField {focus: true}Rectangle {width: 100; height: 100color: "lightblue"}
}
28. 多媒体支持
- SoundPlayer:用于播放声音文件,支持音频的控制(如播放、暂停、停止等)。
- Video:播放视频,支持控制视频的播放、暂停和跳转。
- ImageViewer:图像查看器,支持查看和缩放图片。
示例:
SoundPlayer {source: "sound.mp3"onStatusChanged: {if (status == SoundPlayer.Ready) {play()}}
}Video {source: "video.mp4"width: 400; height: 300onStatusChanged: {if (status == Video.Playing) {console.log("Video is playing.")}}
}
- NumberAnimation
分类: 动画组件
用途和功能:NumberAnimation
是一种用于数值属性的动画,当属性的数值发生改变时,可以通过插值产生平滑过渡效果 (NumberAnimation QML Type | Qt Quick 5.15.1)。例如改变矩形的坐标或大小时,可用 NumberAnimation 在一定时长内逐渐变化,避免瞬间跳变。
基本使用方式: 通常将NumberAnimation
绑定到某个数值属性上(使用语法 “NumberAnimation on <属性>
”),指定目标值范围(from
/to
)和持续时间(duration
)等。动画触发时会在起始值和目标值之间插值变化,可配合状态切换或属性绑定自动执行。
代码示例: 下面示例将一个矩形的横坐标x
从当前值动画到 50,耗时1秒:
Rectangle {width: 100; height: 100; color: "red"NumberAnimation on x { to: 50; duration: 1000 }
}
- ColorAnimation
分类: 动画组件
用途和功能:ColorAnimation
用于在颜色属性变化时提供平滑过渡 (ColorAnimation QML Type | Qt for MCUs 2.8.2)。当一个物体的颜色需要从一种渐变为另一种时,ColorAnimation 可以在指定时长内插值颜色值,实现渐变效果。
基本使用方式: 将ColorAnimation
绑定到颜色属性(如color
)上,设置目标颜色值(to
)和动画时长等。当属性值改变时,动画会在起始颜色和目标颜色之间平滑过渡。也可在状态转换或行为中使用,以在状态切换时自动渐变颜色。
代码示例: 将矩形的颜色从当前的红色动画过渡到黄色,持续1秒:
Rectangle {width: 100; height: 100; color: "red"ColorAnimation on color { to: "yellow"; duration: 1000 }
}
- RotationAnimation
分类: 动画组件
用途和功能:RotationAnimation
用于在旋转角度属性变化时执行动画。它是专门用于旋转的属性动画,可以控制旋转方向和路径 (RotationAnimation QML Type | Qt Quick 6.8.3)。例如当需要使物体旋转一定角度时,通过 RotationAnimation 可指定顺时针或逆时针方向以及是否走最短路径。
基本使用方式: 将RotationAnimation
绑定到物体的rotation
属性上,设置目标角度(to
)和持续时间,并可通过direction
属性指定旋转方向(顺时针或逆时针)。当 rotation 值改变时,动画会按照指定方向逐步旋转到目标角度。
代码示例: 点击矩形时将其旋转360度(顺时针方向),以1秒完成旋转:
Rectangle {id: rect; width: 100; height: 50; color: "skyblue"RotationAnimation on rotation { to: 360; duration: 1000; direction: RotationAnimation.Clockwise }MouseArea { anchors.fill: parent; onClicked: rect.rotation = 360 }
}
- SequentialAnimation
分类: 动画组件
用途和功能:SequentialAnimation
用于按顺序播放多个动画 (SequentialAnimation QML Type | Qt Quick 6.8.3)。当将多个子动画(例如 NumberAnimation、ColorAnimation 等)放入 SequentialAnimation 时,它们会一个接一个地依次执行。这常用于需要串联动画效果的场景,比如先移动再缩放。
基本使用方式: 在SequentialAnimation
内声明一系列动画元素,这些动画会按照声明顺序顺次播放。可以通过设置SequentialAnimation.running
来启动整个序列,序列中的前一个动画结束后才会开始下一个。
代码示例: 将矩形依次先水平移动到 x=50,然后垂直移动到 y=50,每步耗时1秒:
Rectangle {id: rect; width: 100; height: 100; color: "red"SequentialAnimation {running: true // 自动开始动画序列NumberAnimation { target: rect; property: "x"; to: 50; duration: 1000 }NumberAnimation { target: rect; property: "y"; to: 50; duration: 1000 }}
}
- ParallelAnimation
分类: 动画组件
用途和功能:ParallelAnimation
用于同时并行地播放多个动画 (SequentialAnimation QML Type | Qt Quick 6.8.3)。将多个子动画添加到 ParallelAnimation 中,这些动画会同时开始、同时进行,用于需要多个属性同步变化的情况,例如同时改变位置和缩放。
基本使用方式: 在ParallelAnimation
内列出多个动画元素,这些动画会并行执行。和 SequentialAnimation 不同,ParallelAnimation 中各动画会同时启动,不等待彼此完成。可以结合状态转换或直接设置running
来触发并行动画。
代码示例: 同时改变矩形的位置和颜色,两个动画并行运行:
Rectangle {id: rect; width: 100; height: 100; color: "blue"ParallelAnimation {running: trueNumberAnimation { target: rect; property: "x"; to: 80; duration: 1000 }ColorAnimation { target: rect; property: "color"; to: "green"; duration: 1000 }}
}
- PauseAnimation
分类: 动画组件
用途和功能:PauseAnimation
会在动画序列中插入一个“空等待”步骤,即暂停指定时长而不做任何变化 (PauseAnimation QML Type | Qt Quick 6.8.3)。它常与 SequentialAnimation 配合使用,用来在两个动画之间加一个停顿间隔。
基本使用方式: 在 SequentialAnimation 中加入PauseAnimation
元素,并设置其duration
属性(暂停时间,毫秒)。当执行到该步骤时,动画会静止等待相应时长,然后再继续后续动画。
代码示例: 将两个方块依次改变颜色,中间插入0.5秒的停顿:
SequentialAnimation {Rectangle { id: box; width: 50; height: 50; color: "yellow" }ColorAnimation { target: box; property: "color"; to: "red"; duration: 500 }PauseAnimation { duration: 500 } // 等待0.5秒ColorAnimation { target: box; property: "color"; to: "green"; duration: 500 }
}
- Behavior
分类: 动画组件
用途和功能:Behavior
定义属性变化时默认应用的动画效果 (Behavior QML Type | Qt Quick 5.7)。也就是说,当某个属性值发生改变时,如果为其设置了 Behavior,则会自动运行内部指定的动画,使属性平滑过渡到新值。Behavior 常用于为属性赋值添加平滑动画,而不需要手动启动动画。
基本使用方式: 在元素内使用Behavior on <属性>
来声明,对应属性每次变动时都会触发 Behavior 包含的动画。需要在 Behavior 内指定一个动画(如 NumberAnimation),可选地设置启用/禁用状态(enabled
)。注意一个属性同时只能有一个 Behavior,如需多个动画可在 Behavior 内使用 ParallelAnimation 或 SequentialAnimation 组合。
代码示例: 当矩形宽度变化时自动应用动画,使宽度渐变:
Rectangle {id: rect; width: 100; height: 100; color: "red"Behavior on width { NumberAnimation { duration: 1000 } }MouseArea {anchors.fill: parentonClicked: rect.width = rect.width == 100 ? 200 : 100 // 点击切换宽度}
}
- SmoothedAnimation
分类: 动画组件
用途和功能:SmoothedAnimation
是NumberAnimation
的特殊形式,用于在目标值频繁变化时保持平滑跟随 (SmoothedAnimation QML Type | Qt Quick 6.8.3)。它会根据属性当前变化的速度,平滑衔接新旧目标值的动画曲线,从而避免生硬跳跃。例如一个对象连续移动目标发生改变时,SmoothedAnimation 可使其运动路线更自然。
基本使用方式: 一般结合 Behavior 使用,将属性的 Behavior 动画设为 SmoothedAnimation,并通过设置velocity
(速度)或duration
控制动画跟随速度。当属性目标值不断更新时,SmoothedAnimation 会自动调整动画,使对象平滑移动到最新目标。
代码示例: 使一个绿色方块平滑跟随红色方块的位置变化:
Rectangle {id: leader; width: 40; height: 40; color: "red"// 可以通过键盘或鼠标改变 leader 的位置
}
Rectangle {id: follower; width: 40; height: 40; color: "green"// 跟随 leader 的坐标,使用 SmoothedAnimation 实现平滑过渡x: leader.x; y: leader.yBehavior on x { SmoothedAnimation { velocity: 200 } }Behavior on y { SmoothedAnimation { velocity: 200 } }
}
- SpringAnimation
分类: 动画组件
用途和功能:SpringAnimation
使属性值以弹簧振荡的效果过渡,带有弹性和阻尼的物理动画 (SpringAnimation QML Type | Qt Quick 6.8.3)。当目标值改变时,对象会像连着弹簧一样先过冲后回摆,逐渐稳定到目标值。弹性动画常用于制造具有物理拟真感的过渡效果,例如按钮弹跳或列表回弹。
基本使用方式: 将SpringAnimation
作为属性动画使用,通常配合 Behavior 或状态转换。当属性变化时,SpringAnimation 根据设定的弹性系数(spring
)和阻尼系数(damping
)计算运动轨迹。可以限制最大速度(velocity
)等参数来调整弹性力度和振幅衰减速度。
代码示例: 点击空白处使方块弹性移动到点击位置:
Item {width: 300; height: 300Rectangle {id: rect; width: 50; height: 50; color: "orange"// 为 x 和 y 属性添加弹性动画行为Behavior on x { SpringAnimation { spring: 2; damping: 0.2 } }Behavior on y { SpringAnimation { spring: 2; damping: 0.2 } }}MouseArea {anchors.fill: parentonClicked: {// 将矩形移动到点击处,弹性动画会自动执行rect.x = mouse.x - rect.width/2rect.y = mouse.y - rect.height/2}}
}
- PathAnimation
分类: 动画组件
用途和功能:PathAnimation
可以使物件沿预定义的路径运动 (Qt Quick QML Types - Felgo)。通过指定一条由若干路径段(PathLine、PathArc 等)构成的路径,以及目标物件和周期参数,PathAnimation 会在路径上移动目标物件。常用于实现复杂轨迹动画,如沿曲线移动的效果。
基本使用方式: 在PathAnimation
中设置target
(目标元素)、path
(路径定义)和持续时间等属性。路径使用Path { ... }
元素定义,由一系列 Path 子元素组成。可以设置动画的循环(loops
)次数或是否往返(yoyo
)。启动动画后,目标将按路径坐标依序运动。
代码示例: 让一个小球沿三角形路径循环运动:
Rectangle {width: 200; height: 200Rectangle { id: ball; width: 20; height: 20; color: "purple"; radius: 10 }PathAnimation {target: ball; duration: 3000; loops: Animation.Infinitepath: Path {startX: 100; startY: 20PathLine { x: 180; y: 180 } // 直线路径PathLine { x: 20; y: 180 }PathLine { x: 100; y: 20 }}}
}
- State
分类: 状态配置组件
用途和功能:State
用于定义界面元素的一组属性配置,可以让元素在不同状态间切换属性值集合 (State QML Type | Qt Quick 6.8.3)。每个元素默认有一个基础状态,通过添加State
对象到其states
列表,可以描述在特定状态下属性如何变化(例如位置、颜色或可见性改变)。状态之间切换时,可配合 Transition 实现动画过渡。
基本使用方式: 在元素的states
属性中添加一个或多个State
,为每个 State 指定name
(状态名)以及一系列属性更改(使用子元素如PropertyChanges
或AnchorChanges
等描述)。可以使用when
表达式自动切换状态(当条件为真时进入该状态) (State QML Type | Qt Quick 6.8.3)。也可通过直接设置元素的state
属性(赋值状态名)来触发状态切换。
代码示例: 点击切换矩形的颜色状态(默认黑色和“clicked”红色):
Rectangle {id: myRect; width: 100; height: 100; color: "black"MouseArea {anchors.fill: parentonClicked: myRect.state = (myRect.state == "clicked" ? "" : "clicked")}states: [State {name: "clicked"PropertyChanges { target: myRect; color: "red" }}]
}
- Transition
分类: 动画过渡组件
用途和功能:Transition
定义状态切换时应用的动画效果 (Transition QML Type | Qt Quick 5.15.1)。当元素从一种 State 切换到另一种 State 时,若匹配相应的 Transition,则其中包含的动画会在属性变化过程中执行,使状态变化过程平滑可视。例如在状态A到状态B的切换中为位置和颜色变化添加过渡动画。
基本使用方式: 在元素的transitions
列表中添加Transition
,可选设置from
和to
状态名(限制仅在特定状态切换时应用),并在内部定义一个或多个动画(如 NumberAnimation 等)用于属性过渡。Transition 会在状态改变发生时自动触发对应动画。若多个 Transition 条件重叠,reversible
等属性可控制行为。
代码示例: 定义矩形在默认状态和“moved”状态切换时位置平滑移动:
Rectangle {id: rect; width: 100; height: 100; color: "orange"MouseArea { id: area; anchors.fill: parent }states: State {name: "moved"; when: area.pressedPropertyChanges { target: rect; x: 50; y: 50 }}transitions: Transition {NumberAnimation { properties: "x,y"; duration: 500; easing.type: Easing.InOutQuad }}
}
- Audio
分类: 多媒体组件
用途和功能:Audio
元素用于在 QML 中播放音频(音乐或声音)文件。它提供简便的音频播放功能,可指定音频源(文件或流 URL)、控制播放(播放/暂停/停止)以及音量等属性。适合用于背景音乐或一般音频内容的播放。
基本使用方式: 在 QML 中声明一个Audio
元素,设置其source
为音频文件路径或 URL。可以通过调用其方法play()
、pause()
、stop()
来控制播放,也可设置autoPlay
在加载后自动播放。volume
属性控制音量大小(0.0~1.0)。当需要响应播放状态变化时,可连接其信号如playing
,paused
等进行处理。
代码示例: 点击按钮播放一段音乐:
Button {text: "播放音乐"Audio { id: bgm; source: "music.mp3"; volume: 0.8 }onClicked: bgm.play()
}
- SoundEffect
分类: 多媒体组件
用途和功能:SoundEffect
专用于播放短促的音效(通常为未压缩的 WAV 文件),具有低延迟的特点 (SoundEffect QML Type | Qt Multimedia 5.12.8)。它适合用于按钮点击音、通知提示等需要即时响声反馈的场景。如果对延迟不敏感,也可以使用 Audio 或 MediaPlayer 播放各种格式的音频 (SoundEffect QML Type | Qt Multimedia 5.12.8)。SoundEffect 在加载后常驻内存,以便快速播放。
基本使用方式: 在 QML 中创建SoundEffect
对象,设置音频文件的source
(通常为短 WAV 文件)。可选地设置loops
以控制播放次数(默认为1,设为Infinity
可循环),以及音量volume
。调用play()
方法即可播放音效。由于 SoundEffect 会预加载音频数据,建议重复使用同一个实例来避免重复加载。
代码示例: 按钮点击时播放“叮”音效:
SoundEffect { id: dingSound; source: "ding.wav"; volume: 0.9 }
Button {text: "点我"onClicked: dingSound.play() // 点击按钮时播放音效
}
- MediaPlayer
分类: 多媒体组件
用途和功能:MediaPlayer
是底层多媒体播放组件,用于在后台管理音视频的播放。它本身不提供可视界面,通常与VideoOutput
搭配显示视频画面。MediaPlayer 支持多种媒体格式,可以控制播放进度、状态、音量等,并发出播放状态改变的信号。适合需要更灵活控制或与自定义输出结合的场景。
基本使用方式: 在 QML 中声明MediaPlayer
,设置媒体源 (source
可以是文件路径或流 URL)。如需视频输出,将 MediaPlayer 的实例赋给VideoOutput
的source
属性。通过调用play()
、pause()
、stop()
控制播放,使用position
属性调整进度,volume
控制音量。结合PlaybackState
枚举和信号可以监控播放状态。
代码示例: 使用 MediaPlayer 播放视频并输出到界面:
MediaPlayer { id: player; source: "movie.mp4"; autoPlay: true }
VideoOutput { source: player; anchors.fill: parent }
- VideoOutput
分类: 多媒体组件
用途和功能:VideoOutput
用于在界面上呈现视频画面。它本身是一个可视元素,需绑定一个媒体源(如 MediaPlayer 或 Camera),才能显示其视频流。VideoOutput 可以调整填充模式(拉伸、保持宽高比等)以及旋转、镜像等属性,用于将媒体内容绘制到 QML 场景中。
基本使用方式: 将VideoOutput
的source
属性连接到一个输出视频流的对象上,例如MediaPlayer
、Camera
或ScreenCapture
。将 VideoOutput 放入界面布局中并设置适当大小。通过fillMode
可以控制视频如何适配显示区域(如VideoOutput.PreserveAspectFit
等)。在 Qt 6 中通常通过CaptureSession
将 Camera 和 VideoOutput 关联,但在 Qt 5 中可以直接将 Camera赋给 VideoOutput。
代码示例: 将摄像头画面显示在界面上:
Camera { id: cam; active: true }
VideoOutput { source: cam; anchors.fill: parent; fillMode: VideoOutput.PreserveAspectFit }
- Video
分类: 多媒体组件
用途和功能:Video
是对 MediaPlayer+VideoOutput 功能的封装型组件,提供简单的视频播放能力 (Video QML Type | Qt Multimedia 5.15.18)。使用Video
元素可以直接播放视频而无需手动组合 MediaPlayer 和 VideoOutput,非常方便地用于播放本地视频文件或流媒体内容。它支持控制播放、暂停、停止、音量以及进度等。
基本使用方式: 在 QML 中使用Video
元素,设置source
为视频文件或流的 URL。可通过属性控制如自动播放(autoPlay
)、循环次数(loops
)等,使用方法如play()
、pause()
控制播放。Video 元素会自身创建视频输出界面,因此只需将它放入布局即可。
代码示例: 点击区域控制视频播放和暂停:
Video {id: videoPlayersource: "sample.mp4"width: 800; height: 600; autoPlay: falseMouseArea {anchors.fill: parentonClicked: {videoPlayer.playbackState === MediaPlayer.PlayingState ? videoPlayer.pause() : videoPlayer.play()}}
}
- Camera
分类: 多媒体组件
用途和功能:Camera
提供对设备摄像头的访问,允许在 QML 中捕获实时视频流或拍照。通过 Camera 元素可以选择前/后摄像头,设置分辨率、焦距、闪光灯等参数,并将视频流输出到界面显示或录制保存。它与VideoOutput
配合可实现摄像头预览画面,与ImageCapture
、VideoRecorder
等协同可拍照或录像。
基本使用方式: 在 QML 中添加Camera
元素,并设置其属性如active
(开始捕获)等。如果使用 Qt 5,直接将 Camera 赋给VideoOutput.source
即可显示预览;在 Qt 6 中,需要使用CaptureSession
将 Camera 和 VideoOutput 关联在一起。可以使用camera.cameraDevice
选择特定摄像头。拍照可借助ImageCapture
,录像可通过MediaRecorder
(Qt6) 或 Camera 自带方法(Qt5)。
代码示例: 简单地显示摄像头预览画面:
Camera { id: camera; active: true }
VideoOutput { source: camera; anchors.fill: parent }
(注:在Qt6中需通过 CaptureSession 连接 Camera 和 VideoOutput。)
- RowLayout
分类: 布局组件
用途和功能:RowLayout
在水平方向上排列子元素,将它们放置在同一行内 ([
Resizing UIs with QML Layouts | DMC, Inc.
](https://www.dmcinfo.com/latest-thinking/blog/id/10393/resizing-uis-with-qml-layouts#:~:text=,or%20bottom%20to%20top))。与基础的 Row 定位器不同,RowLayout 属于 Qt Quick Layouts 模块,支持自动调整子元素尺寸、对齐方式和弹性伸展等特性。当容器大小改变时,RowLayout 内的元素会根据各自的最小/最大/首选宽度等属性重新分配空间。
基本使用方式: 在 QML 中用 RowLayout
包裹需要横向排列的子元素。可以通过附加属性(如 Layout.preferredWidth
、Layout.minimumWidth
等)为子元素设置布局约束。还可设置 spacing
控制元素间距,layoutDirection
控制排列方向(左到右或右到左)。RowLayout 自身通常需要指定大小(例如锚定填满父容器)以约束布局区域。
代码示例: 将两个矩形水平排列,并指定它们的首选宽度:
RowLayout {anchors.fill: parentspacing: 10Rectangle {color: "teal"Layout.preferredWidth: 100; Layout.preferredHeight: 50}Rectangle {color: "orange"Layout.preferredWidth: 150; Layout.preferredHeight: 50}
}
- ColumnLayout
分类: 布局组件
用途和功能:ColumnLayout
在垂直方向上排列子元素,将它们依次放置在一列中 ([
Resizing UIs with QML Layouts | DMC, Inc.
](https://www.dmcinfo.com/latest-thinking/blog/id/10393/resizing-uis-with-qml-layouts#:~:text=,or%20bottom%20to%20top))。它与 RowLayout 类似,但方向为上下排列。ColumnLayout 同样支持子元素的大小约束和自动伸展,可以在父容器高度变化时重新分配每个子元素的高度,使布局自适应。常用于创建竖向排列的表单控件、按钮列表等界面。
基本使用方式: 使用 ColumnLayout
容器包含需要竖直排列的多个子元素,通过附加的 Layout
属性来约束每个子元素的高度或宽度。可以设置整体的 spacing
控制垂直间隔,layoutDirection
控制从上到下(默认)或下到上排列。将 ColumnLayout 锚定或限定高度后,子元素会依据其最小/首选高度进行排布,多余空间可按伸展系数分配。
代码示例: 将两个不同高度的文本框垂直排列:
ColumnLayout {width: 200; spacing: 8TextField {placeholderText: "用户名"Layout.preferredHeight: 40}TextField {placeholderText: "密码"Layout.preferredHeight: 40}
}
- GridLayout
分类: 布局组件
用途和功能:GridLayout
将子元素放入网格中,按行列排列布局 ([
Resizing UIs with QML Layouts | DMC, Inc.
](https://www.dmcinfo.com/latest-thinking/blog/id/10393/resizing-uis-with-qml-layouts#:~:text=,only%20one%20row%20or%20column))。它会依次将子元素填充到网格的单元格里,当 GridLayout 尺寸改变时,各单元格的布局会自动调整。RowLayout 和 ColumnLayout 可以看作是只有一行或一列的特殊网格布局 ([
Resizing UIs with QML Layouts | DMC, Inc.
](https://www.dmcinfo.com/latest-thinking/blog/id/10393/resizing-uis-with-qml-layouts#:~:text=,only%20one%20row%20or%20column))。GridLayout 常用于需要二维网格排列控件的场景,比如表格表单等。
基本使用方式: 在 QML 中使用 GridLayout
容器,并通过其 rows
或 columns
属性设定网格尺寸(可不显式设置,默认根据子元素数量自适应)。子元素按照声明顺序依次填充格子,或者可以为每个子元素设置附加属性 Layout.row
和 Layout.column
来指定位置。也可使用 rowSpan
/columnSpan
附加属性让元素跨行或跨列。GridLayout 同样支持子元素的最小/最大/首选大小约束和间距等属性。
代码示例: 将四个矩形放入2x2网格布局:
GridLayout {columns: 2; spacing: 5Rectangle { color: "red"; Layout.preferredWidth: 50; Layout.preferredHeight: 50 }Rectangle { color: "green"; Layout.preferredWidth: 50; Layout.preferredHeight: 50 }Rectangle { color: "blue"; Layout.preferredWidth: 50; Layout.preferredHeight: 50 }Rectangle { color: "yellow";Layout.preferredWidth: 50; Layout.preferredHeight: 50 }
}
- StackLayout
分类: 布局组件
用途和功能:StackLayout
提供堆叠布局,一次只显示其中的一个子元素,相当于一组“页面”或“选项卡” ([
Resizing UIs with QML Layouts | DMC, Inc.
](https://www.dmcinfo.com/latest-thinking/blog/id/10393/resizing-uis-with-qml-layouts#:~:text=There%20is%20one%20more%20QML,on%20your%20own))。它适用于在相同空间区域切换不同内容,比如实现选项卡界面或多步骤表单。StackLayout 的子元素都会叠放在一起,但只有当前索引(currentIndex
)对应的子元素可见。
基本使用方式: 将多个子项目直接放入 StackLayout
中,子元素的位置和大小通常跟随 StackLayout(例如填满)。通过更改 StackLayout 的 currentIndex
或使用方法 setCurrentIndex()
来切换显示哪一个子元素。非当前显示的子元素会被隐藏。StackLayout 本身也支持附加的 Layout 属性,可嵌套在其它布局中使用。
代码示例: 两个页面组件叠放,只显示当前索引的一个:
StackLayout {id: pagesanchors.fill: parentPage { /* 第一个页面内容 */ }Page { /* 第二个页面内容 */ }
}
Button {text: "切换页面"onClicked: pages.currentIndex = (pages.currentIndex + 1) % 2
}
- Shape
分类: 几何图形组件
用途和功能:Shape
提供在 QML 中绘制矢量图形的能力。它通过描述路径并使用 GPU 对路径进行三角形填充来渲染图形,比用 Canvas 绘制具有更高的性能和平滑度 (Shape QML Type | Qt Quick 6.8.3)。开发者可以使用 Shape 绘制任意形状的轮廓和填充,例如多边形、曲线等,在界面中展示自定义图形元素。
基本使用方式: 使用Shape
元素容纳一个或多个ShapePath
子元素。每个 ShapePath 定义一条要绘制的路径及其样式(填充和描边)。Shape 没有锚点属性但可以像 Item 一样定位,可通过设置其宽高或使用路径的范围来决定绘图区域大小。需要注意,Shape默认不自动调整大小以包裹内容,可结合BoundingRect
获取路径范围调整。
代码示例: 绘制一个填充黄色、描边黑色的三角形:
Shape {width: 200; height: 200 // 定义绘制区域大小ShapePath {strokeWidth: 2strokeColor: "black"fillColor: "yellow"path: Path {startX: 100; startY: 20 // 起点PathLine { x: 180; y: 180 } // 底边右端点PathLine { x: 20; y: 180 } // 底边左端点PathLine { x: 100; y: 20 } // 回到起点(闭合三角形)}}
}
- ShapePath
分类: 几何图形组件
用途和功能:ShapePath
定义了 Shape 中的一条绘制路径及其样式。它包括路径几何和绘制属性,如描边颜色/宽度、虚线样式、填充颜色或渐变等。一个 Shape 可以包含多个 ShapePath,相当于在同一图形中绘制多层路径,各自拥有独立的样式。由于 ShapePath 是特殊处理的,可与其它普通元素一同成为 Shape 的子元素 (Shape QML Type | Qt Quick 6.8.3) (Shape QML Type | Qt Quick 6.8.3)。
基本使用方式: 在Shape
内部添加一个ShapePath
元素。通过其属性设置绘制样式,例如strokeColor
(边框颜色)、strokeWidth
(边框线宽)、fillColor
或fillGradient
(填充)。使用path
属性指定路径数据,一般赋值一个Path { ... }
对象,内部由若干 Path 段构成。ShapePath 也支持strokeStyle
等高级样式属性。多个 ShapePath 会按照声明顺序绘制(后面的覆盖前面的填充区域)。
代码示例: 绘制一条红色虚线斜线:
Shape {width: 200; height: 200ShapePath {strokeColor: "red"; strokeWidth: 4strokeStyle: ShapePath.DashLine // 虚线样式dashPattern: [4, 4] // 虚线长度模式path: Path {startX: 20; startY: 180PathLine { x: 180; y: 20 } // 从左下到右上的一条斜线}}
}
- Path
分类: 几何图形组件(路径定义)
用途和功能:Path
用于定义一系列连贯的二维路径段。它本身并不渲染,可看作路径的容器,由一个起点和若干后续路径元素(如直线、曲线、弧等)组成 (Path QML Type | Qt Quick 6.8.3)。在 QML 中,Path 主要用于两种场景:一是在 Shape/ShapePath 中定义矢量图形路径,二是在 PathView(视图组件)中指定项目排列的曲线路径。
基本使用方式: 在 QML 中通过声明Path { startX: ..., startY: ...; <若干路径段元素> }
来定义路径。startX
、startY
指定路径起点坐标,然后添加不同类型的路径段(如PathLine
、PathQuad
等)来构建完整路径。各段按顺序首尾相接。Path 不可独立显示,需配合 ShapePath 或 PathAnimation、PathView 等一起使用,其坐标通常相对于使用它的元素坐标系。
代码示例: 定义一条由直线和曲线组成的路径:
Path {startX: 0; startY: 0PathLine { x: 100; y: 0 } // 从 (0,0) 到 (100,0) 的直线PathQuad { x: 150; y: 50; controlX: 100; controlY: 50 } // 从直线终点到 (150,50) 的二次贝塞尔曲线PathCubic { x: 200; y: 100;control1X: 150; control1Y: 100;control2X: 180; control2Y: 80 } // 接着到 (200,100) 的三次贝塞尔曲线
}
- PathLine
分类: 几何图形组件(路径段)
用途和功能:PathLine
表示路径中的一段直线。它将当前路径点连接到指定的目标坐标,绘制一条直线路径段。在 Path 定义中使用 PathLine,可以简单明了地连接两个点,是路径构成中最基本的元素之一。
基本使用方式: 在Path
内添加PathLine { x: <终点X>; y: <终点Y> }
即可。PathLine可以有绝对坐标(x, y)或使用相对坐标(relativeX, relativeY)属性相对于当前点位移。加入 PathLine 后,路径的当前端点会更新为此 PathLine 的终点,为后续路径段提供起点。
代码示例: 使用 PathLine 绘制折线的一段:
Path {startX: 10; startY: 10PathLine { x: 100; y: 10 } // 从 (10,10) 到 (100,10) 的水平直线段PathLine { x: 100; y: 100 } // 接着从 (100,10) 到 (100,100) 的垂直直线段
}
- PathQuad
分类: 几何图形组件(路径段)
用途和功能:PathQuad
表示路径中的一段二次贝塞尔曲线。它从当前路径点出发,经过一个控制点,弯曲地连接到指定的终点,绘制出平滑的曲线路径段。二次贝塞尔曲线只有一个控制点,曲线形状相对简单,适合绘制平滑拱形等。
基本使用方式: 在Path
内添加PathQuad { x: <终点X>; y: <终点Y>; controlX: <控制点X>; controlY: <控制点Y> }
。控制点坐标决定曲线的弯曲程度和方向。和 PathLine 类似,可以使用相对坐标(relativeX 等)定义终点和控制点相对于当前点的偏移。添加 PathQuad 后,路径当前点更新为该曲线的终点。
代码示例: 绘制一段二次贝塞尔曲线路径:
Path {startX: 0; startY: 50// 从 (0,50) 到 (100,50) 绘制拱形曲线,控制点在 (50,0) 上方PathQuad { x: 100; y: 50; controlX: 50; controlY: 0 }
}
- PathCubic
分类: 几何图形组件(路径段)
用途和功能:PathCubic
表示路径中的一段三次贝塞尔曲线。它使用两个控制点来影响曲线形状,从当前点平滑弯曲地连接到指定终点。相比二次曲线,三次贝塞尔曲线能绘制更复杂和精细的曲线路径,常用于高质量的矢量图形绘制。
基本使用方式: 在Path
中加入PathCubic { x: <终点X>; y: <终点Y>; control1X: <控制点1 X>; control1Y: <控制点1 Y>; control2X: <控制点2 X>; control2Y: <控制点2 Y> }
。两个控制点一般分别影响曲线起点和终点附近的走势,使曲线更灵活。和其他路径段一样,可使用绝对或相对坐标。PathCubic 添加后,路径当前点更新为终点。
代码示例: 绘制一段带两个控制点的三次贝塞尔曲线:
Path {startX: 0; startY: 0PathCubic {x: 150; y: 100control1X: 50; control1Y: 100 // 控制起点附近曲线走势control2X: 100; control2Y: 0 // 控制终点附近曲线走势}
}
- PathArc
分类: 几何图形组件(路径段)
用途和功能:PathArc
表示路径中的一段圆弧或椭圆弧曲线。它根据指定的终点和半径,沿椭圆弧连接当前点到目标点,形成圆滑的弧形段。PathArc 通常用于绘制圆角或圆形的一部分,可以通过参数控制绘制大弧还是小弧,以及顺时针或逆时针方向。
基本使用方式: 在Path
中加入PathArc { x: <终点X>; y: <终点Y>; radiusX: <椭圆半径X>; radiusY: <椭圆半径Y>; useLargeArc: <bool>; direction: <PathArc.Clockwise/Counterclockwise> }
。其中radiusX
、radiusY
决定椭圆形状,useLargeArc 指定绘制大于180度的长弧还是小于180度的短弧,direction 指定弧线方向。默认情况下将选择满足要求的弧段连接到终点。
代码示例: 绘制一段半径为50的四分之一圆弧:
Path {startX: 100; startY: 0// 从 (100,0) 绘制到 (0,100) 的四分之一圆弧(90度弧)PathArc {x: 0; y: 100radiusX: 100; radiusY: 100 // 半径相等形成圆弧useLargeArc: false // 使用小弧段direction: PathArc.Clockwise // 顺时针方向绘制}
}
- PathSvg
分类: 几何图形组件(路径段)
用途和功能:PathSvg
允许使用 SVG 路径数据字符串来定义路径段。它相当于直接按 SVG 的路径语法描绘形状,支持复杂路径的一次性描述。开发者可以把熟悉的 SVG “d”属性路径数据直接粘贴到 PathSvg 中,QML 会解析该字符串为对应的路径段序列。这样复杂图形不必逐段手写 PathLine/PathCubic 等。
基本使用方式: 在Path
内使用PathSvg { path: "<SVG路径数据字符串>" }
。其中path
字符串格式与 SVG 的路径数据相同,例如"M10 10 L100 100 C150 50 150 150 100 100 Z"
等等。PathSvg 解析后会按字符串描述添加所需的内部路径段,实现与 SVG 渲染一致的形状。使用 PathSvg 时,需要确保字符串格式正确,否则路径无法绘制。
代码示例: 使用 PathSvg 绘制心形的路径:
Path {// SVG 路径字符串:移动到 (50,15),绘制贝塞尔曲线形成心形并闭合路径PathSvg { path: "M50 15 C50 0, 90 0, 90 30 C90 60, 50 80, 50 95 C50 80, 10 60, 10 30 C10 0, 50 0, 50 15 Z" }
}