Qt Quick 与 QML（三）qml中的基础控件

一**、******基础控件

控件名称‌	‌功能描述‌	‌示例代码‌
‌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: rect
        width: 200; height: 100
        color: "transparent"
        antialiasing: true
        border { color: "green"; width: 3 }
        radius: 10
        gradient: 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: 0
        font {
            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: 400
        width: 200; height: 100
        text: "测试文本 Label"
        leftInset: 15
        rightInset: 15
        topInset: 8
        bottomInset: 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: 110
        text: "渐变按钮"
        background: Rectangle {
            radius: 8
            color: 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.text
            color: "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: chk
        x: 200; y: 110
        text: "高级选项"
        tristate: true
        checkState: Qt.PartiallyChecked

        nextCheckState: function() {
            if (checkState === Qt.Unchecked)
                return Qt.PartiallyChecked
            else if (checkState === Qt.PartiallyChecked)
                return Qt.Checked
            else
                return 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: radioGroup
        exclusive: true  // 默认true可不写
        onCheckedButtonChanged: {
            console.log("当前选择:", checkedButton.text)
        }
    }
    RadioButton {
        id: radio1
        x: 400; y: 110
        text: "选项A"
        ButtonGroup.group: radioGroup  // 分组控制
        onClicked: if(checked) text = "选项A(已选)"  // 点击信号
    }
    RadioButton {
        x: 400; y: 150
        text: "选项B"
        ButtonGroup.group: radioGroup
        onCheckedChanged: {  // 状态变化信号
            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: demoField
        width: 200
        x: 0; y: 210
        placeholderText: "输入数字(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: area
        x: 200; y: 210
        placeholderText: "支持富文本+自动滚动"
        textFormat: TextEdit.RichText
        wrapMode: TextArea.Wrap
        selectByMouse: true
        background: 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: combo
        width: 200
        x: 400; y: 210
        editable: true
        textRole: "text"
        model: ListModel {
            ListElement { text: "Apple"; color: "red" }
            ListElement { text: "Banana"; color: "yellow" }
        }

        delegate: ItemDelegate {
            width: parent.width
            contentItem: Text {
                text: model.text
                color: model.color
                font.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

未完待续。。。