焦点事件

当元素获得或失去焦点时将发生焦点事件。

当您需要更改焦点，使其进入和离开视觉元素时，焦点事件非常有用。控件通常使用焦点事件来更改其内容，具体取决于焦点状态。例如，文本字段可以在未获得焦点时显示占位文本，或者对 FocusInEvent 作出反应以清除占位文本。

焦点可通过用户交互操作（例如 Tab 键或单击）或使用带有 element.Focus() 的 C# 脚本转到某个视觉元素上。

焦点事件分为两种不同的类型：

• 在焦点发生变化之前沿着传播路径发送的 FocusOutEvent 和 FocusInEvent 事件。
• 在焦点变化后立即发送到事件目标的 FocusEvent 和 BlurEvent 事件。

所有焦点事件的基类是 FocusEventBase。

独特的属性

以下部分解释了焦点事件独有的相关属性。这并非焦点事件系列中所有属性的完整列表。有关完整列表，请参阅 API 文档中的 FocusEventBase。

relatedTarget：包含作为事件次要目标的视觉元素。对于 FocusOut 和 Blur 事件，包含获取焦点的元素。对于 FocusIn 和 Focus 事件，包含失去焦点的元素。

事件列表

FocusOutEvent

当元素即将失去焦点时发送 FocusOutEvent 事件。

target：将失去焦点的元素。

relatedTarget：将获得焦点的元素。

FocusInEvent

当元素即将获得焦点时发送 FocusInEvent 事件。

target：将获得焦点的元素。

relatedTarget：将失去焦点的元素。

BlurEvent

当元素失去焦点后发送的事件。

target：失去焦点的元素。

relatedTarget：获得焦点的元素。

FocusEvent

当元素获得焦点后发送的事件。

target：获得焦点的元素。

relatedTarget：失去焦点的元素。

示例

以下示例显示如何在 TextField 中使用占位文本。

通过 UXML 创建元素后，脚本会为 TextField 分配一个占位文本。当 TextField 获得焦点时，FocusInEvent 会触发并清除占位文本。FocusOutEvent 将根据 TextField 内容切换占位模式。

要查看示例运行效果，请执行以下操作：

1. 创建一个名为 PlaceHolderExample 的 C# 新脚本。
2. 将该示例代码复制到 C# 脚本。
3. 在 Window > UI Toolkit > PlaceHolderExample 下，打开新创建的编辑器窗口。

using UnityEditor;
using UnityEngine;
using UnityEngine.UIElements;

public class PlaceHolderExample : EditorWindow
{
    [MenuItem("Window/UI Toolkit/PlaceHolderExample")]
    public static void ShowExample()
    {
        PlaceHolderExample wnd = GetWindow<PlaceHolderExample>();
        wnd.titleContent = new GUIContent("PlaceHolderExample");
    }

    private bool placeHolderMode = true;
    private const string placeHolderText = "Write here";

    public void CreateGUI()
    {
        TextField textField = new TextField();
        textField.value = placeHolderText;
        rootVisualElement.Add(textField);

        textField.RegisterCallback<FocusInEvent>(OnFocusInTextField);
        textField.RegisterCallback<FocusOutEvent>(OnFocusOutTextField);
    }

    private void OnFocusInTextField(FocusInEvent evt)
    {
        // 如果文本字段刚刚获得焦点并且用户可能想要编写
        // 或编辑里面的文本，占位文本应该被清除（如果活动）
        if (placeHolderMode)
        {
            var textField = evt.target as TextField;
            textField.value = "";
        }
    }

    private void OnFocusOutTextField(FocusOutEvent evt)
    {
        // 如果用户完成编辑后文本字段为空，并且
        //元素失去焦点，将占位文本写入文本字段
        var textField = evt.target as TextField;
        placeHolderMode = string.IsNullOrEmpty(textField.value);
        if (placeHolderMode)
            textField.value = placeHolderText;
    }
}