UI 布局

Estella 提供了完整的 UI 框架，包含布局、交互、文本渲染和一系列预制控件。布局计算在 C++/WASM 中运行以确保性能，所有组件通过 TypeScript 配置。

注意

所有 UI 插件由引擎自动注册，无需手动设置。

快速开始

在编辑器中：右键 Hierarchy → Create → UI → 选择一个控件（Button、Slider、Text 等）。编辑器会创建预配置好所有必需组件的实体层级。

通过代码创建 UI：

import { defineSystem, addStartupSystem, Commands, Transform, Sprite, UIRect, Text, Parent } from 'esengine';

addStartupSystem(defineSystem([Commands()], (cmds) => {
    const root = cmds.spawn()
        .insert(Transform)
        .insert(UIRect, { anchorMin: { x: 0, y: 0 }, anchorMax: { x: 1, y: 1 } })
        .id();

    cmds.spawn()
        .insert(Transform)
        .insert(Sprite)
        .insert(UIRect, { size: { x: 200, y: 40 } })
        .insert(Text, { content: 'Hello World', fontSize: 24 })
        .insert(Parent, { entity: root });
}));

UIRect

每个 UI 元素都需要 UIRect 来参与布局。它使用锚点系统定义相对于父级的位置和尺寸。

属性	类型	默认值	说明
anchorMin	Vec2	{0.5, 0.5}	左下锚点（0–1）
anchorMax	Vec2	{0.5, 0.5}	右上锚点（0–1）
offsetMin	Vec2	{0, 0}	相对 anchorMin 的像素偏移
offsetMax	Vec2	{0, 0}	相对 anchorMax 的像素偏移
size	Vec2	{100, 100}	宽高（锚点相等时使用）
pivot	Vec2	{0.5, 0.5}	旋转和缩放中心点

当 anchorMin 等于 anchorMax 时，元素在锚点处具有固定 size。当两者不同时，元素在锚点之间拉伸，尺寸自动计算。

FlexContainer

类似 CSS Flexbox 的自动子元素排列布局，基于 Yoga 布局引擎。

属性	类型	默认值	说明
direction	FlexDirection	Row	Row、Column、RowReverse、ColumnReverse
wrap	FlexWrap	NoWrap	NoWrap、Wrap
justifyContent	JustifyContent	Start	Start、Center、End、SpaceBetween、SpaceAround、SpaceEvenly
alignItems	AlignItems	Stretch	Start、Center、End、Stretch
alignContent	AlignContent	Start	Start、Center、End、Stretch、SpaceBetween、SpaceAround — 控制多行交叉轴对齐
gap	Vec2	{0, 0}	子元素间距（x = 列间距，y = 行间距）
padding	Padding	{left:0, top:0, right:0, bottom:0}	内边距

FlexItem

FlexContainer 内子实体的 Flex 属性。

属性	类型	默认值	说明
flexGrow	number	0	扩展以填充空间的比例
flexShrink	number	1	空间不足时收缩的比例
flexBasis	number	-1	扩展/收缩前的基础尺寸（-1 = 自动）
order	number	0	显示顺序覆盖
alignSelf	AlignSelf	Auto	Auto、Start、Center、End、Stretch — 覆盖父级 alignItems
margin	Padding	{left:0, top:0, right:0, bottom:0}	外边距
minWidth / minHeight	number	-1	最小尺寸（-1 = 无限制）
maxWidth / maxHeight	number	-1	最大尺寸（-1 = 无限制）
widthPercent / heightPercent	number	-1	相对父级的百分比尺寸（-1 = 禁用）

LayoutGroup

带方向、间距和对齐的网格式布局。

属性	类型	默认值	说明
direction	LayoutDirection	Horizontal	Horizontal (0)、Vertical (1)
spacing	number	0	子元素间距
padding	object	{left:0, top:0, right:0, bottom:0}	边距
childAlignment	ChildAlignment	Start	Start、Center、End
reverseOrder	boolean	false	反向排列

下一步

• 文本与图片 — 文本渲染和图片显示
• 交互 — 指针事件、焦点和拖拽
• 控件 — 按钮、滑块、开关等
• 遮罩与安全区 — 裁剪和设备安全区域