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

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-26T08:48:09.549Z",
+  "generatedAt": "2026-10-26T09:07:20.198Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -210,7 +210,8 @@
           "mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value",
           "treeSelect(props)：树形选择，按钮触发弹层并复用 tree（搜索 / 多选 / 级联），单选选中即收起、多选保持展开，Esc 与点外收起",
           "link(props)：链接，站内跳转与站外跳转统一入口，external 自动补 ↗ 与 rel=noopener noreferrer 并给读屏播报",
-          "avatarGroup(props)：头像组，横向叠放并在超出 max 时折叠成 +N，整组 title 列出全部姓名"
+          "avatarGroup(props)：头像组，横向叠放并在超出 max 时折叠成 +N，整组 title 列出全部姓名",
+          "virtualList(props)：虚拟列表，固定行高长列表只渲染可视窗口 + 上下缓冲条，万级数据滚动不随总量掉帧；返回 { el, scrollTo } 句柄"
         ],
         "keyTypes": [
           "ButtonProps",
@@ -3636,6 +3637,52 @@
               "整组是展示型元素：要有点击行为就在外面包 button 或 link，不要给单个头像加交互",
               "size 与单个 avatar 一致，混排时把并排 avatar 与 avatarGroup 传同一个 size，视觉才对得上"
             ]
+          },
+          {
+            "id": "virtualList",
+            "title": "虚拟列表 VirtualList",
+            "demo": "sec-vlist",
+            "props": [
+              {
+                "n": "items",
+                "t": "unknown[]",
+                "r": 1,
+                "d": "全量数据（不切片，由组件按滚动位置取窗口）"
+              },
+              {
+                "n": "itemHeight",
+                "t": "number",
+                "r": 1,
+                "d": "每行固定高度像素；虚拟化前提是行高一致"
+              },
+              {
+                "n": "height",
+                "t": "number",
+                "r": 1,
+                "d": "容器可视高度像素，超出即容器内滚动"
+              },
+              {
+                "n": "overscan",
+                "t": "number",
+                "d": "上下各多渲染的缓冲条数；缺省 5，滚动更平滑",
+                "df": "5"
+              },
+              {
+                "n": "renderItem",
+                "t": "(item, index) => unknown",
+                "r": 1,
+                "d": "行内容渲染器：返回字符串 / DOM / 响应式值"
+              }
+            ],
+            "example": "const vlist = virtualList({ items: users, itemHeight: 44, height: 320, renderItem: (u) => u.name }); vlist.scrollTo(500);",
+            "steps": [
+              "itemHeight 必须与每行真实高度一致：行高由组件钉死，行内容超高会溢出，请保持单行或内部滚动",
+              "height 是容器可视高度（像素），列表在容器内滚动，不会撑开页面",
+              "renderItem 第二参是原始下标（全量数据中的位置），不是窗口内序号",
+              "滚回某条用句柄 scrollTo(index)，越界自动钳制；DOM 里只存在可视窗口的行，勿按全量下标查行节点",
+              "数据整体变化（换数据源）请销毁重建实例：items 是创建时快照，不响应外部数组突变",
+              "滚动事件内部已 rAF 合帧，滚动回调无需节流"
+            ]
           }
         ]
       },

AGENTS.md

@@ -21,7 +21,7 @@
 
 - `packages/core/table-core`（@ui-arch/table-core）：Headless 表格逻辑内核
 - `packages/core/frame`（@ui-arch/frame）：signal + hyperscript 微框架
-- `packages/skin/ui`（@ui-arch/ui）：67 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
+- `packages/skin/ui`（@ui-arch/ui）：68 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
 - `packages/design/tokens`（@ui-arch/tokens）：设计令牌
 - `packages/tools/cli`（@ui-arch/cli）：`ua` 命令行 + MCP 注册表服务（private）
 - `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html

ARCHITECTURE.md

@@ -34,7 +34,7 @@ ui-arch-mvp/
 │   │   ├── table-core/       # 表格状态内核
 │   │   └── frame/            # 信号 + hyperscript 微框架
 │   ├── skin/                 # 皮肤层（DOM 组件，可发布）
-│   │   └── ui/               # 67 个组件 + ui.css
+│   │   └── ui/               # 68 个组件 + ui.css
 │   ├── design/               # 资产层（可发布）
 │   │   └── tokens/           # --ua-* 设计令牌
 │   └── tools/                # 工程层（private，不发布）

README.md

@@ -12,13 +12,13 @@ npm run docs            # 生成人类文档站 apps/docs/index.html + Agent 全
 npm run changelog       # 依据 git 提交史重写 CHANGELOG.md（发版前跑；changelog:check 可查漂移）
 ```
 
-## 组件（共 67 个）
+## 组件（共 68 个）
 
 <!-- ua:components -->
-accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · image · inputNumber · link · list · menu · modal · mentions · multiSelect · notification · pagination · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · watermark
+accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · image · inputNumber · link · list · menu · modal · mentions · multiSelect · notification · pagination · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark
 <!-- /ua:components -->
 
-分组：表单（button / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / popconfirm / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography）、其他（floatButton / grid / link / space / divider / splitter / backTop / affix / tour / watermark）。
+分组：表单（button / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / popconfirm / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / link / space / divider / splitter / backTop / affix / tour / watermark）。
 
 ## 可访问性约定
 
@@ -32,7 +32,7 @@ accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup
 |---|---|
 | `packages/core/frame` | @ui-arch/frame：signal / computed / effect + hyperscript（无虚拟 DOM） |
 | `packages/core/table-core` | @ui-arch/table-core：headless 表格（filter → sort → paginate 派生管线） |
-| `packages/skin/ui` | @ui-arch/ui：67 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
+| `packages/skin/ui` | @ui-arch/ui：68 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
 | `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） |
 | `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server |
 | `apps/demo` | 交互演示（esbuild 打包成单文件） |

apps/demo/main.ts

@@ -77,6 +77,7 @@ import {
   tour,
   tooltip,
   typography,
+  virtualList,
 } from '@ui-arch/ui';
 import type { RowKey } from '@ui-arch/ui';
 
@@ -1496,6 +1497,28 @@ const content = h(
       ),
     ),
   ),
+  section(
+    'sec-vlist',
+    '虚拟列表',
+    'virtualList 固定行高虚拟化：DOM 里只保留可视窗口 + 上下缓冲条（本例 10,000 行常驻约 20 行），滚动 rAF 合帧整窗重建；句柄 scrollTo 按全量下标回跳，越界自动钳制。',
+    grid({ min: '320px' },
+      card({ title: '10,000 行订单流水' },
+        (() => {
+          const rows = Array.from({ length: 10000 }, (_, i) => ({ id: `SO-${10000 + i}`, amount: 88 + (i % 97) * 13 })); // 金额按下标推导，回看稳定
+          return virtualList({ items: rows, itemHeight: 44, height: 320, renderItem: (raw, i) => `#${i + 1} · ${(raw as { id: string }).id} · ¥${(raw as { amount: number }).amount}` }).el;
+        })(),
+        typography({ variant: 'paragraph', type: 'secondary', content: '滚动条是真实全长，但 DOM 只渲染可视窗口——开 DevTools 数一数 .ua-vlist-item 就知道。' }),
+      ),
+      card({ title: '滚回第 500 条' },
+        (() => {
+          const rows = Array.from({ length: 10000 }, (_, i) => ({ id: `SO-${10000 + i}`, amount: 88 + (i % 97) * 13 }));
+          const vlist = virtualList({ items: rows, itemHeight: 44, height: 320, renderItem: (raw, i) => `#${i + 1} · ${(raw as { id: string }).id} · ¥${(raw as { amount: number }).amount}` });
+          return h('div', null, vlist.el, space({ size: 'sm' }, button({ label: '跳到 #500', onClick: () => vlist.scrollTo(499) })));
+        })(),
+        typography({ variant: 'paragraph', type: 'secondary', content: 'scrollTo(index) 接全量下标（从 0 计），组件同步重渲，不等下一次滚动事件。' }),
+      ),
+    ),
+  ),
 );
 
 // 悬浮按钮：fixed 定位，挂 body 不参与页面布局

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 } 句柄
 
 一行用法：
 

llms.txt

@@ -116,6 +116,7 @@
   - treeSelect(props)：树形选择，按钮触发弹层并复用 tree（搜索 / 多选 / 级联），单选选中即收起、多选保持展开，Esc 与点外收起
   - link(props)：链接，站内跳转与站外跳转统一入口，external 自动补 ↗ 与 rel=noopener noreferrer 并给读屏播报
   - avatarGroup(props)：头像组，横向叠放并在超出 max 时折叠成 +N，整组 title 列出全部姓名
+  - virtualList(props)：虚拟列表，固定行高长列表只渲染可视窗口 + 上下缓冲条，万级数据滚动不随总量掉帧；返回 { el, scrollTo } 句柄
 - 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')`
 - 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号
 - 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调

packages/skin/ui/src/index.ts

@@ -67,3 +67,4 @@ export { mentions } from './mentions.js';
 export { treeSelect } from './treeSelect.js';
 export { link } from './link.js';
 export { avatarGroup } from './avatarGroup.js';
+export { virtualList } from './virtualList.js';

packages/skin/ui/src/types.ts

@@ -876,3 +876,18 @@ export interface AvatarGroupProps {
 }
 
 export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方
+
+/*** 虚拟列表入参：固定行高，只渲染可视窗口 + 缓冲条 ***/
+export interface VirtualListProps {
+  items: unknown[];  // 全量数据（不切片，由组件按滚动位置取窗口）
+  itemHeight: number; // 每行固定高度像素（虚拟化前提：行高一致）
+  height: number;     // 容器可视高度像素（超出即容器内滚动）
+  overscan?: number;  // 上下各多渲染的缓冲条数；缺省 5（滚动更平滑）
+  renderItem: (item: unknown, index: number) => unknown; // 行内容渲染器：返回字符串/DOM/响应式值
+}
+
+/*** 虚拟列表句柄 ***/
+export interface VirtualListHandle {
+  el: HTMLElement;              // 列表根节点（本身即滚动容器）
+  scrollTo: (index: number) => void; // 滚动到指定行下标（越界自动钳制）
+}

packages/skin/ui/src/virtualList.ts

@@ -0,0 +1,44 @@
+import { h } from '@ui-arch/frame';
+import type { VirtualListProps, VirtualListHandle } from './types.js';
+
+/*** 虚拟列表：固定行高长列表只渲染可视窗口 + 上下缓冲条，万级数据滚动不随总量掉帧 ***/
+export function virtualList(props: VirtualListProps): VirtualListHandle {
+  // —— 状态集中声明 ——
+  const overscan = props.overscan ?? 5;   // 上下各多渲染的缓冲条数，滚动更平滑
+  const total = props.items.length;       // 数据总量（决定占位层高度）
+  const raf = { n: 0 };                   // 滚动节流帧句柄（对象包装便于闭包内改写）
+  const view = h('div', { class: 'ua-vlist', role: 'list', style: `height:${props.height}px` }) as HTMLElement; // 可视容器：唯一滚动源
+  const phantom = h('div', { class: 'ua-vlist-phantom' }) as HTMLElement;   // 占位层：撑出真实滚动高度
+  const win = h('div', { class: 'ua-vlist-window' }) as HTMLElement;        // 可视窗口层：整体平移对齐滚动位置
+
+  /*** 按当前 scrollTop 重算可视区间并整窗重建：窗口内条目数固定少量，重建比 diff 更简单可靠 ***/
+  const render = (): void => {
+    const first = Math.max(0, Math.floor(view.scrollTop / props.itemHeight) - overscan); // 窗口首条（含缓冲上探）
+    const visible = Math.ceil(props.height / props.itemHeight) + 1;                      // 视口能容纳的整条数（+1 补零头）
+    const end = Math.min(total, first + visible + overscan * 2);                         // 窗口尾条（含缓冲）
+    win.style.transform = `translateY(${first * props.itemHeight}px)`;                    // 窗口平移到首条位置
+    const rows: HTMLElement[] = [];                                                       // 本轮窗口内的行节点
+    for (let i = first; i < end; i++) {
+      rows.push(h('div', { class: 'ua-vlist-item', role: 'listitem', style: `height:${props.itemHeight}px` }, props.renderItem(props.items[i], i)));
+    }
+    win.replaceChildren(...rows); // 一次性换入，避免逐个 append 的中间态闪烁
+  };
+
+  /*** 滚动事件：rAF 合并同帧多次触发，滚得再快也只渲一帧 ***/
+  const onScroll = (): void => {
+    if (raf.n) return; // 已有排程中的帧，吞掉本次
+    raf.n = requestAnimationFrame(() => { raf.n = 0; render(); });
+  };
+  view.addEventListener('scroll', onScroll);
+  phantom.style.height = `${total * props.itemHeight}px`; // 占位高度 = 总行数 × 行高
+  view.append(phantom, win);
+  render(); // 首屏先渲一帧，不等滚动
+  return {
+    el: view,
+    /*** 滚动到指定下标（钳制到有效区间），同步重渲避免同帧 scroll 不触发 ***/
+    scrollTo(index: number): void {
+      view.scrollTop = Math.max(0, Math.min(index, total - 1)) * props.itemHeight; // 越界钳制
+      render();
+    },
+  };
+}

packages/skin/ui/ua.manifest.json

@@ -81,7 +81,8 @@
       "mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value",
       "treeSelect(props)：树形选择，按钮触发弹层并复用 tree（搜索 / 多选 / 级联），单选选中即收起、多选保持展开，Esc 与点外收起",
       "link(props)：链接，站内跳转与站外跳转统一入口，external 自动补 ↗ 与 rel=noopener noreferrer 并给读屏播报",
-      "avatarGroup(props)：头像组，横向叠放并在超出 max 时折叠成 +N，整组 title 列出全部姓名"
+      "avatarGroup(props)：头像组，横向叠放并在超出 max 时折叠成 +N，整组 title 列出全部姓名",
+      "virtualList(props)：虚拟列表，固定行高长列表只渲染可视窗口 + 上下缓冲条，万级数据滚动不随总量掉帧；返回 { el, scrollTo } 句柄"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -3507,7 +3508,53 @@
           "整组是展示型元素：要有点击行为就在外面包 button 或 link，不要给单个头像加交互",
           "size 与单个 avatar 一致，混排时把并排 avatar 与 avatarGroup 传同一个 size，视觉才对得上"
         ]
+      },
+      {
+        "id": "virtualList",
+        "title": "虚拟列表 VirtualList",
+        "demo": "sec-vlist",
+        "props": [
+          {
+            "n": "items",
+            "t": "unknown[]",
+            "r": 1,
+            "d": "全量数据（不切片，由组件按滚动位置取窗口）"
+          },
+          {
+            "n": "itemHeight",
+            "t": "number",
+            "r": 1,
+            "d": "每行固定高度像素；虚拟化前提是行高一致"
+          },
+          {
+            "n": "height",
+            "t": "number",
+            "r": 1,
+            "d": "容器可视高度像素，超出即容器内滚动"
+          },
+          {
+            "n": "overscan",
+            "t": "number",
+            "d": "上下各多渲染的缓冲条数；缺省 5，滚动更平滑",
+            "df": "5"
+          },
+          {
+            "n": "renderItem",
+            "t": "(item, index) => unknown",
+            "r": 1,
+            "d": "行内容渲染器：返回字符串 / DOM / 响应式值"
+          }
+        ],
+        "example": "const vlist = virtualList({ items: users, itemHeight: 44, height: 320, renderItem: (u) => u.name }); vlist.scrollTo(500);",
+        "steps": [
+          "itemHeight 必须与每行真实高度一致：行高由组件钉死，行内容超高会溢出，请保持单行或内部滚动",
+          "height 是容器可视高度（像素），列表在容器内滚动，不会撑开页面",
+          "renderItem 第二参是原始下标（全量数据中的位置），不是窗口内序号",
+          "滚回某条用句柄 scrollTo(index)，越界自动钳制；DOM 里只存在可视窗口的行，勿按全量下标查行节点",
+          "数据整体变化（换数据源）请销毁重建实例：items 是创建时快照，不响应外部数组突变",
+          "滚动事件内部已 rAF 合帧，滚动回调无需节流"
+        ]
       }
     ]
   }
-}
+}

packages/skin/ui/ui.css

@@ -4723,3 +4723,35 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
     transition: none;
   }
 }
+
+/* —— 虚拟列表 —— */
+.ua-vlist {
+  position: relative;
+  overflow-y: auto;                       /* 唯一滚动源：容器内滚动 */
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-md);
+  background: var(--ua-color-surface);
+  overscroll-behavior: contain;           /* 滚到头不带动页面滚动 */
+}
+.ua-vlist-phantom {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 1px;                             /* 只撑高度，不占布局宽度 */
+}
+.ua-vlist-window {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  will-change: transform;                 /* 平移层独立合成，滚动不掉帧 */
+}
+.ua-vlist-item {
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+  padding: 0 var(--ua-space-3);           /* 行高由行内样式按 itemHeight 钉死 */
+}
+.ua-vlist-item + .ua-vlist-item {
+  border-top: 1px solid color-mix(in srgb, var(--ua-color-border) 60%, transparent);
+}