iter(g187): 新增虚拟列表组件
This commit is contained in:
HIsheR
+49
-2
@@ -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 合帧，滚动回调无需节流"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@@ -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
|
||||
|
||||
+1
-1
@@ -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，不发布）
|
||||
|
||||
@@ -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 打包成单文件） |
|
||||
|
||||
@@ -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 不参与页面布局
|
||||
|
||||
+29
-1
@@ -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 } 句柄
|
||||
|
||||
一行用法：
|
||||
|
||||
|
||||
@@ -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 为回调
|
||||
|
||||
@@ -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';
|
||||
|
||||
@@ -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; // 滚动到指定行下标（越界自动钳制）
|
||||
}
|
||||
|
||||
@@ -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();
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -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 合帧，滚动回调无需节流"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user