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(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.mdxindex 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 scrollingFor 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 adiff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdxindex 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(它驱动一个隐藏的原生