一、基礎控件

控件名稱?	?功能描述?	?示例代碼?
?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

未完待續。。。