目录三种场景一览Text 文本换行演示代码关键逻辑解析适用场景注意点Text 文本省略演示代码关键逻辑解析适用场景注意点Text 字体自适应演示代码关键逻辑解析适用场景注意点对比表格运行验证扩展复用方向小结实际项目里文本长度和容器尺寸往往是不确定的。列表项标题可能超长、卡片宽度会随窗口变化、大屏上的数字需要自动撑满空间。Text提供了三组属性来应对这些问题换行、省略和字体自适应。这篇把这三组属性的用法和注意点一次讲清楚。三种场景一览需求关键属性解决的问题控制换行wrapMode长文本在有限宽度内如何折行截断显示elidemaximumLineCount超出范围的文本用省略号收尾自动缩放fontSizeModeminimumPixelSize文字随容器大小自动调整字号这三个能力经常组合使用比如新闻列表的摘要需要两行省略大屏 KPI 数字需要自适应容器。Text 文本换行wrapMode决定长文本如何折行。这个 demo 展示了NoWrap、WordWrap、Wrap三种模式的区别。演示代码import QtQuick import QtQuick.Layouts FadeInAnimation { ColumnLayout { anchors.fill: parent anchors.margins: 20 spacing: 15 // ... 省略标题组件 TitleSeparator ... ColumnLayout { Layout.leftMargin: 20 spacing: 15 Text { Layout.preferredWidth: 250 text: NoWrap: This is a very long text that will not wrap by default wrapMode: Text.NoWrap font.pointSize: 12 } Text { Layout.preferredWidth: 250 text: WordWrap: This is a very long text that only wraps at word boundaries wrapMode: Text.WordWrap font.pointSize: 12 } Text { Layout.preferredWidth: 250 text: Wrap: This is a very long text that prefers word boundaries but can break anywhere if needed wrapMode: Text.Wrap font.pointSize: 12 } } Item { Layout.fillHeight: true } } }关键逻辑解析Text.NoWrap不换行超出部分直接绘制出去Text.WordWrap只在单词边界换行阅读体验最好Text.Wrap优先单词边界必要时可在任意位置断行常用搭配wrapMode: Text.WordWrapLayout.fillWidth: true适用场景WordWrap适合文章正文、说明文字Wrap适合路径、URL、代码片段这类需要严格填满宽度的内容NoWrap适合配合elide做单行截断标题。注意点中文没有明显的单词边界WordWrap和Wrap在中文下的表现差异不大。但在英文界面里两者区别很明显不要乱用。Text 文本省略列表、卡片里经常需要把过长的文字截断显示。这个 demo 展示了右侧省略、左侧省略、中间省略以及多行省略的写法。演示代码import QtQuick import QtQuick.Layouts FadeInAnimation { ColumnLayout { anchors.fill: parent anchors.margins: 20 spacing: 15 // ... 省略标题组件 TitleSeparator ... ColumnLayout { Layout.leftMargin: 20 spacing: 12 Text { Layout.preferredWidth: 250 text: ElideRight: 这是一段需要被省略的长文本 elide: Text.ElideRight font.pointSize: 11 } Text { Layout.preferredWidth: 250 text: ElideLeft: 这是一段需要被省略的长文本 elide: Text.ElideLeft font.pointSize: 11 } Text { Layout.preferredWidth: 250 text: ElideMiddle: 这是一段需要被省略的长文本 elide: Text.ElideMiddle font.pointSize: 11 } Text { Layout.preferredWidth: 250 text: 多行省略: 这是一段很长的文本用来演示 maximumLineCount 属性的效果。当文本超过指定行数时会被省略。 maximumLineCount: 2 elide: Text.ElideRight wrapMode: Text.WordWrap font.pointSize: 10 } } Item { Layout.fillHeight: true } } }关键逻辑解析elide省略模式ElideRight/ElideLeft/ElideMiddlemaximumLineCount最多显示几行配合wrapMode使用多行省略必须同时设置wrapMode: Text.WordWrap和elide: Text.ElideRight适用场景ElideRight适合大多数列表标题ElideMiddle适合文件路径保留开头和结尾ElideLeft适合显示日志时间戳后面的关键信息。多行省略适合新闻摘要、商品简介等场景。注意点单行省略只需要设置elide和固定宽度多行省略必须同时开启wrapMode否则maximumLineCount不会生效。另外elide对富文本RichText的支持有限复杂场景建议用TextMetrics自己截断。Text 字体自适应做响应式布局或大屏展示时希望文字自动填满容器。fontSizeMode就是干这个的。这个 demo 展示了HorizontalFit、VerticalFit、Fit三种模式最后一个容器还可以拖动改变大小来观察效果。演示代码import QtQuick import QtQuick.Layouts FadeInAnimation { ColumnLayout { anchors.fill: parent anchors.margins: 20 spacing: 15 // ... 省略标题组件 TitleSeparator ... ColumnLayout { Layout.fillWidth: true Layout.leftMargin: 20 Layout.rightMargin: 20 spacing: 15 Rectangle { Layout.preferredWidth: 300 Layout.preferredHeight: 40 color: #fff3e0 border.color: #ffb74d radius: 4 Text { anchors.fill: parent anchors.margins: 4 text: HorizontalFit 适配宽度 fontSizeMode: Text.HorizontalFit font.pixelSize: 72 horizontalAlignment: Text.AlignHCenter verticalAlignment: Text.AlignVCenter } } Rectangle { Layout.preferredWidth: 300 Layout.preferredHeight: 50 color: #e3f2fd border.color: #42a5f5 radius: 4 Text { anchors.fill: parent anchors.margins: 4 text: VerticalFit 适配高度 fontSizeMode: Text.VerticalFit font.pixelSize: 72 horizontalAlignment: Text.AlignHCenter verticalAlignment: Text.AlignVCenter } } Rectangle { Layout.preferredWidth: 300 Layout.preferredHeight: 60 color: #e8f5e9 border.color: #66bb6a radius: 4 Text { anchors.fill: parent anchors.margins: 4 text: Fit 适配宽高 fontSizeMode: Text.Fit minimumPixelSize: 10 font.pixelSize: 72 horizontalAlignment: Text.AlignHCenter verticalAlignment: Text.AlignVCenter } } Rectangle { id: resizableBox Layout.preferredWidth: 300 Layout.preferredHeight: 60 color: #f3e5f5 border.color: #ab47bc border.width: 2 radius: 4 Text { anchors.fill: parent anchors.margins: 4 text: 拖动改变大小 fontSizeMode: Text.Fit minimumPixelSize: 10 font.pixelSize: 72 horizontalAlignment: Text.AlignHCenter verticalAlignment: Text.AlignVCenter } MouseArea { anchors.right: parent.right anchors.bottom: parent.bottom width: 24 height: 24 cursorShape: Qt.SizeFDiagCursor preventStealing: true property real startX property real startY onPressed: (mouse) { startX mouse.x startY mouse.y } onPositionChanged: (mouse) { var newW resizableBox.width (mouse.x - startX) var newH resizableBox.height (mouse.y - startY) if (newW 80) resizableBox.width newW if (newH 30) resizableBox.height newH startX mouse.x startY mouse.y } } } } Item { Layout.fillHeight: true } } }关键逻辑解析fontSizeMode: Text.HorizontalFit宽度变化时字体跟着变高度固定fontSizeMode: Text.VerticalFit高度变化时字体跟着变宽度固定fontSizeMode: Text.Fit同时适配宽高minimumPixelSize限制最小字号避免容器太小时字缩到看不见font.pixelSize设一个较大值作为上限实际大小由容器决定适用场景Text.Fit最适合大屏数字展示、欢迎页标题、广告牌文字。HorizontalFit适合宽度会变化但高度固定的标签栏。VerticalFit适合竖向布局里的标题。注意点fontSizeMode只在文字内容较短时效果最好。如果文字很长字号会缩到很小才能塞进容器这时应该改用wrapMode或elide。另外自适应模式下建议始终设置minimumPixelSize避免极端情况下文字不可读。对比表格需求关键属性注意点控制换行wrapMode多行用WordWrap截断显示elide单行省略只需elide多行需加maximumLineCountwrapMode自动缩放fontSizeMode配合minimumPixelSize使用运行验证Qt Creator 打开qml_text/CMakeLists.txt按CtrlR运行在左侧导航切换文本换行、文本省略、字体自适应扩展复用方向封装EllipsisText组件默认开启ElideRight支持设置最大行数在大屏 KPI 展示中用Text.Fit让数字自动撑满卡片新闻列表用maximumLineCount: 2elide: ElideRight做两行摘要做响应式卡片时结合Layout.fillWidth和WordWrap让正文随窗口自动换行小结换行、省略、自适应是Text处理动态内容的三把利器。wrapMode解决文本折行elide解决超长截断fontSizeMode解决字号适配。三者可以单独使用也可以组合比如一个响应式新闻卡片标题用elide单行省略摘要用wrapModemaximumLineCount多行省略核心数据用fontSizeMode自动撑满。掌握这些属性就能让文本在不同尺寸下都保持良好的阅读体验。已验证环境Qt 版本Qt 6.11.1操作系统Windows 11完整代码https://gitcode.com/u011186532/qml_demo/tree/main/qml_text
