mirror of
https://github.com/galacean/engine.git
synced 2026-06-06 04:57:29 +08:00
feat: add widget doc (#2830)
This commit is contained in:
AZhan
@@ -7,16 +7,16 @@ label: UI
|
||||
|
||||
UI is a system used to build user interfaces. It provides a range of tools and components to help developers create interactive interface elements. Here are its key features:
|
||||
|
||||
- **Visual Editing**: With the basic nodes and component creation capabilities in the [editor](https://galacean.antgroup.com/editor/projects), combined with the RectTool (shortcut key T), developing interactive interfaces becomes more intuitive and efficient.
|
||||
- **Rendering and Interactive Components**: Supports rendering components like Image, Text, etc., as well as basic interactive components such as Button.
|
||||
- **Transferable Opacity and Interactivity Attributes**: Through the UIGroup component, properties such as **opacity** and **interactivity** can be inherited or ignored.
|
||||
- **Events**: In addition to supporting original Pointer events, UI components also support **event bubbling** for interactions triggered by the UI.
|
||||
- **Visual Editing**: With the basic nodes and component creation capabilities in the [editor](https://galacean.antgroup.com/editor/projects), combined with the `RectTool` (shortcut key `T`), developing interactive interfaces becomes more intuitive and efficient.
|
||||
- **Rendering and Interactive Components**: Supports rendering components like `Image`, `Text`, etc., as well as basic interactive components such as `Button`.
|
||||
- **Transferable Opacity and Interactivity Attributes**: Through the `UIGroup` component, properties such as **opacity** and **interactivity** can be inherited or ignored.
|
||||
- **Events**: In addition to supporting original Pointer events, UI components also support **event bubbling** for interactions triggered by UI components.
|
||||
|
||||
In this section, you will:
|
||||
|
||||
- Learn how to quickly develop a UI interface:
|
||||
- Create a [Root Canvas](/en/docs/UI/quickStart/canvas)
|
||||
- Familiarize yourself with [UITransform](/en/docs/UI/quickStart/transform)
|
||||
- Adjust size and relative layout through [UITransform](/en/docs/UI/quickStart/transform)
|
||||
- Create [Image](/en/docs/UI/quickStart/image)
|
||||
- Create [Text](/en/docs/UI/quickStart/text)
|
||||
- Create [Button](/en/docs/UI/quickStart/button)
|
||||
|
||||
@@ -5,30 +5,361 @@ type: UI
|
||||
label: UI
|
||||
---
|
||||
|
||||
The `UITransform` component is specifically designed to represent the size and position of UI elements. It inherits from the [Transform](/apis/core/#Transform) component.
|
||||
`UITransform` is a transform component specifically designed for UI elements, 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.
|
||||
|
||||
## Editor Usage
|
||||
|
||||
When a node with a UI component is added, the `UITransform` component will automatically be added (replacing the previous [Transform](/apis/core/#Transform) component). In the editor, you can select the node and use the `RectTool` (shortcut key `T`) to quickly adjust properties, or you can set precise properties in the **[Inspector Panel](/en/docs/interface/inspector)**.
|
||||
When a node with UI components is added, the `UITransform` component will be automatically added (replacing the previous [Transform](/apis/core/#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](/en/docs/interface/inspector)**.
|
||||
|
||||
<Image src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*hJ81TKtDKLIAAAAAAAAAAAAAehuCAQ/original" style={{zoom:"50%"}} />
|
||||
### Adjusting Size and Pivot
|
||||
|
||||
> 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.**
|
||||
<Image
|
||||
src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*VvXkSavtjkMAAAAAgJAAAAgAehuCAQ/original"
|
||||
style={{ zoom: "50%" }}
|
||||
/>
|
||||
|
||||
### Setting Relative Layout
|
||||
|
||||
<Image
|
||||
src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*gu1OQZUIRaYAAAAAgHAAAAgAehuCAQ/original"
|
||||
style={{ zoom: "50%" }}
|
||||
/>
|
||||
|
||||
> 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. The default is `100` for both. |
|
||||
| `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 (0.5, 0.5). |
|
||||
| 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
|
||||
|
||||
```typescript
|
||||
// Add UICanvas
|
||||
// Add canvas
|
||||
const canvasEntity = root.createChild("canvas");
|
||||
const canvas = canvasEntity.addComponent(UICanvas);
|
||||
const imageEntity = canvasEntity.create("Image");
|
||||
(<UITransform>imageEntity.transform).size.set(200, 200);
|
||||
(<UITransform>imageEntity.transform).pivot.set(0, 0);
|
||||
```
|
||||
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
|
||||
|
||||
```typescript
|
||||
// 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
|
||||
|
||||
```typescript
|
||||
// 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.
|
||||
|
||||
```typescript
|
||||
// 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
|
||||
|
||||
1. **Relative Layout Priority**: When relative layout is set, directly setting `position` will be overridden by alignment calculations
|
||||
2. **Margin Effectiveness**: Each margin property only takes effect under the corresponding alignment mode
|
||||
3. **Stretch Mode**: When using `LeftAndRight` or `TopAndBottom`, the corresponding direction's `size` will be automatically calculated
|
||||
4. **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
|
||||
```typescript
|
||||
get size(): Vector2
|
||||
set size(value: Vector2)
|
||||
```
|
||||
Width and height of the UI element.
|
||||
|
||||
**Example:**
|
||||
```typescript
|
||||
// Set UI element size to 200x100
|
||||
uiTransform.size = new Vector2(200, 100);
|
||||
```
|
||||
|
||||
#### pivot
|
||||
```typescript
|
||||
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:**
|
||||
```typescript
|
||||
// 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
|
||||
```typescript
|
||||
get horizontalAlignment(): HorizontalAlignmentMode
|
||||
set horizontalAlignment(value: HorizontalAlignmentMode)
|
||||
```
|
||||
Horizontal alignment mode that controls the element's horizontal position within its parent container.
|
||||
|
||||
#### alignLeft
|
||||
```typescript
|
||||
get alignLeft(): number
|
||||
set alignLeft(value: number)
|
||||
```
|
||||
Left margin, only effective when `horizontalAlignment` is `Left` or `LeftAndRight`.
|
||||
|
||||
#### alignRight
|
||||
```typescript
|
||||
get alignRight(): number
|
||||
set alignRight(value: number)
|
||||
```
|
||||
Right margin, only effective when `horizontalAlignment` is `Right` or `LeftAndRight`.
|
||||
|
||||
#### alignCenter
|
||||
```typescript
|
||||
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
|
||||
```typescript
|
||||
get verticalAlignment(): VerticalAlignmentMode
|
||||
set verticalAlignment(value: VerticalAlignmentMode)
|
||||
```
|
||||
Vertical alignment mode that controls the element's vertical position within its parent container.
|
||||
|
||||
#### alignTop
|
||||
```typescript
|
||||
get alignTop(): number
|
||||
set alignTop(value: number)
|
||||
```
|
||||
Top margin, only effective when `verticalAlignment` is `Top` or `TopAndBottom`.
|
||||
|
||||
#### alignBottom
|
||||
```typescript
|
||||
get alignBottom(): number
|
||||
set alignBottom(value: number)
|
||||
```
|
||||
Bottom margin, only effective when `verticalAlignment` is `Bottom` or `TopAndBottom`.
|
||||
|
||||
#### alignMiddle
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
// 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
|
||||
|
||||
```typescript
|
||||
// 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
|
||||
|
||||
```typescript
|
||||
// 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.
|
||||
|
||||
```typescript
|
||||
// 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
|
||||
|
||||
1. **Alignment Priority**: When alignment modes are set, directly setting `position` may be overridden by alignment calculations
|
||||
2. **Margin Effectiveness**: Each margin property only takes effect under the corresponding alignment mode
|
||||
3. **Stretch Mode**: When using `LeftAndRight` or `TopAndBottom`, the corresponding direction's `size` will be automatically calculated
|
||||
4. **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.
|
||||
@@ -16,7 +16,7 @@ UI 是用于构建用户界面的系统，它提供了一系列工具和组件
|
||||
|
||||
- 学会如何快速开发 UI 界面：
|
||||
- 创建 [根画布](/docs/UI/quickStart/canvas)
|
||||
- 熟悉 [UITransform](/docs/UI/quickStart/transform)
|
||||
- 通过 [UITransform](/docs/UI/quickStart/transform) 调整尺寸与相对布局
|
||||
- 创建 [Image](/docs/UI/quickStart/image)
|
||||
- 创建 [Text](/docs/UI/quickStart/text)
|
||||
- 创建 [Button](/docs/UI/quickStart/button)
|
||||
|
||||
@@ -5,30 +5,122 @@ type: UI
|
||||
label: UI
|
||||
---
|
||||
|
||||
`UITransform` 组件是专门设计用来表示 UI 元素的尺寸和位置的，它继承于 [Transform](/apis/core/#Transform) 。
|
||||
`UITransform` 是专门为 UI 元素设计的变换组件，继承自基础的 `[Transform](/apis/core/#Transform)` 组件。它提供了丰富的布局和对齐功能，是构建灵活 UI 系统的核心组件。
|
||||
|
||||
## 编辑器使用
|
||||
|
||||
添加了 UI 组件的节点，会自动添加 `UITransform` 组件（替换原先旧的 [Transform](/apis/core/#Transform) 组件），在编辑器中，可以选中节点可以使用 `RectTool` （快捷键 `T` ）快速设置属性，也可以在在 **[检查器面板](/docs/interface/inspector)** 设置精确属性。
|
||||
|
||||
<Image src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*hJ81TKtDKLIAAAAAAAAAAAAAehuCAQ/original" style={{zoom:"50%"}} />
|
||||
### 调整尺寸和锚点
|
||||
|
||||
<Image
|
||||
src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*VvXkSavtjkMAAAAAgJAAAAgAehuCAQ/original"
|
||||
style={{ zoom: "50%" }}
|
||||
/>
|
||||
|
||||
### 设置相对布局
|
||||
|
||||
<Image
|
||||
src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*gu1OQZUIRaYAAAAAgHAAAAgAehuCAQ/original"
|
||||
style={{ zoom: "50%" }}
|
||||
/>
|
||||
|
||||
> 当主画布的渲染模式为 `Screen` 时，编辑器侧会禁止修改它的 `transform` 避免屏幕适配异常，因此在脚本中，**开发者应当自己避免去篡改屏幕空间主画布 `transform` 的属性**。
|
||||
|
||||
## 属性
|
||||
|
||||
| 属性名 | 描述 |
|
||||
| :------ | :----------------------------------------------------------------------------------- |
|
||||
| `size` | UI 元素的尺寸，`x` 代表宽度，`y` 代表高度，初始化都默认为 `100` |
|
||||
| 属性名 | 描述 |
|
||||
| :-- | :-- |
|
||||
| `size` | UI 元素的尺寸，`x` 代表宽度，`y` 代表高度，初始化都默认为 `100` |
|
||||
| `pivot` | UI 元素的锚点，它是一个以左下角为原点的归一化的二元向量，默认值为中心点，即(0.5,0.5) |
|
||||
| `horizontalAlignment` | 水平相对布局模式 `HorizontalAlignment` |
|
||||
| `alignLeft` | 与父元素左边缘的距离，当且仅当 `HorizontalAlignment.Left` 或 `HorizontalAlignment.LeftAndRight` 时生效 |
|
||||
| `alignRight` | 与父元素右边缘的距离，当且仅当 `HorizontalAlignment.Right` 或 `HorizontalAlignment.LeftAndRight` 时生效 |
|
||||
| `alignCenter` | 水平居中偏移，当且仅当 `HorizontalAlignment.Center` 时生效 |
|
||||
| `verticalAlignment` | 垂直相对布局模式 `VerticalAlignment` |
|
||||
| `alignTop` | 与父元素上边缘的距离，当且仅当 `VerticalAlignment.Top` 或 `VerticalAlignment.TopAndBottom` 时生效 |
|
||||
| `alignBottom` | 与父元素下边缘的距离，当且仅当 `VerticalAlignment.Bottom` 或 `VerticalAlignment.TopAndBottom` 时生效 |
|
||||
| `alignMiddle` | 垂直居中偏移，当且仅当 `VerticalAlignment.Middle` 时生效 |
|
||||
|
||||
> 相对布局的属性仅在对应的布局模式下才会生效。
|
||||
|
||||
## 脚本使用
|
||||
|
||||
### 设置尺寸和锚点
|
||||
|
||||
```typescript
|
||||
// Add UICanvas
|
||||
// 添加画布
|
||||
const canvasEntity = root.createChild("canvas");
|
||||
const canvas = canvasEntity.addComponent(UICanvas);
|
||||
const imageEntity = canvasEntity.create("Image");
|
||||
(<UITransform>imageEntity.transform).size.set(200, 200);
|
||||
(<UITransform>imageEntity.transform).pivot.set(0, 0);
|
||||
const uiTransform = <UITransform>imageEntity.transform;
|
||||
// 设置尺寸
|
||||
uiTransform.size = new Vector2(200, 100);
|
||||
// 设置锚点
|
||||
uiTransform.pivot = new Vector2(0.5, 0.5);
|
||||
```
|
||||
|
||||
### 设置水平相对布局
|
||||
|
||||
```typescript
|
||||
// 左对齐，距离左边缘 10
|
||||
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Left;
|
||||
uiTransform.alignLeft = 10;
|
||||
|
||||
// 右对齐，距离右边缘 20
|
||||
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Right;
|
||||
uiTransform.alignRight = 20;
|
||||
|
||||
// 水平居中，向右偏移 15
|
||||
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Center;
|
||||
uiTransform.alignCenter = 15;
|
||||
|
||||
// 水平拉伸，左右边距各 30
|
||||
uiTransform.horizontalAlignment = HorizontalAlignmentMode.LeftAndRight;
|
||||
uiTransform.alignLeft = 30;
|
||||
uiTransform.alignRight = 30;
|
||||
```
|
||||
|
||||
### 设置垂直相对布局
|
||||
|
||||
```typescript
|
||||
// 顶部对齐，距离顶部 10
|
||||
uiTransform.verticalAlignment = VerticalAlignmentMode.Top;
|
||||
uiTransform.alignTop = 10;
|
||||
|
||||
// 底部对齐，距离底部 20
|
||||
uiTransform.verticalAlignment = VerticalAlignmentMode.Bottom;
|
||||
uiTransform.alignBottom = 20;
|
||||
|
||||
// 垂直居中，向上偏移 5
|
||||
uiTransform.verticalAlignment = VerticalAlignmentMode.Middle;
|
||||
uiTransform.alignMiddle = 5;
|
||||
|
||||
// 垂直拉伸，上下边距各 25
|
||||
uiTransform.verticalAlignment = VerticalAlignmentMode.TopAndBottom;
|
||||
uiTransform.alignTop = 25;
|
||||
uiTransform.alignBottom = 25;
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 响应式布局
|
||||
使用 `LeftAndRight` 和 `TopAndBottom` 对齐模式可以创建响应式布局，元素会根据父容器的大小自动调整。
|
||||
|
||||
```typescript
|
||||
// 创建一个始终与父元素尺寸相同的元素
|
||||
uiTransform.horizontalAlignment = HorizontalAlignmentMode.LeftAndRight;
|
||||
uiTransform.verticalAlignment = VerticalAlignmentMode.TopAndBottom;
|
||||
uiTransform.alignLeft = uiTransform.alignRight = 0;
|
||||
uiTransform.alignTop = uiTransform.alignBottom = 0;
|
||||
```
|
||||
|
||||
### 性能考虑
|
||||
- 避免频繁修改对齐属性，这会触发布局重新计算
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **相对布局优先级**: 当设置了相对布局时，直接设置的 `position` 会被对齐计算覆盖
|
||||
2. **边距生效条件**: 各个边距属性只在对应的对齐模式下才会生效
|
||||
3. **拉伸模式**: 使用 `LeftAndRight` 或 `TopAndBottom` 时，对应方向的 `size` 会被自动计算
|
||||
4. **父子关系**: UI 对齐基于父元素的 UITransform，确保父元素也是 UI 元素
|
||||
|
||||
Reference in New Issue
Block a user