文本 QML 类型

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

对于 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。

这些属性表示内容的周围空间。此空间在 contentWidth 和 contentHeight 之外预留。

第一个文本项基线起点到紧跟在当前文本项之后出现的文本项的第一个字符基线起点的像素距离。

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

用于确定 Text 是否需要抗锯齿。只有具有 Text.NativeRendering 渲染类型的 Text 可以禁用抗锯齿。

默认值为 true。

该属性指定一个基 URL，用于解析文本内的相对 URL。

URL 将解析为与基 URL 目标相同的目录，这意味着路径中最后一个 '/' 之后的部分将被忽略。

默认值是实例化 Text 项的 QML 文件的 URL。

此属性表示文本是否被裁剪。

注意，如果文本不适合边界矩形，它将被突然切断。

如果您想在有限的区域内显示可能很长的文本，您可能想使用 elide。

文本颜色。

以下是一个使用十六进制表示法定义的绿色文本的示例

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

以下是一个使用 SVG 颜色名称定义的钢蓝色文本的示例

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

返回文本的高度，包括超出指定高度覆盖的部分。

返回文本的宽度，包括由于换行模式不足而覆盖的宽度。

将此属性设置为此fit to the Text item's width的文本部分将省略。只有当显式设置宽度时，文本才会省略。

该属性不能用于富文本。

省略可以是

如果将此属性设置为Text.ElideRight，则可以与< xmlhttp-qtquick-text.html#wrapMode-prop" translate="no">折叠文本一起使用。只有在设置了< code translate="no">maximumLineCount 或 height 时才会省略文本。如果同时设置了 maximumLineCount 和 height，除非行数无法在允许的高度中适合，否则将应用 maximumLineCount。

如果文本是多长度字符串，并且模式不是 < code translate="no">Text.ElideNone，则将使用适合的第一个字符串，否则将省略最后一个字符串。

多长度字符串按最长到最短的顺序排列，由Unicode“字符串终止符”字符< code translate="no">U009C（在QML中以 < code translate="no">"\u009C" 或 < code translate="no">"\x9C" 写入）分隔。

设置字体是否加粗。

设置文本的大写形式。

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

设置字体的家族名称。

家族名称不区分大小写，可以包含铸造厂名称，例如“Helvetica [Cronyx]”。如果家族可以从多个铸造厂中获取并且没有指定铸造厂，则选择任意铸造厂。如果家族不可用，将使用字体匹配算法设置家族。

在根据< i translate="no">features中的内容排列文本时，将整数值应用于特定的OpenType功能。这提供了对字体形状过程的深入访问，并可以用于支持API中未涉及的字体功能。

字体特征由从四个字母标签到整数的映射表示。在这种情况下，整数值通常表示布尔值：零值表示功能被禁用，非零值表示启用。但是，某些字体功能可能有其他解释。例如，当应用于< code translate="no">salt功能时，值是指定要使用的样式选择的索引。

例如，< code translate="no">frac字体特性将以不同的表示转换带有斜杠的分隔的斜线分数（例如< code translate="no">1/2）。通常这会涉及将整个分数烘焙到单个字符宽度中（例如< code translate="no">½）。

如果字体支持< code translate="no">frac特性，则可以在形状器中启用，如下面的代码所示

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 }
    }
}

此属性是在Qt 6.6中引入的。

另请参阅：QFont::setFeature。

设置文本的首选提示。这会提示底层文本渲染系统使用特定的提示级别，平台间的支持程度不同。有关更多详细信息，请参见QFont::HintingPreference的文档中的表格。

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

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

在造型文本时启用或禁用字距微调OpenType功能。禁用此功能可能在创建或更改文本时提高性能，但会以一些外观功能为代价。默认值为true。

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

设置字体的字母间距。

字母间距改变了字体重置的字母之间间距。正值按相应像素增加字母间距；负值按相等像素减少间距。

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

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

设置字体大小（以磅为单位）。磅值必须大于零。

有时，为了正确显示一组字符，字体将应用复杂的规则。在一些书写系统中，如布拉米克书写系统，这是为了使文本易于阅读，但在例如拉丁文字母中，这仅仅是一个装饰性功能。将preferShaping属性设置为false将在不需要时禁用所有此类功能，这将提高大部分情况下的性能。

默认值是true。

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

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

设置字体的样式名称。

样式名称不区分大小写。如果已设置，则字体将与样式名称匹配，而不是与字体属性font.weight、font.bold和font.italic匹配。

设置文本是否带下划线。

为可变字体的变量轴应用浮点值。

可变字体提供了一种方法，可以在同一个字体文件中存储多个变体（具有不同的重量、宽度或样式）。这些变体是以预定义参数集的浮点值给出的，称为“变量轴”。特定的实例通常由字体设计者命名，在Qt中，这些可以使用setStyleName()像传统子族一样选择。

在有些情况下，提供不同轴的任意值也可能有用。例如，如果字体有常规和粗体子族，您可能希望在这些子族之间有一个中间的粗细。然后您可以通过在字体中为“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（四个拉丁-1字符的序列）的要求。

默认情况下，不设置变量轴。

此属性在Qt 6.7中引入。

也见 QFont::setVariableAxis。

请求的字体重量。请求的重量必须是介于1和1000之间的整数，或以下预定义值之一

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

设置字体的单词间距。

字间距会更改默认的字词间距。正值会增加相应的像素字间距，而负值会相应地减少字间距。

当前字体和 fontSizeMode 解析后的字体信息的粗体状态。如果解析后的字体的粗细度为粗体或更粗，则为真。

已解析的当前字体和 fontSizeMode 的字体家族名称。

当前字体和 fontSizeMode 解析后的字体信息的中斜体状态。

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

已解析的当前字体和 fontSizeMode 的字体信息的磅值大小。

已解析的当前字体和 fontSizeMode 的字体信息的样式名称。

已解析的当前字体和 fontSizeMode 的字体信息的粗细度。

该属性指定了显示文本的字体大小是如何确定的。可能的值有

适配文本的字体大小有最小边界由 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 设置。

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

另请参阅linkHovered 和 linkAt()。

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

该属性不支持富文本。

另请参阅maximumLineCount。

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

默认值是一个1.0的乘数。行高必须是正值。

该属性确定如何指定行高。可能的值包括

文本中链接的颜色。

该属性与StyledText的textFormat属性一起工作，但不与RichText一起工作。可以在富文本中通过包含CSS样式标签来指定RichText中的链接颜色。

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

该属性不支持富文本。

另请参阅lineCount 和 elide。

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

如果fontSizeMode为Text.FixedSize或font.pixelSize为-1，则忽略此属性。

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

如果fontSizeMode为Text.FixedSize或font.pointSize为-1，则忽略此属性。

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

支持的渲染类型包括

如果希望文本在目标平台上的外观看起来原生并且不需要文本变换等高级功能，请选择Text.NativeRendering。使用与NativeRendering渲染类型结合的高级功能将导致结果梅糟糕的，有时是像素化的。

两种技术《Text.QtRendering》和《Text.CurveRendering》都采用硬件加速。其中《QtRendering》运行速度更快，但占用更多内存，并且在较大尺寸时会显示出渲染伪影。《CurveRendering》在《QtRendering》无法提供良好的视觉效果，或者降低图形内存消耗是重点的情况下，可以作为替代方案。

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

为该组件覆盖默认渲染类型质量。这是一种低级别定制，在大多数情况下可以忽略。目前它只在对renderType为《Text.QtRendering》时有效。

Text.QtRendering使用的栅格化算法在大字体尺寸时可能会产生伪影，例如锐利的角落看起来比应有的更圆。如果这是特定文本项的问题，可以将《renderTypeQuality》增加以提高渲染质量，但这会增加内存消耗。

《renderTypeQuality》可以是任何大于0的整数或以下预定义值之一

此属性自Qt 6.0起引入。

设置额外的文本样式。

支持以下文本样式

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》不会被使用，它用作走边文本的轮廓颜色，和在凸起或凹陷文本中的阴影颜色。

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

详见：style。

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

该元素将尝试自动确定文本是否应为样式文本。这种确定是使用Qt::mightBeRichText()进行的。但是，Markdown的检测不是自动的。

详见：textFormat。

确定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，因为它们能提供更好的性能。

• 代码块使用默认的等宽字体，但没有围绕的高亮框
• 引用块缩进，但旁边没有垂直线

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

该属性不支持富文本。

另请参见 maximumLineCount 和 elide。

将此属性设置以将文本包裹成 Text 项的宽度。只有设置了显式宽度时，文本才会包裹。wrapMode 可以是以下之一

此信号在文本或样式文本模式下进行布局过程中为每一行文本发出。在富文本模式下不会发出此信号。指定的 line 对象提供了有关当前正在布局的行的更多详细信息。

这为在布局过程中定位和调整行的大小提供了机会。它可以用作创建列或围绕对象布局文本的例子。

指定的 line 对象的属性包括

例如，以下代码将文本项的前五行向右移动 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
    }
}

当用户点击文本中嵌入的链接时，将发出此信号。链接必须在富文本或HTML格式中，并且链接字符串提供对特定链接的访问。

    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 链接已激活。

当用户悬停在文本中嵌入的链接上时，将发出此信号。链接必须在富文本或HTML格式中，并且链接字符串提供对特定链接的访问。

另请参阅：hoveredLink和linkAt方法。

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

返回在内容坐标中点x、y处的链接字符串，或者在该点不存在链接时返回空字符串。

另请参阅：hoveredLink。