使用 UQuery 查找视觉元素

您可以使用 UQuery 从可视化树 由轻量级节点组成的对象图，用于保存窗口或面板中的所有元素。它定义了使用 UI 工具包构建的每个 UI。
请参阅术语表.UQuery 的灵感来自 JQuery 和 Linq，旨在限制动态内存分配。这允许在移动平台上实现最佳性能。

查询方法

您可以通过以下扩展方法使用 UQuery：

• Q
• Query

在内部，Q和Query方法 使用UQueryBuilder构造查询。这些扩展方法减少了创建UQueryBuilder.

要使用 UQuery 查找元素，您必须先加载并实例化 UXML，然后使用Query或Q在根上构造选择规则视觉元素实例化或派生自 C# 的可视化树的节点VisualElement类。您可以设置外观样式、定义行为并将其作为 UI 的一部分显示在屏幕上。更多信息
请参阅术语表.

Query返回与选择规则匹配的元素列表。您可以筛选Query使用UQueryBuilder，例如 First、Last、AtIndex、Children 和 Where。

Q是Query<T>.First().它返回与选择规则匹配的第一个元素。

查询元素

可以按元素名称、USS 类或元素类型（C# 类型）查询元素。还可以使用谓词进行查询或进行复杂的分层查询。

以下小节使用此示例UXML来演示如何查找元素：

<UXML xmlns="UnityEngine.UIElements">
    <VisualElement name="container1">
      <Button name="OK" text="OK" />
      <Button name="Cancel" text="Cancel" />
    </VisualElement>
     <VisualElement name="container2">
      <Button name="OK" class="yellow" text="OK" />
      <Button name="Cancel" text="Cancel" />
    </VisualElement>
    <VisualElement name="container3">
      <Button name="OK" class="yellow" text="OK" />
      <Button name="Cancel" class="yellow" text="Cancel" />
    </VisualElement>
</UXML>

按名称查询

要按名称查找元素，请使用Query(name: "element-name")或Q(name: "element-name").您可以省略name因为它是第一个参数。例如：

以下示例查找名为“OK”的元素列表：

List<VisualElement> result = root.Query("OK").ToList();

以下示例使用Query找到第一个名为“OK”的元素：

VisualElement result = root.Query("OK").First(); //or VisualElement result = root.Q("OK");

以下示例使用Q找到第一个名为“OK”的元素：

VisualElement result = root.Q("OK");

以下示例查找名为“OK”的第二个元素：

VisualElement result3 = root.Query("OK").AtIndex(1);

以下示例查找名为“OK”的最后一个元素：

VisualElement result4 = root.Query("OK").Last();

按USS级查询

要按 USS 类查找元素，请使用Query(className: "class-name")或Q(className: "class-name").

以下示例查找具有类“yellow”的所有元素，并将它们分配给列表：

List<VisualElement> result = root.Query(className: "yellow").ToList();

以下示例查找具有类“yellow”的第一个元素：

VisualElement result = root.Q(className: "yellow");

按元素类型查询

若要按元素类型（C# 类型）查找元素，请使用Query<Type>或Q<Type>.

以下示例查找第一个按钮并为其添加工具提示：

VisualElement result = root.Q<Button>();
result.tooltip = "This is a tooltip!";

以下示例查找第三个按钮：

VisualElement result = root.Query<Button>().AtIndex(2);

注意：您只能按元素的实际类型进行查询，而不能按基类进行查询。

使用谓词进行查询

除了按名称、类和类型查询元素外，还可以使用Where方法来选择满足谓词的所有元素。谓词必须是函数回调，该回调采用单个VisualElement论点。

以下示例查找具有“黄色”USS 类且没有工具提示的所有元素：

List<VisualElement> result = root.Query(className: "yellow").Where(elem => elem.tooltip == "").ToList();

复杂的分层查询

您可以组合名称、类和类型来进行复杂的分层查询。

以下示例查找第一个名为“OK”的按钮，该按钮的类为“yellow”：

VisualElement result = root.Query<Button>(className: "yellow", name: "OK").First();

以下示例查找“container2”的子取消按钮：

VisualElement result = root.Query<VisualElement>("container2").Children<Button>("Cancel").First();

根据结果进行作

可以使用 ForEach 方法直接对查询结果进行作。

以下示例为没有工具提示的任何元素添加工具提示：

root.Query().Where(elem => elem.tooltip == "").ForEach(elem => elem.tooltip="This is a tooltip!");

最佳做法

使用 UQuery 时，请考虑以下事项：

• UQuery 遍历层次结构，按名称、类或类型查找元素。初始化时来自 UQuery 的缓存结果。
• 如果您需要检索多个元素，请使用QueryStatestruct（由element.Query()方法）并枚举它以避免创建列表。您还可以构造一次查询并在不同的元素上执行它。
• UI 工具包不会销毁不再需要的视觉元素，它使用 C# 垃圾回收器来收集它们。请注意，不要意外地在类中保留对视觉元素的引用，该类的寿命超过元素来源的 UIDocuments 或 Window。
• 捕获VisualElement闭包内的变量。
• 创建或释放大量元素时，请启用增量垃圾回收以避免垃圾回收器峰值。

其他资源

• USS 选择器
• 视觉元素和视觉树简介
• 从 C# 脚本加载 UXML 和 USS
• 使用 C 实例化 UXML#