iter(g187): 新增虚拟列表组件

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T08:48:09.549Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T09:07:20.198Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -1919,6 +1919,33 @@ avatarGroup({ items: [{ name: '张三' }, { name: '李四', variant: 'success' }
 
 现场演示：apps/docs/demo.html#sec-avatar
 
+### virtualList — 虚拟列表 VirtualList
+
+参数：
+
+- items（必填）：unknown[] —— 全量数据（不切片，由组件按滚动位置取窗口）
+- itemHeight（必填）：number —— 每行固定高度像素；虚拟化前提是行高一致
+- height（必填）：number —— 容器可视高度像素，超出即容器内滚动
+- overscan（默认 5）：number —— 上下各多渲染的缓冲条数；缺省 5，滚动更平滑
+- renderItem（必填）：(item, index) => unknown —— 行内容渲染器：返回字符串 / DOM / 响应式值
+
+示例：
+
+```
+const vlist = virtualList({ items: users, itemHeight: 44, height: 320, renderItem: (u) => u.name }); vlist.scrollTo(500);
+```
+
+手把手：
+
+1. itemHeight 必须与每行真实高度一致：行高由组件钉死，行内容超高会溢出，请保持单行或内部滚动
+2. height 是容器可视高度（像素），列表在容器内滚动，不会撑开页面
+3. renderItem 第二参是原始下标（全量数据中的位置），不是窗口内序号
+4. 滚回某条用句柄 scrollTo(index)，越界自动钳制；DOM 里只存在可视窗口的行，勿按全量下标查行节点
+5. 数据整体变化（换数据源）请销毁重建实例：items 是创建时快照，不响应外部数组突变
+6. 滚动事件内部已 rAF 合帧，滚动回调无需节流
+
+现场演示：apps/docs/demo.html#sec-vlist
+
 API 速览：
 
 - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
@@ -1990,6 +2017,7 @@ API 速览：
 - treeSelect(props)：树形选择，按钮触发弹层并复用 tree（搜索 / 多选 / 级联），单选选中即收起、多选保持展开，Esc 与点外收起
 - link(props)：链接，站内跳转与站外跳转统一入口，external 自动补 ↗ 与 rel=noopener noreferrer 并给读屏播报
 - avatarGroup(props)：头像组，横向叠放并在超出 max 时折叠成 +N，整组 title 列出全部姓名
+- virtualList(props)：虚拟列表，固定行高长列表只渲染可视窗口 + 上下缓冲条，万级数据滚动不随总量掉帧；返回 { el, scrollTo } 句柄
 
 一行用法：