mirror of
https://github.com/galacean/engine.git
synced 2026-05-08 15:57:13 +08:00
127 lines
4.9 KiB
Plaintext
127 lines
4.9 KiB
Plaintext
---
|
||
order: 1
|
||
title: UITransform
|
||
type: UI
|
||
label: UI
|
||
---
|
||
|
||
`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*VvXkSavtjkMAAAAAgJAAAAgAehuCAQ/original"
|
||
style={{ zoom: "50%" }}
|
||
/>
|
||
|
||
### 设置相对布局
|
||
|
||
<Image
|
||
src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*gGR7TqS0aI0AAAAAgCAAAAgAehuCAQ/original"
|
||
style={{ zoom: "50%" }}
|
||
/>
|
||
|
||
> 当主画布的渲染模式为 `Screen` 时，编辑器侧会禁止修改它的 `transform` 避免屏幕适配异常，因此在脚本中，**开发者应当自己避免去篡改屏幕空间主画布 `transform` 的属性**。
|
||
|
||
## 属性
|
||
|
||
| 属性名 | 描述 |
|
||
| :-- | :-- |
|
||
| `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
|
||
// 添加画布
|
||
const canvasEntity = root.createChild("canvas");
|
||
const canvas = canvasEntity.addComponent(UICanvas);
|
||
const imageEntity = canvasEntity.create("Image");
|
||
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 元素
|