UITransform

UITransform is a transform component specifically designed for UI elements, inheriting from the base Transform component. It provides rich layout and alignment features and is a core component for building flexible UI systems.

Editor Usage

When a node with UI components is added, the UITransform component will be automatically added (replacing the previous Transform component). In the editor, you can select the node and use the RectTool (shortcut key T) to quickly set properties, or set precise properties in the Inspector Panel.

Adjusting Size and Pivot

Setting Relative Layout

When the main canvas's render mode is Screen, the editor will prohibit modifications to its transform to avoid screen adaptation issues. Therefore, in scripts, developers should avoid modifying the transform properties of the main canvas in screen space.

Properties

Property Name	Description
`size`	The size of the UI element. `x` represents width, and `y` represents height. Both default to `100`
`pivot`	The anchor point of the UI element. It is a normalized 2D vector with the origin at the bottom-left corner, with the default value being the center point (0.5, 0.5)
`horizontalAlignment`	Horizontal relative layout mode `HorizontalAlignment`
`alignLeft`	Distance from the parent element's left edge, effective only when `HorizontalAlignment.Left` or `HorizontalAlignment.LeftAndRight`
`alignRight`	Distance from the parent element's right edge, effective only when `HorizontalAlignment.Right` or `HorizontalAlignment.LeftAndRight`
`alignCenter`	Horizontal center offset, effective only when `HorizontalAlignment.Center`
`verticalAlignment`	Vertical relative layout mode `VerticalAlignment`
`alignTop`	Distance from the parent element's top edge, effective only when `VerticalAlignment.Top` or `VerticalAlignment.TopAndBottom`
`alignBottom`	Distance from the parent element's bottom edge, effective only when `VerticalAlignment.Bottom` or `VerticalAlignment.TopAndBottom`
`alignMiddle`	Vertical center offset, effective only when `VerticalAlignment.Middle`

Relative layout properties only take effect under the corresponding layout mode.

Script Usage

Setting Size and Pivot

// Add canvas
const canvasEntity = root.createChild("canvas");
const canvas = canvasEntity.addComponent(UICanvas);
const imageEntity = canvasEntity.create("Image");
const uiTransform = <UITransform>imageEntity.transform;
// Set size
uiTransform.size = new Vector2(200, 100);
// Set pivot
uiTransform.pivot = new Vector2(0.5, 0.5);

Setting Horizontal Relative Layout

// Left align, 10 pixels from left edge
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Left;
uiTransform.alignLeft = 10;
 
// Right align, 20 pixels from right edge
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Right;
uiTransform.alignRight = 20;
 
// Horizontal center, offset 15 pixels to the right
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Center;
uiTransform.alignCenter = 15;
 
// Horizontal stretch, 30 pixels margin on both sides
uiTransform.horizontalAlignment = HorizontalAlignmentMode.LeftAndRight;
uiTransform.alignLeft = 30;
uiTransform.alignRight = 30;

Setting Vertical Relative Layout

// Top align, 10 pixels from top
uiTransform.verticalAlignment = VerticalAlignmentMode.Top;
uiTransform.alignTop = 10;
 
// Bottom align, 20 pixels from bottom
uiTransform.verticalAlignment = VerticalAlignmentMode.Bottom;
uiTransform.alignBottom = 20;
 
// Vertical center, offset 5 pixels up
uiTransform.verticalAlignment = VerticalAlignmentMode.Middle;
uiTransform.alignMiddle = 5;
 
// Vertical stretch, 25 pixels margin on top and bottom
uiTransform.verticalAlignment = VerticalAlignmentMode.TopAndBottom;
uiTransform.alignTop = 25;
uiTransform.alignBottom = 25;

Best Practices

Responsive Layout

Using LeftAndRight and TopAndBottom alignment modes can create responsive layouts where elements automatically adjust according to the parent container's size.

// Create an element that always matches the parent element's size
uiTransform.horizontalAlignment = HorizontalAlignmentMode.LeftAndRight;
uiTransform.verticalAlignment = VerticalAlignmentMode.TopAndBottom;
uiTransform.alignLeft = uiTransform.alignRight = 0;
uiTransform.alignTop = uiTransform.alignBottom = 0;

Performance Considerations

Avoid frequent modifications to alignment properties as they trigger layout recalculation

Important Notes

Relative Layout Priority: When relative layout is set, directly setting position will be overridden by alignment calculations
Margin Effectiveness: Each margin property only takes effect under the corresponding alignment mode
Stretch Mode: When using LeftAndRight or TopAndBottom, the corresponding direction's size will be automatically calculated
Parent-Child Relationship: UI alignment is based on the parent element's UITransform, ensure the parent element is also a UI element 1 title: UITransform type: UI label: UI

UITransform Component

UITransform is a transform component specifically designed for UI elements in the Galacean engine, inheriting from the base [Transform](/apis/core/#Transform) component. It provides rich layout and alignment features and is a core component for building flexible UI systems.

Core Features

Size and Pivot Control

size: Controls the width and height of UI elements
pivot: Sets the anchor point position of UI elements, affecting the center point for rotation and scaling

Horizontal Alignment System

UITransform provides four horizontal alignment modes:

Left: Align to the left edge of the parent element
Center: Center align to the horizontal center of the parent element
Right: Align to the right edge of the parent element
LeftAndRight: Align to both left and right edges (stretch to fill width)

Vertical Alignment System

Similarly provides four vertical alignment modes:

Top: Align to the top edge of the parent element
Middle: Center align to the vertical center of the parent element
Bottom: Align to the bottom edge of the parent element
TopAndBottom: Align to both top and bottom edges (stretch to fill height)

Main Properties

Basic Properties

size

get size(): Vector2
set size(value: Vector2)

Width and height of the UI element.

Example:

// Set UI element size to 200x100
uiTransform.size = new Vector2(200, 100);

pivot

get pivot(): Vector2
set pivot(value: Vector2)

Anchor point of the UI element, ranging from (0,0) to (1,1).

(0,0) represents bottom-left corner
(0.5,0.5) represents center point
(1,1) represents top-right corner

Example:

// Set pivot to center
uiTransform.pivot = new Vector2(0.5, 0.5);
// Set pivot to bottom-left corner
uiTransform.pivot = new Vector2(0, 0);

Horizontal Alignment Properties

horizontalAlignment

get horizontalAlignment(): HorizontalAlignmentMode
set horizontalAlignment(value: HorizontalAlignmentMode)

Horizontal alignment mode that controls the element's horizontal position within its parent container.

alignLeft

get alignLeft(): number
set alignLeft(value: number)

Left margin, only effective when horizontalAlignment is Left or LeftAndRight.

alignRight

get alignRight(): number
set alignRight(value: number)

Right margin, only effective when horizontalAlignment is Right or LeftAndRight.

alignCenter

get alignCenter(): number
set alignCenter(value: number)

Horizontal center offset, only effective when horizontalAlignment is Center.

Positive values: move right
Negative values: move left

Vertical Alignment Properties

verticalAlignment

get verticalAlignment(): VerticalAlignmentMode
set verticalAlignment(value: VerticalAlignmentMode)

Vertical alignment mode that controls the element's vertical position within its parent container.

alignTop

get alignTop(): number
set alignTop(value: number)

Top margin, only effective when verticalAlignment is Top or TopAndBottom.

alignBottom

get alignBottom(): number
set alignBottom(value: number)

Bottom margin, only effective when verticalAlignment is Bottom or TopAndBottom.

alignMiddle

get alignMiddle(): number
set alignMiddle(value: number)

Vertical center offset, only effective when verticalAlignment is Middle.

Positive values: move up
Negative values: move down

Usage Examples

Basic Layout Setup

import { UITransform, HorizontalAlignmentMode, VerticalAlignmentMode } from "@galacean/engine";
 
// Get the Transform component of the UI element
const uiTransform = entity.getComponent(UITransform);
 
// Set size
uiTransform.size = new Vector2(200, 100);
 
// Set pivot to center
uiTransform.pivot = new Vector2(0.5, 0.5);

Horizontal Alignment Examples

// Left align, 10 pixels from left edge
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Left;
uiTransform.alignLeft = 10;
 
// Right align, 20 pixels from right edge
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Right;
uiTransform.alignRight = 20;
 
// Horizontal center, offset 15 pixels to the right
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Center;
uiTransform.alignCenter = 15;
 
// Horizontal stretch, 30 pixels margin on both sides
uiTransform.horizontalAlignment = HorizontalAlignmentMode.LeftAndRight;
uiTransform.alignLeft = 30;
uiTransform.alignRight = 30;

Vertical Alignment Examples

// Top align, 10 pixels from top
uiTransform.verticalAlignment = VerticalAlignmentMode.Top;
uiTransform.alignTop = 10;
 
// Bottom align, 20 pixels from bottom
uiTransform.verticalAlignment = VerticalAlignmentMode.Bottom;
uiTransform.alignBottom = 20;
 
// Vertical center, offset 5 pixels up
uiTransform.verticalAlignment = VerticalAlignmentMode.Middle;
uiTransform.alignMiddle = 5;
 
// Vertical stretch, 25 pixels margin on top and bottom
uiTransform.verticalAlignment = VerticalAlignmentMode.TopAndBottom;
uiTransform.alignTop = 25;
uiTransform.alignBottom = 25;

Composite Alignment Examples

// Create a UI element in the top-right corner of parent container
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Right;
uiTransform.verticalAlignment = VerticalAlignmentMode.Top;
uiTransform.alignRight = 10;  // 10 pixels from right
uiTransform.alignTop = 10;    // 10 pixels from top
 
// Create a UI element that fills the parent container (with margins)
uiTransform.horizontalAlignment = HorizontalAlignmentMode.LeftAndRight;
uiTransform.verticalAlignment = VerticalAlignmentMode.TopAndBottom;
uiTransform.alignLeft = 20;
uiTransform.alignRight = 20;
uiTransform.alignTop = 20;
uiTransform.alignBottom = 20;

Best Practices

1. Responsive Layout

Using LeftAndRight and TopAndBottom alignment modes can create responsive layouts where elements automatically adjust according to the parent container's size.

// Create an element that always occupies 80% of the parent container
uiTransform.horizontalAlignment = HorizontalAlignmentMode.LeftAndRight;
uiTransform.verticalAlignment = VerticalAlignmentMode.TopAndBottom;
const margin = parentSize * 0.1; // 10% margin
uiTransform.alignLeft = margin;
uiTransform.alignRight = margin;
uiTransform.alignTop = margin;
uiTransform.alignBottom = margin;

2. Pivot Selection

Choose appropriate pivots based on the UI element's purpose:

Buttons: Usually use center pivot (0.5, 0.5)
Text: Choose pivot based on alignment
Icons: Usually use center pivot

3. Performance Considerations

Avoid frequent modifications to alignment properties as they trigger layout recalculation
When batch updating UI, consider setting all related properties at once

Important Notes

Alignment Priority: When alignment modes are set, directly setting position may be overridden by alignment calculations
Margin Effectiveness: Each margin property only takes effect under the corresponding alignment mode
Stretch Mode: When using LeftAndRight or TopAndBottom, the corresponding direction's size will be automatically calculated
Parent-Child Relationship: UI alignment is based on the parent element's UITransform, ensure the parent element is also a UI element

The UITransform component provides powerful and flexible UI layout capabilities for the Galacean engine. By properly using these features, you can build beautiful UI interfaces that adapt to different screen sizes.

Was this page helpful?