QML Label 完整用法与 Text 组件选型

目录什么时候应该用 LabelLabel 基础用法演示代码关键逻辑解析适用场景注意点Label 内边距控制演示代码关键逻辑解析适用场景注意点Label 背景支持演示代码关键逻辑解析适用场景注意点Text vs Label 对比演示代码关键逻辑解析选型建议运行验证扩展复用方向小结QML 里显示文本最常用的两个组件是Text和Label。它们看起来都能显示文字但使用场景并不一样Text更轻量、更底层Label则继承了 Controls 主题的字体和颜色还能设置背景。很多新手会在该用Label的地方写成Text结果字体和主题对不上又要手动调一堆属性。这篇把Label的三个核心能力讲透——基础样式、内边距和背景支持最后再用一个对比 demo 帮你快速决定该用哪个组件。什么时候应该用 Label如果你只是想在一块区域里显示一段文字不关心主题一致性Text完全够用。但遇到下面这些情况Label会更省心做表单、设置页需要文字和 Switch、Slider、ComboBox 等 Controls 组件风格统一需要给文字加背景色、边框、圆角做成标签或徽章项目使用了Material、Fusion、Universal等 Controls 主题希望文字自动跟随主题字体Label本质上是对Text的封装增加了主题继承和background属性所以 API 大部分通用学习成本很低。Label 基础用法Label来自QtQuick.Controls默认会继承应用字体。你可以把它理解为带主题加持的 Text。这个 demo 展示了最常用的字体样式设置默认字体、大小、颜色、粗体和斜体。演示代码import QtQuick import QtQuick.Controls import QtQuick.Layouts FadeInAnimation { ColumnLayout { anchors.fill: parent anchors.margins: 20 spacing: 15 // ... 省略标题组件 TitleSeparator ... ColumnLayout { Layout.leftMargin: 20 spacing: 12 Label { text: Label - 自动继承应用字体 } Label { text: 自定义字体大小 font.pixelSize: 24 } Label { text: 自定义颜色 color: #E91E63 } Label { text: 粗体 斜体 font.bold: true font.italic: true } // ... 省略说明文本 ... } Item { Layout.fillHeight: true } } }关键逻辑解析Label的 API 和Text很像但默认会跟随 Controls 主题。如果你用了Material或Fusion风格Label的字体会自动适配而Text不会。想改大小用font.pixelSize或font.pointSize想改颜色直接用color想加粗斜体font.bold、font.italic适用场景这种基础用法最适合做设置页的标签、列表项标题、按钮旁边的说明文字。比如用户名、“音量”、主题这类文字用Label可以直接和界面其他 Controls 组件保持一致的视觉风格不需要额外指定字体。注意点font.pixelSize和font.pointSize不要同时设置否则实际显示大小会按最后一个生效容易让人困惑。建议在项目里统一用一种单位。Label 内边距控制给 Label 加背景时内边距决定了文字和背景边界的距离。如果 padding 设得太小文字会贴边设得太大背景又会显得臃肿。这个 demo 展示了统一内边距和四边独立控制两种方式。演示代码import QtQuick import QtQuick.Controls import QtQuick.Layouts FadeInAnimation { ColumnLayout { anchors.fill: parent anchors.margins: 20 spacing: 15 // ... 省略标题组件 TitleSeparator ... ColumnLayout { Layout.leftMargin: 20 spacing: 12 Label { text: 默认内边距 padding: 10 background: Rectangle { color: #e8f5e9; border.color: #66bb6a } } Label { text: 自定义内边距 padding: 10 topPadding: 20 bottomPadding: 20 leftPadding: 30 rightPadding: 30 background: Rectangle { color: #fff3e0; border.color: #ffb74d } } // ... 省略说明文本 ... } Item { Layout.fillHeight: true } } }关键逻辑解析padding统一设置四边topPadding/bottomPadding/leftPadding/rightPadding单独控制某一边背景大小会跟着内边距自动撑开适用场景内边距控制在做按钮式标签、状态徽章、提示条时特别有用。比如一个已完成的绿色标签上下左右各留一点空间视觉会更舒服。如果四个方向需要的留白不一样就用独立内边距属性。注意点单独设置topPadding等属性时它们会覆盖padding在对应方向的值。所以代码里常见写法是先给一个基础padding: 10再用leftPadding: 30把某一边加大。Label 背景支持Label支持background属性这是Text没有的。你可以给文字加纯色背景、渐变背景甚至模拟阴影效果。做标签、徽章、提示条时非常方便。演示代码import QtQuick import QtQuick.Controls import QtQuick.Layouts FadeInAnimation { ColumnLayout { anchors.fill: parent anchors.margins: 20 spacing: 15 // ... 省略标题组件 TitleSeparator ... ColumnLayout { Layout.leftMargin: 20 spacing: 12 Label { text: 圆角背景 padding: 8 background: Rectangle { color: #e3f2fd border.color: #1976D2 border.width: 1 radius: 6 } } Label { text: 渐变背景 padding: 8 background: Rectangle { gradient: Gradient { GradientStop { position: 0.0; color: #E91E63 } GradientStop { position: 1.0; color: #9C27B0 } } radius: 6 } color: white } Label { text: 阴影效果 padding: 10 background: Rectangle { color: white border.color: #ddd radius: 4 Rectangle { anchors.fill: parent anchors.margins: -2 color: transparent border.color: #e0e0e0 radius: 6 z: -1 } } } // ... 省略说明文本 ... } Item { Layout.fillHeight: true } } }关键逻辑解析background接受任意Item通常放Rectangle。你可以做圆角、渐变、阴影甚至嵌套更复杂的组件。圆角背景给Rectangle设置radius渐变背景用Gradient定义两个或多个颜色停止点阴影效果QML 没有内置阴影这里用了一个稍大、居后的透明Rectangle边框来模拟适用场景背景支持让Label可以直接当徽章、标签、提示气泡用。比如消息列表里的未读小红点、任务状态标签、表单里的必填提示都可以用它实现不需要再套一层Rectangle。注意点渐变背景上的文字颜色要自己保证可读性。demo 里把渐变文字设成白色是因为粉色/紫色背景上白色对比度足够。如果你的背景偏浅文字就要用深色。Text vs Label 对比最后用一个对比页总结选型。这个 demo 把两种组件的字体继承、背景支持和推荐场景放在同一页方便直观比较。演示代码import QtQuick import QtQuick.Controls import QtQuick.Layouts FadeInAnimation { ColumnLayout { anchors.fill: parent anchors.margins: 20 spacing: 15 // ... 省略标题组件 TitleSeparator ... Rectangle { Layout.fillWidth: true Layout.topMargin: 5 Layout.bottomMargin: 5 color: #f8f9fa border.color: #e0e0e0 border.width: 1 radius: 8 implicitHeight: compareRow.implicitHeight 40 RowLayout { id: compareRow anchors.centerIn: parent spacing: 30 ColumnLayout { spacing: 8 Layout.alignment: Qt.AlignHCenter Text { text: Text font.pointSize: 14 font.bold: true color: #1976D2 Layout.alignment: Qt.AlignHCenter } Text { text: 手动设置字体; font.pointSize: 11; Layout.alignment: Qt.AlignHCenter } Text { text: 不支持背景; font.pointSize: 11; Layout.alignment: Qt.AlignHCenter } Text { text: 适合: 文本展示; font.pointSize: 11; color: #666; Layout.alignment: Qt.AlignHCenter } } Rectangle { width: 1 Layout.fillHeight: true color: #ccc } ColumnLayout { spacing: 8 Layout.alignment: Qt.AlignHCenter Text { text: Label font.pointSize: 14 font.bold: true color: #E91E63 Layout.alignment: Qt.AlignHCenter } Label { text: 继承应用字体; font.pointSize: 11; Layout.alignment: Qt.AlignHCenter } Label { text: 支持背景; font.pointSize: 11; Layout.alignment: Qt.AlignHCenter } Label { text: 适合: 表单设置; font.pointSize: 11; color: #666; Layout.alignment: Qt.AlignHCenter } } } } // ... 省略底部建议文本 ... Item { Layout.fillHeight: true } } }关键逻辑解析场景推荐简单文本展示不需要主题一致Text需要背景 / 表单场景Label与 Controls 组件配合使用Label选型建议可以记住一条简单规则如果这段文字旁边都是Button、Switch、Slider这类 Controls 组件或者需要背景装饰优先用Label如果只是纯展示、做动画效果、或者在自定义组件内部显示文字用Text更轻量。运行验证Qt Creator 打开qml_text/CMakeLists.txt按CtrlR运行在左侧导航切换 Label 基础用法、内边距控制、背景支持、Text vs Label扩展复用方向把 Label 背景做成 Badge 组件支持 success、warning、error 等状态色用 Label 做设置项标题配合 Switch、Slider 使用保持主题一致给 Label 加MouseArea实现可点击标签比如筛选标签、分类标签把带渐变背景的 Label 封装成标题组件用在卡片头部小结Label不是Text的替代品而是Text在 Controls 场景下的增强版。它解决了三个实际问题主题字体继承、内边距控制、背景支持。掌握了这三点再配合Text vs Label的选型思路就能在 QML 项目里合理地使用文本组件。已验证环境Qt 版本Qt 6.11.1操作系统Windows 11完整代码https://gitcode.com/u011186532/qml_demo/tree/main/qml_text