Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

docs: rewrite the UI guide to the complete-reference template

yhhc930dd306941
diff --git a/docs/astro/src/content/docs/guides/ui.mdx b/docs/astro/src/content/docs/guides/ui.mdx
index e975da927..f76f3df7d 100644
--- a/docs/astro/src/content/docs/guides/ui.mdx
+++ b/docs/astro/src/content/docs/guides/ui.mdx
@@ -1,49 +1,48 @@
---
title: UI
-description: Build flexbox interfaces — in the editor or in code — and handle interaction.
+description: The complete UI reference — the flexbox component model (UINode/FlexContainer), text, visuals, widgets, and interaction handling.
---
-import { Aside, Steps } from '@astrojs/starlight/components';
+import { Aside } from '@astrojs/starlight/components';
Estella's UI is a CSS-like flexbox system solved in the C++ core. You compose an
-interface from UI components — either visually in the editor, or in code — and
-handle interaction from your systems. This guide builds a working pause menu in
-code, then covers layout and interaction.
+interface from UI components — visually in the editor or in code — and handle
+interaction from your systems. There is **no `RectTransform`**: `UINode` is real
+flexbox, sized with `px` / `percent` / `auto` plus `Absolute` insets.
## The components
| Component | Role |
|---|---|
-| `UINode` | The layout box. Holds the flex-item fields (`width`, `height`, `flexGrow`, `margin*`, `inset*`). |
-| `FlexContainer` | Makes a node lay its children out with flexbox (`direction`, `justifyContent`, `alignItems`, `gap`). |
-| `Text` | Text via an SDF glyph atlas (`content`, `fontSize`, `color`, `align`, …). |
-| `UIVisual` | The fill — solid color, texture, 9-slice, or tiled. |
+| `UINode` | The layout box; holds the per-item flex fields (size, grow/shrink, margin, inset). |
+| `FlexContainer` | Lays a node's children out with flexbox (direction, justify, align, gap, padding). |
+| `Text` | Text via an SDF glyph atlas (content, font, color, align, stroke, shadow, rich text). |
+| `UIVisual` | The fill — solid color, texture, 9-slice, tiled, or filled. |
| `UIMask` | Clips its children. |
-| `Interactable` | Marks a node hit-testable, so it can be hovered/clicked. |
+| `Interactable` | Marks a node hit-testable so it can be hovered/clicked. |
+| `UIInteraction` | Engine-written per-frame pointer state (read-only for your logic). |
## Build a UI in code
-Here's a complete pause menu: a panel laid out as a centered column, with a title
-and a button that runs a handler on click. Register it as a **startup system** so
-it builds once.
+A complete pause menu — a centered column panel with a title and a button — built
+once from a **startup system**:
```typescript
import {
defineSystem, addStartupSystem, GetWorld, Res, UIEvents,
spawnUIEntity, createButton,
- FlexContainer, FlexDirection, JustifyContent, AlignItems,
- px,
+ FlexContainer, FlexDirection, JustifyContent, AlignItems, px,
} from 'esengine';
const buildPauseMenu = defineSystem([GetWorld(), Res(UIEvents)], (world, events) => {
- // 1. A panel: 320×220 with a dark translucent background.
+ // A panel: 320×220 with a dark translucent background.
const panel = spawnUIEntity({
world,
node: { width: px(320), height: px(220) },
visual: { color: { r: 0.08, g: 0.10, b: 0.16, a: 0.95 } },
});
- // 2. Lay its children out as a centered vertical column.
+ // Lay its children out as a centered vertical column.
world.insert(panel, FlexContainer, {
direction: FlexDirection.Column,
justifyContent: JustifyContent.Center,
@@ -51,85 +50,139 @@ const buildPauseMenu = defineSystem([GetWorld(), Res(UIEvents)], (world, events)
gap: { x: 0, y: 16 },
});
- // 3. A title label, parented to the panel.
- spawnUIEntity({
- world,
- parent: panel,
- text: { content: 'Paused', fontSize: 28 },
- });
+ // A title, parented to the panel.
+ spawnUIEntity({ world, parent: panel, text: { content: 'Paused', fontSize: 28 } });
- // 4. A button that resumes the game on click.
+ // A button that resumes the game on click.
createButton({
- world,
- events,
- parent: panel,
- text: 'Resume',
+ world, events, parent: panel, text: 'Resume',
node: { width: px(160), height: px(44) },
states: {
normal: { color: { r: 0.20, g: 0.55, b: 1.0, a: 1 } },
hover: { color: { r: 0.30, g: 0.65, b: 1.0, a: 1 } },
pressed: { color: { r: 0.12, g: 0.45, b: 0.9, a: 1 } },
},
- onClick: () => {
- // resume: unpause, switch scene, hide the menu…
- },
+ onClick: () => { /* unpause, switch scene, hide the menu… */ },
});
});
addStartupSystem(buildPauseMenu);
```
-- `spawnUIEntity({ world, parent?, node?, visual?, text? })` returns the entity —
- pass `parent` to nest it.
-- Sizes use the dimension helpers `px`, `percent`, `auto`.
-- The other widget factories work the same way: `createToggle`, `createSlider`,
- `createProgress`, `createDialog`, `createDropdown`.
+`spawnUIEntity({ world, parent?, node?, visual?, text? })` returns the entity; pass
+`parent` to nest. Sizes use the dimension helpers `px`, `percent`, `auto`. The other
+widget factories work the same way: `createToggle`, `createSlider`, `createProgress`,
+`createDialog`, `createDropdown`.
<Aside type="tip">
- UI renders under the scene's UI camera — the default project sets one up. In
- the editor you can build the same tree visually: add `UINode` entities, nest
- them, and add a `FlexContainer` / `Text` / `UIVisual` / `Interactable` in the
- inspector.
+ In the editor you build the same tree visually: add `UINode` entities, nest them,
+ and add `FlexContainer` / `Text` / `UIVisual` / `Interactable` in the inspector.
</Aside>
-## Layout with FlexContainer
-
-Add a `FlexContainer` to a node to lay out its children. The enums mirror CSS:
-
-- `FlexDirection` — `Row`, `Column`, `RowReverse`, `ColumnReverse`.
-- `JustifyContent` — `Start`, `Center`, `End`, `SpaceBetween`, `SpaceAround`,
- `SpaceEvenly` (main axis).
-- `AlignItems` — `Start`, `Center`, `End`, `Stretch` (cross axis).
-- `gap` (a `Vec2`) and `padding`.
-
-Per-child sizing lives on each child's `UINode`: `flexGrow`, `flexShrink`,
-`width` / `height`, `margin*`, and `inset*` for `Absolute` positioning.
+## `UINode` — the layout box
+
+Per-item sizing and placement live here (dimensions are built with `px()` /
+`percent()` / `auto()`).
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `position` | `UIPositionType` | `Relative` | `Relative` (in flow) or `Absolute` (placed by inset). |
+| `width` / `height` | Dimension | `auto` | Box size; `auto` = content-/flex-driven. |
+| `minWidth` / `minHeight` | Dimension | `auto` | Lower size bounds. |
+| `maxWidth` / `maxHeight` | Dimension | `auto` | Upper size bounds. |
+| `flexGrow` | number | `0` | Share of free space to absorb. |
+| `flexShrink` | number | `1` | Shrink factor when space is tight. |
+| `flexBasis` | Dimension | `auto` | Base size before grow/shrink. |
+| `alignSelf` | `AlignSelf` | `Auto` | Per-item cross-axis alignment override. |
+| `marginLeft/Top/Right/Bottom` | Dimension | `0` | Outer spacing. |
+| `insetLeft/Top/Right/Bottom` | Dimension | `auto` | Edge offsets when `Absolute`. |
+
+## `FlexContainer` — layout
+
+Add a `FlexContainer` to a node to lay out its children. The enums mirror CSS.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `direction` | `FlexDirection` | `Row` | `Row` / `Column` / `RowReverse` / `ColumnReverse`. |
+| `wrap` | `FlexWrap` | `NoWrap` | `NoWrap` / `Wrap`. |
+| `justifyContent` | `JustifyContent` | `Start` | Main-axis distribution (`Start`…`SpaceEvenly`). |
+| `alignItems` | `AlignItems` | `Stretch` | Cross-axis alignment (`Start` / `Center` / `End` / `Stretch`). |
+| `alignContent` | `AlignContent` | `Start` | Wrapped-line distribution. |
+| `gap` | Vec2 | `{0, 0}` | Space between children (x = column gap, y = row gap). |
+| `padding` | Padding | `{0,0,0,0}` | Inner spacing (`left/top/right/bottom`). |
+
+## `Text`
+
+Text is rendered from an SDF glyph atlas, so it scales crisply.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `content` | string | `''` | The string to display. |
+| `fontFamily` | string | `'Arial'` | Font family. |
+| `fontSize` | number | `24` | Size in pixels. |
+| `color` | Color | `{1,1,1,1}` | Text color. |
+| `align` | `TextAlign` | `Left` | Horizontal alignment. |
+| `verticalAlign` | `TextVerticalAlign` | `Top` | Vertical alignment. |
+| `wordWrap` | boolean | `true` | Wrap at the box width. |
+| `overflow` | `TextOverflow` | `Visible` | Overflow handling. |
+| `lineHeight` | number | — | Line spacing multiplier. |
+| `bold` / `italic` | boolean | `false` | Font style. |
+| `strokeColor` / `strokeWidth` | Color / number | — | Outline. |
+| `shadowColor` / `shadowBlur` / `shadowOffsetX` / `shadowOffsetY` | — | Drop shadow. |
+| `richText` | boolean | `false` | Parse inline rich-text markup. |
+
+## `UIVisual` — the fill
+
+`UIVisual` draws the node's background. `visualType` selects the mode:
+
+| `UIVisualType` | Uses | Description |
+|---|---|---|
+| `None` | — | Invisible (layout/hit-test only). |
+| `SolidColor` | `color` | Tinted quad. |
+| `Image` | `texture`, `uvOffset`, `uvScale` | Textured quad / sprite region. |
+| `NineSlice` | `sliceBorder` | Scalable panel with fixed corners. |
+| `Tiled` | `tileSize` | Texture repeated across the box. |
+| `Filled` | `fillAmount`, `fillMethod`, `fillOrigin` | Cropped fill (health/progress bars). |
## Handling interaction
-`createButton` gives you `onClick` directly. For your own widgets, the hit-test
-system writes per-frame pointer state into `UIInteraction` (`hovered`, `pressed`,
-`justPressed`, `justReleased`) on any entity that has an `Interactable`. It's
-**read-only for your logic** — query it to react:
+`createButton` gives you `onClick` directly. For custom widgets, the hit-test system
+writes per-frame pointer state into `UIInteraction` on any entity with an
+`Interactable`. It is **read-only** — query it, never mutate it:
```typescript
import { defineSystem, Query, Interactable, UIInteraction } from 'esengine';
const onTiles = defineSystem([Query(Interactable, UIInteraction)], (q) => {
for (const [entity, _gate, state] of q) {
- if (state.justReleased) {
- // this node was clicked
- }
+ if (state.justReleased) { /* this node was clicked */ }
}
});
```
+| `UIInteraction` field | Description |
+|---|---|
+| `hovered` | The pointer is over the node. |
+| `pressed` | The pointer is held down on the node. |
+| `justPressed` | Became pressed this frame. |
+| `justReleased` | Released this frame (a click). |
+
For bubbling events — `click`, `hover_enter`, `change`, `submit`, `drag` up the
-parent chain — read the `UIEvents` resource (the event bus, a `UIEventQueue`).
+parent chain — read the `UIEvents` resource (the UI event bus).
-<Aside type="note">
- There is no `RectTransform`: `UINode` is real flexbox, sized with `px`,
- `percent`, and `auto`, plus `Absolute` positioning via insets. `UIInteraction`
- is written by the engine each frame — drive your logic from it or from
- `UIEvents`, never mutate it.
-</Aside>
+## Best practices
+
+- **Flex, not absolute** — lay out with `FlexContainer` + `flexGrow`; reserve
+ `Absolute` insets for overlays and badges.
+- **Size with `percent` / `auto`** for resolution independence; hard `px` only where
+ a fixed size is intended.
+- **Drive logic from `UIInteraction` or `UIEvents`**, never by mutating them.
+- **Reuse the widget factories** (`createButton`, `createSlider`, …) for consistent
+ state visuals instead of wiring hover/press by hand.
+- **9-slice panels** (`NineSlice`) keep borders crisp at any size.
+
+## See also
+
+- [Input](/docs/guides/input/) — raw keyboard/mouse/touch below the UI layer.
+- [Localization](/docs/guides/localization/) — bind `Text.content` to translated keys.
+- [Animation](/docs/guides/animation/) — tween UI color/position for juice.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui.mdx
index 439775cd6..497e7c3c6 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ui.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ui.mdx
@@ -1,47 +1,46 @@
---
title: UI
-description: 用弹性盒搭建界面 —— 在编辑器里或用代码 —— 并处理交互。
+description: UI 完整参考——弹性盒组件模型(UINode/FlexContainer)、文本、视觉、控件与交互处理。
---
-import { Aside, Steps } from '@astrojs/starlight/components';
+import { Aside } from '@astrojs/starlight/components';
-Estella 的 UI 是一套在 C++ 内核里求解的类 CSS 弹性盒(flexbox)系统。你用 UI 组件组合
-界面——在编辑器里可视化地搭,或用代码搭——再从系统里处理交互。本篇用代码搭一个可用的
-暂停菜单,然后讲布局与交互。
+Estella 的 UI 是在 C++ 内核里求解的 CSS 式弹性盒(flexbox)系统。你用 UI 组件组合界面——
+在编辑器里或用代码——并在系统里处理交互。**没有 `RectTransform`**:`UINode` 就是真正的
+flexbox,用 `px` / `percent` / `auto` 加 `Absolute` 内偏移(inset)来定尺寸。
## 组件
-| 组件 | 作用 |
+| 组件 | 职责 |
|---|---|
-| `UINode` | 布局盒。持有弹性项字段(`width`、`height`、`flexGrow`、`margin*`、`inset*`)。|
-| `FlexContainer` | 让一个节点用弹性盒排布子元素(`direction`、`justifyContent`、`alignItems`、`gap`)。|
-| `Text` | 通过 SDF 字形图集渲染的文本(`content`、`fontSize`、`color`、`align` 等)。|
-| `UIVisual` | 填充——纯色、贴图、九宫格或平铺。|
-| `UIMask` | 裁剪其子元素。|
-| `Interactable` | 标记节点可命中测试,从而能被悬停/点击。|
+| `UINode` | 布局盒;持有逐项的 flex 字段(尺寸、grow/shrink、margin、inset)。 |
+| `FlexContainer` | 用 flexbox 排布一个节点的子项(方向、对齐、gap、padding)。 |
+| `Text` | 经 SDF 字形图集渲染文本(内容、字体、颜色、对齐、描边、阴影、富文本)。 |
+| `UIVisual` | 填充——纯色、纹理、九宫格、平铺或填充。 |
+| `UIMask` | 裁剪它的子项。 |
+| `Interactable` | 标记节点可命中,从而能被悬停/点击。 |
+| `UIInteraction` | 引擎每帧写入的指针状态(对你的逻辑只读)。 |
## 用代码搭建 UI
-下面是一个完整的暂停菜单:一个按居中列排布的面板,含标题和一个点击后运行回调的按钮。
-把它注册为**启动系统(startup system)**,只在启动时搭一次。
+一个完整的暂停菜单——居中的列面板,带标题和一个按钮——用**启动系统**构建一次:
```typescript
import {
defineSystem, addStartupSystem, GetWorld, Res, UIEvents,
spawnUIEntity, createButton,
- FlexContainer, FlexDirection, JustifyContent, AlignItems,
- px,
+ FlexContainer, FlexDirection, JustifyContent, AlignItems, px,
} from 'esengine';
const buildPauseMenu = defineSystem([GetWorld(), Res(UIEvents)], (world, events) => {
- // 1. 面板:320×220,深色半透明背景。
+ // A panel: 320×220 with a dark translucent background.
const panel = spawnUIEntity({
world,
node: { width: px(320), height: px(220) },
visual: { color: { r: 0.08, g: 0.10, b: 0.16, a: 0.95 } },
});
- // 2. 把它的子元素按居中的竖直列排布。
+ // Lay its children out as a centered vertical column.
world.insert(panel, FlexContainer, {
direction: FlexDirection.Column,
justifyContent: JustifyContent.Center,
@@ -49,82 +48,134 @@ const buildPauseMenu = defineSystem([GetWorld(), Res(UIEvents)], (world, events)
gap: { x: 0, y: 16 },
});
- // 3. 标题文本,挂到面板下。
- spawnUIEntity({
- world,
- parent: panel,
- text: { content: 'Paused', fontSize: 28 },
- });
+ // A title, parented to the panel.
+ spawnUIEntity({ world, parent: panel, text: { content: 'Paused', fontSize: 28 } });
- // 4. 一个点击后恢复游戏的按钮。
+ // A button that resumes the game on click.
createButton({
- world,
- events,
- parent: panel,
- text: 'Resume',
+ world, events, parent: panel, text: 'Resume',
node: { width: px(160), height: px(44) },
states: {
normal: { color: { r: 0.20, g: 0.55, b: 1.0, a: 1 } },
hover: { color: { r: 0.30, g: 0.65, b: 1.0, a: 1 } },
pressed: { color: { r: 0.12, g: 0.45, b: 0.9, a: 1 } },
},
- onClick: () => {
- // 恢复:取消暂停、切换场景、隐藏菜单……
- },
+ onClick: () => { /* unpause, switch scene, hide the menu… */ },
});
});
addStartupSystem(buildPauseMenu);
```
-- `spawnUIEntity({ world, parent?, node?, visual?, text? })` 返回实体——传 `parent`
- 即可嵌套。
-- 尺寸用助手 `px`、`percent`、`auto`。
-- 其他控件工厂用法相同:`createToggle`、`createSlider`、`createProgress`、
- `createDialog`、`createDropdown`。
+`spawnUIEntity({ world, parent?, node?, visual?, text? })` 返回实体;传 `parent` 即嵌套。
+尺寸用维度辅助 `px`、`percent`、`auto`。其它控件工厂用法相同:`createToggle`、`createSlider`、
+`createProgress`、`createDialog`、`createDropdown`。
<Aside type="tip">
- UI 在场景的 UI 相机下渲染——默认项目会自动设好一个。在编辑器里你也能可视化搭同样的
- 树:添加 `UINode` 实体、嵌套它们,并在检视面板里加 `FlexContainer` / `Text` /
- `UIVisual` / `Interactable`。
+ 在编辑器里你可以可视化地搭同一棵树:添加 `UINode` 实体、嵌套它们,并在检视面板里加
+ `FlexContainer` / `Text` / `UIVisual` / `Interactable`。
</Aside>
-## 用 FlexContainer 布局
-
-给节点加一个 `FlexContainer` 来排布它的子元素。枚举与 CSS 对应:
-
-- `FlexDirection` —— `Row`、`Column`、`RowReverse`、`ColumnReverse`。
-- `JustifyContent` —— `Start`、`Center`、`End`、`SpaceBetween`、`SpaceAround`、
- `SpaceEvenly`(主轴)。
-- `AlignItems` —— `Start`、`Center`、`End`、`Stretch`(交叉轴)。
-- `gap`(一个 `Vec2`)与 `padding`。
-
-每个子元素的尺寸在它自己的 `UINode` 上:`flexGrow`、`flexShrink`、`width` / `height`、
-`margin*`,以及用于 `Absolute` 定位的 `inset*`。
+## `UINode` —— 布局盒
+
+逐项的尺寸与放置在这里(维度用 `px()` / `percent()` / `auto()` 构造)。
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `position` | `UIPositionType` | `Relative` | `Relative`(在流中)或 `Absolute`(按 inset 放置)。 |
+| `width` / `height` | Dimension | `auto` | 盒尺寸;`auto` = 由内容/flex 决定。 |
+| `minWidth` / `minHeight` | Dimension | `auto` | 尺寸下界。 |
+| `maxWidth` / `maxHeight` | Dimension | `auto` | 尺寸上界。 |
+| `flexGrow` | number | `0` | 吸收多余空间的份额。 |
+| `flexShrink` | number | `1` | 空间紧张时的收缩因子。 |
+| `flexBasis` | Dimension | `auto` | grow/shrink 前的基准尺寸。 |
+| `alignSelf` | `AlignSelf` | `Auto` | 逐项的交叉轴对齐覆盖。 |
+| `marginLeft/Top/Right/Bottom` | Dimension | `0` | 外间距。 |
+| `insetLeft/Top/Right/Bottom` | Dimension | `auto` | `Absolute` 时的边偏移。 |
+
+## `FlexContainer` —— 布局
+
+给节点加一个 `FlexContainer` 来排布它的子项。枚举与 CSS 对应。
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `direction` | `FlexDirection` | `Row` | `Row` / `Column` / `RowReverse` / `ColumnReverse`。 |
+| `wrap` | `FlexWrap` | `NoWrap` | `NoWrap` / `Wrap`。 |
+| `justifyContent` | `JustifyContent` | `Start` | 主轴分布(`Start`…`SpaceEvenly`)。 |
+| `alignItems` | `AlignItems` | `Stretch` | 交叉轴对齐(`Start` / `Center` / `End` / `Stretch`)。 |
+| `alignContent` | `AlignContent` | `Start` | 换行后各行的分布。 |
+| `gap` | Vec2 | `{0, 0}` | 子项间距(x = 列间距,y = 行间距)。 |
+| `padding` | Padding | `{0,0,0,0}` | 内间距(`left/top/right/bottom`)。 |
+
+## `Text`
+
+文本从 SDF 字形图集渲染,所以缩放清晰。
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `content` | string | `''` | 要显示的字符串。 |
+| `fontFamily` | string | `'Arial'` | 字体族。 |
+| `fontSize` | number | `24` | 字号(像素)。 |
+| `color` | Color | `{1,1,1,1}` | 文本颜色。 |
+| `align` | `TextAlign` | `Left` | 水平对齐。 |
+| `verticalAlign` | `TextVerticalAlign` | `Top` | 垂直对齐。 |
+| `wordWrap` | boolean | `true` | 在盒宽处换行。 |
+| `overflow` | `TextOverflow` | `Visible` | 溢出处理。 |
+| `lineHeight` | number | — | 行距倍率。 |
+| `bold` / `italic` | boolean | `false` | 字形样式。 |
+| `strokeColor` / `strokeWidth` | Color / number | — | 描边。 |
+| `shadowColor` / `shadowBlur` / `shadowOffsetX` / `shadowOffsetY` | — | 投影。 |
+| `richText` | boolean | `false` | 解析内联富文本标记。 |
+
+## `UIVisual` —— 填充
+
+`UIVisual` 绘制节点的背景。`visualType` 选择模式:
+
+| `UIVisualType` | 使用 | 说明 |
+|---|---|---|
+| `None` | — | 不可见(仅布局/命中)。 |
+| `SolidColor` | `color` | 着色方块。 |
+| `Image` | `texture`、`uvOffset`、`uvScale` | 纹理方块 / 精灵区域。 |
+| `NineSlice` | `sliceBorder` | 角固定、可缩放的面板。 |
+| `Tiled` | `tileSize` | 纹理在盒内重复。 |
+| `Filled` | `fillAmount`、`fillMethod`、`fillOrigin` | 裁剪填充(血条/进度条)。 |
## 处理交互
-`createButton` 直接给你 `onClick`。对于你自己的控件,命中测试系统每帧把指针状态写入
-带 `Interactable` 的实体的 `UIInteraction`(`hovered`、`pressed`、`justPressed`、
-`justReleased`)。它对你的逻辑而言是**只读的**——查询它即可响应:
+`createButton` 直接给你 `onClick`。对于自定义控件,命中系统会把每帧的指针状态写入任何带
+`Interactable` 的实体上的 `UIInteraction`。它是**只读**的——查询它,绝不修改:
```typescript
import { defineSystem, Query, Interactable, UIInteraction } from 'esengine';
const onTiles = defineSystem([Query(Interactable, UIInteraction)], (q) => {
for (const [entity, _gate, state] of q) {
- if (state.justReleased) {
- // 这个节点被点击了
- }
+ if (state.justReleased) { /* this node was clicked */ }
}
});
```
-若需要冒泡事件——沿父链的 `click`、`hover_enter`、`change`、`submit`、`drag`——请读取
-`UIEvents` 资源(事件总线,一个 `UIEventQueue`)。
+| `UIInteraction` 字段 | 说明 |
+|---|---|
+| `hovered` | 指针在节点上方。 |
+| `pressed` | 指针在节点上按住。 |
+| `justPressed` | 本帧变为按下。 |
+| `justReleased` | 本帧释放(一次点击)。 |
-<Aside type="note">
- 这里没有 `RectTransform`:`UINode` 是真正的弹性盒,用 `px`、`percent`、`auto` 设定
- 尺寸,加上通过 inset 的 `Absolute` 定位。`UIInteraction` 由引擎每帧写入——请用它或
- `UIEvents` 驱动逻辑,绝不要去修改它。
-</Aside>
+对于冒泡事件——`click`、`hover_enter`、`change`、`submit`、`drag` 沿父链向上——读
+`UIEvents` 资源(UI 事件总线)。
+
+## 最佳实践
+
+- **用 flex,别用绝对定位**——用 `FlexContainer` + `flexGrow` 布局;`Absolute` inset 留给
+ 浮层和角标。
+- **用 `percent` / `auto` 定尺寸**做分辨率无关;只在确实要固定尺寸处用硬 `px`。
+- **逻辑由 `UIInteraction` 或 `UIEvents` 驱动**,绝不通过修改它们。
+- **复用控件工厂**(`createButton`、`createSlider`……)获得一致的状态视觉,别手接悬停/按下。
+- **九宫格面板**(`NineSlice`)让边框在任何尺寸都保持清晰。
+
+## 参见
+
+- [输入](/docs/zh-cn/guides/input/) —— UI 层之下的原始键鼠/触摸。
+- [本地化](/docs/zh-cn/guides/localization/) —— 把 `Text.content` 绑到翻译 key。
+- [动画](/docs/zh-cn/guides/animation/) —— 补间 UI 颜色/位置增加手感。