跳到主要内容

UI Toolkit 设置指南

本指南将引导你使用 Unity 的新一代 UI 系统 UI Toolkit 来实现 Pinnr。

设置 UI Document​

在菜单栏中点击 GameObject → UI Toolkit → UI Document，创建一个 UI Document GameObject。

也可以在 Hierarchy 视图中右键单击，然后选择 UI Toolkit → UI Document 来完成。

Create a Document

Document Added

系统会自动分配一个默认的 Panel Settings。建议打开该 Panel Settings 资源，确认其 Render Mode 已设置为 Screen Space Overlay，因为 Pinnr 当前尚不支持 UI Toolkit 的 World Space Render Mode。

Ensure Screen Space

在创建的 UI Document GameObject 上添加 Pinnr UI Document 组件：在 Inspector 面板中点击 Add Component → Scripts → Calcatz.Pinnr → Pinnr UI Document。

Add Pinnr UI Document

Pinnr UI Document Added

如果将组件正确添加到 UI Document GameObject 上，这些属性将会自动完成赋值。其中 Camera 属性会默认从主摄像机自动获取；如果需要使用指定的摄像机，也可以手动指定摄像机引用。

在菜单栏中点击 Assets → Create → UI Toolkit → UI Document (UXML)，创建一个新的 Visual Tree Asset（UXML）。

Create UXML

将新创建的 UXML 指定到之前创建的 UI Document GameObject 的 Source Asset 字段中。

Assign UXML

双击该 UXML 资源即可打开 UI Builder。在这里我们将添加所需的 Visual Element。

UI Builder

设置世界空间目标对象​

对于世界空间目标对象的设置方式没有限制。我们只需指定需要跟踪的 Transform，该 Transform 将用于确定 UI 元素的位置。

在 Demo 场景中，我们添加了一个跟随胶囊角色顶部的 UI 元素。为此，我们在角色上方创建了一个子 GameObject，并将其作为 UI 元素跟随的目标。

Create Target

设置 UI 元素​

准备 UXML​

我们可以先在 UI Builder 中创建任意需要的 Visual Element。如果尚未熟悉 Visual Element，可以参考提供的 DemoVisualTree，其中包含一个可正常工作的 Pinnr UXML 示例。

要使 Visual Element 能正确与 Pinnr 配合使用，其样式中的 Position Mode 必须设置为 Absolute。同时，该元素的名称必须唯一，以便进行查询。

为了更快速地完成设置，可以使用提供的 PinnrStyleSheet.uss 文件，并通过 UI Builder 将其添加到当前的 UXML 中。

Add USS

在该 StyleSheet 中会包含一个名为 .pinnr-element 的类。将其拖拽到我们之前创建的元素上。该类会处理所需的样式设置，包括将 Position Mode 设置为 Absolute。

Add Class

实现 Pinnr 元素​

与 UGUI Canvas 不同，UI Toolkit 中的 Visual Element 并不存在于 Hierarchy 中的 GameObject 或 Component。

要将世界空间目标对象的位置应用到 Visual Element 上，需要使用 Pinnr Element UITK 组件。该组件会查询对应的 Visual Element，并更新其位置。

可以将 Pinnr Element UITK 组件添加到任意 GameObject 上，但为了更好的 Hierarchy 组织，建议将其添加到 UI Document GameObject 下的一个空子 GameObject 上。

在 Inspector 面板中点击 Add Component → Scripts → Calcatz.Pinnr → Pinnr Element UITK，以添加 Pinnr Element UITK 组件。

Add Pinnr Element UITK

将之前创建的世界空间目标对象进行指定。

Assign Target

在 Element Name 字段中填写 Visual Element 的名称。这也是为什么该元素的名称必须保持唯一。也可以通过类来进一步缩小查询范围。

Assign Element Name

  • World Space Target Object: UI 元素需要跟随的世界空间目标对象。
  • Always Update UI Position: 每帧更新 UI 位置。如果 UI 元素不需要持续跟随目标，可将其禁用以优化性能，并在需要时通过脚本调用 UpdateUIPosition() 方法手动更新位置。
  • Disable If Behind Camera: 当目标物体位于摄像机后方时禁用该行为（防止其显示在屏幕上）。
  • Auto Update In Edit Mode: 在编辑模式下（编辑器未处于播放模式时）每帧自动更新位置。
  • Document: 只要根 UI Document GameObject 上已添加 Pinnr UI Document 组件，该属性将自动初始化。此项为必需。
  • Enable Proximity Based Scaling: 启用后可使用基于距离的缩放功能。该功能会根据摄像机与 UI 元素之间的距离对元素进行缩放。 Proximity Based Scaling
    • Initial Scale: 元素的初始缩放值。
    • Distance:
      • Far: 当摄像机与该元素之间的距离大于或等于 Far 值时，应用最小缩放值。
      • Near: 当摄像机与该元素之间的距离小于或等于 Near 值时，应用最大缩放值。
    • Scale: 根据指定的距离数值应用的缩放值。如果距离介于 Far 与 Near 之间，则缩放值会根据两者之间的距离比例进行插值计算。
    • World Space Scale Render Factor (Pinnr Element UITK 不可用): 仅在 World Space Render Mode 下使用的缩放系数。

至此设置完成，创建的 UI 元素将会跟随目标的位置。