UXML 元素 TextField

TextField 允许用户将文本数据输入到应用程序中。它接受并显示文本输入。您可以设置占位符文本，为用户提供有关输入内容的提示或说明。您还可以添加验证函数以确保输入的数据满足某些要求。

注意：要将 TextField 与 检视器一个 Unity 窗口，显示有关当前选定游戏对象、资源或项目设置的信息，允许您检查和编辑值。 更多信息
请参阅 术语表 窗口中的其他字段对齐，只需将其应用 .unity-base-field__aligned USS 类即可。有关更多信息，请参阅 BaseField。

创建 TextField

您可以使用 UI(用户界面) 允许用户与您的应用程序交互。Unity 目前支持三种 UI 系统。 更多信息
请参阅 术语表 生成器、UXML 和 C# 创建 TextField。以下 C# 示例创建了一个允许多行文本输入的 TextField

var textField = new TextField();
textField.label = "Enter your text here:";
textField.multiline = true;
textField.maxLength = 140;

设置占位符文本

您可以为该元素设置占位符文本。您也可以在获得焦点时隐藏占位符文本。

注意：如果您为该元素设置了值，则占位符文本不会显示。要在 UI 生成器中取消设置值，请右键单击该元素的检视器选项卡中的值字段，然后选择取消设置。

在 C# 中，使用 placeholder 和 hidePlaceholderOnFocus 属性通过 textEdition

myElement.textEdition.placeholder = "Enter your value here";
myElement.textEdition.hidePlaceholderOnFocus = true;

要设置占位符文本的样式，请使用 .unity-base-text-field__input--placeholder USS 选择器。

自定义输入文本选择

默认情况下，输入文本是可选择的。您可以自定义选择行为，例如 selectAllOnMouseUP 和 selectAllOnFocus。

在 C# 中，通过 textSelection

myElement.textSelection.selectAllOnMouseUp = false;
myElement.textSelection.selectAllOnFocus = false;

您还可以使用 --unity-selection-color USS 自定义属性设置选定文本的样式。例如，以下 USS 将选定输入文本的颜色设置为黄色

.unity-base-text-field__input {
    --unity-selection-color: yellow;
}

启用垂直滚动条

如果您在 TextField 上启用了多行文本，则可以为 文本输入字段允许用户输入文本字符串的字段 更多信息
请参阅 术语表 显示垂直滚动条。

在 C# 中，设置 verticalScrollerVisibility 属性为 ScrollerVisibility.Auto 或 ScrollerVisibility.AlwaysVisible

// Set the multiline property to true to enable multiple lines of text
textField.multiline = true;

// Set the vertical scrollbar visibility to AlwaysVisible
textField.verticalScrollerVisibility = ScrollerVisibility.AlwaysVisible;

控制输入文本的行为

您可以使用 事件 来控制输入文本的行为。以下示例使用事件回调函数来处理文本字段的导航和提交事件。该示例向 导航事件 注册 TrickleDown 阶段，然后由 TextElement 基类处理这些事件

// A callback function that executes submit logic to handle user input submission. 
// It stops the propagation of the event to prevent it from reaching other event handlers.
myField.RegisterCallback<NavigationSubmitEvent>((evt) => {

    // Submit logic
    evt.StopPropagation();
}, TrickleDown.TrickleDown);

// A callback function that executes focus logic to handle navigation between different UI elements. 
// If the navigation direction is up, down, left, or right, it stops the propagation of the event and instructs 
// the focusController to ignore the event.
myField.RegisterCallback<NavigationMoveEvent>((evt) => {

    if (evt.direction == NavigationMoveEvent.Direction.Up || evt.direction == NavigationMoveEvent.Direction.Down || evt.direction == NavigationMoveEvent.Direction.Left || evt.direction == NavigationMoveEvent.Direction.Right)
    {
        // Focus logic
        evt.StopPropagation();
        focusController.IgnoreEvent(evt);
    }

}, TrickleDown.TrickleDown);

示例

以下 UXML 示例创建了一个 TextField

<UXML xmlns="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements">
    <TextField label="UXML Field" name="the-uxml-field" value="It's snowing outside." />
</UXML>

以下 C# 示例说明了 TextField 的一些可自定义功能

/// <sample>
// Get a reference to the field from UXML and append a value to it.
var uxmlField = container.Q<TextField>("the-uxml-field");
uxmlField.value += "..";

// Create a new field, disable it, and give it a style class.
var csharpField = new TextField("C# Field");
csharpField.value = "It's snowing outside...";
csharpField.SetEnabled(false);
csharpField.AddToClassList("some-styled-field");
csharpField.value = uxmlField.value;
container.Add(csharpField);

// Mirror the value of the UXML field into the C# field.
uxmlField.RegisterCallback<ChangeEvent<string>>((evt) =>
{
    csharpField.value = evt.newValue;
});
/// </sample>

要在 Unity 中实时尝试此示例，请转到窗口 > UI 工具包 > 示例。

C# 基类和命名空间

C# 类：TextField
命名空间：UnityEngine.UIElements
基类：TextInputBaseField_1

成员 UXML 属性

该元素具有以下成员属性

名称	类型	描述
multiline	布尔值	将其设置为 true 以允许文本字段中的多行，否则设置为 false。
value	字符串	该字段当前公开的字符串。

继承的 UXML 属性

该元素从其基类继承以下属性

名称	类型	描述
auto-correction	布尔值	确定触摸屏键盘自动更正是否开启或关闭。
binding-path	字符串	要绑定的目标属性的路径。
emoji-fallback-support	布尔值	指定系统在呈现文本时查找 Emoji 字符的顺序。如果启用此设置，系统将首先在全局 Emoji 回退列表中搜索 Unicode 14.0 标准中定义为 Emoji 的字符。
focusable	布尔值	如果该元素可以获得焦点，则为 true。
hide-mobile-input	布尔值	隐藏或显示移动输入字段。
is-delayed	布尔值	如果设置为 true，则在用户按 Enter 键或文本字段失去焦点之前，不会更新 value 属性。
keyboard-type	TouchScreenKeyboardType	将使用的移动键盘类型。
label	字符串	表示将出现在字段旁边的标签的字符串。
max-length	int	该字段的最大字符数。
select-all-on-focus	布尔值	控制元素在获得焦点时是否选择其内容。
select-all-on-mouse-up	布尔值	控制首次鼠标抬起时是否选择元素的内容。
tabindex	int	用于对焦点环中的可聚焦项进行排序的整数。必须大于或等于零。
value	字符串	与该字段关联的值。
vertical-scroller-visibility	UIElements.ScrollerVisibility	用于控制 TextInputBaseField_1 中垂直滚动条可见性的选项。

该元素还从 VisualElement 继承以下属性

名称	类型	描述
content-container	字符串	子元素被添加到它中，通常与元素本身相同。
data-source	对象	将数据源分配给此 VisualElement，这会覆盖任何继承的数据源。此数据源由所有子元素继承。
data-source-path	字符串	从数据源到值的路径。
data-source-type	System.Type	可分配给此 VisualElement 的数据源的可能类型。 此信息仅由 UI 生成器用作提示，以便在设计时无法指定有效数据源时为数据源路径字段提供一些完成。
language-direction	UIElements.LanguageDirection	指示元素文本的方向。该值将传播到元素的子元素。 将 languageDirection 设置为 RTL 将通过反转文本并适当处理换行符和单词换行来添加对从右到左 (RTL) 的基本支持。但是，它不提供全面的 RTL 支持，因为这将需要文本整形，包括字符重新排序和 OpenType 字体功能支持。全面的 RTL 支持计划在未来的更新中提供，这将涉及处理语言、脚本和字体功能规范的附加 API。 为了增强此属性的 RTL 功能，用户可以探索 Unity Asset Store 中可用的第三方插件，并使用 ITextElementExperimentalFeatures.renderedText
name	字符串	此 VisualElement 的名称。 使用此属性编写针对特定元素的 USS 选择器。标准做法是为元素指定唯一名称。
picking-mode	UIElements.PickingMode	确定此元素在鼠标事件或 IPanel.Pick 查询期间是否可被选中。
style	字符串	设置 VisualElement 样式值。
tooltip	字符串	在用户将鼠标悬停在元素上很短时间后，在信息框中显示的文本。这仅在编辑器 UI 中受支持。
usage-hints	UIElements.UsageHints	指定 VisualElement 的高级预期使用模式的提示值组合。仅在 VisualElement 尚未成为 Panel 的一部分时，才能设置此属性。一旦成为 Panel 的一部分，此属性将变为有效只读，尝试更改它将引发异常。正确 UsageHints 的规范会驱动系统做出更好的决策，根据预期的使用模式来处理或加速某些操作。请注意，这些提示不会影响行为或视觉效果，只会影响面板及其内部元素的整体性能。建议始终考虑指定正确的 UsageHints，但请记住，某些 UsageHints 可能会在某些情况下被内部忽略（例如，由于目标平台上的硬件限制）。
view-data-key	字符串	用于视图数据持久性，例如树展开状态、滚动位置或缩放级别。 此键用于从视图数据存储中保存和加载视图数据。如果您没有设置此键，则与关联 VisualElement 相关的持久性将被禁用。有关更多信息，请参阅 视图数据持久性。

USS 类

下表列出了所有 C# 公共属性名称及其相关的 USS 选择器。

C# 属性	USS 选择器	描述
ussClassName	.unity-text-field	此类型元素的 USS 类名。
labelUssClassName	.unity-text-field__label	此类型元素中标签的 USS 类名。
inputUssClassName	.unity-text-field__input	此类型元素中输入元素的 USS 类名。
ussClassName	.unity-base-text-field	此类型元素的 USS 类名。
labelUssClassName	.unity-base-text-field__label	此类型元素中标签的 USS 类名。
inputUssClassName	.unity-base-text-field__input	此类型元素中输入元素的 USS 类名。
singleLineInputUssClassName	.unity-base-text-field__input--single-line	此类型元素中单行输入元素的 USS 类名。
multilineInputUssClassName	.unity-base-text-field__input--multiline	此类型元素中多行输入元素的 USS 类名。
placeholderUssClassName	.unity-base-text-field__input--placeholder	显示占位符文本时输入元素的 USS 类名
ussClassName	.unity-base-field	此类型元素的 USS 类名。
labelUssClassName	.unity-base-field__label	此类型元素中标签的 USS 类名。
inputUssClassName	.unity-base-field__input	此类型元素中输入元素的 USS 类名。
noLabelVariantUssClassName	.unity-base-field--no-label	此类型元素的 USS 类名，当没有标签时。
labelDraggerVariantUssClassName	.unity-base-field__label--with-dragger	此类型元素中标签的 USS 类名，当它们附加了拖动器时。
mixedValueLabelUssClassName	.unity-base-field__label--mixed-value	显示混合值的元素的 USS 类名
alignedFieldUssClassName	.unity-base-field__aligned	在检视器元素中对齐的元素的 USS 类名
disabledUssClassName	.unity-disabled	本地禁用元素的 USS 类名。

您还可以使用 检视器或 UI 工具包调试器中的匹配选择器部分 来查看哪些 USS 选择器影响 VisualElement 层次结构中每个级别的组件。

USS 自定义属性

下表概述了仅在 USS 中的 TextField 元素中可用的自定义属性

属性	类型	描述
--unity-cursor-color	字符串	文本插入符的颜色代码。
--unity-selection-color	字符串	选定文本的颜色代码。

其他资源

• 处理文本
• UXML 元素 Label
• UXML 元素 DoubleField
• UXML 元素 LongField
• UXML 元素 FloatField
• UXML 元素 IntegerField
• UXML 元素 PropertyField