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(ui): auto-height ListView rows, measureText, TextInput renderMode (bilingual)

yhhc0fd5744d7ee
diff --git a/docs/astro/src/content/docs/guides/ui-components.mdx b/docs/astro/src/content/docs/guides/ui-components.mdx
index bc80283cb..b4fa44498 100644
--- a/docs/astro/src/content/docs/guides/ui-components.mdx
+++ b/docs/astro/src/content/docs/guides/ui-components.mdx
@@ -298,7 +298,7 @@ so keep it a pure "apply this data" function.
| `layout` | Result |
|---|---|
-| `{ itemHeight }` | A vertical list. |
+| `{ itemHeight }` | A vertical list — a fixed row height, or a **`(index) => number`** for [auto-height rows](#auto-height-rows). |
| `{ itemWidth, direction: 'row' }` | A horizontal list. |
| `{ columns, itemSize }` | A grid (a *TileView*). |
@@ -327,6 +327,34 @@ list.data.setItems(freshList); // replace all
`item`, and give the data source a `getItemType(i)`.
</Aside>
+### Auto-height rows
+
+Pass a **function** for `itemHeight` to size each row to its content — perfect for a
+chat log where a bubble grows with its wrapped text. The list caches the measurement
+and re-flows on data or viewport changes:
+
+```typescript
+import { measureText } from 'esengine';
+
+createListView<Message>({
+ world, host: uiPlugin, parent,
+ viewportSize: { x: 360, y: 480 },
+ data: messages,
+ layout: {
+ itemHeight: (i) => measureText(messages.getItem(i).text, {
+ fontSize: 14, maxWidth: 320,
+ }).height + 16, // wrapped text height + vertical padding
+ spacing: 8,
+ },
+ item: { /* create / bind */ },
+});
+```
+
+`measureText(text, { fontSize, maxWidth?, bold?, italic?, letterSpacing?, lineHeight? })`
+returns `{ width, lineCount, height }` measured off the **same Canvas2D metrics the glyph
+atlas draws from**, so a measured height matches what actually renders — no more clipped
+or overflowing rows. (A DOM-less host falls back to an average-glyph estimate.)
+
### Free-form scrolling
For a scrollable panel of **arbitrary content** (a settings page, a long form) — no
@@ -386,9 +414,11 @@ events.on(field, 'submit', () => save(world.get(field, TextInput).value)); // E
| `password` | `false` | Mask the characters. |
| `readOnly` | `false` | Focusable but not editable. |
| `fontSize` / `fontFamily` | `16` / `Arial` | Text style — `color`, `placeholderColor`, `backgroundColor`, and `padding` (`6`) round out the look. |
+| `renderMode` | `Auto` | Glyph pipeline for the field text — `Auto` (crisp bitmap when unscaled, SDF once scaled), always `Bitmap`, or always `Sdf`. |
Click (or Tab to) the field to focus it; **Escape** blurs, **Enter** fires
-`submit` on single-line fields.
+`submit` on single-line fields. A value longer than the box **clips to it and scrolls
+horizontally** so the caret stays in view as you type.
<Aside type="note">
Text input runs in **play mode only** and needs a browser DOM (it drives a
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
index 9d0a0d13b..58f0c08f3 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
@@ -281,7 +281,7 @@ const list = createListView<Player>({
| `layout` | 结果 |
|---|---|
-| `{ itemHeight }` | 竖直列表。 |
+| `{ itemHeight }` | 竖直列表——固定行高,或传 **`(index) => number`** 实现[自适应行高](#自适应行高)。 |
| `{ itemWidth, direction: 'row' }` | 水平列表。 |
| `{ columns, itemSize }` | 网格(*TileView*)。 |
@@ -306,6 +306,32 @@ list.data.setItems(freshList); // 全替换
的映射代替单个 `item`,并给数据源一个 `getItemType(i)`。
</Aside>
+### 自适应行高
+
+给 `itemHeight` 传一个**函数**,让每行按内容自适应高度——聊天记录里气泡随换行文本增高就是
+典型场景。列表会缓存测量结果,并在数据或视口变化时重排:
+
+```typescript
+import { measureText } from 'esengine';
+
+createListView<Message>({
+ world, host: uiPlugin, parent,
+ viewportSize: { x: 360, y: 480 },
+ data: messages,
+ layout: {
+ itemHeight: (i) => measureText(messages.getItem(i).text, {
+ fontSize: 14, maxWidth: 320,
+ }).height + 16, // 换行文本高度 + 上下内边距
+ spacing: 8,
+ },
+ item: { /* create / bind */ },
+});
+```
+
+`measureText(text, { fontSize, maxWidth?, bold?, italic?, letterSpacing?, lineHeight? })`
+返回 `{ width, lineCount, height }`,用的是**渲染器取字形 advance 的同一套 Canvas2D 度量**,
+所以测出的高度和实际渲染一致——不再有裁剪或溢出的行(无 DOM 的环境回退到平均字宽估算)。
+
### 自由内容滚动
滚动**任意内容**的面板(设置页、长表单)——不虚拟化、无数据源——用 `createScrollView`,
@@ -362,9 +388,10 @@ events.on(field, 'submit', () => save(world.get(field, TextInput).value)); //
| `password` | `false` | 掩码显示。 |
| `readOnly` | `false` | 可聚焦但不可编辑。 |
| `fontSize` / `fontFamily` | `16` / `Arial` | 文字样式——`color`、`placeholderColor`、`backgroundColor` 和 `padding`(`6`)补全观感。 |
+| `renderMode` | `Auto` | 输入文本的字形管线——`Auto`(不缩放时用清晰位图、缩放后转 SDF)、始终 `Bitmap`、或始终 `Sdf`。 |
点击(或 Tab 到)输入框即聚焦;**Escape** 失焦,单行输入框按**回车**触发
-`submit`。
+`submit`。内容超出框宽时会**裁剪到框内并横向滚动**,让光标随输入始终可见。
<Aside type="note">
文本输入只在**播放模式**运行,且需要浏览器 DOM(它驱动一个隐藏的原生