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 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.mdx
index 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 prefabs
The same widgets ship as editor prefabs, so **Create… → UI** drops a ready-made
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 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 等放进