UI 组件

下面每个字段都由引擎自身的组件注册表推导而来——就是编辑器 Details 面板读的那一份—— 所以这里的类型和默认值就是你添加组件时真正拿到的值，且不可能与代码脱节。讲怎么用的正文在 每条目所链接的指南里。字段说明取自 C++ ES_PROPERTY 处的原文，因此为英文。

DraggableDragStateFlexContainerFocusableInteractableSafeAreaTextTextInputThemeStyleUIControllerUIDialogUIDropdownUIGearUIInteractionUIMaskUINodeUIScrollUISliderUIToggleUIVisual

Draggable

Lets the pointer drag a UI node, optionally constrained to an axis.

Explained in ui/interaction.

Field	Type	Default	Notes
enabled	boolean	true
dragThreshold	number	5
lockX	boolean	false
lockY	boolean	false
constraintMin	unknown	—
constraintMax	unknown	—

DragStatetransient

Transient per-frame geometry of a drag in progress; the drag system rebuilds it, scene saves omit it.

Explained in ui/interaction.

Field	Type	Default	Notes
isDragging	boolean	false
startWorldPos	Vec2	(0, 0)
currentWorldPos	Vec2	(0, 0)
deltaWorld	Vec2	(0, 0)
totalDeltaWorld	Vec2	(0, 0)
pointerStartWorld	Vec2	(0, 0)

FlexContainer

Lays children out along an axis — direction, justification, alignment, wrapping and gaps.

Explained in ui/layout.

Field	Type	Default	Notes
direction	enum	Row	One of Row, Column, RowReverse, ColumnReverse.
wrap	enum	NoWrap	One of NoWrap, Wrap.
justifyContent	enum	Start	One of Start, Center, End, SpaceBetween, SpaceAround, SpaceEvenly.
alignItems	enum	Stretch	One of Start, Center, End, Stretch.
alignContent	enum	Start	One of Start, Center, End, Stretch, SpaceBetween, SpaceAround.
gap	Vec2	(0, 0)
padding	Padding	{"left":0,"top":0,"right":0,"bottom":0}

Focusable

Puts a widget in the keyboard focus order.

Explained in ui/interaction.

Field	Type	Default	Notes
tabIndex	number	0
isFocused	boolean	false

Interactable

Makes a UI node hit-testable, so pointer events can land on it.

Explained in ui/interaction.

Field	Type	Default	Notes
enabled	boolean	true
blockRaycast	boolean	true
raycastTarget	boolean	true

SafeArea

Insets an absolute UI node clear of notches and rounded corners.

Explained in core-concepts/screen.

Field	Type	Default	Notes
applyTop	boolean	true
applyBottom	boolean	true
applyLeft	boolean	true
applyRight	boolean	true

Text

UI text — font, size, alignment, colour, outline, shadow, rich-text markup and a localization key.

Explained in ui/text.

Field	Type	Default	Notes
content	string	empty
i18nKey	enum (localeKeys)	empty	Localization key — when set, content is resolved from the Localization catalogs (and re-resolved on locale switch). Leave empty for plain text.
font	Asset<font>	none	A font file this project ships (.ttf / .otf). Overrides Font Family when set; leave empty to use a font the host already has.
fontFamily	string	"Arial"	A font the HOST already has (system or page-loaded). Ignored when Font is set.
fontSize	number	24
color	Color	#ffffff
align	enum	Left	Horizontal alignment: within the layout box when the entity has a UINode, else it anchors the text to the entity origin (left/center/right edge). One of Left, Center, Right.
verticalAlign	enum	Top	Vertical alignment: within the layout box when the entity has a UINode, else it anchors the text to the entity origin (top/middle/bottom). One of Top, Middle, Bottom.
wordWrap	boolean	true
overflow	enum	Visible	What text too big for its box does. Needs a layout box: Clip and Ellipsis drop the lines past its height and trim a line past its width. One of Visible, Clip, Ellipsis.
lineHeight	number	1.2
bold	boolean	false
italic	boolean	false
strokeColor	Color	#000000
strokeWidth	number	0
shadowColor	Color	#000000
shadowBlur	number	0
shadowOffsetX	number	0
shadowOffsetY	number	0
richText	boolean	false
renderMode	enum	Auto	One of Auto, Bitmap, Sdf.
layer	number	0	Draw layer for a text standing in the WORLD (no UINode) — read like Sprite/ShapeRenderer layer, so a label can sit in front of the content around it. Ignored inside a Canvas, where the UI render order decides.
enabled	boolean	true

TextInput

An editable text field with a caret, selection and IME support.

Explained in ui/widgets.

Field	Type	Default	Notes
value	string	empty
placeholder	string	empty
placeholderColor	Color	#999999
font	Asset<font>	none	A font file this project ships (.ttf / .otf). Overrides Font Family when set; leave empty to use a font the host already has.
fontFamily	string	"Arial"	A font the HOST already has (system or page-loaded). Ignored when Font is set.
fontSize	number	16
color	Color	#ffffff
backgroundColor	Color	#262626
padding	number	6
maxLength	number	0
multiline	boolean	false
password	boolean	false
readOnly	boolean	false
focused	boolean	false
cursorPos	number	0
dirty	boolean	true
textAlign	enum	Left	Where the value sits in the field. A single line holds the alignment while it fits, then scrolls to follow the caret. One of Left, Center, Right.
renderMode	enum	Auto	Glyph pipeline for the field text — Auto (hinted bitmap when unscaled, SDF once scaled), always Bitmap, or always SDF. One of Auto, Bitmap, Sdf.

ThemeStyle

Records which theme role an entity's colours came from, so a live theme swap can repaint it.

Explained in ui/theming.

Field	Type	Default	Notes
visual	unknown	—
text	unknown	—
states	object	empty
input	unknown	—

UIController

Shared named page state a whole subtree switches on — no bespoke per-widget state.

Explained in ui/controllers.

Field	Type	Default	Notes
controllers	array	empty

UIDialog

A modal dialog surface — backdrop, result, and open/close state.

Explained in ui/widgets.

Field	Type	Default	Notes
closeOnEscape	boolean	true
closeOnBackdrop	boolean	true

UIDropdown

A dropdown selector: its options and the selected index.

Explained in ui/widgets.

Field	Type	Default	Notes
options	array	empty
selectedIndex	number	0
optionHeight	number	32
label	Entity	none

UIGear

Per-page field values a controller drives declaratively, authored from the Details panel.

Explained in ui/controllers.

Field	Type	Default	Notes
bindings	array	empty

UIInteractiontransient

Live pointer state for an interactable node — hovered, pressed, and the frame's transitions.

Explained in ui/interaction.

Field	Type	Default	Notes
hovered	boolean	false
pressed	boolean	false
justPressed	boolean	false
justReleased	boolean	false

UIMask

Clips descendants to this node's rect, with an optional alpha cutoff.

Explained in ui/lists.

Field	Type	Default	Notes
enabled	boolean	true
mode	enum	Scissor	One of Scissor, Stencil.
alphaCutoff	number	0	Stencil only: above 0, clip to the mask sprite's shape instead of its box.

UINode

The UI box: size, position, margins and padding in design pixels. Every UI entity has one.

Explained in ui/layout.

Field	Type	Default	Notes
position	enum	Relative	One of Relative, Absolute.
display	enum	Flex	None removes this node and its whole subtree from layout, rendering and input. One of Flex, None.
opacity	number	1	Subtree opacity, multiplied down the tree. Fades this node and everything under it. Range 0–1.
pointerEvents	enum	Auto	None makes this node and its subtree transparent to the pointer — hits pass through to what is behind. One of Auto, None.
width	Dimension	{"value":0,"unit":2}
height	Dimension	{"value":0,"unit":2}
minWidth	Dimension	{"value":0,"unit":2}
minHeight	Dimension	{"value":0,"unit":2}
maxWidth	Dimension	{"value":0,"unit":2}
maxHeight	Dimension	{"value":0,"unit":2}
flexGrow	number	0
flexShrink	number	1
flexBasis	Dimension	{"value":0,"unit":2}
alignSelf	enum	Auto	One of Auto, Start, Center, End, Stretch.
marginLeft	Dimension	{"value":0,"unit":0}
marginTop	Dimension	{"value":0,"unit":0}
marginRight	Dimension	{"value":0,"unit":0}
marginBottom	Dimension	{"value":0,"unit":0}
insetLeft	Dimension	{"value":0,"unit":2}
insetTop	Dimension	{"value":0,"unit":2}
insetRight	Dimension	{"value":0,"unit":2}
insetBottom	Dimension	{"value":0,"unit":2}

UIScroll

Scrollable content inside a clipped viewport, with momentum and scrollbars.

Explained in ui/overview.

Field	Type	Default	Notes
enabled	boolean	true
content	Entity	none	The child that scrolls inside this node. Leave empty to use the first child.
horizontal	boolean	false
vertical	boolean	true
movement	enum	Clamped	Clamped stops at the ends; Elastic overshoots and springs back. One of Clamped, Elastic.
wheelSpeed	number	1	Range ≥ 0.
dragScroll	boolean	true
decelerationRate	number	0.135	Fraction of flick velocity kept per second. 0 stops on release. Range 0–1.

UISlider

A draggable value along a range, with an optional step.

Explained in ui/widgets.

Field	Type	Default	Notes
min	number	0
max	number	1
step	number	0
value	number	0
fill	Entity	none
handle	Entity	none

UIToggle

A two-state widget — checkbox or switch — and its group membership.

Explained in ui/widgets.

Field	Type	Default	Notes
isOn	boolean	false
check	Entity	none

UIVisual

What a UI node actually paints — a colour, a texture, or a nine-sliced sprite.

Explained in ui/overview.

Field	Type	Default	Notes
visualType	enum	None	One of None, SolidColor, Image, NineSlice, Tiled, Filled.
texture	Asset<texture>	none
color	Color	#ffffff
fit	enum	Fill	How the image fits its box: Fill stretches, Contain letterboxes it whole, Cover fills and crops. One of Fill, Contain, Cover.
uvOffset	Vec2	(0, 0)
uvScale	Vec2	(1, 1)
sliceBorder	Vec4	(0, 0, 0, 0)
tileSize	Vec2	(32, 32)
fillMethod	enum	Horizontal	One of Horizontal, Vertical, Radial360, Radial90, Radial180.
fillOrigin	enum	Left	One of Left, Right, Bottom, Top.
fillAmount	number	1
material	Asset<material>	none
enabled	boolean	true