Text QML Type

指定如何将格式化文本添加到场景中。更多...

• 所有成员列表，包括继承的成员
• 已弃用的成员

属性

• advance : size
• antialiasing : bool
• baseUrl : url
• bottomPadding : real
• clip : bool
• color : color
• contentHeight : real
• contentWidth : real
• effectiveHorizontalAlignment : enumeration
• elide : enumeration
• font.bold : bool
• font.capitalization : enumeration
• font.contextFontMerging : bool (since 6.8)
• font.family : string
• font.features : object (since 6.6)
• font.hintingPreference : enumeration
• font.italic : bool
• font.kerning : bool
• font.letterSpacing : real
• font.pixelSize : int
• font.pointSize : real
• font.preferShaping : bool
• font.preferTypoLineMetrics : bool (since 6.8)
• font.strikeout : bool
• font.styleName : string
• font.underline : bool
• font.variableAxes : object (since 6.7)
• font.weight : int
• font.wordSpacing : real
• fontInfo.bold : bool
• fontInfo.family : string
• fontInfo.italic : bool
• fontInfo.pixelSize : int
• fontInfo.pointSize : real
• fontInfo.styleName : string
• fontInfo.weight : int
• fontSizeMode : enumeration
• horizontalAlignment : enumeration
• hoveredLink : string
• leftPadding : real
• lineCount : int
• lineHeight : real
• lineHeightMode : enumeration
• linkColor : color
• maximumLineCount : int
• minimumPixelSize : int
• minimumPointSize : int
• padding : real
• renderType : enumeration
• renderTypeQuality : int (since 6.0)
• rightPadding : real
• style : enumeration
• styleColor : color
• text : string
• textFormat : enumeration
• topPadding : real
• truncated : bool
• verticalAlignment : enumeration
• wrapMode : enumeration

信号

• lineLaidOut(object line)
• linkActivated(string link)
• linkHovered(string link)

方法

• void forceLayout()
• string linkAt(real x, real y)

详细说明

文本项既可以显示纯文本，也可以显示富文本。例如，您可以像这样定义一种特定字体和字号的红色文本：

Text {
    text: "Hello World!"
    font.family: "Helvetica"
    font.pointSize: 24
    color: "red"
}

使用 HTML 风格的标记或 Markdown 来定义富文本：

Text {
    text: "<b>Hello</b> <i>World!</i>"
}

Text {
    text: "**Hello** *World!*"
}

如果未显式设置高度和宽度，Text 将尝试确定所需的空间大小并据此进行设置。除非设置了 `wrapMode `，否则它将始终优先考虑宽度而非高度（所有文本都将排成一行）。

若要将一行纯文本调整为固定宽度，可以使用elide 属性。

“文本”控件提供只读文本。有关可编辑文本，请参阅“TextEdit ”。

另请参阅 “字体”示例。

属性文档

advance : size [read-only]

从文本项中第一个字符的基线原点到文本流中紧随其后的文本项中第一个字符的基线原点之间的距离（以像素为单位）。

请注意，如果文本从右向左流动，则该间距可以为负值。

antialiasing : bool

用于决定文本是否应使用抗锯齿。只有`renderType `属性设置为`Text.NativeRendering`的文本才能禁用抗锯齿。

默认值为true 。

baseUrl : url

此属性指定了一个用于解析文本中相对 URL 的基准 URL。

URL 将被解析为位于基准 URL 目标所在的同一目录下，这意味着路径中最后一个 '/' 之后的任何部分都将被忽略。

默认值是实例化“文本”项的 QML 文件的 URL。

这些属性控制了内容周围的内边距。除了contentWidth 和contentHeight 之外，还会额外预留出这部分空间。

clip : bool

无论文本是否被裁剪，此属性均有效。

请注意，如果文本无法完全容纳在边界矩形内，则会被突然截断。

如果您想在有限的空间内显示可能较长的文本，建议改用elide 。

color : color

文字颜色。

使用十六进制表示法定义绿色文本的示例：

Text {
    color: "#00FF00"
    text: "green text"
}

使用 SVG 颜色名称定义钢蓝色文本的示例：

Text {
    color: "steelblue"
    text: "blue text"
}

contentHeight : real [read-only]

返回文本的高度，包括因文本内容超出设定高度而导致被遮盖的部分之外的高度。

contentWidth : real [read-only]

返回文本的宽度，包括因 WrapMode 已设置而导致因换行不足而超出指定宽度的部分。

设置文本项宽度和高度范围内文本的水平和垂直对齐方式。默认情况下，文本垂直对齐于顶部。水平对齐遵循文本的自然对齐方式，例如，从左到右阅读的文本将左对齐。

horizontalAlignment 的有效值为：Text.AlignLeft 、Text.AlignRight 、Text.AlignHCenter 和Text.AlignJustify 。verticalAlignment 的有效值为：Text.AlignTop 、Text.AlignBottom 和Text.AlignVCenter 。

请注意，对于单行文本，文本的大小即为文本所占的区域。在此常见情况下，所有对齐方式均等效。若希望文本在父容器中居中显示，则需修改Item::anchors 属性，或将horizontalAlignment 设置为Text.AlignHCenter，并将宽度绑定至父容器的宽度。

当使用附加属性LayoutMirroring::enabled 来镜像应用程序布局时，文本的水平对齐方式也会被镜像。但是，horizontalAlignment 属性将保持不变。要查询Text的实际水平对齐方式，请使用只读属性effectiveHorizontalAlignment 。

elide : enumeration

将此属性设置为“省略”可使文本部分被截断，以适应“文本”项的宽度。只有在显式设置了宽度时，文本才会被截断。

此属性适用于Text.PlainText 和Text.StyledText 格式，但不适用于Text.RichText 或Text.MarkdownText 格式。

省略行为可设置为：

如果将此属性设置为 Text.ElideRight，则可与wrapped 文本配合使用。只有当maximumLineCount 或height 已被设置时，文本才会进行省略。如果同时设置了maximumLineCount 和height ，则会应用maximumLineCount ，除非行数超出允许的高度范围。

如果文本是多长度字符串，且模式不是Text.ElideNone ，则使用第一个能完全显示的字符串；否则，最后一个字符串将被截断。

多长度字符串按从长到短的顺序排列，并以 Unicode “字符串终止符”U009C 分隔（在 QML 中使用"\u009C" 或"\x9C" 表示）。

font.bold : bool

设置字体粗细是否为粗体。

font.capitalization : enumeration

设置文本的大写规则。

Text { text: "Hello"; font.capitalization: Font.AllLowercase }

font.contextFontMerging : bool [since 6.8]

如果所选字体不包含某个特定字符，Qt 会自动选择一种外观相似且包含该字符的备用字体。默认情况下，此操作是按字符逐个进行的。

这意味着在某些不常见的情况下，即使文本属于同一脚本，也可能使用许多不同的字体来呈现同一字符串。将 `contextFontMerging ` 设置为 `true` 时，系统将尝试查找与输入字符串最大子集相匹配的备用字体。对于存在缺失字形的字符串，此操作的开销会更大，但可能提供更一致的结果。 默认情况下，contextFontMerging 的值为false 。

该属性自 Qt 6.8 起引入。

另请参阅 QFont::StyleStrategy 。

font.family : string

设置字体的字体家族名称。

字体家族名称不区分大小写，可选地包含字体厂商名称，例如“Helvetica [Cronyx]”。 如果该字体家族由多个字体厂商提供，且未指定具体厂商，则会随机选择一家厂商。如果该字体家族不可用，将使用字体匹配算法设置一个字体家族。

font.features : object [since 6.6]

在根据内容调整文本形状时，将整数值应用于特定的 OpenType 特征。这提供了对字体调整过程的高级控制，可用于支持 API 中未涵盖的字体特征。

字体特征通过一个从四字母标签到整数值的映射来表示。在大多数情况下，随标签一起传递的该整数值代表一个布尔值：值为零表示该特征已禁用，非零值表示已启用。但对于某些字体特征，其含义可能有所不同。 例如，当应用于salt 特性时，该值是一个索引，用于指定要使用的样式变体。

例如，frac 字体功能会将用斜杠分隔的斜体分数（如1/2 ）转换为不同的表示形式。通常，这会将整个分数“压缩”为单个字符宽度（如½ ）。

如果字体支持frac 功能，则可以在Shaper中通过以下代码启用该功能：

Text {
    text: "One divided by two is 1/2"
    font.family: "MyFractionFont"
    font.features: { "frac": 1 }
}

可以在同一映射中为多个特性分配值。例如，如果您还希望禁用该字体的字间距调整，可以如下所示显式禁用此功能：

Text {
    text: "One divided by two is 1/2"
    font.family: "MyFractionFont"
    font.features: { "frac": 1, "kern": 0 }
}

您还可以将字体属性收集到一个对象中：

Text {
    text: "One divided by two is 1/2"
    font: {
        family: "MyFractionFont"
        features: { "frac": 1, "kern": 0 }
    }
}

dlig,hlig ）若设置了font.letterSpacing 属性则会被禁用，但仅限于连字仅用于装饰效果的书写系统。对于必须使用连字的书写系统，这些功能将保持默认状态。 通过font.features 设置的值将覆盖默认行为。例如，如果将"kern" 设置为1，则无论font::kerning 属性是否设置为false，字距调整都将始终启用。同样，

如果将其设置为0 ，则字距调整将始终被禁用。

该属性自 Qt 6.6 起引入。

另请参阅 QFont::setFeature()。

font.hintingPreference : enumeration

为文本设置首选的提示。

这是向底层文本渲染系统发出的提示，用于指定使用特定级别的提示处理，且在不同平台上的支持情况各不相同。更多详细信息请参阅QFont::HintingPreference 文档中的表格。

Text { text: "Hello"; renderType: Text.NativeRendering; font.hintingPreference: Font.PreferVerticalHinting }

font.italic : bool

设置字体是否具有斜体样式。

font.kerning : bool

在调整文本形状时，启用或禁用字间距（kerning）OpenType功能。禁用此功能可在创建或修改文本时提高性能，但会牺牲部分视觉效果。默认值为true 。

Text { text: "OATS FLAVOUR WAY"; font.kerning: false }

font.letterSpacing : real

设置字体的字间距。

字母间距会改变字体中各个字母之间的默认间距。正值会将字母间距增加相应的像素数；负值则会减少该间距。

font.pixelSize : int

设置以像素为单位的字体大小。

使用此函数会使字体依赖于设备。请使用 `pointSize ` 以与设备无关的方式设置字体大小。

font.pointSize : real

设置以点为单位的字体大小。字体大小必须大于零。

font.preferShaping : bool

有时，字体会对一组字符应用复杂的规则，以确保其正确显示。 在某些书写系统中（如梵文字系），这是确保文本可读性的必要条件；但在拉丁字母等系统中，这仅仅是一种美观功能。当不需要这些功能时，将preferShaping 属性设置为false将禁用所有此类功能，这在大多数情况下都能提高性能。

默认值为true 。

Text { text: "Some text"; font.preferShaping: false }

font.preferTypoLineMetrics : bool [since 6.8]

提供字体ascent 、descent 和leading 的几组相互竞争的垂直线度量值。这些通常被称为win（Windows）度量值和typo（排版）度量值。 虽然规范建议使用typo 度量值来控制行间距，但许多应用程序更倾向于使用win 度量值，除非在字体的fsSelection字段中设置了USE_TYPO_METRICS 标志。出于向后兼容性的考虑，Qt 应用程序也是如此。 对于将USE_TYPO_METRICS 标志设为有效以表明typo 度量有效的字体，以及win 度量与typo 度量相匹配的字体，这不会构成问题。然而，对于某些字体，win 度量可能大于理想的行间距，且USE_TYPO_METRICS 标志可能因疏忽而未被设置。对于此类字体，设置font.preferTypoLineMetrics 可能获得更佳的效果。

默认情况下，preferTypoLineMetrics 的值为false 。

该属性自 Qt 6.8 起引入。

另请参阅 QFont::StyleStrategy 。

font.strikeout : bool

设置字体是否具有删除线样式。

font.styleName : string

设置字体的样式名称。

样式名称不区分大小写。如果设置了该属性，系统将根据样式名称来匹配字体，而不是根据字体属性font.weight 、font.bold 和font.italic 。

font.underline : bool

用于设置文本是否带下划线。

font.variableAxes : object [since 6.7]

将浮点数值应用于可变字体的可变轴。

可变字体提供了一种在同一个字体文件中存储多种变体（具有不同的字重、字宽或样式）的方法。这些变体通过预定义参数集（称为“可变轴”）的浮点数值来表示。 具体变体通常由字体设计师命名，在 Qt 中，可像选择传统子字体家族一样，通过 setStyleName() 函数进行选择。

在某些情况下，为不同的轴提供任意值也很有用。例如，如果一种字体有 Regular 和 Bold 两个子家族，您可能希望获得介于两者之间的字重。此时，您可以通过为字体的“wght”轴提供自定义值来手动请求该字重。

Text {
    text: "Foobar"
    font.family: "MyVariableFont"
    font.variableAxes: { "wght": (Font.Normal + Font.Bold) / 2.0 }
}

如果字体支持“wght”轴，且给定的值在其定义的范围内，则会提供对应于字重 550.0 的字体。

许多字体都提供了一些标准轴，例如“wght”（字重）、“wdth”（字宽）、“ital”（斜体）和“opsz”（光学尺寸）。它们各自在字体本身中都有定义的范围。 例如，“wght”的范围可能从 100 到 900（QFont::Thin 到QFont::Black ），而“ital”的范围则可能从 0 到 1（从非斜体到完全斜体）。

字体还可以选择定义自定义轴；唯一的限制是名称必须符合QFont::Tag 的要求（即由四个 Latin-1 字符组成的序列）。

默认情况下，不设置任何可变坐标轴。

该属性在 Qt 6.7 中引入。

另请参阅 QFont::setVariableAxis()。

font.weight : int

请求的字体粗细。请求的粗细必须是1到1000之间的整数，或以下预定义值之一：

Text { text: "Hello"; font.weight: Font.DemiBold }

font.wordSpacing : real

设置字体的词间距。

单词间距会改变单词之间的默认间距。正值会按相应的像素数量增加单词间距，而负值则会相应地减少单词间距。

fontInfo.bold : bool [read-only]

当前字体及fontSizeMode 已解析的字体信息的粗体状态。当已解析字体的字重为粗体或更粗时，此属性为真。

fontInfo.family : string [read-only]

当前字体已解析出的字体家族名称，以及fontSizeMode 。

fontInfo.italic : bool [read-only]

当前字体已解析的字体信息中的斜体状态，以及fontSizeMode 。

fontInfo.pixelSize : int [read-only]

当前字体已解析的字体信息以及fontSizeMode 的像素大小。

fontInfo.pointSize : real [read-only]

当前字体已解析的字体信息中的点大小，以及fontSizeMode 。

fontInfo.styleName : string [read-only]

针对当前字体已解析的字体信息及其样式名称，以及fontSizeMode 。

fontInfo.weight : int [read-only]

当前字体及fontSizeMode 所解析的字体信息的权重。

fontSizeMode : enumeration

此属性指定如何确定显示文本的字号。可能的取值包括：

适应文本的字体大小具有由minimumPointSize 或minimumPixelSize 属性指定的最小限制，以及由font.pointSize 或font.pixelSize 属性指定的最大限制。

Text { text: "Hello"; fontSizeMode: Text.Fit; minimumPixelSize: 10; font.pixelSize: 72 }

如果文本在使用最小字体大小时无法容纳在项目边界内，则将根据elide 属性对文本进行截断。

如果将textFormat 属性设置为Text.RichText ，则该属性将完全被忽略，因此不会产生任何效果。如果将textFormat 设置为Text.StyledText ，则只要文本中不包含字体大小标签，该属性就会被遵循；如果存在字体大小标签，该属性仍会优先遵循这些标签。这可能会导致其无法完全符合fontSizeMode设置的要求。

hoveredLink : string [read-only]

当用户将鼠标悬停在文本中嵌入的链接上时，该属性将包含该链接的字符串。链接必须为富文本或HTML格式，而hoveredLink 字符串可提供对该特定链接的访问。

另请参阅 linkHovered 和linkAt()。

lineCount : int [read-only]

返回文本项中可见的行数。

此属性不支持富文本。

另请参阅 maximumLineCount 。

lineHeight : real

设置文本的行高。该值可以是像素数，也可以是倍数，具体取决于lineHeightMode 。

默认值为倍数 1.0。行高必须为正数。

lineHeightMode : enumeration

此属性决定了行高的指定方式。可能的取值包括：

linkColor : color

文本中链接的颜色。

此属性适用于 StyledText（textFormat ），但不适用于 RichText。在 RichText 中，可通过在文本中嵌入 CSS 样式标签来指定链接颜色。

maximumLineCount : int

设置此属性可限制文本项显示的行数。如果将 elide 设置为 Text.ElideRight，文本将进行适当的截断。默认情况下，此属性取最大可能的整数值。

此属性不支持富文本。

另请参阅 lineCount 和elide 。

minimumPixelSize : int

此属性指定了由fontSizeMode 属性缩放后的文本的最小字体像素大小。

如果fontSizeMode 为Text.FixedSize，或者font.pixelSize 为-1，则该属性将被忽略。

minimumPointSize : int

此属性指定由fontSizeMode 属性缩放后的文本的最小字体点size 。

如果fontSizeMode 为Text.FixedSize，或者font.pointSize 为-1，则该属性将被忽略。

renderType : enumeration

覆盖此组件的默认渲染类型。

支持的渲染类型包括：

如果您希望文本在目标平台上呈现原生外观，且不需要文本变换等高级功能，请选择 `Text.NativeRendering `。若在 `NativeRendering` 渲染类型下使用此类功能，将导致渲染效果不佳，有时甚至会出现像素化现象。

Text.QtRendering 和Text.CurveRendering 都是硬件加速技术。其中QtRendering 速度更快，但占用更多内存，且在大尺寸下会出现渲染瑕疵。当QtRendering 无法提供良好的视觉效果，或者需要优先降低图形内存消耗时，应考虑将CurveRendering 作为替代方案。

默认渲染类型由QQuickWindow::textRenderType() 决定。

renderTypeQuality : int [since 6.0]

覆盖此组件的默认渲染质量。这是一项低级自定义设置，在大多数情况下可以忽略。目前，只有当renderType 的值为Text.QtRendering 时，此设置才会生效。

Text.QtRendering 使用的光栅化算法在文本尺寸较大时可能会产生渲染瑕疵，例如锐利的角看起来比实际更圆。如果特定文本项存在此问题，可增加renderTypeQuality 值以提高渲染质量，但会增加内存消耗。

renderTypeQuality 可以是大于 0 的任意整数，或以下预定义值之一

该属性在 Qt 6.0 中引入。

style : enumeration

设置一个额外的文本样式。

支持的文本样式包括：

Row {
    Text { font.pointSize: 24; text: "Normal" }
    Text { font.pointSize: 24; text: "Raised"; style: Text.Raised; styleColor: "#AAAAAA" }
    Text { font.pointSize: 24; text: "Outline";style: Text.Outline; styleColor: "red" }
    Text { font.pointSize: 24; text: "Sunken"; style: Text.Sunken; styleColor: "#AAAAAA" }
}

styleColor : color

定义文本样式所使用的辅助颜色。

styleColor 该颜色用作带轮廓文本的轮廓色，以及凸起或凹陷文本的阴影色。如果未设置任何样式，则完全不使用该颜色。

Text { font.pointSize: 18; text: "hello"; style: Text.Raised; styleColor: "gray" }

另请参阅 style 。

text : string

要显示的文本。文本支持纯文本和富文本字符串。

该项将尝试自动判断该文本是否应被视为带样式的文本。此判断是通过Qt::mightBeRichText() 实现的。但 Markdown 的检测并非自动进行。

另请参阅 textFormat 。

textFormat : enumeration

text 属性的显示方式。

支持的文本格式包括：

如果文本格式为Text.AutoText ，则“文本”项将自动判断该文本是否应被视为带样式的文本。此判断通过Qt::mightBeRichText() 实现，该函数可检测文本首行是否存在 HTML 标签，但无法区分 Markdown 与纯文本。

Text.StyledText 是一种经过优化的格式，支持某些基本的文本样式标记，风格类似于 HTML 3.2：

<b></b> - bold
<del></del> - strike out (removed content)
<s></s> - strike out (no longer accurate or no longer relevant content)
<strong></strong> - bold
<i></i> - italic
<br> - new line
<p> - paragraph
<u> - underlined text
<font color="color_name" size="1-7"></font>
<h1> to <h6> - headers
<a href=""> - anchor
<img src="" align="top,middle,bottom" width="" height=""> - inline images
<ol type="">, <ul type=""> and <li> - ordered and unordered lists
<pre></pre> - preformatted
All entities

Text.StyledText 解析器非常严格，要求标签必须正确嵌套。

Column {
    Text {
        font.pointSize: 24
        text: "<b>Hello</b> <i>World!</i>"
    }
    Text {
        font.pointSize: 24
        textFormat: Text.RichText
        text: "<b>Hello</b> <i>World!</i>"
    }
    Text {
        font.pointSize: 24
        textFormat: Text.PlainText
        text: "<b>Hello</b> <i>World!</i>"
    }
    Text {
        font.pointSize: 24
        textFormat: Text.MarkdownText
        text: "**Hello** *World!*"
    }
}

Text.RichText 支持更广泛的 HTML 4 子集，具体说明请参见“支持的 HTML 子集”页面。建议优先使用Text.PlainText 、Text.StyledText 或Text.MarkdownText ，因为它们能提供更佳的性能。

• 代码块虽采用default monospace font 格式，但周围没有高亮框
• 块引用会缩进，但引用旁没有竖线

truncated : bool [read-only]

如果文本因maximumLineCount 或elide 而被截断，则返回true。

此属性不支持富文本。

另请参阅 maximumLineCount 和elide 。

wrapMode : enumeration

将此属性设置为按“文本”项的宽度进行换行。只有在显式设置了宽度时，文本才会换行。wrapMode 可以是以下值之一：

Signal 文档

lineLaidOut(object line)

在纯文本或样式化文本模式下，布局过程中每排文本完成布局时都会发出此信号。在富文本模式下不会发出此信号。指定的line 对象提供了有关当前正在布局的文本行的更多详细信息。

这使得可以在文本行布局过程中对其进行定位和调整大小。例如，可用于创建多栏布局或实现文本环绕对象。

指定的line 对象具有以下属性：

例如，以下代码将 Text 项的前 5 行向右移动 100 像素：

onLineLaidOut: (line)=> {
    if (line.number < 5) {
        line.x = line.x + 100
        line.width = line.width - 100
    }
}

以下示例将允许您将一个项目定位在最后一行末尾：

onLineLaidOut: (line)=> {
    if (line.isLast) {
        lastLineMarker.x = line.x + line.implicitWidth
        lastLineMarker.y = line.y + (line.height - lastLineMarker.height) / 2
    }
}

linkActivated(string link)

当用户点击文本中嵌入的链接时，会触发此信号。该链接必须为富文本或 HTML 格式，且字符串link 用于访问该特定链接。

    Text {
            textFormat: Text.RichText
            text: "See the <a href=\"http://qt-project.org\">Qt Project website</a>."
            onLinkActivated: (link)=> console.log(link + " link activated")
    }

示例代码将显示文本“查看Qt 项目网站”。

点击高亮显示的链接，将向控制台输出http://qt-project.org link activated 。

linkHovered(string link)

当用户将鼠标悬停在文本中嵌入的链接上时，会触发此信号。该链接必须为富文本或HTML格式，且字符串link 可访问该特定链接。

另请参阅 hoveredLink 和linkAt()。

方法文档

void forceLayout()

触发显示文本的重新布局。

string linkAt(real x, real y)

返回位于点x 、y （以内容坐标计）处的链接字符串；如果该点不存在链接，则返回空字符串。

另请参阅 hoveredLink 。