TextField

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

注意：要将 TextField 与 Inspector 窗口中的其他字段对齐，只需将 .unity-base-field__aligned USS 类加以应用即可。有关更多信息，请参阅 BaseField。

创建 TextField

您可以使用__ UI__（即用户界面，User Interface）让用户能够与您的应用程序进行交互。Unity 目前支持三种 UI 系统。更多信息
See in Glossary Builder、UXML 和 C# 创建 TextField。以下 C# 示例将创建允许多行文本输入的 TextField：

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

设置占位文本

可为元素设置占位文本。还可以在焦点上隐藏占位文本。

注意：如果为元素设置了值，则不会显示占位文本。要在 UI Builder 中取消设置值，请右键单击元素的检视面板 (Inspector) 选项卡中的值 (Value) 字段，然后选择取消设置 (Unset)。

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

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 中实时试用此示例，请转到窗口 (Window) > UI 工具包 (UI Toolkit) > 示例 (Samples)。

C# 基类和命名空间

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

成员 UXML 属性

此元素具有以下成员属性：

继承 UXML 属性

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

此元素还从 VisualElement 继承以下属性：

USS 类

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

还可以使用检视器中的匹配选择器 (Matching Selectors) 部分或 UI 工具包调试器来查看哪些 USS 选择器在其层级视图的每个级别上影响 VisualElement 的组件。

USS 自定义属性

下表概述了 USS 中专用于 TextField 元素的自定义属性：

其他资源

• 处理文本
• Label
• DoubleField
• LongField
• FloatField
• IntegerField
• PropertyField