From a4f31e56dbb504ed850f1a311f34f712a2fc44f9 Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Tue, 28 Oct 2025 11:27:36 +0800
Subject: [PATCH 1/2] =?UTF-8?q?fix(virtual-list):=20=E8=A7=A3=E5=86=B3ts?=
 =?UTF-8?q?=E5=8F=8Aeslint=E6=8A=A5=E9=94=99?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/virtual-list/OVirtualList.vue         | 44 +++++++++----------
 packages/opendesign/src/virtual-list/types.ts |  2 +-
 2 files changed, 22 insertions(+), 24 deletions(-)

diff --git a/packages/opendesign/src/virtual-list/OVirtualList.vue b/packages/opendesign/src/virtual-list/OVirtualList.vue
index 338244cec..e48a9e857 100644
--- a/packages/opendesign/src/virtual-list/OVirtualList.vue
+++ b/packages/opendesign/src/virtual-list/OVirtualList.vue
@@ -1,13 +1,12 @@
 <script lang="ts" setup>
 import { ref, computed, onMounted, watch, nextTick } from 'vue';
-import { vScrollbar } from '../scrollbar';
+import { vScrollbar, type BaseScrollerPropsT } from '../scrollbar';
 import { virtualListProps, RenderIndexInfo } from './types';
 import { isUndefined } from '../_utils/is';
 import { vOnResize } from '../directives/on-resize';
 import { debounceRAF } from '../_utils/helper';
 
 const props = defineProps(virtualListProps);
-
 const emits = defineEmits<{
   (e: 'renderChange', renderIndex: RenderIndexInfo): void;
 }>();
@@ -19,7 +18,7 @@ const scrollbarProps = computed(() => {
     return {
       showType: 'always',
       size: 'medium',
-    };
+    } as Partial<BaseScrollerPropsT>;
   }
   return props.scrollbar;
 });
@@ -88,6 +87,24 @@ const renderList = computed(() => {
   return listData.value.slice(startIndex.value, endIndex.value + 1);
 });
 
+interface ItemMeta {
+  id: string | number;
+  index: number;
+  top: number;
+  bottom: number;
+  size: number;
+  measured: boolean;
+  isScrolling: boolean;
+}
+const wrapperRef = ref<HTMLElement>();
+// 虚拟列表偏移量，用于虚拟滚动
+const offset = ref(0);
+/**
+ * 初始化滚动位置
+ */
+let initialScroll = props.itemSize ? true : false;
+let listMetaData: Array<ItemMeta> = [];
+
 watch(listData, (value) => {
   if (!isUndefined(visibleStartId) && wrapperRef.value) {
     // 计算滚动偏移量
@@ -102,8 +119,6 @@ watch(listData, (value) => {
   }
 });
 
-const wrapperRef = ref<HTMLElement>();
-
 // 列表虚拟总高度，先给定初始值
 const contentSize = ref((props.itemSize ? props.itemSize : props.defaultItemSize) * listData.value.length);
 
@@ -160,19 +175,12 @@ const contentStyle = computed(() => ({
   '--content-height': `${contentSize.value}px`,
 }));
 
-// 虚拟列表偏移量，用于虚拟滚动
-const offset = ref(0);
 const renderListStyle = computed(() => {
   return {
     '--offsetY': `${offset.value}px`,
   };
 });
 
-/**
- * 初始化滚动位置
- */
-let initialScroll = props.itemSize ? true : false;
-
 /**
  * 将指定项滚动到视口内，不定高场景下，可能存在滚动不准确
  * @param index 指定项
@@ -222,17 +230,6 @@ const scrollToView = (index: number, align: 'start' | 'end' | 'center' | 'neares
   });
 };
 
-interface ItemMeta {
-  id: string | number;
-  index: number;
-  top: number;
-  bottom: number;
-  size: number;
-  measured: boolean;
-  isScrolling: boolean;
-}
-
-let listMetaData: Array<ItemMeta> = [];
 // 列表数据变换时，重新计算尺寸数据
 watch(
   [() => props.itemSize, () => listData.value],
@@ -401,6 +398,7 @@ onMounted(() => {
 });
 
 defineExpose({
+  /** expose: scroll into view */
   scrollToView,
 });
 </script>
diff --git a/packages/opendesign/src/virtual-list/types.ts b/packages/opendesign/src/virtual-list/types.ts
index 0a9d7f94f..d18329846 100644
--- a/packages/opendesign/src/virtual-list/types.ts
+++ b/packages/opendesign/src/virtual-list/types.ts
@@ -26,7 +26,7 @@ export const virtualListProps = {
   list: {
     type: Array<any>,
     required: true,
-    default: [],
+    default: () => [],
   },
   /**
    * 每一项的高度，如果每一项高度不一致或不确定（渲染时确定），则不传
-- 
Gitee


From c2c6887058e69e4d16f80fcb6e86f060193e9545 Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Tue, 28 Oct 2025 11:45:10 +0800
Subject: [PATCH 2/2] =?UTF-8?q?doc(virtual-list):=20=E5=AE=8C=E5=96=84?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...rtualListUsage.ts => VirtualListUsage.vue} | 109 ++++++++++++------
 .../virtual-list/__docs__/__case__/style.scss |  39 -------
 .../src/virtual-list/__docs__/index.en-US.md  |   9 +-
 .../src/virtual-list/__docs__/index.zh-CN.md  |   7 +-
 packages/opendesign/src/virtual-list/types.ts |  22 +++-
 5 files changed, 93 insertions(+), 93 deletions(-)
 rename packages/opendesign/src/virtual-list/__docs__/__case__/{virtualListUsage.ts => VirtualListUsage.vue} (33%)
 delete mode 100644 packages/opendesign/src/virtual-list/__docs__/__case__/style.scss

diff --git a/packages/opendesign/src/virtual-list/__docs__/__case__/virtualListUsage.ts b/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListUsage.vue
similarity index 33%
rename from packages/opendesign/src/virtual-list/__docs__/__case__/virtualListUsage.ts
rename to packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListUsage.vue
index e316e9664..ae05f660d 100644
--- a/packages/opendesign/src/virtual-list/__docs__/__case__/virtualListUsage.ts
+++ b/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListUsage.vue
@@ -1,51 +1,86 @@
-import { propsToAttrStr } from '../../../_demo/utils';
-import './style.scss';
-
-// 该导出会作为该使用示例的文案，文案是markdown格式
-export const docs = {
-  'zh-CN':
-    '虚拟滚动用于控制列表中渲染项目的数量以达到优化渲染性能的目的。可设置项包含：  \n' +
-    '- 列表数据`list`  \n' +
-    '- 默认滚动到第几项`defaultStartIndex`  \n' +
-    '- 每一项高度`itemSize`  \n' +
-    '- 不定高时每一项的默认高度`defaultItemSize`  \n' +
-    '- 前后预留空白`buffer`  \n' +
-    '- scrollbar行为`scrollbar`等',
-  'en-US':
-    'Virtual scrolling is used to control the number of rendered items in a list to optimize rendering performance.Configurable options include:  \n' +
-    '- list: the list data to render  \n' +
-    '- defaultStartIndex: sets the default initial scroll position item  \n' +
-    '- itemSize: defines the height of each item  \n' +
-    '- defaultItemSize: specifies the default item height for variable-height items  \n' +
-    '- buffer: sets front/render buffer padding  \n' +
-    '- scrollbar: controls scrollbar behavior',
-};
+<docs lang="md">
+<!-- zh-CN -->
 
-export const ctx = {
-  list: new Array(100).fill(0).map((_, i) => ({ label: i + 1 }))
-};
+### 使用
 
-export const template = (_props: Record<string, any>) => {
-  return `<OVirtualList class="virtual-list-demo container" ${propsToAttrStr(_props)} :list="ctx.list">
-  <template  #default="{ item, index }">
-    <div :key="item.label" class="section" :class="\`item-\${index + 1}\`">
-      <span>Row:</span> <span>{{ item.label }}</span>------<span>Height:</span> <span>80px</span>
-    </div>
-  </template>
-</OVirtualList>`;
+<!-- en-US -->
+
+### Usage
+</docs>
+<script setup lang="ts">
+import { propsToAttrStr } from '../../../_demo/utils';
+import { DocDemoSchema, DocDemoTemplate } from '../../../_demo/types';
+
+const _ctx = {
+  list: new Array(100).fill(0).map((_, i) => ({ label: i + 1 })),
 };
 
-export const schema = {
+const _schema = {
   defaultStartIndex: {
     type: 'number',
-    default: 10
+    default: 10,
   },
   itemSize: {
     type: 'number',
-    default: 80
+    default: 80,
   },
   buffer: {
     type: 'number',
     default: 1,
   },
-};
\ No newline at end of file
+} satisfies Record<string, DocDemoSchema>;
+
+const _template: DocDemoTemplate<typeof _schema> = (_props) => {
+  return `<OVirtualList class="virtual-list-demo container" ${propsToAttrStr(_props)} :list="ctx.list">
+  <template  #default="{ item, index }">
+    <div :key="item.label" class="section" :class="\`item-\${index % 3}\`">
+      <span>Row:</span> <span>{{ item.label }}</span>------<span>Height:</span> <span>80px</span>
+    </div>
+  </template>
+</OVirtualList>`;
+};
+</script>
+<style lang="scss">
+.virtual-list-demo {
+  &.scrollbar-wrapper {
+    position: relative;
+  }
+  &.container {
+    width: 100%;
+    height: 300px;
+    border: 2px solid rgb(111, 45, 234);
+    box-sizing: border-box;
+    display: flex;
+  }
+  .col {
+    flex: 1;
+  }
+
+  .item-0 {
+    background-color: #9c27b0;
+    color: white;
+  }
+  .item-1 {
+    background-color: #ff9800;
+  }
+  .item-2 {
+    background-color: #4caf50;
+  }
+
+  section > div {
+    flex: 0 1 30%;
+  }
+  .section {
+    height: 60px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    margin: 10px 0;
+  }
+
+  .container2 {
+    width: 100%;
+    border: 2px solid rgb(111, 45, 234);
+  }
+}
+</style>
diff --git a/packages/opendesign/src/virtual-list/__docs__/__case__/style.scss b/packages/opendesign/src/virtual-list/__docs__/__case__/style.scss
deleted file mode 100644
index e2beaf55a..000000000
--- a/packages/opendesign/src/virtual-list/__docs__/__case__/style.scss
+++ /dev/null
@@ -1,39 +0,0 @@
-@use "sass:math";
-
-.virtual-list-demo {
-  &.scrollbar-wrapper {
-    position: relative;
-  }
-  &.container {
-    width: 100%;
-    height: 300px;
-    border: 2px solid rgb(111, 45, 234);
-    box-sizing: border-box;
-    display: flex;
-  }
-  .col {
-    flex: 1;
-  }
-
-  section > div {
-    flex: 0 1 30%;
-  }
-  .section {
-    height: 60px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    margin: 10px 0;
-  }
-
-  @for $i from 1 through 100 {
-    .item-#{$i} {
-      background-color: rgba(math.random(255), math.random(255), math.random(255), 1);
-    }
-  }
-
-  .container2 {
-    width: 100%;
-    border: 2px solid rgb(111, 45, 234);
-  }
-}
\ No newline at end of file
diff --git a/packages/opendesign/src/virtual-list/__docs__/index.en-US.md b/packages/opendesign/src/virtual-list/__docs__/index.en-US.md
index 1840c3144..4ba07259d 100644
--- a/packages/opendesign/src/virtual-list/__docs__/index.en-US.md
+++ b/packages/opendesign/src/virtual-list/__docs__/index.en-US.md
@@ -5,16 +5,13 @@ kind: container
 
 # virtual list
 
-## Usage
-
-<!-- @usage virtualUsage -->
-
-## Cases
+## Demo
 
+<!-- @usage VirtualListUsage -->
 <!-- @case VirtualListAPI -->
 <!-- @case VirtualListBasic -->
 <!-- @case VirtualListDynamic -->
 
 ## Api
 
-<!-- @api OVirtualList -->
\ No newline at end of file
+<!-- @api OVirtualList -->
diff --git a/packages/opendesign/src/virtual-list/__docs__/index.zh-CN.md b/packages/opendesign/src/virtual-list/__docs__/index.zh-CN.md
index 6c2af0d14..a27ea66fd 100644
--- a/packages/opendesign/src/virtual-list/__docs__/index.zh-CN.md
+++ b/packages/opendesign/src/virtual-list/__docs__/index.zh-CN.md
@@ -5,16 +5,13 @@ kind: container
 
 # 虚拟滚动
 
-## 使用
-
-<!-- @usage virtualListUsage -->
-
 ## 示例
 
+<!-- @usage VirtualListUsage -->
 <!-- @case VirtualListAPI -->
 <!-- @case VirtualListBasic -->
 <!-- @case VirtualListDynamic -->
 
 ## Api
 
-<!-- @api OVirtualList -->
\ No newline at end of file
+<!-- @api OVirtualList -->
diff --git a/packages/opendesign/src/virtual-list/types.ts b/packages/opendesign/src/virtual-list/types.ts
index d18329846..c84c15e86 100644
--- a/packages/opendesign/src/virtual-list/types.ts
+++ b/packages/opendesign/src/virtual-list/types.ts
@@ -14,14 +14,17 @@ export interface RenderIndexInfo {
 
 export const virtualListProps = {
   /**
-   * 默认滚动到第几项
+   * @zh-CN 默认滚动到第几项
+   * @en-US Default scroll index
+   * @default 0
    */
   defaultStartIndex: {
     type: Number,
     default: 0,
   },
   /**
-   * 列表数据，如果数据存在动态追加，需要每一项需包含唯一ID
+   * @zh-CN 列表数据，如果数据存在动态追加，需要每一项需包含唯一ID
+   * @en-US List data, if dynamic addition exists, each item must contain a unique ID
    */
   list: {
     type: Array<any>,
@@ -29,27 +32,34 @@ export const virtualListProps = {
     default: () => [],
   },
   /**
-   * 每一项的高度，如果每一项高度不一致或不确定（渲染时确定），则不传
+   * @zh-CN 每一项的高度，如果每一项高度不一致或不确定（渲染时确定），则不传
+   * @en-US The height of each item, if the height of each item is inconsistent or undetermined (determined at render time), do not pass
    */
   itemSize: {
     type: Number,
   },
   /**
-   * 不定高时，每一项的默认高度
+   * @zh-CN 不定高时，每一项的默认高度
+   * @en-US If the height of each item is not consistent, the default height of each item
+   * @default 80
    */
   defaultItemSize: {
     type: Number,
     default: 80,
   },
   /**
-   * 前后预留项，减少滚动式空白
+   * @zh-CN 前后预留项，减少滚动式空白
+   * @en-US Front and back reserved items, reducing scrolling blank
+   * @default 1
    */
   buffer: {
     type: Number,
     default: 1,
   },
   /**
-   * 使用内置scrollbar，支持传递scrollbar配置项
+   * @zh-CN scrollbar配置项
+   * @en-US scrollbar configuration item
+   * @default true
    */
   scrollbar: {
     type: [Boolean, Object] as PropType<boolean | Partial<BaseScrollerPropsT>>,
-- 
Gitee