TextInput QML Type

设置TextInput 项目宽度和高度内文本的水平对齐方式。默认情况下，文本对齐方式遵循文本的自然对齐方式，例如，从左到右阅读的文本将向左对齐。

TextInput 由于自然高度恰好是单行文本的高度，因此"...... "不采用垂直对齐方式。如果手动将高度设置得更大， 将始终垂直居上对齐。您可以使用锚点在其他项目中任意对齐。TextInput

horizontalAlignment 的有效值为TextInput.AlignLeft 、TextInput.AlignRight 和TextInput.AlignHCenter 。

verticalAlignment 的有效值是TextInput.AlignTop （默认）、TextInput.AlignBottom TextInput.AlignVCenter 。

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

这些属性保留了内容周围的填充。这些空间是在contentWidth 和contentHeight 之外保留的。

除非明确设置，否则各个 padding 属性都将使用padding 属性的值。例如，如果将padding 设置为4 ，将leftPadding 设置为8 ，则8 将用作左侧填充。

除非设置了验证器或输入屏蔽，否则该属性始终为真。如果已设置验证器或输入掩码，只有当当前文本作为最终字符串（而非中间字符串）可被验证器或输入掩码接受时，该属性才会为真。

TextInput 是否应在按下鼠标时获得主动焦点。默认设置为 "true"。

当文本长度大于宽度时，TextInput 是否应滚动。默认设置为 true。

另请参阅 ensureVisible()。

如果TextInput 可写，且剪贴板内容适合粘贴到TextInput ，则返回 true。

如果TextInput 是可写的，且有undone 操作可以重做，则返回 true。

如果TextInput 可写，且之前的操作可以撤销，则返回 true。

文本颜色。

返回文本的高度，包括超出高度的部分，如果文本不适合所设置的高度。

如果设置了wrapMode ，则会返回文本的宽度，包括超出宽度的部分，即由于包装不足而覆盖的宽度。

TextInput 中的游标委托。

如果为TextInput 设置了 cursorDelegate，则将使用该委托来绘制光标，而不是标准光标。当需要光标时，TextInput 将创建并管理该委托的实例，委托实例的 x 属性将被设置为当前字符左上角前一个像素。

请注意，委托组件的根项必须是QQuickItem 或QQuickItem 派生项。

光标在TextInput 中的位置。光标位于字符之间。

displayText 如果 设置为 ，光标位置就会不同：此时，每个 都是 "窄 "字符（光标位置总是移动 1），即使 中的文本不是 "窄 "字符。echoMode TextInput.Password passwordCharacter TextInput

在文本输入中呈现标准文本光标的矩形区域。只读。

当光标矩形发生变化时，自定义cursorDelegate 的位置和高度会自动跟随光标矩形更新。委托的宽度不受光标矩形变化的影响。

当TextInput 显示光标时，设置为 true。

当TextInput 获得活动焦点时，该属性将被设置或取消设置，这样其他属性就可以与当前是否显示光标绑定。由于该属性会自动设置和取消设置，因此当您自己设置该值时，必须注意您的值可能会被覆盖。

光标可以直接在脚本中设置，例如，如果 KeyProxy 将按键转发给光标，而你希望光标在转发时看起来处于活动状态（但实际上并没有给予光标活动焦点）。

但不应直接在项目上设置（如下面的 QML），因为指定的值将被覆盖，并在焦点改变时丢失。

TextInput {
    text: "Text"
    cursorVisible: false
}

在上述代码段中，当TextInput 获得活动焦点时，光标仍将可见。

这就是TextInput 中显示的文本。

如果echoMode 设置为 TextInput::Normal，则该值与TextInput::text 属性的值相同。否则，该属性将保留用户可见的文本，而text 属性将保留实际输入的文本。

另请参阅 preeditText 。

指定文本在TextInput 中的显示方式。

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

设置字体是否加粗。

设置文本的大小写。

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

如果所选字体不包含特定字符，Qt 会自动选择包含该字符的相似字体。默认情况下，这是在逐个字符的基础上进行的。

这意味着在某些不常见的情况下，即使是在同一个脚本中，也可能会使用多种不同的字体来表示一串文本。如果将contextFontMerging 设置为 true，就会尝试查找与输入字符串最大子集匹配的后备字体。这对字形缺失的字符串来说代价较高，但结果可能更一致。默认情况下，contextFontMerging 是false 。

此属性在 Qt 6.8 中引入。

另请参阅 QFont::StyleStrategy 。

设置字体的族名。

族名不区分大小写，可选择包含代工厂名称，例如 "Helvetica [Cronyx]"。如果有一个以上的字体代工厂提供该族，但未指定代工厂，则会任意选择一个代工厂。如果没有可用的族，则将使用字体匹配算法设置一个族。

在根据features 中的内容塑造文本时，为特定 OpenType 特征应用整数值。这为字体整形过程提供了高级访问权限，可用于支持 API 未涵盖的字体特征。

字体特征由四字母标记到整数值的映射表示。在大多数情况下，与标签一起传递的整数值代表一个布尔值：零值表示禁用该功能，非零值表示启用该功能。但对于某些字体功能，它可能有其他解释。例如，当应用于salt 功能时，该值是一个索引，用于指定要使用的替代样式。

例如，frac 字体功能会将用斜线分隔的对角线分数（如1/2 ）转换为不同的表示方法。通常情况下，这需要将完整的分数转换为单个字符宽度（如½ ）。

如果字体支持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 文档中的表格。

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

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

在调整文本形状时启用或禁用OpenType字形分隔功能。禁用该功能可能会提高创建或更改文本时的性能，但会牺牲一些外观特性。默认值为 true。

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

设置字体的字母间距。

字母间距可更改字体中单个字母之间的默认间距。正值增加相应像素的字母间距，负值减小间距。

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

使用此功能会使字体取决于设备。使用pointSize 可以独立于设备设置字体大小。

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

有时，字体会对一组字符应用复杂的规则，以正确显示这些字符。在某些书写系统（如婆罗门文字）中，为了使文字清晰易读，必须这样做，但在拉丁字母等文字中，这只是一种外观特征。将preferShaping 属性设置为 false 将在不需要时禁用所有此类功能，从而在大多数情况下提高性能。

默认值为 true。

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

竞争提供字体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.weight,font.bold 和font.italic 匹配。

设置文本是否有下划线。

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

可变字体提供了一种在同一字体文件中存储多个变量（具有不同的重量、宽度或样式）的方法。这些变化以浮点数值的形式给出，用于一组预定义的参数，称为 "变量轴"。具体实例通常由字体设计者命名，在 Qt Designer 中，可以使用 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 之间的整数，或预定义值之一：

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

设置字体的字间距。

字间距更改单个字之间的默认间距。正值会相应增加字间距的像素数，而负值则会相应减少字间距。

允许在TextInput 上设置输入掩码，限制允许的文本输入。详情请参见QLineEdit::inputMask ，因为TextInput 也使用了完全相同的屏蔽字符串。

另请参阅 acceptableInput 和validator 。

无论TextInput 是否有来自输入法的部分文本输入，该属性都有效。

在合成输入法时，输入法可能会依靠来自TextInput 的鼠标或按键事件来编辑或提交部分文本。此属性可用于确定何时禁用可能干扰输入法正确运行的事件处理程序。

为输入法提供有关文本输入预期内容及其操作方式的提示。

其值是标志的按位组合，如果未设置提示，则为 Qt.ImhNone。

可改变行为的标志有

限制输入的标志（专用标志）有

屏蔽：

返回TextInput 项目中的字符总数。

如果TextInput 有inputMask ，则长度将包括掩码字符，并可能与text 属性返回的字符串长度不同。

该属性比查询text 属性的长度更快，因为它不需要复制或转换TextInput 的内部字符串数据。

TextInput 中允许的最大文本长度。

如果文本过长，将在限制长度处截断。

默认情况下，该属性的值为 32767。

指定使用鼠标选择文本的方式。

该属性仅适用于selectByMouse 为 true 时。

用户输入的文本是否会覆盖现有文本。

与许多文本编辑器一样，文本编辑器 widget 可以配置为插入用户输入的新文本或覆盖现有文本。

如果该属性为true ，现有文本将被新文本逐字覆盖；否则，文本将插入光标位置，取代现有文本。

默认情况下，该属性为false （新文本不会覆盖现有文本）。

这是echoMode 设置为密码或 PasswordEchoOnEdit 时显示的字符。默认情况下，它是平台主题使用的密码字符。

如果此属性设置为包含多个字符的字符串，则使用第一个字符。如果字符串为空，该值将被忽略，属性也不会被设置。

设置可见字符被密码字符遮挡前的延迟时间（毫秒）。

赋值为 undefined 时将调用重置方法。

当TextInput 的焦点移至场景中的其他项目时，是否应保留其选择。默认设置为 false；

该属性包含来自输入法的部分文本输入。

要关闭预测产生的部分文本，请在inputMethodHints 中设置Qt.ImhNoPredictiveText 标志。

另请参阅 displayText 和inputMethodHints 。

设置用户输入是否可以修改TextInput 的内容。

如果只读设置为 true，则用户输入不会影响文本属性。任何绑定或设置文本属性的尝试仍然有效。

覆盖该组件的默认呈现类型。

支持的呈现类型有

如果希望文本在目标平台上看起来像本地文本，并且不需要文本转换等高级功能，请选择TextInput.NativeRendering 。将此类功能与 NativeRendering 渲染类型结合使用，效果会很差，有时甚至会出现像素化。

TextInput.QtRendering 和TextInput.CurveRendering 都是硬件加速技术。QtRendering 的速度更快，但内存消耗更大，而且在大尺寸时会出现渲染伪影。如果QtRendering 不能提供良好的视觉效果，或优先考虑减少图形内存消耗，则应将CurveRendering 作为替代选择。

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

默认为true 。

如果为 "true"，用户可以使用鼠标以常规方式选择文本。

此只读属性提供了当前在文本输入中所选的文本。

它等同于下面的代码段，但使用起来更快、更方便。

myTextInput.text.toString().substring(myTextInput.selectionStart,
    myTextInput.selectionEnd);

高亮文本颜色，用于选中文本。

文本高亮颜色，在选中后使用。

当前选区中最后一个字符后的光标位置。

此属性为只读。要更改选区，请使用 select(start,end)、selectAll() 或selectWord() 。

另请参阅 selectionStart 、cursorPosition 和selectedText 。

当前选区中第一个字符之前的光标位置。

该属性为只读。要更改选区，请使用 select(start,end)、selectAll() 或selectWord() 。

另请参阅 selectionEnd,cursorPosition, 和selectedText 。

TextInput 中的文本。

请注意，有些键盘使用预测功能。在这种情况下，由输入法组成的文本不属于此属性。文本中与预测相关的部分会加上下划线，并存储在preeditText 属性中。要获取TextInput 中显示的全部文本，请使用displayText 属性。

另请参阅 clear(),displayText, 和preeditText 。

允许您在TextInput 上设置验证器。设置验证器后，TextInput 只接受文本属性处于可接受或中间状态的输入。只有按下回车键时文本处于可接受状态，才会发送接受信号。

目前支持的验证器有IntValidator 、DoubleValidator 和RegularExpressionValidator 。下面是一个使用验证器的示例，它允许在文本输入中输入 11 到 31 之间的整数：

import QtQuick 2.0
TextInput{
    validator: IntValidator{bottom: 11; top: 31;}
    focus: true
}

另请参阅 acceptableInput 和inputMask 。

设置该属性可将文本换行为TextInput 项的宽度。只有设置了明确的宽度，文本才会换行。

默认值是TextInput.NoWrap。如果设置了宽度，请考虑使用TextInput.Wrap。

按下 Return 键或 Enter 键时发出该信号。请注意，如果在文本输入上设置了validator 或inputMask ，则只有在输入处于可接受状态时才会发出该信号。

当按下 Return 或 Enter 键或文本输入失去焦点时，将发出该信号。请注意，如果在文本输入上设置了验证器或inputMask ，并按下回车/回车键，则只有在输入遵循inputMask 且验证器返回可接受状态时，才会发出该信号。

每当编辑文本时都会发出该信号。与textChanged() 不同的是，当以编程方式更改文本（例如更改text 属性的值或调用clear() ）时，不会发出此信号。

清除文本输入内容并重置输入法的部分文本输入。

使用此方法可代替将text 属性设置为空字符串。

另请参阅 QInputMethod::reset().

将当前选择的文本复制到系统剪贴板。

将当前选定的文本移动到系统剪贴板。

删除活动文本选择。

滚动文本输入内容，使指定字符position 在文本输入的边界内可见。

另请参阅 autoScroll 。

返回start 和end 位置之间的文本部分。

如果TextInput 有inputMask ，长度将包括掩码字符。

在position 处插入text 到TextInput 中。

如果在start 和end 位置之间找到的编辑器文本的自然阅读方向是从右到左，则返回 true。

将光标移动到position ，并根据可选的mode 参数更新选区。(要只移动光标，请设置cursorPosition 属性）。

调用此方法时，它还会将selectionStart 或selectionEnd （以光标前一个位置为准）设置到指定位置。这样，您就可以轻松地扩展或收缩选定的文本范围。

选择模式指定是按字符还是按字更新选择。如果未指定，选择模式将默认为TextInput.SelectCharacters 。

例如，下面是一连串的调用：

cursorPosition = 5
moveCursorSelection(9, TextInput.SelectCharacters)
moveCursorSelection(7, TextInput.SelectCharacters)

将光标移动到位置 5，将选择末端从 5 扩展到 9，然后将选择末端从 9 收回到 7，这样就选中了位置 5 至 7 的文本（第 6 和第 7 个字符）。

如果使用TextInput.SelectWords，同样的序列会将选区起点扩展到位置 5 之前或之后的单词边界，并将选区终点扩展到位置 9 之前或之后的单词边界。

用系统剪贴板的内容替换当前选中的文本。

此函数返回从 textInput 左上方x 和y 像素处的字符位置。位置 0 在第一个字符之前，位置 1 在第一个字符之后但在第二个字符之前，依此类推，直到位置 text.length，即所有字符之后。

这意味着，对于第一个字符之前的所有 x 值，该函数都返回 0，而对于最后一个字符之后的所有 x 值，该函数都返回 text.length。如果 y 值位于文本上方，则返回第一行最近字符的位置；如果 y 值位于文本下方，则返回最后一行最近字符的位置。

游标position 参数用于指定游标位置的解析方式：

该函数接收字符位置pos ，并返回光标放置在该字符位置时将占据的矩形区域。

这类似于设置cursorPosition ，然后查询光标矩形，但cursorPosition 不会改变。

如果重做是available ，则重做上次操作。

从TextInput 删除start 和end 位置之间的文本部分。

选择从start 到end 的文本。

如果开始或结束超出范围，则不会更改选择。

调用此方法后，selectionStart 将变为较小的文本，selectionEnd 将变为较大的文本（与传递给此方法的顺序无关）。

另请参阅 selectionStart 和selectionEnd 。

选中所有文本。

选中最接近当前光标位置的文字。

如果撤消是available ，则撤消上次操作。取消选择任何当前选区，并将选区起始位置更新为当前光标位置。