x-next 1.18.1 → 1.19.0

package/AI_USAGE/components/tree-select.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # TreeSelect AI 使用
 
-适用版本：x-next@1.18.1；来源指纹：`5a7a6ac6864f5c967d7414c6cb2bf7b0470f3208f35e8ece68ed34b3b2716d83`。
+适用版本：x-next@1.19.0；来源指纹：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
 
 先读 [通用接入](../core.md)。公开导出：`TreeSelect, TreeSelectDropdown`；主要模型：v-model、v-model:input-value、v-model:popup-visible、v-model:expanded-keys。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./tree-select-api.md)，包含本组件族全部子组件和别名。
 

package/AI_USAGE/components/trend-chart-api.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # TrendChart 完整公开 API
 
-适用版本：x-next@1.18.1；来源指纹：`5a7a6ac6864f5c967d7414c6cb2bf7b0470f3208f35e8ece68ed34b3b2716d83`。
+适用版本：x-next@1.19.0；来源指纹：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
 
 从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
 

package/AI_USAGE/components/trend-chart.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # TrendChart AI 使用
 
-适用版本：x-next@1.18.1；来源指纹：`5a7a6ac6864f5c967d7414c6cb2bf7b0470f3208f35e8ece68ed34b3b2716d83`。
+适用版本：x-next@1.19.0；来源指纹：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
 
 先读 [通用接入](../core.md)。公开导出：`TrendChart`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./trend-chart-api.md)，包含本组件族全部子组件和别名。
 

package/AI_USAGE/components/trigger-api.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Trigger 完整公开 API
 
-适用版本：x-next@1.18.1；来源指纹：`5a7a6ac6864f5c967d7414c6cb2bf7b0470f3208f35e8ece68ed34b3b2716d83`。
+适用版本：x-next@1.19.0；来源指纹：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
 
 从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
 

package/AI_USAGE/components/trigger.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Trigger AI 使用
 
-适用版本：x-next@1.18.1；来源指纹：`5a7a6ac6864f5c967d7414c6cb2bf7b0470f3208f35e8ece68ed34b3b2716d83`。
+适用版本：x-next@1.19.0；来源指纹：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
 
 先读 [通用接入](../core.md)。公开导出：`Trigger`；主要模型：v-model:popup-visible。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./trigger-api.md)，包含本组件族全部子组件和别名。
 

package/AI_USAGE/components/upload-api.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Upload 完整公开 API
 
-适用版本：x-next@1.18.1；来源指纹：`5a7a6ac6864f5c967d7414c6cb2bf7b0470f3208f35e8ece68ed34b3b2716d83`。
+适用版本：x-next@1.19.0；来源指纹：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
 
 从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
 

package/AI_USAGE/components/upload.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Upload AI 使用
 
-适用版本：x-next@1.18.1；来源指纹：`5a7a6ac6864f5c967d7414c6cb2bf7b0470f3208f35e8ece68ed34b3b2716d83`。
+适用版本：x-next@1.19.0；来源指纹：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
 
 先读 [通用接入](../core.md)。公开导出：`Upload`；主要模型：v-model:file-list。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./upload-api.md)，包含本组件族全部子组件和别名。
 

package/AI_USAGE/components/virtual-list-api.md

@@ -0,0 +1,135 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# VirtualList 完整公开 API
+
+适用版本：x-next@1.19.0；来源指纹：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## VirtualList API
+
+公开声明：`dist/components/virtual-list-v2/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| height | 视口高度，数字按 px，也支持 CSS 高度 | undefined &#124; string &#124; number | 否 | 200 |
+| data | 完整对象数组 | undefined &#124; Record<string, any>[] | 否 | [] |
+| threshold | 数量小于等于阈值时完整渲染，默认 0 | undefined &#124; number | 否 | 0 |
+| itemKey | 稳定键属性，默认 key | undefined &#124; string | 否 | "key" |
+| fixedSize | 固定高度模式，默认 false | undefined &#124; false &#124; true | 否 | false |
+| estimatedSize | 固定或预估行高，默认 30 | undefined &#124; number | 否 | 30 |
+| buffer | 缓冲行数，窗口约为三倍，默认 10 | undefined &#124; number | 否 | 10 |
+| component | 见场景用法与类型 | undefined &#124; string &#124; { [x: string]: any; } | 否 | "div" |
+| listAttrs | 业务列表层属性 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+| contentAttrs | 业务内容层属性 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+| paddingPosition | 见场景用法与类型 | undefined &#124; string | 否 | "content" |
+| scrollbar | 使用统一滚动条，默认 false | undefined &#124; false &#124; true &#124; ScrollbarProps | 否 | false |
+| preserveScroll | 数据改变时保持滚动，默认 false | undefined &#124; false &#124; true | 否 | false |
+| pinnedKeys | 固定高度模式中保留挂载的稳定键；应只保留少量 | undefined &#124; VirtualItemKey[] | 否 | undefined |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| scroll | 实际滚动事件，event.target 为滚动节点 | undefined &#124; (ev: Event) => any |
+| reachBottom | 滚动触底，不自动请求 | undefined &#124; (ev: Event) => any |
+| rangeChange | 窗口 start/end，end 为开区间 | undefined &#124; (range: { start: number; end: number; }) => any |
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| scrollTo | (options: ScrollOptions) => void |
+| containerRef | any |
+| currentList | Record<string, any>[] |
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type VirtualItemKey = string | number;
+
+interface InternalDataItem {
+    key: VirtualItemKey;
+    index: number;
+    item: unknown;
+}
+
+type ItemSlot = (props: {
+    item: unknown;
+    index: number;
+}) => VNode[];
+
+interface ScrollIntoViewOptions {
+    index?: number;
+    key?: VirtualItemKey;
+    align: 'auto' | 'top' | 'bottom';
+}
+
+interface VirtualListProps {
+    /**
+     * @zh 可视区域高度
+     * @en Viewable area height
+     */
+    height?: number | string;
+    /**
+     * @zh 开启虚拟滚动的元素数量阈值，当数据数量小于阈值时不会开启虚拟滚动。
+     * @en The threshold of the number of elements to enable virtual scrolling. When the number of data is less than the threshold, virtual scrolling will not be enabled.
+     */
+    threshold?: number;
+    /**
+     * @zh （已废除）元素高度是否是固定的。2.34.1 版本废除，请使用 `fixedSize`
+     * @en (Repealed) Is the element height fixed. Version 2.18.0 deprecated, please use `fixedSize`
+     */
+    isStaticItemHeight?: boolean;
+    /**
+     * @zh 元素高度是否是固定的。
+     * @en Is the element height fixed.
+     * @version 2.34.1
+     */
+    fixedSize?: boolean;
+    /**
+     * @zh 元素高度不固定时的预估高度。
+     * @en Is the element height fixed.
+     * @version 2.34.1
+     */
+    estimatedSize?: number;
+    /**
+     * @zh 视口边界外提前挂载的元素数量。
+     * @en The number of elements mounted in advance outside the boundary of the viewport.
+     * @defaultValue 10
+     * @version 2.34.1
+     */
+    buffer?: number;
+    data?: unknown[];
+    itemKey?: string;
+    component?: keyof HTMLElementTagNameMap;
+    /** 使用库内滚动条；独立 VirtualList 默认 false，Select 会传入自己的配置。 */
+    scrollbar?: boolean | ScrollbarProps;
+    /** 数据重排/展开时保持像素位置；调用方可按稳定 key 恢复更精确的锚点。 */
+    preserveScroll?: boolean;
+    /** 仅 fixedSize 生效；传入数组启用定位行，指定键在视口外仍保持同一 DOM。 */
+    pinnedKeys?: VirtualItemKey[];
+    listAttrs?: Record<string, unknown>;
+    contentAttrs?: Record<string, unknown>;
+}
+
+type ScrollOptions = number | {
+    index?: number;
+    key?: VirtualItemKey;
+    align?: 'auto' | 'top' | 'bottom';
+};
+
+interface VirtualListRef {
+    scrollTo: (options: ScrollOptions) => void;
+}
+```
+
+
+返回 [VirtualList 用法](./virtual-list.md)。

package/AI_USAGE/components/virtual-list.md

@@ -0,0 +1,62 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# VirtualList AI 使用
+
+适用版本：x-next@1.19.0；来源指纹：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
+
+先读 [通用接入](../core.md)。公开导出：`VirtualList`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./virtual-list-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/scrollbar-v2`（包含 base.css、scrollbar-v2.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `script/ai-usage/pages/virtual-list.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./virtual-list-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与边界
+
+用于长列表的有界 DOM 渲染。`data` 为稳定键对象数组，`itemKey` 指定键属性；`#item` 提供 `item` 和完整数据的 `index`。组件不负责树层级、分页请求、权限或拖放业务。
+
+
+### 固定高度与统一滚动条
+
+`height` 为可视区高度；固定行需同时设置 `fixedSize` 与 `estimatedSize`，插槽自行保证行高。`buffer` 控制窗口，设置为至少视口行数的一半，渲染量约为其三倍。`scrollbar` 使用库内滚动条，可传 `{ disableHorizontal: true }`。
+
+```vue
+<script setup lang="ts">
+import { VirtualList } from 'x-next';
+import 'x-next/style.css';
+const rows = Array.from({ length: 10000 }, (_, index) => ({ key: `row-${index}`, title: `条目 ${index}` }));
+</script>
+<template>
+<VirtualList :data="rows" :height="320" fixed-size :estimated-size="32" :buffer="12" :scrollbar="{ disableHorizontal: true }">
+    <template #item="{ item }"><div style="height: 32px">{{ item.title }}</div></template>
+  </VirtualList>
+</template>
+```
+
+### 数据更新与拖放组合
+
+`preserveScroll` 在数据重排或展开后保留像素位置；默认 false，保持过滤列表回顶的既有行为。`pinnedKeys` 仅 fixedSize 有效，传入空数组即可启用固定位置布局；加入稳定键后，该行即使离开窗口仍保留同一个 DOM，可用于拖放源或当前键盘焦点。未传时保持原来的流式布局。
+
+`contentAttrs`／`listAttrs` 分别作用于列表内容层／列表层。可通过业务自己的 id 配合 Draggable 的公开 target；不访问库内部类名。`rangeChange` 返回窗口的 start/end（不含保留行），业务索引必须基于完整 data。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { VirtualList } from 'x-next';
+import type { VirtualListRef } from 'x-next';
+import 'x-next/style.css';
+const list = ref<VirtualListRef>();
+const rows = Array.from({ length: 2000 }, (_, index) => ({ key: `row-${index}`, title: `条目 ${index}` }));
+const pinned = ref<string[]>([]);
+</script>
+<template>
+<button @click="list?.scrollTo({ key: 'row-1500', align: 'auto' })">定位到 1500</button>
+  <VirtualList ref="list" :data="rows" :height="320" fixed-size :estimated-size="32" :buffer="12"
+    preserve-scroll :pinned-keys="pinned" :scrollbar="true" :content-attrs="{ id: 'business-items', role: 'list' }">
+    <template #item="{ item }"><div role="listitem" style="height: 32px">{{ item.title }}</div></template>
+  </VirtualList>
+</template>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./virtual-list-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/watermark-api.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Watermark 完整公开 API
 
-适用版本：x-next@1.18.1；来源指纹：`5a7a6ac6864f5c967d7414c6cb2bf7b0470f3208f35e8ece68ed34b3b2716d83`。
+适用版本：x-next@1.19.0；来源指纹：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
 
 从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
 

package/AI_USAGE/components/watermark.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Watermark AI 使用
 
-适用版本：x-next@1.18.1；来源指纹：`5a7a6ac6864f5c967d7414c6cb2bf7b0470f3208f35e8ece68ed34b3b2716d83`。
+适用版本：x-next@1.19.0；来源指纹：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
 
 先读 [通用接入](../core.md)。公开导出：`Watermark`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./watermark-api.md)，包含本组件族全部子组件和别名。
 

package/AI_USAGE/core.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # x-next AI 通用接入
 
-适用版本：x-next@1.18.1；来源指纹：`5a7a6ac6864f5c967d7414c6cb2bf7b0470f3208f35e8ece68ed34b3b2716d83`。
+适用版本：x-next@1.19.0；来源指纹：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
 
 ```sh
 npm install x-next

package/AI_USAGE/index.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # x-next AI 按需入口
 
-适用版本：x-next@1.18.1；来源指纹：`5a7a6ac6864f5c967d7414c6cb2bf7b0470f3208f35e8ece68ed34b3b2716d83`。
+适用版本：x-next@1.19.0；来源指纹：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
 
 AI 专用资料，与文档站独立分发。先读 [core.md](./core.md)，再只读本任务需要的组件页；各页含场景 SFC，完整 API 位于对应 `*-api.md`。全部公开组件与服务有本地导航，查本包用法优先包内文件，不默认网络搜索。
 
@@ -59,6 +59,7 @@ AI 专用资料，与文档站独立分发。先读 [core.md](./core.md)，再
 | Popup | [popup](./components/popup.md) | v-model:popup-visible | `x-next/style/popup` |
 | ResizeBox | [resize-box](./components/resize-box.md) | v-model:width、v-model:height | `x-next/style/resize-box` |
 | Scrollbar | [scrollbar](./components/scrollbar.md) | 无 | `x-next/style/scrollbar-v2` |
+| VirtualList | [virtual-list](./components/virtual-list.md) | 无 | `x-next/style/scrollbar-v2` |
 | Skeleton | [skeleton](./components/skeleton.md) | 无 | `x-next/style/skeleton` |
 | Space | [space](./components/space.md) | 无 | `x-next/style/space` |
 | Spin | [spin](./components/spin.md) | 无 | `x-next/style/spin` |
@@ -76,7 +77,7 @@ AI 专用资料，与文档站独立分发。先读 [core.md](./core.md)，再
 - [按需表单完整 SFC](./recipes/form-on-demand.md)：Input + Textarea + Select + Checkbox + ConfigProvider。
 - 编辑弹窗：读 Dialog、Form、Input、Select；列表查 Table，子组件和服务查 [公开导航](./catalog.md)。
 - [图表选型](./components/charts.md)、[Boxicons](./components/boxicons.md)、[Finicon](./components/finicon.md)。
-- [公开组件/服务导航](./catalog.md)：59 个组件族、106 个公共导出，含本地 API 和声明。
+- [公开组件/服务导航](./catalog.md)：60 个组件族、107 个公共导出，含本地 API 和声明。
 - [完整兼容手册](../AI_USAGE.md)：新任务不默认读取全文。
 
 本地资料仍须配合严格类型、构建与真实浏览器验证；若查到缺口，反馈当前安装版本和具体 API，不套用其他库用法。

package/AI_USAGE/recipes/form-on-demand.md

@@ -1,7 +1,7 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # 按需样式与表单接入
 
-适用版本：x-next@1.18.1；来源指纹：`5a7a6ac6864f5c967d7414c6cb2bf7b0470f3208f35e8ece68ed34b3b2716d83`。
+适用版本：x-next@1.19.0；来源指纹：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
 
 先读 [通用接入](../core.md)，相关组件规则：[config-provider](../components/config-provider.md)、[input](../components/input.md)、[textarea](../components/textarea.md)、[select](../components/select.md)、[checkbox](../components/checkbox.md)。
 

package/AI_USAGE.md

@@ -1,11 +1,11 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # x-next AI 使用手册
 
-适用版本：**x-next@1.18.1**。Vue：`^3.5.0`；Node：`>=20.19.0`。
+适用版本：**x-next@1.19.0**。Vue：`^3.5.0`；Node：`>=20.19.0`。
 
-来源指纹（AI 行为说明、docs 导入快照、映射、样式依赖、版本、公开类型和 API 参考）：`5a7a6ac6864f5c967d7414c6cb2bf7b0470f3208f35e8ece68ed34b3b2716d83`。
+来源指纹（AI 行为说明、docs 导入快照、映射、样式依赖、版本、公开类型和 API 参考）：`e5b7042cefff2ec3b2745b9e108e701ef2b629f5e959a26f03c1d74515160caa`。
 
-覆盖 59 个组件族与 106 个公开组件/服务导出。优先通过 [本地按需索引](./AI_USAGE/index.md) 读取组件页和 API，不为查本包用法默认搜索网络。
+覆盖 60 个组件族与 107 个公开组件/服务导出。优先通过 [本地按需索引](./AI_USAGE/index.md) 读取组件页和 API，不为查本包用法默认搜索网络。
 
 读取入口：`node_modules/x-next/AI_USAGE.md`；可用 `require.resolve('x-next/AI_USAGE.md')` 定位。消费项目应在自己的指令中明确引用。
 
@@ -63,6 +63,7 @@
 | Popup | `Popup` | `<x-popup>` | `v-model:popup-visible` | `x-next/style/popup` | `popover.css`, `trigger.css` | [组件文档](https://x-next.yjmf.com/components/popup) |
 | ResizeBox | `ResizeBox` | `<x-resize-box>` | `v-model:width`, `v-model:height` | `x-next/style/resize-box` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/resize-box) |
 | Scrollbar | `Scrollbar` | `<x-scrollbar>` | 无 | `x-next/style/scrollbar-v2` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/scrollbar) |
+| VirtualList | `VirtualList` | `<x-virtual-list>` | 无 | `x-next/style/scrollbar-v2` | 无独立依赖 | [组件文档](./AI_USAGE/components/virtual-list.md) |
 | Skeleton | `Skeleton`, `SkeletonLine`, `SkeletonShape` | `<x-skeleton>` | 无 | `x-next/style/skeleton` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/skeleton) |
 | Space | `Space` | `<x-space>` | 无 | `x-next/style/space` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/space) |
 | Spin | `Spin` | `<x-spin>` | 无 | `x-next/style/spin` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/spin) |
@@ -15860,6 +15861,55 @@ import { Scrollbar } from 'x-next';
 </template>
 ```
 
+## VirtualList 扩展场景
+
+### 用途与边界
+
+用于长列表的有界 DOM 渲染。`data` 为稳定键对象数组，`itemKey` 指定键属性；`#item` 提供 `item` 和完整数据的 `index`。组件不负责树层级、分页请求、权限或拖放业务。
+
+
+### 固定高度与统一滚动条
+
+`height` 为可视区高度；固定行需同时设置 `fixedSize` 与 `estimatedSize`，插槽自行保证行高。`buffer` 控制窗口，设置为至少视口行数的一半，渲染量约为其三倍。`scrollbar` 使用库内滚动条，可传 `{ disableHorizontal: true }`。
+
+```vue
+<script setup lang="ts">
+import { VirtualList } from 'x-next';
+import 'x-next/style.css';
+const rows = Array.from({ length: 10000 }, (_, index) => ({ key: `row-${index}`, title: `条目 ${index}` }));
+</script>
+<template>
+<VirtualList :data="rows" :height="320" fixed-size :estimated-size="32" :buffer="12" :scrollbar="{ disableHorizontal: true }">
+    <template #item="{ item }"><div style="height: 32px">{{ item.title }}</div></template>
+  </VirtualList>
+</template>
+```
+
+### 数据更新与拖放组合
+
+`preserveScroll` 在数据重排或展开后保留像素位置；默认 false，保持过滤列表回顶的既有行为。`pinnedKeys` 仅 fixedSize 有效，传入空数组即可启用固定位置布局；加入稳定键后，该行即使离开窗口仍保留同一个 DOM，可用于拖放源或当前键盘焦点。未传时保持原来的流式布局。
+
+`contentAttrs`／`listAttrs` 分别作用于列表内容层／列表层。可通过业务自己的 id 配合 Draggable 的公开 target；不访问库内部类名。`rangeChange` 返回窗口的 start/end（不含保留行），业务索引必须基于完整 data。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { VirtualList } from 'x-next';
+import type { VirtualListRef } from 'x-next';
+import 'x-next/style.css';
+const list = ref<VirtualListRef>();
+const rows = Array.from({ length: 2000 }, (_, index) => ({ key: `row-${index}`, title: `条目 ${index}` }));
+const pinned = ref<string[]>([]);
+</script>
+<template>
+<button @click="list?.scrollTo({ key: 'row-1500', align: 'auto' })">定位到 1500</button>
+  <VirtualList ref="list" :data="rows" :height="320" fixed-size :estimated-size="32" :buffer="12"
+    preserve-scroll :pinned-keys="pinned" :scrollbar="true" :content-attrs="{ id: 'business-items', role: 'list' }">
+    <template #item="{ item }"><div role="listitem" style="height: 32px">{{ item.title }}</div></template>
+  </VirtualList>
+</template>
+```
+
 ## Skeleton 扩展场景
 
 ### 用途与选型
@@ -36526,6 +36576,133 @@ interface UploadShowUploadButton {
 ```
 
 
+## VirtualList API
+
+公开声明：`dist/components/virtual-list-v2/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| height | 视口高度，数字按 px，也支持 CSS 高度 | undefined &#124; string &#124; number | 否 | 200 |
+| data | 完整对象数组 | undefined &#124; Record<string, any>[] | 否 | [] |
+| threshold | 数量小于等于阈值时完整渲染，默认 0 | undefined &#124; number | 否 | 0 |
+| itemKey | 稳定键属性，默认 key | undefined &#124; string | 否 | "key" |
+| fixedSize | 固定高度模式，默认 false | undefined &#124; false &#124; true | 否 | false |
+| estimatedSize | 固定或预估行高，默认 30 | undefined &#124; number | 否 | 30 |
+| buffer | 缓冲行数，窗口约为三倍，默认 10 | undefined &#124; number | 否 | 10 |
+| component | 见场景用法与类型 | undefined &#124; string &#124; { [x: string]: any; } | 否 | "div" |
+| listAttrs | 业务列表层属性 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+| contentAttrs | 业务内容层属性 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+| paddingPosition | 见场景用法与类型 | undefined &#124; string | 否 | "content" |
+| scrollbar | 使用统一滚动条，默认 false | undefined &#124; false &#124; true &#124; ScrollbarProps | 否 | false |
+| preserveScroll | 数据改变时保持滚动，默认 false | undefined &#124; false &#124; true | 否 | false |
+| pinnedKeys | 固定高度模式中保留挂载的稳定键；应只保留少量 | undefined &#124; VirtualItemKey[] | 否 | undefined |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| scroll | 实际滚动事件，event.target 为滚动节点 | undefined &#124; (ev: Event) => any |
+| reachBottom | 滚动触底，不自动请求 | undefined &#124; (ev: Event) => any |
+| rangeChange | 窗口 start/end，end 为开区间 | undefined &#124; (range: { start: number; end: number; }) => any |
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| scrollTo | (options: ScrollOptions) => void |
+| containerRef | any |
+| currentList | Record<string, any>[] |
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type VirtualItemKey = string | number;
+
+interface InternalDataItem {
+    key: VirtualItemKey;
+    index: number;
+    item: unknown;
+}
+
+type ItemSlot = (props: {
+    item: unknown;
+    index: number;
+}) => VNode[];
+
+interface ScrollIntoViewOptions {
+    index?: number;
+    key?: VirtualItemKey;
+    align: 'auto' | 'top' | 'bottom';
+}
+
+interface VirtualListProps {
+    /**
+     * @zh 可视区域高度
+     * @en Viewable area height
+     */
+    height?: number | string;
+    /**
+     * @zh 开启虚拟滚动的元素数量阈值，当数据数量小于阈值时不会开启虚拟滚动。
+     * @en The threshold of the number of elements to enable virtual scrolling. When the number of data is less than the threshold, virtual scrolling will not be enabled.
+     */
+    threshold?: number;
+    /**
+     * @zh （已废除）元素高度是否是固定的。2.34.1 版本废除，请使用 `fixedSize`
+     * @en (Repealed) Is the element height fixed. Version 2.18.0 deprecated, please use `fixedSize`
+     */
+    isStaticItemHeight?: boolean;
+    /**
+     * @zh 元素高度是否是固定的。
+     * @en Is the element height fixed.
+     * @version 2.34.1
+     */
+    fixedSize?: boolean;
+    /**
+     * @zh 元素高度不固定时的预估高度。
+     * @en Is the element height fixed.
+     * @version 2.34.1
+     */
+    estimatedSize?: number;
+    /**
+     * @zh 视口边界外提前挂载的元素数量。
+     * @en The number of elements mounted in advance outside the boundary of the viewport.
+     * @defaultValue 10
+     * @version 2.34.1
+     */
+    buffer?: number;
+    data?: unknown[];
+    itemKey?: string;
+    component?: keyof HTMLElementTagNameMap;
+    /** 使用库内滚动条；独立 VirtualList 默认 false，Select 会传入自己的配置。 */
+    scrollbar?: boolean | ScrollbarProps;
+    /** 数据重排/展开时保持像素位置；调用方可按稳定 key 恢复更精确的锚点。 */
+    preserveScroll?: boolean;
+    /** 仅 fixedSize 生效；传入数组启用定位行，指定键在视口外仍保持同一 DOM。 */
+    pinnedKeys?: VirtualItemKey[];
+    listAttrs?: Record<string, unknown>;
+    contentAttrs?: Record<string, unknown>;
+}
+
+type ScrollOptions = number | {
+    index?: number;
+    key?: VirtualItemKey;
+    align?: 'auto' | 'top' | 'bottom';
+};
+
+interface VirtualListRef {
+    scrollTo: (options: ScrollOptions) => void;
+}
+```
+
+
 ## Watermark API
 
 公开声明：`dist/components/watermark/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。

package/CHANGELOG.md

@@ -4,6 +4,35 @@
 
 ## [Unreleased]
 
+## [1.19.0] - 2026-10-23
+
+### 新增
+
+- 公开 VirtualList 组件、全局注册和相关类型，支持通过根入口导入，补齐 Volar 与独立 AI 使用说明。
+- VirtualList 新增 `preserveScroll`、固定高度 `pinnedKeys` 保留行和 `rangeChange`，支持数据重排保持滚动、拖动源离开窗口仍保留 DOM，以及按索引或键定位。
+
+### 修复
+
+- ResizeBox 受控鼠标拖动与键盘使用一致的尺寸起点，避免重复扣除手柄占位；禁用方向时移除残留占位，鼠标抓杆后可继续使用键盘。
+- VirtualList 缺失键定位保持原滚动位置，补齐 `scrollTo` 的底部和自动可见对齐，保留 Table 依赖的实例集成能力。
+
+### 维护
+
+- AI 文档导入支持独立 AI 源页面，同步生成手册、按需索引与完整 API；继续按现有只读 CI 和预打包策略追踪生成结果。
+- 更新 Vite 和 Vitest 同主版本安全补丁，移除开发工具链的已知可修复漏洞。
+
+## [1.18.2] - 2026-10-17
+
+### 文档
+
+- 重新组织 README，加入品牌 Logo、产品口号、版本徽章与文档导航，突出产品定位与核心能力。
+- 将组件长清单整理为分类导航，移除可选图标集的单独介绍，精简接入与维护细节。
+- 更新按需样式、完整引入和局部主题示例，保留 AI 辅助开发与贡献入口。
+
+### 维护
+
+- 依据 npmjs 已发布的 1.18.1 产物校准主入口体积预算，运行产物保持一致，保留组件预算和图标泄漏检查。
+
 ## [1.18.1] - 2026-10-15
 
 ### 修复