Version: 2023.2
Draw order
Structure UI with UXML

Coordinate and position systems

UI Toolkit uses a powerful layout system that automatically calculates the position and size of individual elements based on the layout parameters in their style properties. This is based on Flexbox, a web layout model. For more information, see Layout Engine.

Relative and absolute positions

UI 工具包有两种坐标:

  • Relative: Coordinates relative to the element’s calculated position. The layout system calculates the position of the element, then adds the coordinates as an offset. Parent elements can influence the size and position of the child elements, as the layout engine takes them into account when it calculates the element position. Child elements can only influence the size of the parent element.
  • Absolute: Coordinates relative to the parent element. This circumvents the automatic layout calculation and directly sets the position of the element. Sibling elements under the same parent have no influence on the element’s position. Similarly, the element doesn’t influence the position and size of other siblings under the same parent.

Each visual element determines the coordinate system used to calculate its position. You can configure which coordinate system to use in the element stylesheet.

下面的代码演示如何通过代码设置一个视觉元素的坐标空间和位置:

    var newElement = new VisualElement();
        newElement.style.position = Position.Relative;
        newElement.style.left = 15;
        newElement.style.top = 35;

元素的原点是其左上角。

The layout system computes the VisualElement.layout property (type Rect) for each element, which includes the final position of the element. This takes the relative or absolute position of the element into account.

layout.position 以点 (point) 表示,相对于其父级的坐标空间。

每个 VisualElement 都有一个变换属性 (ITransform),您可以使用它为元素的位置和旋转添加额外的局部偏移。偏移量并不在计算的布局属性中表示。默认情况下,transform 是标识。

Use the worldBound property to retrieve the final window space coordinates of the VisualElement, taking into account both the layout position and the transform. This position includes the height of the header of the window.

坐标系之间的变换

VisualElement.layout.positionVisualElement.transform 属性用于定义如何在局部坐标系和父坐标系之间进行转换。

The VisualElementExtensions static class provides the following extension methods that transform points and rectangles between coordinate systems:

  • WorldToLocalVector2RectPanel 空间转换为元素内的参照。
  • LocalToWorldVector2Rect 转换为 Panel 空间参照。
  • ChangeCoordinatesToVector2Rect 从一个元素的局部空间转换为另一个元素的局部空间。

Additional resource

Draw order
Structure UI with UXML