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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mdxindex 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**:```typescriptimport {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:```typescriptimport { 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.mdxindex 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)**,只在启动时搭一次。+一个完整的暂停菜单——居中的列面板,带标题和一个按钮——用**启动系统**构建一次:```typescriptimport {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`。它是**只读**的——查询它,绝不修改:```typescriptimport { 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 颜色/位置增加手感。