链接器组件从 UIDocument 中解析一个元素，并将其公开为具体的 UI Toolkit 类型。

设置链接器

1. 使用 UXML 资源和 PanelSettings 创建 UIDocument。
2. 添加与目标元素类型匹配的 ULB 链接器，例如为 Button 添加 UitkButton。
3. 为 UIDocument 字段赋值。
4. 选择 Linking Mode，并填写该模式显示的定位条件字段。
5. 需要层级搜索诊断信息时启用 Debug。
6. LinkElement 运行后，通过 Element 或 E 访问结果。

链接模式

Name

Name 使用配置的 Name 对 UIDocument 根元素调用 Query。元素名称唯一且层级变化不应影响链接时使用此模式。

IndexNames

IndexNames 沿配置的 Names 数组逐个层级段查找。Index = -1 的层级段按 Name 匹配。其他 Index 值会选择该位置的子元素，且不验证层级段的 Name。这是默认模式。

Guid

Guid 递归扫描后代元素，查找 IHaveGuid.guid 值与配置的 Guid 匹配的一个 ULB 元素。它不受父级层级变化影响，但可能扫描树中的很大一部分。

Guids

Guids 沿 GUID 值构成的精确分支查找。每个匹配的层级段都必须实现 IHaveGuid。它搜索的树范围更小，但该分支中的父级发生变化时，必须更新保存的路径。

从 UI Builder 复制层级

1. 在 UI Builder 中打开 UXML 资源，并只选择一个目标元素。
2. 在 Unity 主菜单中打开 Tools > D.A. Assets。
3. 选择 UITK Linker: Copy element name hierarchy、Copy element index hierarchy、Copy element index + name hierarchy 或 Copy element guid hierarchy。
4. 将剪贴板中的序列化值粘贴到检查器内链接器的 Names 或 Guids 数组字段中。

索引和名称命令会同时存储两个值以提高可读性，但运行时查找仍会在 Index 不为 -1 时优先使用 Index。

持久化 GUID 值

在 UXML 中使用 ULB *G 元素，保存 UXML 资源，并验证每个 guid 属性仍保持序列化。仅在内存中生成的 GUID 不是稳定的定位条件。

<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:ulb="DA_Assets.ULB">
    <ulb:ButtonG
        name="save-button"
        guid="9c7f1231e0aa438687d8804d63053783"
        text="Save" />
</ui:UXML>

访问已链接的元素

using System.Collections;
using DA_Assets.ULB;
using UnityEngine;

public sealed class SaveView : MonoBehaviour
{
    [SerializeField] private UitkButton saveButton;

    private IEnumerator Start()
    {
        yield return null;
        saveButton.Element.clicked += Save;
    }

    private void Save()
    {
    }
}

Element 和 E 返回同一个强类型引用。

选择模式

• Name：设置最简单；需要稳定且唯一的名称。
• IndexNames：高效地沿一个分支查找；重新排序或重命名层级段后需要更新。
• Guid：不受父级移动影响；会递归搜索后代元素。
• Guids：选择性最高的 GUID 查找；更改 GUID 父级链后需要更新。