一、基础控件
| 控件名称 | 功能描述 | 示例代码 |
|---|---|---|
| Rectangle | 基础绘图控件，创建矩形区域 | Rectangle {width: 100; height: 100<br> color: "red"; radius: 5} |
| Text/Label | 文本显示控件 | Text {text: "Hello World";<br> font.pixelSize: 24} |
| Button | 交互按钮控件 | Button {text: "提交"; onClicked: console.log("点击")} |
| CheckBox | 多选框控件 | CheckBox {text: "同意协议"; checked: true} |
| RadioButton | 单选按钮控件 | RadioButton {text: "男"; ButtonGroup.group: genderGroup} |
| TextField | 单行文本输入框 | TextField {placeholderText: "用户名";maximumLength: 20} |
| TextArea | 多行文本输入框 | qml<br>TextArea {<br> text: "多行文本...";<br> wrapMode: Text.Wrap<br>} |
| ComboBox | 下拉选择框 | qml<br>ComboBox {<br> model: ["选项1", "选项2"]<br> currentIndex: 0<br>} |
| Slider | 滑动条控件 | qml<br>Slider {<br> from: 0; to: 100;<br> value: 50<br>} |
| ProgressBar | 进度条控件 | qml<br>ProgressBar {<br> value: 75;<br> to: 100<br>} |
| Image | 图片显示控件 | qml<br>Image {<br> source: "logo.png";<br> fillMode: Image.PreserveAspectFit<br>} |
| Switch | 开关切换控件 | qml<br>Switch {<br> checked: true;<br> onCheckedChanged: console.log(checked)<br>} |
| Delegate系列 | 列表项专用控件 | qml<br>ListView {<br> delegate: SwitchDelegate {<br> text: "选项"<br> }<br>} |
二、Rectangle
属性及方法说明：
| 属性/方法 | 类型 | 功能描述 | 示例代码 |
|---|---|---|---|
| antialiasing | bool | 控制抗锯齿效果，默认开启（若设置radius则强制开启） | Rectangle {antialiasing: false // 关闭抗锯齿} |
| border | group | 边框属性组，包含颜色和宽度 | Rectangle {border { color: "red"; width: 2 }} |
| border.color | color | 设置边框颜色（支持十六进制/RGB/颜色名） | border.color: "#FF0000" |
| border.width | int | 设置边框宽度（单位为像素，0表示无边框） | border.width: 5 |
| color | color | 设置矩形填充色（与gradient互斥，后者优先级更高） | color: "lightblue" |
| gradient | Gradient | 定义渐变填充（需配合GradientStop使用） | gradient: Gradient {GradientStop { position:0; color:"white" } GradientStop { position:1; color:"black" }} |
| radius | real | 设置圆角半径（可统一设置或分角设置） | radius: height/4 // 动态圆角// 或分角设置：topLeftRadius: 10; bottomRightRadius: 5 |
| clip | bool | 控制是否裁剪超出矩形范围的子内容（默认false） | clip: true // 启用裁剪 |
| contains(point) | method | 判断点是否在矩形内（参数为point对象） | if(rect.contains(Qt.point(10,10))) { ... } |
代码示例：
Rectangle {id: rectwidth: 200; height: 100color: "transparent"antialiasing: trueborder { color: "green"; width: 3 }radius: 10gradient: Gradient { //渐变GradientStop { position:0; color:"yellow" }GradientStop { position:1; color:"orange" }}// 方法调用示例Component.onCompleted: console.log(rect.contains(Qt.point(50,50)))}三、Text
属性及方法说明：
| 属性/方法 | 类型 | 功能描述 | 示例代码 |
|---|---|---|---|
| advance | size | 只读属性，返回字符基线间距（Qt 5.10+引入） | Text { text: "ABC"; onPainted: console.log(advance) } |
| antialiasing | bool | 抗锯齿开关（仅Text.NativeRendering渲染类型可禁用） | Text { text: "Hi"; antialiasing: false } |
| baseUrl | url | 设置相对URL的基础路径（用于富文本中的资源引用） | Text { text: "<img src='icon.png'>"; baseUrl: "qrc:/assets" } |
| clip | bool | 超出文本区域的内容裁剪（默认false） | Text { width:50; text:"LongText"; clip:true } |
| color | color | 文本颜色（支持十六进制/RGB/颜色名） | Text { text:"Red"; color:"#FF0000" } |
| contentHeight | real | 只读属性，返回文本实际高度（含换行） | Text { text:"Multi\nLine"; onPainted: console.log(contentHeight) } |
| elide | enum | 文本省略方式（ElideLeft/Right/Middle） | Text { width:80; text:"LongText"; elide:Text.ElideRight } |
| font.bold | bool | 控制字体加粗状态（true启用粗体） | Text { text:"Bold"; font.bold:true } |
| font.capitalization | enum | 文本大小写转换（支持AllUppercase/SmallCaps等模式） | Text { text:"hello"; font.capitalization:Font.AllUppercase } |
| font.family | string | 设置字体系列（如"Arial"） | Text { text:"Custom"; font.family:"Microsoft YaHei" } |
| font.hintingPreference | enum | 字体微调策略（PreferNone/PreferVerticalHinting等） | Text { text:"Hint"; font.hintingPreference:Font.PreferFullHinting } |
| font.italic | bool | 控制斜体显示 | Text { text:"Italic"; font.italic:true } |
| font.kerning | bool | 启用/禁用字符间距自动调整（默认true） | Text { text:"Kerning"; font.kerning:false } |
| font.letterSpacing | real | 字符间距（单位像素，可负值） | Text { text:"Spaced"; font.letterSpacing:1.5 } |
| font.pixelSize | int | 字体像素大小（与pointSize互斥，优先级更高） | Text { text:"Size24"; font.pixelSize:24 } |
| font.pointSize | real | 字体磅值大小（1磅=1/72英寸） | Text { text:"Point12"; font.pointSize:12 } |
| font.preferShaping | bool | 启用复杂文字排版（如阿拉伯语连字） | Text { text:"شكرا"; font.preferShaping:true } |
| font.strikeout | bool | 添加删除线 | Text { text:"Delete"; font.strikeout:true } |
| font.styleName | string | 指定字体变体（如"Light Condensed"） | Text { text:"Style"; font.styleName:"Semibold Italic" } |
| font.underline | bool | 添加下划线 | Text { text:"Underline"; font.underline:true } |
| font.weight | enum | 字体粗细（Font.Thin到Font.Black共9级） | Text { text:"Weight"; font.weight:Font.Bold } |
| font.wordSpacing | real | 单词间距（单位像素） | Text { text:"Word Space"; font.wordSpacing:5 } |
| horizontalAlignment | enum | 水平对齐（Text.AlignLeft/Right/HCenter） | Text { width:200; text:"Center"; horizontalAlignment:Text.AlignHCenter } |
| lineHeight | real | 行高倍数（需配合lineHeightMode使用） | Text { text:"Line\nHeight"; lineHeight:1.5; lineHeightMode:Text.ProportionalHeight } |
| renderType | enum | 渲染引擎类型（Text.QtRendering/NativeRendering） | Text { text:"Native"; renderType:Text.NativeRendering } |
| textFormat | enum | 文本格式（PlainText/RichText/AutoText） | Text { text:"<b>Bold</b>"; textFormat:Text.RichText } |
| wrapMode | enum | 换行模式（NoWrap/WordWrap/WrapAnywhere） | Text { width:100; text:"LongWord"; wrapMode:Text.WrapAnywhere } |
代码示例：
Text {text: "测试文本 Text"x: 200; y: 0font {family: "Arial" //字体italic: true //斜体letterSpacing: 1.2 //字符间距underline: true //下划线pixelSize: 16 //字体像素大小weight: Font.Medium //字体粗细}}四、Label
属性及方法说明：
| 属性 | 类型 | 功能描述 | 示例代码 |
|---|---|---|---|
| background | Item | 背景组件（可自定义矩形/图像等） | Label { background: Rectangle { color:"lightgray" } } |
| bottomInset | real | 底部内容插入距离（与bottomPadding配合使用） | Label { text:"Text"; bottomInset:5 } |
| implicitBackgroundHeight | real | 背景隐式高度（只读，根据内容自动计算） | Label.onImplicitBackgroundHeightChanged: console.log(implicitBackgroundHeight) |
| implicitBackgroundWidth | real | 背景隐式宽度（只读） | Label.onImplicitBackgroundWidthChanged: console.log(implicitBackgroundWidth) |
| leftInset | real | 左侧内容插入距离 | Label { text:"Text"; leftInset:10 } |
| palette | palette | 调色板配置（控制颜色主题） | Label { palette.windowText:"red" } |
| rightInset | real | 右侧内容插入距离 | Label { text:"Text"; rightInset:10 } |
| topInset | real | 顶部内容插入距离 | Label { text:"Text"; topInset:5 } |
代码示例：
Label {x: 400width: 200; height: 100text: "测试文本 Label"leftInset: 15rightInset: 15topInset: 8bottomInset: 8//支持任意Item类型作为背景元素background: Image {source: "file:///home/li/图片/1.png" //临时方案 正是qrc:/images/1.png 要确保.qrc文件中有对应条目images/1.png//opacity: 0.5}}四、Button
核心属性
| 属性 | 类型 | 功能描述 | 示例代码 |
|---|---|---|---|
| text | string | 按钮显示的文本内容 | Button { text: "提交" } |
| enabled | bool | 控制按钮是否可交互（默认true） | Button { enabled: false } |
| autoRepeat | bool | 长按时是否重复触发信号（默认false） | Button { autoRepeat: true } |
| icon.source | url | 按钮图标路径 | Button { icon.source: "qrc:/save.png" } |
| background | Item | 自定义背景元素 | Button { background: Rectangle { color: "blue" } } |
| font.pixelSize | int | 文本字体大小 | Button { font.pixelSize: 16 } |
| hoverEnabled | bool | 是否启用悬停效果（默认true） | Button { hoverEnabled: false } |
| checkable | bool | 是否支持切换状态（类似开关） | Button { checkable: true } |
| checked | bool | 当前选中状态（需checkable=true） | Button { checked: true } |
| flat | bool | 是否无边框扁平化样式 | Button { flat: true } |
信号/方法
| 信号/方法 | 触发条件 | 示例代码 |
|---|---|---|
| onClicked | 点击按钮时触发 | Button { onClicked: console.log("点击") } |
| onPressed | 按下鼠标时触发 | Button { onPressed: status.text="按下" } |
| onReleased | 释放鼠标时触发 | Button { onReleased: status.text="" } |
| onDoubleClicked | 双击按钮时触发 | Button { onDoubleClicked: zoomImage() } |
| onPressAndHold | 长按超过800ms时触发 | Button { onPressAndHold: showMenu() } |
| toggle() | 切换checkable按钮状态（编程控制） | Button { id: btn; onClicked: btn.toggle() } |
代码示例：
Button {x: 0; y: 110text: "渐变按钮"background: Rectangle {radius: 8color: parent.down ? "#4CAF50" : (parent.hovered ? "#8BC34A" : "#CDDC39")border.color: parent.pressed ? "#2196F3" : "transparent"Behavior on color { ColorAnimation { duration: 100 } }Behavior on border.color { ColorAnimation { duration: 200 } }}contentItem: Text {text: parent.textcolor: "white"font.bold: true}onClicked: console.log("点击事件触发")onPressed: console.log("按下状态")onReleased: console.log("释放状态")}五、CheckBox
核心属性
| 属性 | 类型 | 说明 | 示例代码 |
|---|---|---|---|
checked | bool | 当前选中状态（二态模式） | checked: true // 默认选中 |
checkState | enumeration | 三态模式状态（Qt.Unchecked/Checked/PartiallyChecked） | checkState: Qt.PartiallyChecked |
tristate | bool | 是否启用三态模式（默认false） | tristate: true // 启用部分选中状态 |
text | string | 显示的文本标签 | text: "启用功能" |
indicator | Item | 勾选框的视觉元素 | indicator.width: 20 // 调整勾选框大小 |
nextCheckState | function | 自定义状态切换逻辑 | 见下方代码示例 |
关键方法/信号
| 方法/信号 | 说明 | 触发条件 | 示例代码 |
|---|---|---|---|
toggled(checked) | 二态模式状态变化信号 | 选中状态改变时触发 | onToggled: console.log(checked) |
clicked() | 点击事件信号 | 用户点击时触发 | onClicked: console.log("点击") |
checkStateChanged() | 三态模式状态变化信号 | 三态值改变时触发 | onCheckStateChanged: console.log(checkState) |
代码示例：
CheckBox {id: chkx: 200; y: 110text: "高级选项"tristate: truecheckState: Qt.PartiallyCheckednextCheckState: function() {if (checkState === Qt.Unchecked)return Qt.PartiallyCheckedelse if (checkState === Qt.PartiallyChecked)return Qt.Checkedelsereturn Qt.Unchecked}onCheckStateChanged: {console.log("当前状态:",checkState === Qt.Unchecked ? "未选中" :checkState === Qt.Checked ? "全选" : "部分选中")}}六、RadioButton
核心属性
| 属性 | 类型 | 说明 | 示例代码 |
|---|---|---|---|
checked | bool | 当前选中状态 | checked: true // 默认选中 |
text | string | 显示文本标签 | text: "选项A" |
exclusiveGroup | ExclusiveGroup | 互斥分组对象 | exclusiveGroup: tabGroup |
indicator | Item | 单选按钮的视觉元素 | indicator.width: 20 |
autoExclusive | bool | 是否自动互斥（默认true） | autoExclusive: false // 禁用自动互斥 |
方法/信号
| 方法/信号 | 说明 | 示例代码 |
|---|---|---|
clicked() | 点击事件信号 | onClicked: console.log("选中状态:", checked) |
toggled(checked) | 状态变化信号 | onToggled: label.text = checked ? "已选" : "未选" |
代码示例：
// 互斥分组演示ButtonGroup {id: radioGroupexclusive: true // 默认true可不写onCheckedButtonChanged: {console.log("当前选择:", checkedButton.text)}}RadioButton {id: radio1x: 400; y: 110text: "选项A"ButtonGroup.group: radioGroup // 分组控制onClicked: if(checked) text = "选项A(已选)" // 点击信号}RadioButton {x: 400; y: 150text: "选项B"ButtonGroup.group: radioGrouponCheckedChanged: { // 状态变化信号if(checked){ console.log("选项B"); radio1.text = "选项A"}}}七、TextField
核心属性，方法，信号
| 类别 | 属性/方法 | 说明 | 示例 |
|---|---|---|---|
| 核心属性 | text | 存储当前文本内容 | TextField { text: "默认文本" } |
placeholderText | 空白时的提示文字 | placeholderText: "请输入用户名" | |
echoMode | 文本显示模式（密码/普通） | echoMode: TextInput.Password | |
| 外观控制 | font.pixelSize | 字体大小 | font { pixelSize: 16 } |
color | 文本颜色 | color: "#333333" | |
background | 自定义背景样式 | background: Rectangle { radius: 5 } | |
| 输入限制 | maximumLength | 最大输入长度 | maximumLength: 10 |
validator | 输入验证器 | validator: IntValidator { top: 100 } | |
inputMask | 输入格式掩码 | inputMask: "999.999.999" | |
| 交互控制 | readOnly | 只读模式 | readOnly: true |
selectByMouse | 允许鼠标选择文本 | selectByMouse: true | |
| 信号 | onTextChanged | 文本变化时触发 | onTextChanged: console.log(text) |
onAccepted | 按下回车时触发 | onAccepted: submit() | |
| 方法 | clear() | 清空文本 | button.onClicked: textField.clear() |
selectAll() | 全选文本 | onFocusChanged: if(focus) selectAll() | |
copy()/paste() | 剪贴板操作 | onDoubleClicked: copy() |
代码示例
TextField {id: demoFieldwidth: 200x: 0; y: 210placeholderText: "输入数字(1-100)"validator: IntValidator { bottom: 1; top: 100 }onAccepted: console.log("提交:", text)background: Rectangle {border.color: demoField.focus ? "blue" : "gray"radius: 5}}八、TextArea
核心属性，方法，信号
| 类别 | 属性/方法 | 类型/返回值 | 说明 | 示例 |
|---|---|---|---|---|
| 基础属性 | text | string | 存储的文本内容 | text: "默认内容" |
placeholderText | string | 空白时的灰色提示文本 | placeholderText: "输入描述..." | |
textFormat | enum (AutoText/RichText/PlainText) | 文本格式（支持富文本） | textFormat: TextEdit.RichText | |
| 外观控制 | font | group | 字体属性（family/pixelSize等） | font { family: "Arial"; pixelSize: 14 } |
color | color | 文本颜色 | color: "#333" | |
background | Item | 自定义背景项 | background: Rectangle { radius: 5 } | |
| 滚动与布局 | wrapMode | enum (NoWrap/WordWrap) | 换行模式 | wrapMode: TextArea.WordWrap |
contentWidth/contentHeight | real | 文本内容实际尺寸 | width: Math.max(200, contentWidth) | |
flickable (附属属性) | Flickable | 滚动容器关联属性 | ScrollView { TextArea { ... } } | |
| 交互控制 | readOnly | bool | 只读模式 | readOnly: true |
selectByMouse | bool | 允许鼠标选择文本 | selectByMouse: true | |
cursorPosition | int | 光标位置 | onClicked: cursorPosition = | |
| 信号 | onTextChanged | signal | 文本变化时触发 | onTextChanged: console.log(text) |
onLinkActivated | signal(link) | 点击富文本链接时触发 | onLinkActivated: Qt.openUrlExternally(link) | |
| 方法 | copy() | void | 复制选中文本 | button.onClicked: textArea.copy() |
paste() | void | 粘贴剪贴板内容 | onPressed: paste() | |
selectAll() | void | 全选文本 | onFocusChanged: selectAll() | |
deselect() | void | 取消选择 | onEditingFinished: deselect() |
代码示例：
TextArea {id: areax: 200; y: 210placeholderText: "支持富文本+自动滚动"textFormat: TextEdit.RichTextwrapMode: TextArea.WrapselectByMouse: truebackground: Rectangle {border.color: area.activeFocus ? "blue" : "gray"radius: 5}onLinkActivated: Qt.openUrlExternally(link)}九、ComboBox
核心属性，方法，信号
| 类别 | 属性/方法 | 类型/返回值 | 说明 | 示例 |
|---|---|---|---|---|
| 核心属性 | model | variant | 数据模型（数组/ListModel/整数） | model: ["A", "B", "C"] |
currentIndex | int | 当前选中项索引（-1表示未选中） | currentIndex: 1 | |
currentText | string | 当前选中项文本 | onActivated: console.log(currentText) | |
textRole | string | 指定模型中的文本角色名（需与模型角色严格匹配） | textRole: "text" | |
| 交互控制 | editable | bool | 是否允许编辑输入 | editable: true |
displayText | string | 控件显示文本（可自定义格式） | displayText: "已选: " + currentText | |
popup | Popup | 弹出窗口控制属性 | popup.width: 300 | |
| 外观定制 | delegate | Component | 自定义选项项样式 | 见下方完整示例 |
indicator | Component | 下拉箭头图标 | indicator: Image { source: "arrow.png" } | |
background | Component | 背景样式 | background: Rectangle { radius: 5 } | |
| 信号 | onActivated(int index) | signal | 选项被选中时触发 | onActivated: console.log(index) |
onAccepted() | signal | 编辑模式下回车确认时触发 | onAccepted: addItem(editText) | |
| 方法 | find(string text) | int | 查找文本对应的索引 | find("Apple") |
textAt(int index) | string | 获取指定索引的文本 | textAt(0) // 返回"A" | |
selectAll() | void | 全选编辑框文本 | onEditingFinished: selectAll() |
代码示例：
ComboBox {id: combowidth: 200x: 400; y: 210editable: truetextRole: "text"model: ListModel {ListElement { text: "Apple"; color: "red" }ListElement { text: "Banana"; color: "yellow" }}delegate: ItemDelegate {width: parent.widthcontentItem: Text {text: model.textcolor: model.colorfont.bold: combo.currentIndex === index}}onAccepted: if (find(editText) === -1) model.append({text: editText})}
十、Slider
核心属性，方法，信号
| 类别 | 属性/方法 | 类型/返回值 | 说明 | 示例 |
|---|---|---|---|---|
| 核心属性 | from | real | 滑块最小值 (默认0.0) | from: -100 |
to | real | 滑块最大值 (默认1.0) | to: 200 | |
value | real | 当前值 (介于from/to之间) | value: 50 | |
stepSize | real | 步长 (0表示连续滑动) | stepSize: 5 | |
orientation | enum | 方向 (Qt.Horizontal/Qt.Vertical) | orientation: Qt.Vertical | |
| 交互控制 | live | bool | 拖动时是否实时更新value (默认true) | live: false |
snapMode | enum | 吸附模式 (Slider.NoSnap/SnapOnRelease/SnapAlways) | snapMode: Slider.SnapAlways | |
pressed | bool | 只读，表示滑块是否被按下 | onPressedChanged: console.log(pressed) | |
position | real | 只读，逻辑位置 (0.0-1.0) | Text { text: (position*100).toFixed(0) + "%" } | |
| 样式属性 | background | Component | 滑槽背景组件 | 见下方自定义示例 |
handle | Component | 滑块手柄组件 | 见下方自定义示例 | |
| 方法 | increase() | void | 按stepSize增加value | Button { onClicked: slider.increase() } |
decrease() | void | 按stepSize减少value | Button { onClicked: slider.decrease() } | |
valueAt(real pos) | real | 根据位置比例返回对应值 | slider.valueAt(0.5) 返回中间值 | |
| 信号 | moved() | - | 滑块位置改变时触发 | onMoved: console.log("滑块移动中") |
valueChanged() | - | value属性改变时触发 | onValueChanged: model.rotation = value |
未完待续。。。
