@zerodep-dev/vue-tsx-pro-ui 0.0.0-stage → 0.2.0

package/dist/utils/style/vars.js

@@ -0,0 +1,21 @@
+import * as css from "@zerodep-dev/vue-tsx-pro-tsx/styles";
+//#region src/utils/style/vars.ts
+/**
+* 组件之间约定的 CSS 变量（defineVars）：不属于主题，由外层组件设置、里面的组件读取。
+* 使用方从子路径 `@zerodep-dev/vue-tsx-pro-ui/vars` 导入（同 tokens），主入口不导出。
+*/
+/** 布局变量 */
+var layoutVars = css.defineVars("vtp-layout", { 
+/**
+* 页面顶部被粘性元素（AppShell 的顶栏）挡住的高度：标题的 scroll-margin、粘性侧栏的 top 据此让开，
+* 锚点跳转后标题不会藏在顶栏下面。AppShell 设置它，默认 0
+*/
+stickyOffset: "0px" });
+/** 骨架扫光（shimmer.ts）的变量 */
+var shimmerVars = css.defineVars("vtp-shimmer", { 
+/** 扫过的那道光带的颜色：默认跟随字色；Skeleton 改成正文色的淡色 */
+highlight: "color-mix(in oklab, currentColor 12%, transparent)" });
+//#endregion
+export { layoutVars, shimmerVars };
+
+//# sourceMappingURL=vars.js.map

package/dist/utils/style/vars.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vars.js","names":[],"sources":["../../../src/utils/style/vars.ts"],"sourcesContent":["/**\n * 组件之间约定的 CSS 变量（defineVars）：不属于主题，由外层组件设置、里面的组件读取。\n * 使用方从子路径 `@zerodep-dev/vue-tsx-pro-ui/vars` 导入（同 tokens），主入口不导出。\n */\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\n\n/** 布局变量 */\nexport const layoutVars = css.defineVars('vtp-layout', {\n  /**\n   * 页面顶部被粘性元素（AppShell 的顶栏）挡住的高度：标题的 scroll-margin、粘性侧栏的 top 据此让开，\n   * 锚点跳转后标题不会藏在顶栏下面。AppShell 设置它，默认 0\n   */\n  stickyOffset: '0px',\n});\n\n/** 骨架扫光（shimmer.ts）的变量 */\nexport const shimmerVars = css.defineVars('vtp-shimmer', {\n  /** 扫过的那道光带的颜色：默认跟随字色；Skeleton 改成正文色的淡色 */\n  highlight: 'color-mix(in oklab, currentColor 12%, transparent)',\n});\n"],"mappings":";;;;;;;AAOA,IAAa,aAAa,IAAI,WAAW,cAAc;;;;;AAKrD,cAAc,MAChB,CAAC;;AAGD,IAAa,cAAc,IAAI,WAAW,eAAe;;AAEvD,WAAW,qDACb,CAAC"}

package/dist/utils/virtual/use-virtualizer.d.ts

@@ -0,0 +1,43 @@
+import { type ExtractorRange, type VirtualItem, type VirtualScrollOptions, type VisibleRange } from './virtualizer';
+/** useVirtualizer 每次同步时读取的选项 */
+export interface UseVirtualizerOptions {
+    /** 总项数 */
+    count: number;
+    /** 滚动容器：元素或 window；还没挂载时为 null */
+    scrollElement: HTMLElement | Window | null;
+    /** 列表开头所在的元素：它与滚动内容开头的距离就是 scrollMargin（容器内边距、表头、列表上方的内容） */
+    list: HTMLElement | null;
+    /** 第 index 项的估计大小（px） */
+    estimateSize: (index: number) => number;
+    /** 第 index 项的 key；数据会重排、增删时给稳定的 key */
+    getItemKey?: (index: number) => PropertyKey;
+    /** 可见范围前后各多渲染几项 */
+    overscan?: number;
+    /** 横向 */
+    horizontal?: boolean;
+    /** 改写要渲染哪些项：始终渲染高亮项、吸顶行 */
+    rangeExtractor?: (range: ExtractorRange) => number[];
+    /** 视口开头被吸顶的内容遮住的部分（px），滚动时读取：滚动到某项时避开 */
+    scrollPaddingStart?: () => number;
+    /** 视口末尾被吸底的内容遮住的部分（px），滚动时读取 */
+    scrollPaddingEnd?: () => number;
+    /** 可见范围（不含 overscan）变化：接近末尾时加载更多 */
+    onRangeChange?: (range: VisibleRange) => void;
+}
+/** useVirtualizer 的返回值 */
+export interface VirtualView {
+    /** 要渲染的项 */
+    readonly items: readonly VirtualItem[];
+    /** 列表的总大小（px） */
+    readonly total: number;
+    /** 当前可见范围 */
+    readonly range: VisibleRange | null;
+    /** 项的 ref：渲染后测量真实大小（元素要带 data-index） */
+    measure: (element: unknown) => void;
+    /** 滚动到第 index 项 */
+    scrollToIndex: (index: number, options?: VirtualScrollOptions) => void;
+    /** 滚动到相对列表开头的位置 */
+    scrollToOffset: (offset: number, options?: VirtualScrollOptions) => void;
+}
+/** 在组件 setup 里调用 */
+export declare function useVirtualizer(read: () => UseVirtualizerOptions): VirtualView;

package/dist/utils/virtual/use-virtualizer.js

@@ -0,0 +1,94 @@
+import { Virtualizer, isWindow } from "./virtualizer.js";
+import { onScopeDispose, shallowRef, watch } from "vue";
+//#region src/utils/virtual/use-virtualizer.ts
+/**
+* 虚拟滚动的 Vue 接线：把 Virtualizer（virtualizer.ts，不依赖 Vue）接到组件上。
+* VirtualList、DataTable、TreeDataTable、ListboxView（Select、Combobox 的选项）共用。
+*
+*   const virtual = useVirtualizer(() => ({
+*     count: rows.length,
+*     scrollElement: viewport,           // 滚动容器（元素或 window），就绪前为 null
+*     list: body,                         // 列表开头所在的元素：据此算 scrollMargin
+*     estimateSize: () => 40,
+*     getItemKey: (index) => rows[index]!.id,
+*   }));
+*   virtual.items / virtual.total         渲染：只渲染这些项，列表撑到 total 高
+*   ref={virtual.measure}                 每一项的元素：渲染后测量真实大小
+*
+* read 在 watch 里读取：其中读到的响应式数据（行数、key）变化时重新同步；
+* 选项里的函数（estimateSize、onRangeChange）不在这时调用，它们读到的数据不会变成依赖。
+*/
+/** 在组件 setup 里调用 */
+function useVirtualizer(read) {
+	const view = shallowRef({
+		items: [],
+		total: 0,
+		range: null
+	});
+	let current = read();
+	let reported = null;
+	function build(options) {
+		return {
+			count: options.count,
+			overscan: options.overscan,
+			horizontal: options.horizontal,
+			estimateSize: options.estimateSize,
+			getItemKey: options.getItemKey,
+			rangeExtractor: options.rangeExtractor,
+			scrollPaddingStart: () => current.scrollPaddingStart?.() ?? 0,
+			scrollPaddingEnd: () => current.scrollPaddingEnd?.() ?? 0,
+			getScrollElement: () => current.scrollElement,
+			scrollMargin: () => {
+				const { list, scrollElement, horizontal } = current;
+				if (!list || !scrollElement) return 0;
+				const listRect = list.getBoundingClientRect();
+				if (isWindow(scrollElement)) return horizontal ? listRect.left + window.scrollX : listRect.top + window.scrollY;
+				const rootRect = scrollElement.getBoundingClientRect();
+				return horizontal ? listRect.left - rootRect.left + scrollElement.scrollLeft : listRect.top - rootRect.top + scrollElement.scrollTop;
+			},
+			onChange: (changed) => {
+				const range = changed.getVisibleRange();
+				view.value = {
+					items: changed.getVirtualItems(),
+					total: changed.getTotalSize(),
+					range
+				};
+				if (!range || range.startIndex === reported?.startIndex && range.endIndex === reported.endIndex) return;
+				reported = range;
+				current.onRangeChange?.(range);
+			}
+		};
+	}
+	const virtualizer = new Virtualizer(build(current));
+	watch(read, (next) => {
+		current = next;
+		virtualizer.setOptions(build(next));
+	});
+	let unmount;
+	watch(() => read().scrollElement, (element) => {
+		unmount?.();
+		unmount = element ? virtualizer.mount() : void 0;
+	}, {
+		immediate: true,
+		flush: "post"
+	});
+	onScopeDispose(() => unmount?.());
+	return {
+		get items() {
+			return view.value.items;
+		},
+		get total() {
+			return view.value.total;
+		},
+		get range() {
+			return view.value.range;
+		},
+		measure: virtualizer.measureElement,
+		scrollToIndex: (index, options) => virtualizer.scrollToIndex(index, options),
+		scrollToOffset: (offset, options) => virtualizer.scrollToOffset(offset, options)
+	};
+}
+//#endregion
+export { useVirtualizer };
+
+//# sourceMappingURL=use-virtualizer.js.map

package/dist/utils/virtual/use-virtualizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-virtualizer.js","names":[],"sources":["../../../src/utils/virtual/use-virtualizer.ts"],"sourcesContent":["/**\n * 虚拟滚动的 Vue 接线：把 Virtualizer（virtualizer.ts，不依赖 Vue）接到组件上。\n * VirtualList、DataTable、TreeDataTable、ListboxView（Select、Combobox 的选项）共用。\n *\n *   const virtual = useVirtualizer(() => ({\n *     count: rows.length,\n *     scrollElement: viewport,           // 滚动容器（元素或 window），就绪前为 null\n *     list: body,                         // 列表开头所在的元素：据此算 scrollMargin\n *     estimateSize: () => 40,\n *     getItemKey: (index) => rows[index]!.id,\n *   }));\n *   virtual.items / virtual.total         渲染：只渲染这些项，列表撑到 total 高\n *   ref={virtual.measure}                 每一项的元素：渲染后测量真实大小\n *\n * read 在 watch 里读取：其中读到的响应式数据（行数、key）变化时重新同步；\n * 选项里的函数（estimateSize、onRangeChange）不在这时调用，它们读到的数据不会变成依赖。\n */\nimport { onScopeDispose, shallowRef, watch } from 'vue';\nimport {\n  isWindow,\n  Virtualizer,\n  type ExtractorRange,\n  type VirtualItem,\n  type VirtualScrollOptions,\n  type VisibleRange,\n} from './virtualizer';\n\n/** useVirtualizer 每次同步时读取的选项 */\nexport interface UseVirtualizerOptions {\n  /** 总项数 */\n  count: number;\n  /** 滚动容器：元素或 window；还没挂载时为 null */\n  scrollElement: HTMLElement | Window | null;\n  /** 列表开头所在的元素：它与滚动内容开头的距离就是 scrollMargin（容器内边距、表头、列表上方的内容） */\n  list: HTMLElement | null;\n  /** 第 index 项的估计大小（px） */\n  estimateSize: (index: number) => number;\n  /** 第 index 项的 key；数据会重排、增删时给稳定的 key */\n  getItemKey?: (index: number) => PropertyKey;\n  /** 可见范围前后各多渲染几项 */\n  overscan?: number;\n  /** 横向 */\n  horizontal?: boolean;\n  /** 改写要渲染哪些项：始终渲染高亮项、吸顶行 */\n  rangeExtractor?: (range: ExtractorRange) => number[];\n  /** 视口开头被吸顶的内容遮住的部分（px），滚动时读取：滚动到某项时避开 */\n  scrollPaddingStart?: () => number;\n  /** 视口末尾被吸底的内容遮住的部分（px），滚动时读取 */\n  scrollPaddingEnd?: () => number;\n  /** 可见范围（不含 overscan）变化：接近末尾时加载更多 */\n  onRangeChange?: (range: VisibleRange) => void;\n}\n\n/** useVirtualizer 的返回值 */\nexport interface VirtualView {\n  /** 要渲染的项 */\n  readonly items: readonly VirtualItem[];\n  /** 列表的总大小（px） */\n  readonly total: number;\n  /** 当前可见范围 */\n  readonly range: VisibleRange | null;\n  /** 项的 ref：渲染后测量真实大小（元素要带 data-index） */\n  measure: (element: unknown) => void;\n  /** 滚动到第 index 项 */\n  scrollToIndex: (index: number, options?: VirtualScrollOptions) => void;\n  /** 滚动到相对列表开头的位置 */\n  scrollToOffset: (offset: number, options?: VirtualScrollOptions) => void;\n}\n\n/** 在组件 setup 里调用 */\nexport function useVirtualizer(read: () => UseVirtualizerOptions): VirtualView {\n  // 渲染需要的只有这些；滚动本身不触发重新渲染\n  const view = shallowRef<{ items: VirtualItem[]; total: number; range: VisibleRange | null }>({\n    items: [],\n    total: 0,\n    range: null,\n  });\n  let current = read();\n  let reported: VisibleRange | null = null;\n\n  function build(options: UseVirtualizerOptions) {\n    return {\n      count: options.count,\n      overscan: options.overscan,\n      horizontal: options.horizontal,\n      estimateSize: options.estimateSize,\n      getItemKey: options.getItemKey,\n      rangeExtractor: options.rangeExtractor,\n      scrollPaddingStart: () => current.scrollPaddingStart?.() ?? 0,\n      scrollPaddingEnd: () => current.scrollPaddingEnd?.() ?? 0,\n      getScrollElement: () => current.scrollElement,\n      scrollMargin: () => {\n        const { list, scrollElement, horizontal } = current;\n        if (!list || !scrollElement) return 0;\n        const listRect = list.getBoundingClientRect();\n        if (isWindow(scrollElement)) {\n          return horizontal ? listRect.left + window.scrollX : listRect.top + window.scrollY;\n        }\n        const rootRect = scrollElement.getBoundingClientRect();\n        return horizontal\n          ? listRect.left - rootRect.left + scrollElement.scrollLeft\n          : listRect.top - rootRect.top + scrollElement.scrollTop;\n      },\n      onChange: (changed: Virtualizer) => {\n        const range = changed.getVisibleRange();\n        view.value = { items: changed.getVirtualItems(), total: changed.getTotalSize(), range };\n        // 测量也会触发 onChange，可见范围没变时不报告\n        if (\n          !range ||\n          (range.startIndex === reported?.startIndex && range.endIndex === reported.endIndex)\n        ) {\n          return;\n        }\n        reported = range;\n        current.onRangeChange?.(range);\n      },\n    };\n  }\n\n  const virtualizer = new Virtualizer(build(current));\n\n  watch(read, (next) => {\n    current = next;\n    virtualizer.setOptions(build(next));\n  });\n\n  // 滚动容器就绪（或换了）时挂载：监听滚动与大小\n  let unmount: (() => void) | undefined;\n  watch(\n    () => read().scrollElement,\n    (element) => {\n      unmount?.();\n      unmount = element ? virtualizer.mount() : undefined;\n    },\n    { immediate: true, flush: 'post' },\n  );\n  onScopeDispose(() => unmount?.());\n\n  return {\n    get items() {\n      return view.value.items;\n    },\n    get total() {\n      return view.value.total;\n    },\n    get range() {\n      return view.value.range;\n    },\n    measure: virtualizer.measureElement as (element: unknown) => void,\n    scrollToIndex: (index, options) => virtualizer.scrollToIndex(index, options),\n    scrollToOffset: (offset, options) => virtualizer.scrollToOffset(offset, options),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAsEA,SAAgB,eAAe,MAAgD;CAE7E,MAAM,OAAO,WAAgF;EAC3F,OAAO,CAAC;EACR,OAAO;EACP,OAAO;CACT,CAAC;CACD,IAAI,UAAU,KAAK;CACnB,IAAI,WAAgC;CAEpC,SAAS,MAAM,SAAgC;EAC7C,OAAO;GACL,OAAO,QAAQ;GACf,UAAU,QAAQ;GAClB,YAAY,QAAQ;GACpB,cAAc,QAAQ;GACtB,YAAY,QAAQ;GACpB,gBAAgB,QAAQ;GACxB,0BAA0B,QAAQ,qBAAqB,KAAK;GAC5D,wBAAwB,QAAQ,mBAAmB,KAAK;GACxD,wBAAwB,QAAQ;GAChC,oBAAoB;IAClB,MAAM,EAAE,MAAM,eAAe,eAAe;IAC5C,IAAI,CAAC,QAAQ,CAAC,eAAe,OAAO;IACpC,MAAM,WAAW,KAAK,sBAAsB;IAC5C,IAAI,SAAS,aAAa,GACxB,OAAO,aAAa,SAAS,OAAO,OAAO,UAAU,SAAS,MAAM,OAAO;IAE7E,MAAM,WAAW,cAAc,sBAAsB;IACrD,OAAO,aACH,SAAS,OAAO,SAAS,OAAO,cAAc,aAC9C,SAAS,MAAM,SAAS,MAAM,cAAc;GAClD;GACA,WAAW,YAAyB;IAClC,MAAM,QAAQ,QAAQ,gBAAgB;IACtC,KAAK,QAAQ;KAAE,OAAO,QAAQ,gBAAgB;KAAG,OAAO,QAAQ,aAAa;KAAG;IAAM;IAEtF,IACE,CAAC,SACA,MAAM,eAAe,UAAU,cAAc,MAAM,aAAa,SAAS,UAE1E;IAEF,WAAW;IACX,QAAQ,gBAAgB,KAAK;GAC/B;EACF;CACF;CAEA,MAAM,cAAc,IAAI,YAAY,MAAM,OAAO,CAAC;CAElD,MAAM,OAAO,SAAS;EACpB,UAAU;EACV,YAAY,WAAW,MAAM,IAAI,CAAC;CACpC,CAAC;CAGD,IAAI;CACJ,YACQ,KAAK,CAAC,CAAC,gBACZ,YAAY;EACX,UAAU;EACV,UAAU,UAAU,YAAY,MAAM,IAAI,KAAA;CAC5C,GACA;EAAE,WAAW;EAAM,OAAO;CAAO,CACnC;CACA,qBAAqB,UAAU,CAAC;CAEhC,OAAO;EACL,IAAI,QAAQ;GACV,OAAO,KAAK,MAAM;EACpB;EACA,IAAI,QAAQ;GACV,OAAO,KAAK,MAAM;EACpB;EACA,IAAI,QAAQ;GACV,OAAO,KAAK,MAAM;EACpB;EACA,SAAS,YAAY;EACrB,gBAAgB,OAAO,YAAY,YAAY,cAAc,OAAO,OAAO;EAC3E,iBAAiB,QAAQ,YAAY,YAAY,eAAe,QAAQ,OAAO;CACjF;AACF"}

package/dist/utils/virtual/virtualizer.d.ts

@@ -0,0 +1,145 @@
+/** 一个要渲染的项；位置都相对列表开头，单位 px */
+export interface VirtualItem {
+    /** 在数据里的序号 */
+    readonly index: number;
+    /** getItemKey 给出的 key，测量结果按它缓存 */
+    readonly key: PropertyKey;
+    /** 起始位置 */
+    readonly start: number;
+    /** 大小：测量过的为真实大小，否则为估计值 */
+    readonly size: number;
+    /** 结束位置（start + size） */
+    readonly end: number;
+}
+/** 可见范围（不含 overscan），两端都包含 */
+export interface VisibleRange {
+    /** 第一个可见项 */
+    readonly startIndex: number;
+    /** 最后一个可见项 */
+    readonly endIndex: number;
+}
+/** 交给 rangeExtractor 的范围：可见范围、overscan 与总数 */
+export interface ExtractorRange extends VisibleRange {
+    /** 可见范围前后各多渲染几项 */
+    readonly overscan: number;
+    /** 总项数 */
+    readonly count: number;
+}
+/** 滚动到某一项时，它停在视口的什么位置 */
+export interface ScrollAligns {
+    /** 顶端（横向时为起始端）对齐视口开头 */
+    start: unknown;
+    /** 居中 */
+    center: unknown;
+    /** 末端对齐视口末尾 */
+    end: unknown;
+    /** 已经完整可见就不动，否则就近对齐开头或末尾（默认） */
+    auto: unknown;
+}
+/** scrollToIndex、scrollToOffset 的选项 */
+export interface VirtualScrollOptions {
+    /** 目标项停在视口的什么位置，默认 auto（scrollToOffset 不用） */
+    align?: keyof ScrollAligns;
+    /** 滚动方式，同 Element.scrollTo；smooth 时动态大小的项可能停得不够准 */
+    behavior?: ScrollBehavior;
+}
+/** Virtualizer 的选项 */
+export interface VirtualizerOptions {
+    /** 总项数 */
+    count: number;
+    /** 滚动容器：元素或 window；还没有时返回 null */
+    getScrollElement: () => HTMLElement | Window | null;
+    /** 第 index 项的估计大小（px）；渲染后以测量值为准，估计得越接近，滚动条越稳 */
+    estimateSize: (index: number) => number;
+    /** 第 index 项的 key，默认就是 index；数据会重排、增删时给稳定的 key，测量结果才对得上 */
+    getItemKey?: (index: number) => PropertyKey;
+    /** 可见范围前后各多渲染几项，默认 3：快速滚动时不露白 */
+    overscan?: number;
+    /** 横向滚动 */
+    horizontal?: boolean;
+    /** 列表开头距滚动内容开头的距离（px），如列表上方还有其他内容；函数在每次滚动时读取，默认 0 */
+    scrollMargin?: () => number;
+    /** 视口开头被吸顶的内容（表头）遮住的部分（px）：scrollToIndex 对齐时避开，被遮住的项不算可见；函数在滚动时读取 */
+    scrollPaddingStart?: () => number;
+    /** 视口末尾被吸底的内容（合计行）遮住的部分（px）；吸底的内容要在列表之后的正常流里 */
+    scrollPaddingEnd?: () => number;
+    /** 改写要渲染哪些项（序号升序）：吸顶行、固定行在这里加上，默认是可见范围加 overscan */
+    rangeExtractor?: (range: ExtractorRange) => number[];
+    /** 渲染范围或总大小变了：重新渲染 */
+    onChange?: (virtualizer: Virtualizer) => void;
+}
+/** 按大小依次排出每项的位置 */
+export declare function computeMeasurements(count: number, sizeOf: (index: number, key: PropertyKey) => number, keyOf: (index: number) => PropertyKey): VirtualItem[];
+/** 与 [offset, offset + viewport) 相交的项；视口为 0 时只有 offset 处的一项；没有项时为 null */
+export declare function findVisibleRange(items: readonly VirtualItem[], offset: number, viewport: number): VisibleRange | null;
+/** 默认的渲染范围：可见范围前后各加 overscan 项 */
+export declare function defaultRangeExtractor({ startIndex, endIndex, overscan, count, }: ExtractorRange): number[];
+/** 滚动容器是不是 window（整页滚动） */
+export declare const isWindow: (target: HTMLElement | Window) => target is Window;
+/** 虚拟滚动的状态与计算：位置表、可见范围、测量、滚动到指定项（用法见文件开头） */
+export declare class Virtualizer {
+    private options;
+    /** key → 测量到的大小 */
+    private readonly sizes;
+    /** 位置表；前 valid 项是准的，之后的在下次读取时从第 valid 项往后重排 */
+    private measurements;
+    private valid;
+    /** 同一轮里的多次测量只通知一次 */
+    private updateQueued;
+    /** 每测到一次新的大小加一：scrollToIndex 据此判断位置是否已经稳定 */
+    private sizeVersion;
+    /** 滚动位置，相对列表开头 */
+    private offset;
+    private viewport;
+    private range;
+    private scrollElement;
+    private itemObserver;
+    private readonly observed;
+    /** 这一批新渲染、还没量过的项 */
+    private readonly unmeasured;
+    private pendingScroll;
+    constructor(options: VirtualizerOptions);
+    /** 换一组选项（总数、估计大小、key 等）：重新排位置表，测量过的大小按 key 保留 */
+    setOptions(options: VirtualizerOptions): void;
+    /** 开始监听滚动容器的滚动与大小变化；返回清理函数 */
+    mount(): () => void;
+    /** 每项的位置表 */
+    getMeasurements(): readonly VirtualItem[];
+    /**
+     * 位置表补算到第 index 项为止：只从第一个变了大小的项往后重排，不是每次测量都重建整张表
+     * （一万行时每次重建要几毫秒，滚动时每帧都有新的项被测量）
+     */
+    private measureUpTo;
+    /** 列表的总大小（px）：撑开滚动区域 */
+    getTotalSize(): number;
+    /** 可见范围（不含 overscan）；没有项时为 null */
+    getVisibleRange(): VisibleRange | null;
+    /** 要渲染的项，序号升序 */
+    getVirtualItems(): VirtualItem[];
+    /**
+     * 测量渲染出来的项：作为元素的 ref 回调，元素要带 data-index。同一批渲染的项在微任务里一起量，
+     * 之后大小变化由 ResizeObserver 自动更新。传 null（元素卸载）时不再观察已经离开文档的元素。
+     */
+    measureElement: (element: Element | null) => void;
+    /**
+     * 量这一批新渲染的项：先全部读完再更新。边读边改（调整滚动位置）时每次读取都强制重新布局，
+     * 一次渲染很多项（如滚动容器没有限高，所有项都“可见”）时是平方级的布局，页面会卡死。
+     * 量布局尺寸（offsetHeight）而不是 getBoundingClientRect：浮层进场的 scale 变换会把后者缩小，
+     * 元素之后被复用（列表过滤、重排）时 ResizeObserver 不会再报，缩小的值就一直留着，行与行叠在一起
+     */
+    private measureRendered;
+    /** 滚动到第 index 项 */
+    scrollToIndex(index: number, { align, behavior }?: VirtualScrollOptions): void;
+    /** 滚动到相对列表开头的 offset（px） */
+    scrollToOffset(offset: number, { behavior }?: VirtualScrollOptions): void;
+    /** 第 index 项按 align 对齐时的滚动位置；auto 且已经完整可见时为 null */
+    private offsetForIndex;
+    private resizeItem;
+    private borderBoxSize;
+    private scrollBy;
+    private scrollMargin;
+    private readViewport;
+    private readScroll;
+    /** 重新算可见范围；范围变了或 force 时通知 */
+    private update;
+}

package/dist/utils/virtual/virtualizer.js

@@ -0,0 +1,316 @@
+import { clamp } from "../data/number.js";
+//#region src/utils/virtual/virtualizer.ts
+/**
+* 虚拟滚动的核心：只渲染可见范围内的项（COMPONENTS.md §10.7）。不依赖 Vue，VirtualList、DataTable 都建在它上面。
+* 算法参考 @tanstack/virtual-core：先按估计大小排出位置表，渲染后测量真实大小并按 key 缓存；
+* 可见范围用二分查找；可视区上方的项大小变化时同步调整滚动位置，可见内容不跳。
+*
+*   const virtualizer = new Virtualizer({ count, estimateSize: () => 36, getScrollElement: () => el, onChange });
+*   const cleanup = virtualizer.mount();
+*   virtualizer.getVirtualItems()   // 要渲染的项：index、start（相对列表开头的偏移）、size
+*   <div data-index={item.index} ref={virtualizer.measureElement}>  // 测量真实大小
+*/
+/** 按大小依次排出每项的位置 */
+function computeMeasurements(count, sizeOf, keyOf) {
+	const items = new Array(count);
+	let start = 0;
+	for (let index = 0; index < count; index++) {
+		const key = keyOf(index);
+		const size = sizeOf(index, key);
+		items[index] = {
+			index,
+			key,
+			start,
+			size,
+			end: start + size
+		};
+		start += size;
+	}
+	return items;
+}
+/** 与 [offset, offset + viewport) 相交的项；视口为 0 时只有 offset 处的一项；没有项时为 null */
+function findVisibleRange(items, offset, viewport) {
+	if (!items.length) return null;
+	let low = 0;
+	let high = items.length - 1;
+	while (low < high) {
+		const middle = low + high >> 1;
+		if (items[middle].end > offset) high = middle;
+		else low = middle + 1;
+	}
+	let endIndex = low;
+	while (endIndex < items.length - 1 && items[endIndex].end < offset + viewport) endIndex++;
+	return {
+		startIndex: low,
+		endIndex
+	};
+}
+/** 默认的渲染范围：可见范围前后各加 overscan 项 */
+function defaultRangeExtractor({ startIndex, endIndex, overscan, count }) {
+	const from = Math.max(0, startIndex - overscan);
+	const to = Math.min(count - 1, endIndex + overscan);
+	return Array.from({ length: to - from + 1 }, (_, index) => from + index);
+}
+/** 滚动容器是不是 window（整页滚动） */
+var isWindow = (target) => typeof window !== "undefined" && target === window;
+/** 动态大小下 scrollToIndex 重新对准的最多次数 */
+var MAX_SCROLL_ATTEMPTS = 10;
+/** 虚拟滚动的状态与计算：位置表、可见范围、测量、滚动到指定项（用法见文件开头） */
+var Virtualizer = class {
+	options;
+	/** key → 测量到的大小 */
+	sizes = /* @__PURE__ */ new Map();
+	/** 位置表；前 valid 项是准的，之后的在下次读取时从第 valid 项往后重排 */
+	measurements = null;
+	valid = 0;
+	/** 同一轮里的多次测量只通知一次 */
+	updateQueued = false;
+	/** 每测到一次新的大小加一：scrollToIndex 据此判断位置是否已经稳定 */
+	sizeVersion = 0;
+	/** 滚动位置，相对列表开头 */
+	offset = 0;
+	viewport = 0;
+	range = null;
+	scrollElement = null;
+	itemObserver = null;
+	observed = /* @__PURE__ */ new Set();
+	/** 这一批新渲染、还没量过的项 */
+	unmeasured = [];
+	pendingScroll = 0;
+	constructor(options) {
+		this.options = options;
+	}
+	/** 换一组选项（总数、估计大小、key 等）：重新排位置表，测量过的大小按 key 保留 */
+	setOptions(options) {
+		this.options = options;
+		this.measurements = null;
+		this.valid = 0;
+		this.update(true);
+	}
+	/** 开始监听滚动容器的滚动与大小变化；返回清理函数 */
+	mount() {
+		const element = this.options.getScrollElement();
+		if (!element) return () => {};
+		this.scrollElement = element;
+		const onScroll = () => this.readScroll();
+		const onResize = () => {
+			this.readViewport();
+			this.readScroll();
+		};
+		element.addEventListener("scroll", onScroll, { passive: true });
+		let viewportObserver;
+		if (isWindow(element)) window.addEventListener("resize", onResize);
+		else if (typeof ResizeObserver !== "undefined") {
+			viewportObserver = new ResizeObserver(onResize);
+			viewportObserver.observe(element);
+		}
+		if (typeof ResizeObserver !== "undefined") {
+			this.itemObserver = new ResizeObserver((entries) => {
+				const sizes = entries.map((entry) => [entry.target, this.borderBoxSize(entry)]);
+				requestAnimationFrame(() => {
+					for (const [target, size] of sizes) this.resizeItem(target, size);
+				});
+			});
+			for (const element of this.observed) this.itemObserver.observe(element);
+		}
+		this.readViewport();
+		this.readScroll();
+		return () => {
+			element.removeEventListener("scroll", onScroll);
+			if (isWindow(element)) window.removeEventListener("resize", onResize);
+			viewportObserver?.disconnect();
+			this.itemObserver?.disconnect();
+			this.itemObserver = null;
+			for (const observed of this.observed) if (!observed.isConnected) this.observed.delete(observed);
+			cancelAnimationFrame(this.pendingScroll);
+			this.scrollElement = null;
+		};
+	}
+	/** 每项的位置表 */
+	getMeasurements() {
+		return this.measureUpTo(this.options.count - 1);
+	}
+	/**
+	* 位置表补算到第 index 项为止：只从第一个变了大小的项往后重排，不是每次测量都重建整张表
+	* （一万行时每次重建要几毫秒，滚动时每帧都有新的项被测量）
+	*/
+	measureUpTo(index) {
+		const { count, estimateSize, getItemKey = (i) => i } = this.options;
+		const sizeOf = (i, key) => this.sizes.get(key) ?? estimateSize(i);
+		if (!this.measurements || this.measurements.length !== count) {
+			this.measurements = computeMeasurements(count, sizeOf, getItemKey);
+			this.valid = count;
+			return this.measurements;
+		}
+		const items = this.measurements;
+		const end = Math.min(index, count - 1);
+		let start = this.valid > 0 ? items[this.valid - 1].end : 0;
+		for (let i = this.valid; i <= end; i++) {
+			const key = getItemKey(i);
+			const size = sizeOf(i, key);
+			items[i] = {
+				index: i,
+				key,
+				start,
+				size,
+				end: start + size
+			};
+			start += size;
+		}
+		this.valid = Math.max(this.valid, end + 1);
+		return items;
+	}
+	/** 列表的总大小（px）：撑开滚动区域 */
+	getTotalSize() {
+		return this.getMeasurements().at(-1)?.end ?? 0;
+	}
+	/** 可见范围（不含 overscan）；没有项时为 null */
+	getVisibleRange() {
+		return this.range;
+	}
+	/** 要渲染的项，序号升序 */
+	getVirtualItems() {
+		if (!this.range) return [];
+		const { count, overscan = 3, rangeExtractor = defaultRangeExtractor } = this.options;
+		const measurements = this.getMeasurements();
+		return rangeExtractor({
+			...this.range,
+			overscan,
+			count
+		}).map((index) => measurements[index]).filter((item) => item != null);
+	}
+	/**
+	* 测量渲染出来的项：作为元素的 ref 回调，元素要带 data-index。同一批渲染的项在微任务里一起量，
+	* 之后大小变化由 ResizeObserver 自动更新。传 null（元素卸载）时不再观察已经离开文档的元素。
+	*/
+	measureElement = (element) => {
+		if (!element) {
+			for (const observed of this.observed) {
+				if (observed.isConnected) continue;
+				this.itemObserver?.unobserve(observed);
+				this.observed.delete(observed);
+			}
+			return;
+		}
+		if (this.observed.has(element)) return;
+		this.observed.add(element);
+		this.itemObserver?.observe(element);
+		this.unmeasured.push(element);
+		if (this.unmeasured.length === 1) queueMicrotask(() => this.measureRendered());
+	};
+	/**
+	* 量这一批新渲染的项：先全部读完再更新。边读边改（调整滚动位置）时每次读取都强制重新布局，
+	* 一次渲染很多项（如滚动容器没有限高，所有项都“可见”）时是平方级的布局，页面会卡死。
+	* 量布局尺寸（offsetHeight）而不是 getBoundingClientRect：浮层进场的 scale 变换会把后者缩小，
+	* 元素之后被复用（列表过滤、重排）时 ResizeObserver 不会再报，缩小的值就一直留着，行与行叠在一起
+	*/
+	measureRendered() {
+		const { horizontal } = this.options;
+		const sizes = this.unmeasured.splice(0).map((element) => [element, horizontal ? element.offsetWidth : element.offsetHeight]);
+		for (const [element, size] of sizes) this.resizeItem(element, size);
+	}
+	/** 滚动到第 index 项 */
+	scrollToIndex(index, { align = "auto", behavior } = {}) {
+		cancelAnimationFrame(this.pendingScroll);
+		const target = () => this.offsetForIndex(index, align);
+		const first = target();
+		if (first == null) return;
+		this.scrollToOffset(first, { behavior });
+		if (behavior === "smooth") return;
+		let attempts = 0;
+		let version = this.sizeVersion;
+		const settle = () => {
+			if (++attempts > MAX_SCROLL_ATTEMPTS) return;
+			const next = target();
+			const measured = version !== this.sizeVersion;
+			version = this.sizeVersion;
+			if (next != null && Math.abs(next - this.offset) >= 1) this.scrollToOffset(next);
+			else if (!measured) return;
+			this.pendingScroll = requestAnimationFrame(settle);
+		};
+		this.pendingScroll = requestAnimationFrame(settle);
+	}
+	/** 滚动到相对列表开头的 offset（px） */
+	scrollToOffset(offset, { behavior } = {}) {
+		const element = this.scrollElement;
+		if (!element) return;
+		const position = offset + this.scrollMargin();
+		element.scrollTo(this.options.horizontal ? {
+			left: position,
+			behavior
+		} : {
+			top: position,
+			behavior
+		});
+	}
+	/** 第 index 项按 align 对齐时的滚动位置；auto 且已经完整可见时为 null */
+	offsetForIndex(index, align) {
+		const item = this.getMeasurements()[clamp(index, 0, this.options.count - 1)];
+		if (!item) return null;
+		const { offset, viewport } = this;
+		const before = this.options.scrollPaddingStart?.() ?? 0;
+		const after = this.options.scrollPaddingEnd?.() ?? 0;
+		let target;
+		if (align === "auto") {
+			if (item.start >= offset + before && item.end <= offset + viewport - after) return null;
+			target = item.start < offset + before ? item.start - before : item.end - viewport + after;
+		} else if (align === "start") target = item.start - before;
+		else if (align === "end") target = item.end - viewport + after;
+		else target = item.start + item.size / 2 - (viewport + before - after) / 2;
+		return clamp(target, -before, Math.max(0, this.getTotalSize() - viewport + after));
+	}
+	resizeItem(element, size) {
+		if (!size || !element.isConnected) return;
+		const index = Number(element.getAttribute("data-index"));
+		const item = this.measureUpTo(index)[index];
+		if (!item || item.size === size) return;
+		if (item.start < this.offset) this.scrollBy(size - item.size);
+		this.sizes.set(item.key, size);
+		this.sizeVersion++;
+		this.valid = Math.min(this.valid, index);
+		if (this.updateQueued) return;
+		this.updateQueued = true;
+		queueMicrotask(() => {
+			this.updateQueued = false;
+			this.update(true);
+		});
+	}
+	borderBoxSize(entry) {
+		const box = entry.borderBoxSize?.[0];
+		if (!box) return this.options.horizontal ? entry.contentRect.width : entry.contentRect.height;
+		return this.options.horizontal ? box.inlineSize : box.blockSize;
+	}
+	scrollBy(delta) {
+		this.offset += delta;
+		this.scrollElement?.scrollBy(this.options.horizontal ? { left: delta } : { top: delta });
+	}
+	scrollMargin() {
+		return this.options.scrollMargin?.() ?? 0;
+	}
+	readViewport() {
+		const element = this.scrollElement;
+		if (!element) return;
+		const { horizontal } = this.options;
+		if (isWindow(element)) this.viewport = horizontal ? window.innerWidth : window.innerHeight;
+		else this.viewport = horizontal ? element.clientWidth : element.clientHeight;
+	}
+	readScroll() {
+		const element = this.scrollElement;
+		if (!element) return;
+		const { horizontal } = this.options;
+		const position = isWindow(element) ? horizontal ? window.scrollX : window.scrollY : horizontal ? element.scrollLeft : element.scrollTop;
+		this.offset = position - this.scrollMargin();
+		this.update(false);
+	}
+	/** 重新算可见范围；范围变了或 force 时通知 */
+	update(force) {
+		const range = findVisibleRange(this.getMeasurements(), this.offset, this.viewport);
+		const changed = range?.startIndex !== this.range?.startIndex || range?.endIndex !== this.range?.endIndex;
+		this.range = range;
+		if (changed || force) this.options.onChange?.(this);
+	}
+};
+//#endregion
+export { Virtualizer, computeMeasurements, defaultRangeExtractor, findVisibleRange, isWindow };
+
+//# sourceMappingURL=virtualizer.js.map