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 Components — Lists & collections (createListView)
esengine2fabdeb38697
diff --git a/docs/astro/src/content/docs/guides/ui-components.mdx b/docs/astro/src/content/docs/guides/ui-components.mdxindex e095d4046..cfffb5ed9 100644--- a/docs/astro/src/content/docs/guides/ui-components.mdx+++ b/docs/astro/src/content/docs/guides/ui-components.mdx@@ -211,6 +211,61 @@ dialog.close();**Handle:** `open()`, `close()`, `isOpen()`, `dispose()`, plus `backdropEntity` /`panelEntity`.+## Lists & collections++For long, scrollable, **data-driven** lists — inventories, leaderboards, chat logs —+`createListView` builds a **virtualized** list (or grid): only the items near the+viewport are ever mounted, so a 10 000-row list stays cheap. One call composes a data+source, a layout, item recycling, scrolling, and clipping.++```typescript+import { createListView, arrayDataSource, spawnUIEntity, px } from 'esengine';++const list = createListView<Player>({+ world, parent,+ viewportSize: { x: 320, y: 480 }, // the visible window, in pixels+ data: arrayDataSource(players), // any DataSource<T>, or a raw array+ layout: { itemHeight: 56 }, // a column list+ item: {+ create: (world, parent) => spawnUIEntity({ world, parent, node: { height: px(56) } }),+ bind: (entity, player, index) => { /* fill the row's Text / Sprite from `player` */ },+ },+});+```++`item.create` builds one row entity; `item.bind` fills it from the data. `bind` runs+every time a row is reused for a different index, so keep it a pure "apply this data"+function.++**Layout** is a column, a row, or a grid:++| `layout` | Result |+|---|---|+| `{ itemHeight }` | A vertical list. |+| `{ itemWidth, direction: 'row' }` | A horizontal list. |+| `{ columns, itemSize }` | A grid (a *TileView*). |++**Updating** the list means mutating its data source — an `ArrayDataSource` notifies+the view, which re-syncs on the next frame:++```typescript+list.data.append([newPlayer]); // add+list.data.remove(3); // remove index 3+list.data.update(0, updatedPlayer); // replace one+list.data.setItems(freshList); // replace all+```++**Handle:** `data` (mutate it to change the list) · `scrollToIndex(i)` · `refresh()` ·+`mountedCount()` (never grows with the data — handy in tests) · `dispose()`, plus+`scroll` and `view` as escape hatches to the underlying `ScrollContainer` / `ListView`.++<Aside type="note">+ Mouse-wheel scrolling works out of the box (the viewport is a hover target). Drag /+ touch scrolling isn't wired yet — drive it from your own pointer handler via+ `list.scroll.scrollBy(...)`. For heterogeneous rows, pass a map of item type →+ template instead of one `item`, and give the data source a `getItemType(i)`.+</Aside>+## Editor prefabsThe same widgets ship as editor prefabs, so **Create… → UI** drops a ready-madediff --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 7da5822c4..2ccf5dd33 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@@ -204,6 +204,57 @@ dialog.close();**句柄:** `open()`、`close()`、`isOpen()`、`dispose()`,以及 `backdropEntity` / `panelEntity`。+## 列表与集合++对于长的、可滚动的、**数据驱动**的列表——背包、排行榜、聊天记录——`createListView` 构建一个+**虚拟化**列表(或网格):只有视口附近的条目会被挂载,所以一万行的列表也很轻。一次调用就组合了+数据源、布局、条目回收、滚动和裁剪。++```typescript+import { createListView, arrayDataSource, spawnUIEntity, px } from 'esengine';++const list = createListView<Player>({+ world, parent,+ viewportSize: { x: 320, y: 480 }, // 可见窗口,像素+ data: arrayDataSource(players), // 任意 DataSource<T>,或裸数组+ layout: { itemHeight: 56 }, // 列表+ item: {+ create: (world, parent) => spawnUIEntity({ world, parent, node: { height: px(56) } }),+ bind: (entity, player, index) => { /* 用 `player` 填这行的 Text / Sprite */ },+ },+});+```++`item.create` 建一个行实体;`item.bind` 用数据填它。`bind` 每当一行被复用到不同索引时都会跑,+所以把它写成纯粹的"应用这份数据"函数。++**布局**是列、行或网格:++| `layout` | 结果 |+|---|---|+| `{ itemHeight }` | 竖直列表。 |+| `{ itemWidth, direction: 'row' }` | 水平列表。 |+| `{ columns, itemSize }` | 网格(*TileView*)。 |++**更新**列表 = 改它的数据源——`ArrayDataSource` 会通知视图,视图在下一帧重新同步:++```typescript+list.data.append([newPlayer]); // 增+list.data.remove(3); // 删索引 3+list.data.update(0, updatedPlayer); // 改一个+list.data.setItems(freshList); // 全替换+```++**句柄:** `data`(改它来改列表)· `scrollToIndex(i)` · `refresh()` · `mountedCount()`+(永远不随数据量增长——测试里好用)· `dispose()`,以及 `scroll` 和 `view` 作为通往底层+`ScrollContainer` / `ListView` 的逃生舱。++<Aside type="note">+ 鼠标滚轮滚动开箱即用(视口是悬停目标)。拖拽/触摸滚动尚未接线——需要的话用+ `list.scroll.scrollBy(...)` 从你自己的指针处理器驱动。异构行:用「item 类型 → 模板」的映射+ 代替单个 `item`,并给数据源一个 `getItemType(i)`。+</Aside>+## 编辑器预制体这些控件同时作为编辑器预制体提供,所以 **创建… → UI** 会把现成的 Button、Toggle、Slider 等放进