diff --git a/packages/opendesign/src/virtual-list/OVirtualList.vue b/packages/opendesign/src/virtual-list/OVirtualList.vue
index 338244cec5ed3eb9423a1b3e9a480f5a6695be81..e48a9e857f1de915d848d1d8b5b2dae242816a29 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/__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 e316e9664479915a527f30013477d43419b37e77..ae05f660d62246a9738cece6e8848e91ae82e21c 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 e2beaf55ac764d00e50f6be4858bcdd9e1afe1c5..0000000000000000000000000000000000000000
--- 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 1840c3144470f16ed705a72af636fa3eff94b72d..4ba07259d0ea30539c5bdc26ce7d8b9b7e19f743 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 6c2af0d147b5c01ec6758f1d1115a9326cb7c02a..a27ea66fd4161e989ed550ff22d340c44777ea4e 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 0a9d7f94f2c4ba89d90b6a6c5608b1d57d1712ed..c84c15e86be4c480295cb7c12887573ebb44dd54 100644
--- a/packages/opendesign/src/virtual-list/types.ts
+++ b/packages/opendesign/src/virtual-list/types.ts
@@ -14,42 +14,52 @@ 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>,
     required: true,
-    default: [],
+    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>>,