Version: Unity 6.0 (6000.0)
语言 : 中文
从 C# 脚本实例化 UXML
使用 C# 脚本的结构 UI

使用 UQuery 查找视觉元素

您可以使用 UQuery视觉树中查找元素。UQuery 受 JQuery 和 Linq 的启发,旨在限制动态内存分配。因此适合在移动平台上实现最佳性能。

查询方法

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

在内部,QQuery 方法使用 UQueryBuilder 来构造查询。这些扩展方法降低了创建 UQueryBuilder 的详细级别。

要使用 UQuery 查找元素,必须首先加载实例化 UXML,然后使用 QueryQ 在根视觉元素上构造选择规则。

Query 返回与选择规则匹配的元素列表。您可以使用 UQueryBuilder 的公共方法(例如 FirstLastAtIndexChildrenWhere)过滤 Query 的返回结果。

QQuery<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")

以下示例查找具有“黄色”类的所有元素,并将这些元素分配给列表:

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 的结果。
  • 如果需要检索多个元素,请使用 QueryState 结构(由 element.Query() 方法返回)并进行枚举以避免创建列表。还可以构造一次查询并在不同元素上执行查询。
  • UI 工具包不会销毁不再需要的视觉元素,而是使用 C# 垃圾回收器来收集元素。请注意,不要意外地在超出元素来源的 UIDocuments 或 Window 生命周期的类中保留对视觉元素的引用。
  • 捕获闭包内的 VisualElement 变量。
  • 创建或释放大量元素时,请启用增量垃圾收集以避免垃圾回收器尖峰。

其他资源

从 C# 脚本实例化 UXML
使用 C# 脚本的结构 UI