From 973b58b956a5d613bd03293a9e6dc77660d1a8f8 Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Wed, 16 Jul 2025 14:25:53 +0800
Subject: [PATCH 01/17] =?UTF-8?q?fix:=20=E4=BC=98=E5=8C=96propsToAttrStr?=
 =?UTF-8?q?=E5=87=BD=E6=95=B0=EF=BC=8C=E6=A3=80=E6=9F=A5tag=E5=B1=9E?=
 =?UTF-8?q?=E6=80=A7=E5=90=8D=E6=98=AF=E5=90=A6=E5=90=88=E6=B3=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/opendesign/src/_demo/utils.ts | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/packages/opendesign/src/_demo/utils.ts b/packages/opendesign/src/_demo/utils.ts
index 9be19c80..a705eb0b 100644
--- a/packages/opendesign/src/_demo/utils.ts
+++ b/packages/opendesign/src/_demo/utils.ts
@@ -1,3 +1,5 @@
+const canLog = process.env.NODE_ENV === 'development';
+const validTagAttrName = (name: string) => /^[a-zA-Z0-9_\-]+$/.test(name);
 /**
  * 将组件的props转为属性字符串以便拼接到html标签中
  * 仅在__docs__/__case__/ 中使用
@@ -11,6 +13,12 @@ export function propsToAttrStr(props: Record<string, any>, exclude = [] as strin
       if (exclude.includes(key)) {
         return acc;
       }
+      if (!validTagAttrName(key)) {
+        if (canLog) {
+          console.warn(`Invalid tag attr name: ${name}`);
+        }
+        return acc;
+      }
       switch (typeof value) {
         case 'boolean':
           if (value) {
-- 
Gitee


From 79bed54e0b5cc7fca45fe3255a9a863e7bc6aaca Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Wed, 16 Jul 2025 14:36:30 +0800
Subject: [PATCH 02/17] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9Eanchor=E7=BB=84?=
 =?UTF-8?q?=E4=BB=B6=E6=96=87=E6=A1=A3=EF=BC=8C=E4=BC=98=E5=8C=96button?=
 =?UTF-8?q?=E7=BB=84=E4=BB=B6=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../anchor/__docs__/__case__/AnchorSlot.vue   |  33 +++++
 .../anchor/__docs__/__case__/AnchorUsage.vue  | 113 ++++++++++++++++++
 .../src/anchor/__docs__/index.en-US.md        |  10 ++
 .../src/anchor/__docs__/index.zh-CN.md        |  10 ++
 packages/opendesign/src/anchor/types.ts       |  38 +++++-
 .../button/__docs__/__case__/BtnIconSize.vue  |  28 ++---
 .../button/__docs__/__case__/BtnLoading.vue   |  11 +-
 .../src/button/__docs__/__case__/BtnRound.vue |  10 --
 .../src/button/__docs__/__case__/btnUsage.ts  |   8 +-
 .../src/button/__docs__/index.en-US.md        |   2 +-
 packages/opendesign/src/button/types.ts       |  32 +++--
 11 files changed, 239 insertions(+), 56 deletions(-)
 create mode 100644 packages/opendesign/src/anchor/__docs__/__case__/AnchorSlot.vue
 create mode 100644 packages/opendesign/src/anchor/__docs__/__case__/AnchorUsage.vue
 create mode 100644 packages/opendesign/src/anchor/__docs__/index.en-US.md
 create mode 100644 packages/opendesign/src/anchor/__docs__/index.zh-CN.md

diff --git a/packages/opendesign/src/anchor/__docs__/__case__/AnchorSlot.vue b/packages/opendesign/src/anchor/__docs__/__case__/AnchorSlot.vue
new file mode 100644
index 00000000..9fe8e27f
--- /dev/null
+++ b/packages/opendesign/src/anchor/__docs__/__case__/AnchorSlot.vue
@@ -0,0 +1,33 @@
+<docs lang="md">
+<!-- zh-CN -->
+
+### 自定义标题
+
+使用 `title` 插槽自定义标题内容
+
+<!-- en-US -->
+
+### Custom Title
+
+Use the `title` slot to customize the title content
+</docs>
+<script setup lang="ts">
+import { OAnchor, OAnchorItem, OIconLink } from '@opensig/opendesign';
+</script>
+<template>
+  <OAnchor container="#wrap">
+    <OAnchorItem href="#container-block1">
+      <template #title><span class="anchor-title">container-block1<OIconLink /></span></template>
+    </OAnchorItem>
+  </OAnchor>
+</template>
+<style lang="scss" scoped>
+.anchor-title {
+  display: flex;
+  align-items: center;
+  svg {
+    margin-left: 4px;
+    font-size: var(--o-icon_size-xs);
+  }
+}
+</style>
\ No newline at end of file
diff --git a/packages/opendesign/src/anchor/__docs__/__case__/AnchorUsage.vue b/packages/opendesign/src/anchor/__docs__/__case__/AnchorUsage.vue
new file mode 100644
index 00000000..b6ee355c
--- /dev/null
+++ b/packages/opendesign/src/anchor/__docs__/__case__/AnchorUsage.vue
@@ -0,0 +1,113 @@
+<docs lang="md">
+<!-- zh-CN -->
+
+### 使用
+
+1. `container` 属性
+
+   - 说明：指定锚点监听的滚动容器（默认值：window）
+   - 用法：组件会在该容器上监听 `scroll` 事件，以判断当前激活的锚点
+   - 示例：`container="#wrap"` 表示监听 id 为 wrap 的容器滚动事件
+
+2. `targetOffset` 属性
+
+   - 说明：目标元素跳转或激活时距离容器顶部的偏移量（默认值：0）
+   - 示例：`:target-offset="10"` 表示点击锚点时目标元素会滚动到距离容器顶部 10px 的位置；滚动距离小于 10px 时锚点处于激活状态
+
+3. `bounds` 属性
+
+   - 说明：设置锚点激活的判定边界（默认值：5）
+   - 用法：当需要跳转位置和激活判定边界不一致时可设置
+   - 示例：`:bounds="100" :target-offset="10"` 表示目标元素滚动到距离容器顶部 110px 时锚点激活。可实现点击锚点时目标元素滚动到顶部，滚动浏览时需到容器中上部才激活锚点的交互效果
+
+4. `changeHash` 属性
+   - 说明：是否在点击锚点时改变浏览器地址栏的 hash 值（默认值：true）
+   - 用法：如果需要手动控制 URL 跳转，可以设置为 false，并在 `click` 事件中处理跳转逻辑
+   - 示例：`:change-hash="false"` 表示点击锚点时不会改变浏览器地址栏的 hash 值
+
+5. 锚点嵌套：`OAnchorItem` 可以嵌套使用，形成多级锚点结构
+
+<!-- en-US -->
+
+### Usage
+
+1. `container` property
+
+   - Description: Specifies the scroll container to be monitored by the anchor (default: window)
+   - Usage: The component listens for the `scroll` event on this container to determine the currently active anchor
+   - Example: `container="#wrap"` means listening to the scroll event of the container with id "wrap"
+
+2. `targetOffset` property
+
+   - Description: The offset from the top of the container when the target element is scrolled or activated (default: 0)
+   - Example: `:target-offset="10"` means when clicking the anchor, the target element will scroll to 10px from the top of the container; when the scroll distance is less than 10px, the anchor is considered active
+
+3. `bounds` property
+
+   - Description: Sets the boundary for anchor activation (default: 5)
+   - Usage: Use when the scroll position and activation boundary need to be different
+   - Example: `:bounds="100" :target-offset="10"` means the anchor is activated when the target element is 110px from the top of the container. This allows the target element to scroll to the top when clicking the anchor, but requires scrolling further down to activate
+
+4. `changeHash` property
+   - Description: Whether to change the browser's address bar hash value when clicking the anchor (default: true)
+   - Usage: If you need to manually control URL navigation, set this to false and handle the navigation logic in the `click` event
+   - Example: `:change-hash="false"` means clicking the anchor will not change the hash value in the browser's address bar
+
+5. Nested anchors: `OAnchorItem` can be nested to create multi-level anchor structures
+</docs>
+
+<script setup lang="ts">
+import { OAnchor, OAnchorItem } from '@opensig/opendesign';
+import { useRouter } from 'vue-router';
+const router = useRouter();
+const handleAnchorClick = (_: Event, link?: string) => {
+  // control URL manually
+  if (link) {
+    router.push(link);
+  }
+};
+</script>
+
+<template>
+  <div class="row">
+    <div id="wrap" class="demo-wrap">
+      <div id="container-block1" class="block">container-block1</div>
+      <div id="container-block2" class="block">container-block2</div>
+      <div id="container-block2-1" class="block">container-block2-1</div>
+      <div id="container-block4" class="block">container-block4</div>
+    </div>
+    <div class="demo-anchor">
+      <OAnchor container="#wrap" :bounds="100" :target-offset="10" :change-hash="false" @click="handleAnchorClick">
+        <OAnchorItem href="#container-block1" title="container-block1" />
+        <OAnchorItem href="#container-block2" title="container-block2">
+          <!-- Nested anchor -->
+          <OAnchorItem href="#container-block2-1" title="container-block2-1" />
+        </OAnchorItem>
+        <OAnchorItem href="#container-block4" title="container-block4" />
+      </OAnchor>
+    </div>
+  </div>
+</template>
+
+<style lang="scss" scoped>
+.block {
+  height: 300px;
+
+  &:nth-child(even) {
+    background-color: paleturquoise;
+  }
+
+  &:nth-child(odd) {
+    background-color: pink;
+  }
+}
+
+.demo-wrap {
+  flex: 1;
+  height: 400px;
+  overflow: auto;
+}
+.demo-anchor {
+  min-width: 185px;
+}
+</style>
diff --git a/packages/opendesign/src/anchor/__docs__/index.en-US.md b/packages/opendesign/src/anchor/__docs__/index.en-US.md
new file mode 100644
index 00000000..bc63152a
--- /dev/null
+++ b/packages/opendesign/src/anchor/__docs__/index.en-US.md
@@ -0,0 +1,10 @@
+---
+sidebar: OAnchor
+---
+
+# Anchor
+
+## Demo
+
+<!-- @case AnchorUsage -->
+<!-- @case AnchorSlot -->
diff --git a/packages/opendesign/src/anchor/__docs__/index.zh-CN.md b/packages/opendesign/src/anchor/__docs__/index.zh-CN.md
new file mode 100644
index 00000000..2527fe44
--- /dev/null
+++ b/packages/opendesign/src/anchor/__docs__/index.zh-CN.md
@@ -0,0 +1,10 @@
+---
+sidebar: OAnchor 锚点
+---
+
+# 锚点
+
+## 示例
+
+<!-- @case AnchorUsage -->
+<!-- @case AnchorSlot -->
diff --git a/packages/opendesign/src/anchor/types.ts b/packages/opendesign/src/anchor/types.ts
index bc9d688c..6e5a847a 100644
--- a/packages/opendesign/src/anchor/types.ts
+++ b/packages/opendesign/src/anchor/types.ts
@@ -1,38 +1,70 @@
 import type { ExtractPropTypes, PropType } from 'vue';
 
 export const anchorProps = {
+  /** 
+   * @zh-CN 监测容器
+   * @en-US Scroll container to monitor
+   * @default window
+   */
   container: {
     type: [String, Object] as PropType<string | HTMLElement | Window>,
   },
+  /** 
+   * @zh-CN 锚点激活的边界范围
+   * @en-US Boundary for anchor activation
+   * @default 5
+   */
   bounds: {
     type: Number,
     default: 5,
   },
+  /** 
+   * @zh-CN 锚点激活的判定边界
+   * @en-US Boundary for anchor activation
+   * @default 0
+   */
   targetOffset: {
     type: Number,
     default: 0,
   },
+  /**
+   * @zh-CN 点击锚点时是否改变浏览器地址栏的 hash 值
+   * @en-US Whether to change the browser's address bar hash value when clicking the anchor
+   * @default true
+  */
   changeHash: {
     type: Boolean,
     default: true,
   },
-};
+} as const;
 
 export const anchorItemProps = {
+  /**
+   * @zh-CN 锚点标题
+   * @en-US Anchor title
+  */
   title: {
     type: String,
     default: '',
   },
+  /**
+   * @zh-CN 锚点跳转的目标元素(带#前缀)
+   * @en-US Target element for anchor navigation (with # prefix)
+  */
   href: {
     type: String,
-    default: '',
     required: true,
   },
+  /**
+   * @zh-CN 锚点跳转方式
+   * @en-US Anchor navigation method
+   * @default '_self'
+  */
   target: {
     type: String as PropType<'_blank' | '_parent' | '_self' | '_top'>,
     default: '_self',
   },
-};
+} as const;
 
 export type AnchorContainerT = HTMLElement | Window;
 
diff --git a/packages/opendesign/src/button/__docs__/__case__/BtnIconSize.vue b/packages/opendesign/src/button/__docs__/__case__/BtnIconSize.vue
index af8ad13c..5d163df1 100644
--- a/packages/opendesign/src/button/__docs__/__case__/BtnIconSize.vue
+++ b/packages/opendesign/src/button/__docs__/__case__/BtnIconSize.vue
@@ -1,41 +1,27 @@
 <docs lang="md">
 <!-- zh-CN -->
 
-### icon插槽及按钮大小
+### 插槽及大小
 
-可以通过`icon`插槽设置按钮图标，通过`size`属性设置按钮大小。
+可以通过`icon`插槽设置按钮左侧内容，通过`suffix`插槽设置按钮右侧内容，通过`size`属性设置按钮大小。
 
 <!-- en-US -->
 
-### Icon Slot and Button Size
+### Slots
 
-The button icon can be set using the `icon` slot, and the button size can be adjusted via the `size` prop.
+The button icon can be set using the `icon` slot, and the button suffix can be set using the `suffix` slot, and the button size can be set using the `size` property.
 </docs>
 <script setup lang="ts">
 import { OButton } from '@opensig/opendesign';
-import { OIconAdd } from '@opensig/opendesign';
+import { OIconAdd, OIconSearch } from '@opensig/opendesign';
 </script>
 <template>
   <div class="row">
     <OButton variant="solid" size="small">
-      <template #icon><OIconAdd /></template>small Button
+      <template #icon><OIconAdd /></template>small button with icon slot
     </OButton>
     <OButton variant="solid" size="medium">
-      <template #icon><OIconAdd /></template>outline Button
-    </OButton>
-    <OButton variant="solid" size="large">
-      <template #icon><OIconAdd /></template>large Button
-    </OButton>
-  </div>
-  <div class="row">
-    <OButton variant="outline" size="small">
-      <template #icon><OIconAdd /></template>small Button
-    </OButton>
-    <OButton variant="outline">
-      <template #icon><OIconAdd /></template>outline Button
-    </OButton>
-    <OButton variant="outline" size="large" :icon="OIconAdd">
-      <template #suffix><OIconAdd /></template>large Button
+      <template #suffix><OIconSearch /></template>medium button with suffix slot
     </OButton>
   </div>
   <div class="row">
diff --git a/packages/opendesign/src/button/__docs__/__case__/BtnLoading.vue b/packages/opendesign/src/button/__docs__/__case__/BtnLoading.vue
index 4b1ad829..67eb7046 100644
--- a/packages/opendesign/src/button/__docs__/__case__/BtnLoading.vue
+++ b/packages/opendesign/src/button/__docs__/__case__/BtnLoading.vue
@@ -3,7 +3,7 @@
 
 ### 加载中
 
-加载中的按钮，通过`loading`属性控制按钮的加载状态。当`loading`为`true`时，按钮会显示加载中的状态。同时`icon`插槽会被替换为加载中的图标。
+加载中的按钮，通过`loading`属性控制按钮的加载状态。当`loading`为`true`时，按钮会显示加载中的状态，同时`icon`插槽会被替换为加载中的图标。
 
 <!-- en-US -->
 
@@ -18,9 +18,8 @@ import { OButton } from '@opensig/opendesign';
 const rlt = reactive({
   loading1: false,
   loading2: false,
-  loading3: true,
 });
-const showLoading = (key: 'loading1' | 'loading2' | 'loading3', val: boolean) => {
+const showLoading = (key: keyof typeof rlt, val: boolean) => {
   rlt[key] = val;
   setTimeout(() => {
     rlt[key] = !val;
@@ -29,11 +28,9 @@ const showLoading = (key: 'loading1' | 'loading2' | 'loading3', val: boolean) =>
 </script>
 <template>
   <div class="row">
-    <OButton color="primary" :loading="rlt.loading1" @click="showLoading('loading1', true)">Primary Button</OButton>
+    <OButton color="primary" :loading="rlt.loading1" @click="showLoading('loading1', true)">click me</OButton>
     <OButton variant="outline" :loading="rlt.loading2" @click="showLoading('loading2', true)">
-      <template #icon><OIconAdd /></template>Outline Button
+      <template #icon><OIconAdd /></template>replace icon slot
     </OButton>
-    <OButton variant="text" :loading="rlt.loading3" @click="showLoading('loading3', true)">Text Button</OButton>
-    <OButton :loading="!rlt.loading3" href="https://hiascend.com" target="__blank">Link Button</OButton>
   </div>
 </template>
diff --git a/packages/opendesign/src/button/__docs__/__case__/BtnRound.vue b/packages/opendesign/src/button/__docs__/__case__/BtnRound.vue
index 8382d039..20382355 100644
--- a/packages/opendesign/src/button/__docs__/__case__/BtnRound.vue
+++ b/packages/opendesign/src/button/__docs__/__case__/BtnRound.vue
@@ -39,16 +39,6 @@ const onClick = () => {
         <OButton variant="text" size="small" round="pill">
           <template #icon><OIconAdd /></template>
         </OButton>
-
-        <OButton variant="solid" size="large" round="pill">
-          <template #icon><OIconAdd /></template>Round Button
-        </OButton>
-        <OButton variant="outline" round="pill">
-          <template #icon><OIconAdd /></template>Round Button
-        </OButton>
-        <OButton variant="text" size="small" round="pill">
-          <template #icon><OIconAdd /></template>Round Button
-        </OButton>
       </section>
     </div>
     <div>
diff --git a/packages/opendesign/src/button/__docs__/__case__/btnUsage.ts b/packages/opendesign/src/button/__docs__/__case__/btnUsage.ts
index cbcad743..da006bde 100644
--- a/packages/opendesign/src/button/__docs__/__case__/btnUsage.ts
+++ b/packages/opendesign/src/button/__docs__/__case__/btnUsage.ts
@@ -12,7 +12,7 @@ export const docs = {
 
 // 该模板会在运行时被编译为vue组件，同时作为组件的源码供用户查看和复制
 export const template = (_props: Record<string, any>) => {
-  const { 'icon-slot': iconSlot, 'suffix-slot': suffixSlot } = _props;
+  const { 'icon(slot)': iconSlot, 'suffix(slot)': suffixSlot } = _props;
   let innerHTML = '';
   if (iconSlot) {
     innerHTML += '\n<template #icon><OIconChecked /></template>';
@@ -21,7 +21,7 @@ export const template = (_props: Record<string, any>) => {
   if (suffixSlot) {
     innerHTML += '\n<template #suffix><OIconSearch /></template>';
   }
-  return `<OButton ${propsToAttrStr(_props, ['icon-slot', 'suffix-slot'])}>${innerHTML}\n</OButton>`;
+  return `<OButton ${propsToAttrStr(_props, ['icon(slot)', 'suffix(slot)'])}>${innerHTML}\n</OButton>`;
 };
 
 // 该配置会生成表单控件，表单控件选取的值会作为 template 函数的参数
@@ -48,11 +48,11 @@ export const schema = {
   loading: {
     type: 'boolean',
   },
-  'icon-slot': {
+  'icon(slot)': {
     type: 'boolean',
     default: true,
   },
-  'suffix-slot': {
+  'suffix(slot)': {
     type: 'boolean',
     default: true,
   },
diff --git a/packages/opendesign/src/button/__docs__/index.en-US.md b/packages/opendesign/src/button/__docs__/index.en-US.md
index c1944150..03bb132a 100644
--- a/packages/opendesign/src/button/__docs__/index.en-US.md
+++ b/packages/opendesign/src/button/__docs__/index.en-US.md
@@ -6,7 +6,7 @@ sidebar: OButton
 
 ## Usage
 
-<!-- @usage BtnShowcase -->
+<!-- @usage btnUsage -->
 
 ## Demo
 
diff --git a/packages/opendesign/src/button/types.ts b/packages/opendesign/src/button/types.ts
index 4787b59e..08cc4d16 100644
--- a/packages/opendesign/src/button/types.ts
+++ b/packages/opendesign/src/button/types.ts
@@ -6,62 +6,74 @@ export type ButtonSizeT = (typeof ButtonSizeTypes)[number];
 
 export const buttonProps = {
   /**
-   * 颜色类型 ColorT
+   * @zh-CN 颜色类型
+   * @en-US Color type
+   * @default 'normal'
    */
   color: {
     type: String as PropType<ColorT>,
     default: 'normal',
   },
   /**
-   * 按钮类型 VariantT
+   * @zh-CN 按钮类型
+   * @en-US Button type
+   * @default 'outline'
    */
   variant: {
     type: String as PropType<VariantT>,
     default: 'outline',
   },
   /**
-   * 按钮尺寸 ButtonSizeT
+   * @zh-CN 按钮尺寸
+   * @en-US Button size
    */
   size: {
     type: String as PropType<ButtonSizeT>,
   },
   /**
-   * 圆角值 RoundT
+   * @zh-CN 圆角值
+   * @en-US Border radius
    */
   round: {
     type: String as PropType<RoundT>,
   },
   /**
-   * 是否为loading状态
+   * @zh-CN 是否为加载状态
+   * @en-US Loading state
    */
   loading: {
     type: Boolean,
   },
   /**
-   * 是否为禁用状态
+   * @zh-CN 是否禁用
+   * @en-US Disabled state
    */
   disabled: {
     type: Boolean,
   },
   /**
-   * 链接跳转
+   * @zh-CN 跳转链接，如果设置了此属性，则按钮会以 a 标签渲染
+   * @en-US Link to navigate, if set, the button will render as an anchor tag
    */
   href: {
     type: String,
   },
   /**
-   * 前缀图标
+   * @zh-CN 前缀图标
+   * @en-US Prefix icon
    */
   icon: {
     type: Object as PropType<Component>,
   },
   /**
-   * 自定义元素标签
+   * @zh-CN 自定义按钮渲染标签
+   * @en-US Custom button render tag
+   * @default 'button'
    */
   tag: {
     type: String,
     default: 'button',
   },
-};
+} as const;
 
 export type ButtonPropsT = ExtractPropTypes<typeof buttonProps>;
-- 
Gitee


From 59efcfbf6d4b24d20b76e24ace1e591f5c47d7e1 Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Wed, 16 Jul 2025 14:40:08 +0800
Subject: [PATCH 03/17] =?UTF-8?q?fix:=20=E5=81=9C=E6=AD=A2=E8=B7=9F?=
 =?UTF-8?q?=E8=B8=AAapi.en-US.md=E6=96=87=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/button/__docs__/OButton-api.en-US.md  | 29 -------------------
 1 file changed, 29 deletions(-)
 delete mode 100644 packages/opendesign/src/button/__docs__/OButton-api.en-US.md

diff --git a/packages/opendesign/src/button/__docs__/OButton-api.en-US.md b/packages/opendesign/src/button/__docs__/OButton-api.en-US.md
deleted file mode 100644
index b3cb30d3..00000000
--- a/packages/opendesign/src/button/__docs__/OButton-api.en-US.md
+++ /dev/null
@@ -1,29 +0,0 @@
-## API OButton
-
-### props
-
-| Property | Type | Description |
-| --- | --- | --- |
-| disabled | boolean \| undefined | Whether the button is in a disabled state |
-| loading | boolean \| undefined | Whether the button is in a loading state |
-| color | "success" \| "normal" \| "primary" \| "warning" \| "danger" \| undefined | Color type (ColorT) |
-| variant | "text" \| "solid" \| "outline" \| undefined | Button style variant |
-| tag | string \| undefined | Custom element tag |
-| size | "medium" \| "small" \| "large" \| undefined | Button size (ButtonSizeT) |
-| round | string \| undefined | Border radius value (RoundT) |
-| icon | Component \| undefined | Prefix icon component |
-| href | string \| undefined | Link destination URL |
-
-### events
-
-| Event | Signature |
-| --- | --- |
-| click | (event: "click", evt: MouseEvent): void |
-
-### slots
-
-| Slot | Props |
-| --- | --- |
-| icon | {} |
-| default | {} |
-| suffix | {} |
\ No newline at end of file
-- 
Gitee


From c884674a56024287289511315e25e2bf706e0cfc Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Mon, 21 Jul 2025 08:43:53 +0800
Subject: [PATCH 04/17] =?UTF-8?q?fix:=20=E4=BF=AE=E5=A4=8DgenerateCode?=
 =?UTF-8?q?=E5=87=BD=E6=95=B0bug?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/docs/helper/utils.ts | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/docs/helper/utils.ts b/packages/docs/helper/utils.ts
index 724553a0..3dd6e315 100644
--- a/packages/docs/helper/utils.ts
+++ b/packages/docs/helper/utils.ts
@@ -9,13 +9,13 @@ export function getLangByFileName(_fileName: string) {
 }
 
 export function generateCode(block: SFCBlock) {
-  return `<${block.type} ${Object.entries(block.attrs)
+  return `<${block.type}${Object.entries(block.attrs)
     .map(([key, value]) => {
       if (typeof value === 'string') {
-        return `${key}="${value}"`;
+        return ` ${key}="${value}"`;
       } else {
-        return `${key}`;
+        return ` ${key}`;
       }
     })
-    .join(' ')}>${block.content}</${block.type}>\n`;
+    .join('')}>${block.content}</${block.type}>\n`;
 }
-- 
Gitee


From f55dde4290786dfd741853d4f5dc3387479d4559 Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Mon, 21 Jul 2025 08:49:26 +0800
Subject: [PATCH 05/17] =?UTF-8?q?fix:=20=E4=BC=98=E5=8C=96vite=E6=8F=92?=
 =?UTF-8?q?=E4=BB=B6=E4=BD=BFvue=E6=96=87=E4=BB=B6=E7=9A=84=E8=87=AA?=
 =?UTF-8?q?=E5=AE=9A=E4=B9=89dosc=E5=9D=97=E8=83=BD=E6=9B=B4=E5=A5=BD?=
 =?UTF-8?q?=E5=9C=B0=E8=A7=A3=E6=9E=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/docs/plugins/injectDemoAndApi.ts     |  2 +-
 packages/docs/plugins/injectDemoDocs.ts       | 42 ++++++++++++++++---
 .../docs/src/components/DemoContainer.vue     | 35 +++++++++++-----
 3 files changed, 61 insertions(+), 18 deletions(-)

diff --git a/packages/docs/plugins/injectDemoAndApi.ts b/packages/docs/plugins/injectDemoAndApi.ts
index a4764587..09b1b875 100644
--- a/packages/docs/plugins/injectDemoAndApi.ts
+++ b/packages/docs/plugins/injectDemoAndApi.ts
@@ -12,7 +12,7 @@ export function injectDemoAndApi(): Plugin {
     name: 'portal:inject-demo-and-api',
     enforce: 'pre',
     async transform(code, id) {
-      if (!id.endsWith('.md')) {
+      if (!id.endsWith('.md') || id.startsWith('virtual:')) {
         return;
       }
       const imported: {
diff --git a/packages/docs/plugins/injectDemoDocs.ts b/packages/docs/plugins/injectDemoDocs.ts
index c2744411..8ff49cf8 100644
--- a/packages/docs/plugins/injectDemoDocs.ts
+++ b/packages/docs/plugins/injectDemoDocs.ts
@@ -1,4 +1,4 @@
-import { type Plugin } from 'vite';
+import { type Plugin, type ViteDevServer } from 'vite';
 import { MarkdownItAsync } from 'markdown-it-async';
 import { markdownItPlugins, markdownItOptions } from './markdown/common';
 
@@ -21,6 +21,12 @@ const parseVueQuery = (id: string) => {
     : {};
   return { file, query: queryObj, queryExtension };
 };
+
+const VIRTUAL_PREFIX = 'virtual:demo-docs:';
+const virtualModules = new Map<string, { langCode: string; lang: string }>();
+const genVirtualId = (id: string, lang: string) => {
+  return `${VIRTUAL_PREFIX}${id.split('?')[0]}-${lang}.md`;
+};
 /**
  * vite插件，将vue文件中的自定义块 docs 中的 markdown 保存到_sfc_main.__docs中，
  * 该内容会作为对case组件的富文本描述，被DemoContainer组件使用
@@ -29,28 +35,52 @@ const parseVueQuery = (id: string) => {
 export function injectDemoDocs(): Plugin {
   const md = new MarkdownItAsync(markdownItOptions);
   markdownItPlugins.forEach((plugin) => md.use(plugin));
+  let viteDevServer: ViteDevServer | null = null;
   return {
     name: 'portal:inject-demo-docs',
+    configureServer(server) {
+      viteDevServer = server;
+    },
+    resolveId(id) {
+      if (virtualModules.has(id)) {
+        return id;
+      }
+    },
+    load(id) {
+      return virtualModules.get(id)?.langCode;
+    },
     transform(code, id) {
       const { query } = parseVueQuery(id);
       if (!query.vue || query.type !== 'docs' || !id.endsWith('.md')) {
         return;
       }
-      const __docs: Record<string, string> = {};
       // 通过 <!-- lang --> 分割不同语言的文案块
       const langSeparator = /<!--\s*([a-zA-Z-]+)\s*-->/gm;
       const langMatchList = Array.from(code.matchAll(langSeparator));
+      const virtualIds: string[] = [];
       langMatchList.forEach((langMatch, matchIndex) => {
         const lang = langMatch[1];
         const langCode = code.slice(
           langMatch.index + langMatch[0].length,
           matchIndex === langMatchList.length - 1 ? code.length : langMatchList[matchIndex + 1].index,
         );
-        // 使用 markdown 渲染文案块，并保存到 _sfc_main.__docs 中
-        __docs[lang] = md.render(langCode);
+        const virtualId = genVirtualId(id, lang);
+        if (virtualModules.has(virtualId) && this.environment.mode === 'dev' && viteDevServer) {
+          viteDevServer.watcher.emit('change', virtualId);
+        }
+        virtualModules.set(virtualId, { langCode, lang });
+        virtualIds.push(virtualId);
       });
-      return `export default function (_sfc_main) {
-_sfc_main.__docs = ${JSON.stringify(__docs)};
+      return `${virtualIds.map((vid, index) => `import Docs${index} from ${JSON.stringify(vid)};`).join('\n')}
+export default function (_sfc_main) {
+  _sfc_main.__docs = {
+${virtualIds
+  .map((vid, index) => {
+    const { lang } = virtualModules.get(vid)!;
+    return `    '${lang}': Docs${index}`;
+  })
+  .join(',\n')}
+  };
 }`;
     },
   };
diff --git a/packages/docs/src/components/DemoContainer.vue b/packages/docs/src/components/DemoContainer.vue
index c0515516..9f7ab5b0 100644
--- a/packages/docs/src/components/DemoContainer.vue
+++ b/packages/docs/src/components/DemoContainer.vue
@@ -1,12 +1,13 @@
 <script setup lang="ts">
-import { ref, type Component, PropType } from 'vue';
+import { ref, h, type Component, PropType } from 'vue';
 import { OScroller, OButton, useI18n, OIconChevronUp } from '@opensig/opendesign';
 
+type DocT = Record<string, string | Component>;
 type DemoComponent = Component & {
   /** __docs__/__case__组件源的源码组件 */
   DemoSource?: Component;
   /** __docs__/__case__组件文案 */
-  __docs?: Record<string, string>;
+  __docs?: DocT;
 };
 const props = defineProps({
   demo: {
@@ -19,11 +20,23 @@ const switchShowCode = () => {
   isShowCode.value = !isShowCode.value;
 };
 const { locale } = useI18n();
+const Docs = ({ docs, locale }: { docs?: DocT; locale: string }) => {
+  if (!docs || !docs[locale]) {
+    return;
+  }
+  if (typeof docs[locale] === 'string') {
+    return h('div', {
+      class: 'docs',
+      innerHTML: docs[locale],
+    });
+  }
+  return h('div', { class: 'docs' }, h(docs[locale]));
+};
 </script>
 
 <template>
   <div class="demo-container">
-    <div v-if="props.demo.__docs" class="docs" v-html="props.demo.__docs[locale]"></div>
+    <Docs :docs="props.demo.__docs" :locale="locale" />
     <div class="demo">
       <Component :is="props.demo" />
     </div>
@@ -56,15 +69,15 @@ const { locale } = useI18n();
     margin-top: 12px;
   }
 }
-.docs {
+:deep(.docs) {
   padding: var(--o3-gap-4);
-  :deep(p),
-  :deep(h1),
-  :deep(h2),
-  :deep(h3),
-  :deep(h4),
-  :deep(h5),
-  :deep(h6) {
+  p,
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
     &:first-child {
       margin-top: 0;
     }
-- 
Gitee


From 601f319c852f60cb16d56dd52260bdedb47ee2c8 Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Mon, 21 Jul 2025 08:50:11 +0800
Subject: [PATCH 06/17] =?UTF-8?q?feat:=20DemoUsage=E6=96=B0=E5=A2=9Estring?=
 =?UTF-8?q?=EF=BC=8Cnumber=E4=B8=A4=E7=A7=8D=E6=8E=A7=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/docs/src/components/DemoUsage.vue  | 74 ++++++++++++++++-----
 packages/docs/src/utils/compileComponent.ts | 12 ++++
 2 files changed, 71 insertions(+), 15 deletions(-)
 create mode 100644 packages/docs/src/utils/compileComponent.ts

diff --git a/packages/docs/src/components/DemoUsage.vue b/packages/docs/src/components/DemoUsage.vue
index 0a17b926..93ad017d 100644
--- a/packages/docs/src/components/DemoUsage.vue
+++ b/packages/docs/src/components/DemoUsage.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import * as Vue from 'vue';
-import { OSelect, OOption, OCheckbox, OCheckboxGroup } from '@opensig/opendesign';
+import { reactive, h, Fragment, ref, watchEffect, shallowRef, type VNode,type Component, shallowReactive } from 'vue';
+import { OSelect, OOption, OInput, OInputNumber, OCheckbox, OCheckboxGroup } from '@opensig/opendesign';
 import * as prettier from 'prettier';
 import htmlPlugin from 'prettier/plugins/html';
 import babelPlugin from 'prettier/plugins/babel';
@@ -10,7 +10,7 @@ import esTreePlugin from 'prettier/plugins/estree';
 import { highlight, md } from '../../plugins/markdown/common';
 import { LINENUMBER_TAG_ATTR, LINENUMBER_CSS_ATTR } from '../../plugins/markdown/lineNumber';
 import CodeContainer from './CodeContainer.vue';
-import { compile } from '@vue/compiler-dom';
+import { compileComponent } from '@/utils/compileComponent';
 export type SchemeT =
   | {
       type: 'boolean';
@@ -20,6 +20,17 @@ export type SchemeT =
       type: 'list';
       list: Array<string | number>;
       default?: string | number;
+    }
+  | {
+      type: 'string';
+      default?: string;
+    }
+  | {
+      type: 'number';
+      step?: number;
+      min?: number;
+      max?: number;
+      default?: number;
     };
 const props = defineProps<{
   /** markdown文档 */
@@ -29,7 +40,6 @@ const props = defineProps<{
   /** vue 模板 */
   template: string | ((_props: Record<string, any>) => string);
 }>();
-const { reactive, h, Fragment, ref, watchEffect, shallowRef } = Vue;
 /**
  * 通过表单控制数据，生成表单控件响应式变量的默认值
  * @param schema 表单控件配置数据
@@ -48,6 +58,12 @@ function getInitialValues(schema: Record<string, SchemeT>) {
       case 'list':
         state[key] = value.default ?? value.list[0];
         break;
+      case 'string':
+        state[key] = value.default ?? '';
+        break;
+      case 'number':
+        state[key] = value.default ?? 0;
+        break;
     }
   });
   return {
@@ -64,17 +80,17 @@ const state = reactive(initialValues.state);
  */
 function OperatorView({ schema }: { schema: Record<string, SchemeT> }) {
   /** 复选框控件 */
-  const checkboxGroup: Vue.VNode[] = [];
+  const checkboxGroup: VNode[] = [];
   /** 选着框控件 */
-  const selectionGroup: Vue.VNode[] = [];
-  const operatorGroup: Vue.VNode[] = [];
+  const selectionOrInputGroup: VNode[] = [];
+  const operatorGroup: VNode[] = [];
   Object.entries(schema).forEach(([key, value]) => {
     switch (value.type) {
       case 'boolean':
         checkboxGroup.push(h(OCheckbox, { value: key }, { default: () => key }));
         break;
       case 'list':
-        selectionGroup.push(
+        selectionOrInputGroup.push(
           h(Fragment, [
             h('span', { class: 'props-playground-selector-name' }, key),
             h(
@@ -86,6 +102,29 @@ function OperatorView({ schema }: { schema: Record<string, SchemeT> }) {
             ),
           ]),
         );
+        break;
+      case 'string':
+        selectionOrInputGroup.push(
+          h(Fragment, [
+            h('span', { class: 'props-playground-selector-name' }, key),
+            h(OInput, { modelValue: state[key], 'onUpdate:modelValue': (val) => (state[key] = val) }),
+          ]),
+        );
+        break;
+      case 'number':
+        selectionOrInputGroup.push(
+          h(Fragment, [
+            h('span', { class: 'props-playground-selector-name' }, key),
+            h(OInputNumber, {
+              modelValue: state[key],
+              'onUpdate:modelValue': (val) => (state[key] = val),
+              min: value.min,
+              max: value.max,
+              step: value.step,
+            }),
+          ]),
+        );
+        break;
     }
   });
   if (checkboxGroup.length) {
@@ -112,14 +151,14 @@ function OperatorView({ schema }: { schema: Record<string, SchemeT> }) {
       ),
     );
   }
-  if (selectionGroup.length) {
-    operatorGroup.push(h('div', { class: 'operator-group' }, selectionGroup));
+  if (selectionOrInputGroup.length) {
+    operatorGroup.push(h('div', { class: 'operator-group' }, selectionOrInputGroup));
   }
   return h(Fragment, operatorGroup);
 }
 const highlightedCode = ref('');
 const sourceCode = ref('');
-const showcaseComponent = shallowRef<Vue.Component>(() => {});
+const showcaseComponent = shallowRef<Component>(() => {});
 
 /**
  * 通过 props.template 动态编译vue组件，同时格式化并高亮源码
@@ -140,8 +179,7 @@ function createShowcaseComponent(demoProps: Record<string, any>) {
       sourceCode.value = code;
       highlightedCode.value = highlight(code, 'vue');
     });
-  const showcaseCode = compile(template, { mode: 'function' });
-  return new Function('Vue', showcaseCode.code)(Vue);
+  return compileComponent(template);
 }
 /**
  * 函数式组件，用来渲染 showcaseComponent 的演示组件，以及OperatorView表单控件
@@ -166,15 +204,21 @@ Demo.DemoSource = () => {
     );
   }
 };
+const docs = shallowReactive<Record<string, string>>({});
 watchEffect(() => {
   showcaseComponent.value = createShowcaseComponent(state);
   if (props.docs) {
     Object.keys(props.docs).forEach((key) => {
-      props.docs![key] = md.render(props.docs![key]);
+      docs[key] = md.render(props.docs![key]);
+    });
+  } else {
+    Object.keys(docs).forEach((key) => {
+      delete docs[key]; // 清除之前的文档组件
     });
   }
 });
-Demo.__docs = props.docs;
+
+Demo.__docs = docs;
 </script>
 <template>
   <DemoContainer :demo="Demo" class="props-playground" />
diff --git a/packages/docs/src/utils/compileComponent.ts b/packages/docs/src/utils/compileComponent.ts
new file mode 100644
index 00000000..21b2a488
--- /dev/null
+++ b/packages/docs/src/utils/compileComponent.ts
@@ -0,0 +1,12 @@
+import * as Vue from 'vue';
+import { compile, type CompilerOptions } from '@vue/compiler-dom';
+
+export function compileComponent(template: string, options: Omit<CompilerOptions, 'filename' | 'mode'> = {}): Vue.Component {
+  const { code } = compile(template, {
+    ...options,
+    mode: 'function',
+  });
+  console.log('Compiled code:', code);
+  const component = new Function('Vue', code)(Vue);
+  return component;
+}
-- 
Gitee


From b786c7e122056d4c5e71eb40b7b1c41a1be4cbaa Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Mon, 21 Jul 2025 08:50:30 +0800
Subject: [PATCH 07/17] =?UTF-8?q?style:=20=E4=BC=98=E5=8C=96=E6=A0=B7?=
 =?UTF-8?q?=E5=BC=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/docs/src/assets/style/markdown.scss | 24 ++++++++++----------
 packages/docs/src/assets/style/style.scss    |  3 +++
 2 files changed, 15 insertions(+), 12 deletions(-)

diff --git a/packages/docs/src/assets/style/markdown.scss b/packages/docs/src/assets/style/markdown.scss
index afe88804..e74021a6 100644
--- a/packages/docs/src/assets/style/markdown.scss
+++ b/packages/docs/src/assets/style/markdown.scss
@@ -12,7 +12,15 @@
 [data-o-theme$='dark'] span {
   color: var(--shiki-dark);
 }
-
+p + .code-container {
+  margin-top: 8px;
+}
+ol,
+ul,
+li {
+  margin: 0;
+  padding: 0;
+}
 @include respond-to('>pad_v') {
   ol {
     padding-inline-start: calc(1em + 24px);
@@ -24,8 +32,8 @@
   }
   ul,
   ol {
-    li {
-      margin-top: 8px;
+    li + li {
+      margin-block-start: 4px;
     }
     ul {
       list-style-type: circle;
@@ -36,16 +44,8 @@
     }
     ul,
     ol {
-      margin-top: 4px;
       li {
-        margin-top: 4px;
-      }
-      ul,
-      ol {
-        margin-top: 0;
-        li {
-          margin-top: 0;
-        }
+        margin-block-start: 0px;
       }
       ul {
         list-style-type: square;
diff --git a/packages/docs/src/assets/style/style.scss b/packages/docs/src/assets/style/style.scss
index 14e673e6..237e243f 100644
--- a/packages/docs/src/assets/style/style.scss
+++ b/packages/docs/src/assets/style/style.scss
@@ -157,6 +157,9 @@ section {
 
 .markdown-body {
   padding: 0 var(--o3-gap-5);
+  .markdown-body {
+    padding: 0;
+  }
   @include respond-to('<=pad_v') {
     padding: 0;
   }
-- 
Gitee


From 4c6ffe8ac3e2e4505810d719674050437c543cd5 Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Mon, 21 Jul 2025 10:28:57 +0800
Subject: [PATCH 08/17] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E@api=E6=8C=87?=
 =?UTF-8?q?=E4=BB=A4=E4=BB=A5=E4=BE=BF=E9=80=89=E7=9D=80=E6=80=A7=E5=9C=B0?=
 =?UTF-8?q?=E5=BC=95=E5=85=A5api=E6=96=87=E6=A1=A3=EF=BC=8Capi=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E5=AE=9E=E7=8E=B0=E7=83=AD=E6=9B=B4=E6=96=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/docs/plugins/injectDemoAndApi.ts | 39 ++++++++++++++++-------
 packages/docs/scripts/generateApi.ts      |  8 ++---
 2 files changed, 31 insertions(+), 16 deletions(-)

diff --git a/packages/docs/plugins/injectDemoAndApi.ts b/packages/docs/plugins/injectDemoAndApi.ts
index 09b1b875..ba4e7781 100644
--- a/packages/docs/plugins/injectDemoAndApi.ts
+++ b/packages/docs/plugins/injectDemoAndApi.ts
@@ -1,8 +1,10 @@
 import { type Plugin } from 'vite';
 import { join, dirname } from 'node:path';
-import { existsSync, promises as fsp } from 'node:fs';
+import { existsSync, readFileSync, promises as fsp } from 'node:fs';
 import { getLangByFileName } from '../helper/utils';
 
+const entryFileRegex = /index\.([\w-]+)\.md$/;
+const apiFileRegex = /api\.([\w-]+)\.md$/;
 /**
  * vite 插件，在 index.<lang>.md 添加 /__docs__/__case__ 组件；拼接 api.zh-CN.md 文件
  * @returns Plugin
@@ -12,9 +14,10 @@ export function injectDemoAndApi(): Plugin {
     name: 'portal:inject-demo-and-api',
     enforce: 'pre',
     async transform(code, id) {
-      if (!id.endsWith('.md') || id.startsWith('virtual:')) {
+      if (!entryFileRegex.test(id) || id.startsWith('virtual:')) {
         return;
       }
+      const lang = getLangByFileName(id);
       const imported: {
         default?: string;
         named?: { name: string; alias?: string }[];
@@ -22,7 +25,14 @@ export function injectDemoAndApi(): Plugin {
       }[] = [];
       // 将 <!-- @case CaseComponent --> 注释替换成 <DemoContainer :demo="AutoInjectCaseComponent" />
       // 将 <!-- @usage usageConfig --> 注释替换成 <DemoUsage :docs="docs" :template="template" :schema="schema" />
-      let newCode = code.replace(/<!--\s*@(case|usage)\s+(.*?)\s*-->/g, (match, directive, fileName) => {
+      let newCode = code.replace(/<!--\s*@(case|usage|api)\s+(.*?)\s*-->/g, (match, directive, fileName) => {
+        if (directive === 'api') {
+          // 拼接 api 文件
+          const apiFile = join(dirname(id), `${fileName}-api.${lang.lang}.md`);
+          if (existsSync(apiFile)) {
+            return readFileSync(apiFile, 'utf-8');
+          }
+        }
         const fileNameWidthExt = directive === 'case' ? `./__case__/${fileName}.vue` : `./__case__/${fileName}.ts`;
         const demoFile = join(dirname(id), fileNameWidthExt);
         if (existsSync(demoFile)) {
@@ -72,17 +82,22 @@ export function injectDemoAndApi(): Plugin {
           })
           .join('\n')}\n</script>`;
       }
-      const lang = getLangByFileName(id);
-      const dir = dirname(id);
-      // 读取同文件夹下的所有<fileName>-api.<lang>.md 的api文档，将内容注入到对应语言的index.<lang>.md文件末尾
-      const files = await fsp.readdir(dir);
-      for (const file of files) {
-        const filePath = join(dir, file);
-        if (filePath.endsWith(`api.${lang.lang}.md`) && (await fsp.stat(filePath).then((stat) => stat.isFile()))) {
-          newCode += `\n\n${await fsp.readFile(filePath, 'utf-8')}`;
+      return newCode;
+    },
+    // 处理 api.*.md 文件的热更新
+    handleHotUpdate(ctx) {
+      const { file } = ctx;
+      const match = file.match(apiFileRegex);
+      if (match) {
+        const entryFile = join(dirname(file), `index.${match[1]}.md`);
+        if (existsSync(entryFile)) {
+          const module = ctx.server.moduleGraph.getModuleById(entryFile.replace(/\\/g, '/'));
+          if (module) {
+            ctx.server.moduleGraph.invalidateModule(module);
+            ctx.server.ws.send({ type: 'full-reload' });
+          }
         }
       }
-      return newCode;
     },
   };
 }
diff --git a/packages/docs/scripts/generateApi.ts b/packages/docs/scripts/generateApi.ts
index 4c1462b1..f2e00ab1 100644
--- a/packages/docs/scripts/generateApi.ts
+++ b/packages/docs/scripts/generateApi.ts
@@ -145,7 +145,7 @@ glob('*/O*.vue', { cwd: srcDir, posix: true }).then((files) => {
     const pathMath = file.match(pathReg);
     for (const lang of ['zh-CN', 'en-US']) {
       const apiMdPath = join(fullPath, `../__docs__/${pathMath[1]}-api.${lang}.md`);
-      let mdContent = `## API ${pathMath[1]}`;
+      let mdContent = `### ${pathMath[1]}`;
       // props
       if (meta.props.length) {
         const tableHeader = {
@@ -170,7 +170,7 @@ glob('*/O*.vue', { cwd: srcDir, posix: true }).then((files) => {
           });
         propsData.unshift(tableHeader[lang]);
         propsData = cleanTableData(propsData);
-        mdContent = `${mdContent}\n\n### props\n\n${markdownTable(propsData)}`;
+        mdContent = `${mdContent}\n\n#### props\n\n${markdownTable(propsData)}`;
       }
       // events
       if (meta.events.length) {
@@ -192,7 +192,7 @@ glob('*/O*.vue', { cwd: srcDir, posix: true }).then((files) => {
         });
         eventsData.unshift(tableHeader[lang]);
         eventsData = cleanTableData(eventsData);
-        mdContent = `${mdContent}\n\n### events\n\n${markdownTable(eventsData)}`;
+        mdContent = `${mdContent}\n\n#### events\n\n${markdownTable(eventsData)}`;
       }
       // slots
       if (meta.slots.length) {
@@ -205,7 +205,7 @@ glob('*/O*.vue', { cwd: srcDir, posix: true }).then((files) => {
         });
         slotsData.unshift(tableHeader[lang]);
         slotsData = cleanTableData(slotsData);
-        mdContent = `${mdContent}\n\n### slots\n\n${markdownTable(slotsData)}`;
+        mdContent = `${mdContent}\n\n#### slots\n\n${markdownTable(slotsData)}`;
       }
       await fsp.mkdir(dirname(apiMdPath), { recursive: true }).then(() => fsp.writeFile(apiMdPath, mdContent, { encoding: 'utf-8' }));
     }
-- 
Gitee


From e614d1a849688cbacf4a98d5cc6de3fa85ed0a4d Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Mon, 21 Jul 2025 10:30:20 +0800
Subject: [PATCH 09/17] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9EBreadcrumb?=
 =?UTF-8?q?=E5=8F=8ABadge=E6=96=87=E6=A1=A3=E5=8F=8A=E4=BC=98=E5=8C=96?=
 =?UTF-8?q?=E5=85=B6=E5=AE=83=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/docs/public/avatar.svg               |  1 +
 .../anchor/__docs__/__case__/AnchorUsage.vue  | 70 +++++++++----------
 .../src/anchor/__docs__/index.en-US.md        |  5 ++
 .../src/anchor/__docs__/index.zh-CN.md        |  5 ++
 packages/opendesign/src/anchor/types.ts       |  4 +-
 .../src/badge/__docs__/__case__/BadgeSlot.vue | 24 +++++++
 .../src/badge/__docs__/__case__/badgeUsage.ts | 58 +++++++++++++++
 .../src/badge/__docs__/index.en-US.md         | 15 ++++
 .../src/badge/__docs__/index.zh-CN.md         | 15 ++++
 packages/opendesign/src/badge/types.ts        | 18 +++--
 .../breadcrumb/__docs__/__case__/BcUsage.vue  | 24 +++++++
 .../__docs__/__case__/BcVueRouter.vue         | 54 ++++++++++++++
 .../src/breadcrumb/__docs__/index.en-US.md    | 15 ++++
 .../src/breadcrumb/__docs__/index.zh-CN.md    | 15 ++++
 packages/opendesign/src/breadcrumb/types.ts   | 20 ++++--
 .../src/button/__docs__/__case__/btnUsage.ts  | 14 +++-
 .../src/button/__docs__/index.en-US.md        |  4 ++
 .../src/button/__docs__/index.zh-CN.md        |  4 ++
 packages/opendesign/src/button/types.ts       |  2 +-
 19 files changed, 312 insertions(+), 55 deletions(-)
 create mode 100644 packages/docs/public/avatar.svg
 create mode 100644 packages/opendesign/src/badge/__docs__/__case__/BadgeSlot.vue
 create mode 100644 packages/opendesign/src/badge/__docs__/__case__/badgeUsage.ts
 create mode 100644 packages/opendesign/src/badge/__docs__/index.en-US.md
 create mode 100644 packages/opendesign/src/badge/__docs__/index.zh-CN.md
 create mode 100644 packages/opendesign/src/breadcrumb/__docs__/__case__/BcUsage.vue
 create mode 100644 packages/opendesign/src/breadcrumb/__docs__/__case__/BcVueRouter.vue
 create mode 100644 packages/opendesign/src/breadcrumb/__docs__/index.en-US.md
 create mode 100644 packages/opendesign/src/breadcrumb/__docs__/index.zh-CN.md

diff --git a/packages/docs/public/avatar.svg b/packages/docs/public/avatar.svg
new file mode 100644
index 00000000..995fccea
--- /dev/null
+++ b/packages/docs/public/avatar.svg
@@ -0,0 +1 @@
+<?xml version='1.0' encoding='UTF-8'?><svg xmlns="http://www.w3.org/2000/svg" width="48" height="48"><circle cx="24" cy="24" r="24" opacity=".25"/><path fill="#FFF" fill-opacity=".9" d="M23.92 30.857c11.31 0 14.263 6.778 15.33 9.048.038.078.074.16.108.243A22.207 22.207 0 0 1 24 46.286c-6.01 0-11.465-2.38-15.473-6.248l.063-.133c1.117-2.27 4.02-9.048 15.33-9.048Zm0-19.714a8.143 8.143 0 1 1 0 16.286 8.143 8.143 0 0 1 0-16.286Z"/></svg>
\ No newline at end of file
diff --git a/packages/opendesign/src/anchor/__docs__/__case__/AnchorUsage.vue b/packages/opendesign/src/anchor/__docs__/__case__/AnchorUsage.vue
index b6ee355c..9f06bf18 100644
--- a/packages/opendesign/src/anchor/__docs__/__case__/AnchorUsage.vue
+++ b/packages/opendesign/src/anchor/__docs__/__case__/AnchorUsage.vue
@@ -3,57 +3,51 @@
 
 ### 使用
 
-1. `container` 属性
+`container` 属性
+- 说明：指定锚点监听的滚动容器（默认值：window）
+- 用法：组件会在该容器上监听 `scroll` 事件，以判断当前激活的锚点
+- 示例：`container="#wrap"` 表示监听 id 为 wrap 的容器滚动事件
 
-   - 说明：指定锚点监听的滚动容器（默认值：window）
-   - 用法：组件会在该容器上监听 `scroll` 事件，以判断当前激活的锚点
-   - 示例：`container="#wrap"` 表示监听 id 为 wrap 的容器滚动事件
+`targetOffset` 属性
+- 说明：目标元素跳转或激活时距离容器顶部的偏移量（默认值：0）
+- 示例：`:target-offset="10"` 表示点击锚点时目标元素会滚动到距离容器顶部 10px 的位置；滚动距离小于 10px 时锚点处于激活状态
 
-2. `targetOffset` 属性
+`bounds` 属性
+- 说明：设置锚点激活的判定边界（默认值：5）
+- 用法：当需要跳转位置和激活判定边界不一致时可设置
+- 示例：`:bounds="100" :target-offset="10"` 表示目标元素滚动到距离容器顶部 110px 时锚点激活。可实现点击锚点时目标元素滚动到顶部，滚动浏览时需到容器中上部才激活锚点的交互效果
 
-   - 说明：目标元素跳转或激活时距离容器顶部的偏移量（默认值：0）
-   - 示例：`:target-offset="10"` 表示点击锚点时目标元素会滚动到距离容器顶部 10px 的位置；滚动距离小于 10px 时锚点处于激活状态
+`changeHash` 属性
+- 说明：是否在点击锚点时改变浏览器地址栏的 hash 值（默认值：true）
+- 用法：如果需要手动控制 URL 跳转，可以设置为 false，并在 `click` 事件中处理跳转逻辑
+- 示例：`:change-hash="false"` 表示点击锚点时不会改变浏览器地址栏的 hash 值
 
-3. `bounds` 属性
-
-   - 说明：设置锚点激活的判定边界（默认值：5）
-   - 用法：当需要跳转位置和激活判定边界不一致时可设置
-   - 示例：`:bounds="100" :target-offset="10"` 表示目标元素滚动到距离容器顶部 110px 时锚点激活。可实现点击锚点时目标元素滚动到顶部，滚动浏览时需到容器中上部才激活锚点的交互效果
-
-4. `changeHash` 属性
-   - 说明：是否在点击锚点时改变浏览器地址栏的 hash 值（默认值：true）
-   - 用法：如果需要手动控制 URL 跳转，可以设置为 false，并在 `click` 事件中处理跳转逻辑
-   - 示例：`:change-hash="false"` 表示点击锚点时不会改变浏览器地址栏的 hash 值
-
-5. 锚点嵌套：`OAnchorItem` 可以嵌套使用，形成多级锚点结构
+锚点嵌套：`OAnchorItem` 可以嵌套使用，形成多级锚点结构
 
 <!-- en-US -->
 
 ### Usage
 
-1. `container` property
-
-   - Description: Specifies the scroll container to be monitored by the anchor (default: window)
-   - Usage: The component listens for the `scroll` event on this container to determine the currently active anchor
-   - Example: `container="#wrap"` means listening to the scroll event of the container with id "wrap"
-
-2. `targetOffset` property
-
-   - Description: The offset from the top of the container when the target element is scrolled or activated (default: 0)
-   - Example: `:target-offset="10"` means when clicking the anchor, the target element will scroll to 10px from the top of the container; when the scroll distance is less than 10px, the anchor is considered active
+`container` property
+- Description: Specifies the scroll container to be monitored by the anchor (default: window)
+- Usage: The component listens for the `scroll` event on this container to determine the currently active anchor
+- Example: `container="#wrap"` means listening to the scroll event of the container with id "wrap"
 
-3. `bounds` property
+`targetOffset` property
+- Description: The offset from the top of the container when the target element is scrolled or activated (default: 0)
+- Example: `:target-offset="10"` means when clicking the anchor, the target element will scroll to 10px from the top of the container; when the scroll distance is less than 10px, the anchor is considered active
 
-   - Description: Sets the boundary for anchor activation (default: 5)
-   - Usage: Use when the scroll position and activation boundary need to be different
-   - Example: `:bounds="100" :target-offset="10"` means the anchor is activated when the target element is 110px from the top of the container. This allows the target element to scroll to the top when clicking the anchor, but requires scrolling further down to activate
+`bounds` property
+- Description: Sets the boundary for anchor activation (default: 5)
+- Usage: Use when the scroll position and activation boundary need to be different
+- Example: `:bounds="100" :target-offset="10"` means the anchor is activated when the target element is 110px from the top of the container. This allows the target element to scroll to the top when clicking the anchor, but requires scrolling further down to activate
 
-4. `changeHash` property
-   - Description: Whether to change the browser's address bar hash value when clicking the anchor (default: true)
-   - Usage: If you need to manually control URL navigation, set this to false and handle the navigation logic in the `click` event
-   - Example: `:change-hash="false"` means clicking the anchor will not change the hash value in the browser's address bar
+`changeHash` property
+- Description: Whether to change the browser's address bar hash value when clicking the anchor (default: true)
+- Usage: If you need to manually control URL navigation, set this to false and handle the navigation logic in the `click` event
+- Example: `:change-hash="false"` means clicking the anchor will not change the hash value in the browser's address bar
 
-5. Nested anchors: `OAnchorItem` can be nested to create multi-level anchor structures
+Nested anchors: `OAnchorItem` can be nested to create multi-level anchor structures
 </docs>
 
 <script setup lang="ts">
diff --git a/packages/opendesign/src/anchor/__docs__/index.en-US.md b/packages/opendesign/src/anchor/__docs__/index.en-US.md
index bc63152a..87afa29a 100644
--- a/packages/opendesign/src/anchor/__docs__/index.en-US.md
+++ b/packages/opendesign/src/anchor/__docs__/index.en-US.md
@@ -8,3 +8,8 @@ sidebar: OAnchor
 
 <!-- @case AnchorUsage -->
 <!-- @case AnchorSlot -->
+
+## Api
+
+<!-- @api OAnchor -->
+<!-- @api OAnchorItem -->
diff --git a/packages/opendesign/src/anchor/__docs__/index.zh-CN.md b/packages/opendesign/src/anchor/__docs__/index.zh-CN.md
index 2527fe44..fca9fc4c 100644
--- a/packages/opendesign/src/anchor/__docs__/index.zh-CN.md
+++ b/packages/opendesign/src/anchor/__docs__/index.zh-CN.md
@@ -8,3 +8,8 @@ sidebar: OAnchor 锚点
 
 <!-- @case AnchorUsage -->
 <!-- @case AnchorSlot -->
+
+## Api
+
+<!-- @api OAnchor -->
+<!-- @api OAnchorItem -->
diff --git a/packages/opendesign/src/anchor/types.ts b/packages/opendesign/src/anchor/types.ts
index 6e5a847a..063c1ce0 100644
--- a/packages/opendesign/src/anchor/types.ts
+++ b/packages/opendesign/src/anchor/types.ts
@@ -36,7 +36,7 @@ export const anchorProps = {
     type: Boolean,
     default: true,
   },
-} as const;
+};
 
 export const anchorItemProps = {
   /**
@@ -64,7 +64,7 @@ export const anchorItemProps = {
     type: String as PropType<'_blank' | '_parent' | '_self' | '_top'>,
     default: '_self',
   },
-} as const;
+};
 
 export type AnchorContainerT = HTMLElement | Window;
 
diff --git a/packages/opendesign/src/badge/__docs__/__case__/BadgeSlot.vue b/packages/opendesign/src/badge/__docs__/__case__/BadgeSlot.vue
new file mode 100644
index 00000000..ae7b73f1
--- /dev/null
+++ b/packages/opendesign/src/badge/__docs__/__case__/BadgeSlot.vue
@@ -0,0 +1,24 @@
+<docs lang="md">
+<!-- zh-CN -->
+
+### 自定义徽标内容
+
+可以通过 `content` 插槽自定义徽标内容。如果不提供 `content` 插槽，则显示 `value` 值。
+
+<!-- en-US -->
+
+### Custom Badge Content
+
+You can customize the badge content using the `content` slot. If the `content` slot is not provided, the `value` will be displayed.
+</docs>
+<script setup lang="ts">
+import { OBadge, OIconChecked } from '@opensig/opendesign';
+</script>
+<template>
+  <OBadge>
+    <img src="/avatar.svg" alt="avatar" style="width: 48px; height: 48px" />
+    <template #content>
+      <OIconChecked />
+    </template>
+  </OBadge>
+</template>
diff --git a/packages/opendesign/src/badge/__docs__/__case__/badgeUsage.ts b/packages/opendesign/src/badge/__docs__/__case__/badgeUsage.ts
new file mode 100644
index 00000000..4742ae03
--- /dev/null
+++ b/packages/opendesign/src/badge/__docs__/__case__/badgeUsage.ts
@@ -0,0 +1,58 @@
+import { propsToAttrStr } from '../../../_demo/utils';
+
+export const schema = {
+  value: {
+    type: 'string',
+    default: '100',
+  },
+  max: {
+    type: 'number',
+    default: 99,
+  },
+  color: {
+    type: 'list',
+    list: ['primary', 'success', 'warning', 'danger'],
+    default: 'primary',
+  },
+  dot: {
+    type: 'boolean',
+    default: false,
+  },
+  'offset-x': {
+    type: 'number',
+    default: 0,
+    // min: 0,
+  },
+  'offset-y': {
+    type: 'number',
+    default: 0,
+  },
+};
+const NUMBER_REGEXP = /^\d+$/;
+export const template = (_props: Record<string, any>) => {
+  const { 'offset-x': offsetX, 'offset-y': offsetY, value } = _props;
+  const isNumber = NUMBER_REGEXP.test(value);
+
+  return `<OBadge 
+  ${propsToAttrStr(_props, ['offset-x', 'offset-y', 'value'])}
+  ${isNumber ? `:value="${parseInt(value)}"` : `value="${value}"`}
+  ${offsetX || offsetY ? `:offset="[${offsetX}, ${offsetY}]"` : ''}
+  >
+    <img src="/avatar.svg" alt="avatar" style="width: 48px; height: 48px;" />
+  </OBadge>`;
+};
+
+export const docs = {
+  'zh-CN':
+    '### 使用\n' +
+    '徽标包含 `primary`、`success`、`warning`、`danger` 四种主题色。\n\n' +
+    '徽标 `value` 参数支持数字和文本两种类型的值，当为数字时 `max` 参数会影响值的显示。\n\n' +
+    '徽标支持小红点样式，小红点中不会显示徽标内容。\n\n' +
+    '徽标可以通过 `offset` 设置偏移位置。',
+  'en-US':
+    '### Usage\n' +
+    'The badge includes four theme colors: `primary`, `success`, `warning`, and `danger`.\n\n' +
+    'The `value` parameter of the badge supports both numeric and text values. When it is numeric, the `max` parameter affects how the value is displayed.\n\n' +
+    'The badge supports a small dot style, where the content is not displayed in the dot.\n\n' +
+    'The badge can set an offset position using the `offset` property.',
+};
diff --git a/packages/opendesign/src/badge/__docs__/index.en-US.md b/packages/opendesign/src/badge/__docs__/index.en-US.md
new file mode 100644
index 00000000..ad133c5c
--- /dev/null
+++ b/packages/opendesign/src/badge/__docs__/index.en-US.md
@@ -0,0 +1,15 @@
+---
+sidebar: OBadge
+---
+
+# OBadge
+
+## Demo
+
+<!-- @usage badgeUsage -->
+
+<!-- @case BadgeSlot -->
+
+## Api
+
+<!-- @api OBadge -->
diff --git a/packages/opendesign/src/badge/__docs__/index.zh-CN.md b/packages/opendesign/src/badge/__docs__/index.zh-CN.md
new file mode 100644
index 00000000..1b961e5c
--- /dev/null
+++ b/packages/opendesign/src/badge/__docs__/index.zh-CN.md
@@ -0,0 +1,15 @@
+---
+sidebar: OBadge 徽标
+---
+
+# 徽标
+
+## 示例
+
+<!-- @usage badgeUsage -->
+
+<!-- @case BadgeSlot -->
+
+## Api
+
+<!-- @api OBadge -->
diff --git a/packages/opendesign/src/badge/types.ts b/packages/opendesign/src/badge/types.ts
index 9ddfe818..7558e734 100644
--- a/packages/opendesign/src/badge/types.ts
+++ b/packages/opendesign/src/badge/types.ts
@@ -5,35 +5,43 @@ export type BadgeColorT = (typeof BadgeColorTypes)[number];
 
 export const badgeProps = {
   /**
-   * 显示值
+   * @zh-CN 徽标内容
+   * @en-US Content of the badge
    */
   value: {
     type: [String, Number],
     default: '',
   },
   /**
-   * 最大值，超过最大值显示${max}+(仅当 value 类型为 number 时生效)
+   * @zh-CN 最大值，超过最大值显示${max}+(仅当 value 类型为 number 时生效)
+   * @en-US Max value, display ${max}+ if exceeded (only effective when value type is number)
+   * @default 99
    */
   max: {
     type: Number,
     default: 99,
   },
   /**
-   * 颜色类型 BadgeColorT
+   * @zh-CN 徽标颜色
+   * @en-US Color of the badge
+   * @default 'primary'
    */
   color: {
     type: String as PropType<BadgeColorT>,
     default: 'primary',
   },
   /**
-   * 是否显示为小红点
+   * @zh-CN 是否显示为小红点
+   * @en-US Whether to display as a small red dot
+   * @default false
    */
   dot: {
     type: Boolean,
     default: false,
   },
   /**
-   * 徽标位置偏移量
+   * @zh-CN 徽标位置偏移量
+   * @en-US Badge position offset
    */
   offset: {
     type: Array as PropType<Array<number | string>>,
diff --git a/packages/opendesign/src/breadcrumb/__docs__/__case__/BcUsage.vue b/packages/opendesign/src/breadcrumb/__docs__/__case__/BcUsage.vue
new file mode 100644
index 00000000..3d2cf847
--- /dev/null
+++ b/packages/opendesign/src/breadcrumb/__docs__/__case__/BcUsage.vue
@@ -0,0 +1,24 @@
+<docs lang="md">
+<!-- zh-CN -->
+
+### 基础用法
+
+通过 `href` 属性设置链接跳转地址，或者使用 `to` 属性配合 Vue Router 实现路由跳转。当 `href` 和 `to` 属性都未设置时，`OBreadcrumbItem` 组件会使用 `span` 标签渲染为一个普通的文本（这对于 SEO 是有好处的）。
+
+<!-- en-US -->
+
+### Basic Usage
+
+Set the link jump address using the `href` property, or use the `to` property in conjunction with Vue Router to achieve routing. When neither the `href` nor the `to` property is set, the `OBreadcrumbItem` component will render as a plain text using a `span` tag (which is beneficial for SEO).
+</docs>
+
+<script setup lang="ts">
+import { OBreadcrumb, OBreadcrumbItem } from '@opensig/opendesign';
+</script>
+
+<template>
+  <OBreadcrumb>
+    <OBreadcrumbItem href="/">Home</OBreadcrumbItem>
+    <OBreadcrumbItem>Current Page</OBreadcrumbItem>
+  </OBreadcrumb>
+</template>
diff --git a/packages/opendesign/src/breadcrumb/__docs__/__case__/BcVueRouter.vue b/packages/opendesign/src/breadcrumb/__docs__/__case__/BcVueRouter.vue
new file mode 100644
index 00000000..379f28ea
--- /dev/null
+++ b/packages/opendesign/src/breadcrumb/__docs__/__case__/BcVueRouter.vue
@@ -0,0 +1,54 @@
+<docs lang="md">
+<!-- zh-CN -->
+
+### 配合 Vue Router 使用
+
+当给 `OBreadcrumbItem` 组件传入 `to` 属性时，它会使用`RouterLink`组件渲染。这样可以实现与 Vue Router 的集成，支持 SPA 应用跳转。
+
+传入 `to` 属性时，`OBreadcrumbItem` 还可以使用 `replace` 属性来控制路由跳转时是否覆盖浏览器历史记录（`replace` 的值会直接传给 `RouterLink` 组件）。
+
+需要注意在使用 `OBreadcrumbItem` 时已正确配置 Vue Router。
+
+```js
+import { createRouter, createWebHistory } from 'vue-router';
+import { createApp } from 'vue';
+
+const router = createRouter({
+  /** 省略 */
+});
+const app = createApp(/** 省略 */);
+app.use(router); // 此处确保 OBreadcrumbItem 能正确解析RouterLink组件
+```
+
+<!-- en-US -->
+
+### Using with Vue Router
+
+When the `to` property is passed to the `OBreadcrumbItem` component, it will render using the `RouterLink` component. This allows integration with Vue Router, supporting SPA application navigation.
+
+When the `to` property is passed, the `OBreadcrumbItem` can also use the `replace` property to control whether the browser history is replaced during routing (the value of `replace` will be directly passed to the `RouterLink` component).
+
+It is important to ensure that Vue Router is correctly configured when using `OBreadcrumbItem`.
+
+```js
+import { createRouter, createWebHistory } from 'vue-router';
+import { createApp } from 'vue';
+
+const router = createRouter({
+  /** omitted */
+});
+const app = createApp(/** omitted */);
+app.use(router); // Ensure that OBreadcrumbItem can correctly parse the RouterLink component here
+```
+</docs>
+
+<script setup lang="ts">
+import { OBreadcrumb, OBreadcrumbItem } from '@opensig/opendesign';
+</script>
+
+<template>
+  <OBreadcrumb>
+    <OBreadcrumbItem to="/">Home</OBreadcrumbItem>
+    <OBreadcrumbItem>Current Page</OBreadcrumbItem>
+  </OBreadcrumb>
+</template>
diff --git a/packages/opendesign/src/breadcrumb/__docs__/index.en-US.md b/packages/opendesign/src/breadcrumb/__docs__/index.en-US.md
new file mode 100644
index 00000000..038c835c
--- /dev/null
+++ b/packages/opendesign/src/breadcrumb/__docs__/index.en-US.md
@@ -0,0 +1,15 @@
+---
+sidebar: OBreadcrumb
+---
+
+# Breadcrumb
+
+## Demo
+
+<!-- @case BcUsage -->
+<!-- @case BcVueRouter -->
+
+## Api
+
+<!-- @api OBreadcrumb -->
+<!-- @api OBreadcrumbItem -->
diff --git a/packages/opendesign/src/breadcrumb/__docs__/index.zh-CN.md b/packages/opendesign/src/breadcrumb/__docs__/index.zh-CN.md
new file mode 100644
index 00000000..83469f9c
--- /dev/null
+++ b/packages/opendesign/src/breadcrumb/__docs__/index.zh-CN.md
@@ -0,0 +1,15 @@
+---
+sidebar: OBreadcrumb 面包屑
+---
+
+# 面包屑
+
+## 示例
+
+<!-- @case BcUsage -->
+<!-- @case BcVueRouter -->
+
+## Api
+
+<!-- @api OBreadcrumb -->
+<!-- @api OBreadcrumbItem -->
diff --git a/packages/opendesign/src/breadcrumb/types.ts b/packages/opendesign/src/breadcrumb/types.ts
index 4f692d14..b74145a0 100644
--- a/packages/opendesign/src/breadcrumb/types.ts
+++ b/packages/opendesign/src/breadcrumb/types.ts
@@ -2,7 +2,8 @@ import type { ExtractPropTypes, PropType } from 'vue';
 
 export const breadcrumbProps = {
   /**
-   * 分隔符字符
+   * @zh-CN 分隔符字符
+   * @en-US Separator character
    */
   separator: {
     type: [String, Number],
@@ -11,33 +12,40 @@ export const breadcrumbProps = {
 
 export const breadcrumbItemProps = {
   /**
-   * 链接跳转地址
+   * @zh-CN 链接跳转地址
+   * @en-US Link jump address
    */
   href: {
     type: String,
   },
   /**
-   * 链接跳转方式
+   * @zh-CN 链接跳转方式
+   * @en-US Link jump method
+   * @default '_self'
    */
   target: {
     type: String as PropType<'_blank' | '_parent' | '_self' | '_top'>,
     default: '_self',
   },
   /**
-   * 路由跳转对象
+   * @zh-CN 路由跳转对象。当使用该参数时，OBreadcrumbItem 会渲染为 RouterLink 组件
+   * @en-US Route jump object. When using this parameter, OBreadcrumbItem will render as a RouterLink component
    */
   to: {
     type: [String, Object] as PropType<string | Record<string, unknown>>,
   },
   /**
-   * 路由跳转时，是否覆盖浏览器历史记录
+   * @zh-CN 路由跳转时，是否覆盖浏览器历史记录。该参数会作为 RouterLink 的 replace 属性
+   * @en-US Whether to replace the browser history when routing. This parameter will be used as the replace attribute of RouterLink
+   * @default false
    */
   replace: {
     type: Boolean,
     default: false,
   },
   /**
-   * 分隔符字符
+   * @zh-CN 分隔符字符。会覆盖 OBreadcrumb 的 separator 属性
+   * @en-US Separator character. This will override the separator property of OBreadcrumb
    */
   separator: {
     type: [String, Number],
diff --git a/packages/opendesign/src/button/__docs__/__case__/btnUsage.ts b/packages/opendesign/src/button/__docs__/__case__/btnUsage.ts
index da006bde..2a90027e 100644
--- a/packages/opendesign/src/button/__docs__/__case__/btnUsage.ts
+++ b/packages/opendesign/src/button/__docs__/__case__/btnUsage.ts
@@ -3,11 +3,19 @@ import { propsToAttrStr } from '../../../_demo/utils';
 // 该导出会作为该使用示例的文案，文案是markdown格式
 export const docs = {
   'zh-CN':
-    '按钮包含 `primary`、`success`、`warning`、`danger` 四种主题色，`small`、`medium`、`large` 三种尺寸，`solid`、`outline`、`text` 三种形状，`disabled` 禁用状态，`loading` 加载状态。\n' +
+    '按钮包含 `primary`、`success`、`warning`、`danger` 四种主题色；\n\n' +
+    '三种尺寸：`small`、`medium`、`large` ；\n\n' +
+    '三种形状：`solid`、`outline`、`text` ；\n\n' +
+    '禁用状态：`disabled` ；\n\n' +
+    '加载状态：`loading` ；\n\n' +
     '按钮的圆角可以通过 `pill` 设置为半圆，也可以是 css 属性 `border-radius` 能够接受的其它值。',
   'en-US':
-    'Button contains `primary`, `success`, `warning`, `danger` four theme colors, `small`, `medium`, `large` three sizes, `solid`, `outline`, `text` three shapes, `disabled` disabled state, `loading` loading state.\n' +
-    "Button's radius can be set to half circle by setting `pill` to `true`, or to css property `border-radius` accepted values.",
+    'The button includes four theme colors: `primary`, `success`, `warning`, and `danger`;\n\n' +
+    'Three sizes: `small`, `medium`, and `large`;\n\n' +
+    'Three shapes: `solid`, `outline`, and `text`;\n\n' +
+    'Disabled state: `disabled`;\n\n' +
+    'Loading state: `loading`;\n\n' +
+    'The button\'s radius can be set to half circle by setting `pill` to `true`, or to css property `border-radius` accepted values.',
 };
 
 // 该模板会在运行时被编译为vue组件，同时作为组件的源码供用户查看和复制
diff --git a/packages/opendesign/src/button/__docs__/index.en-US.md b/packages/opendesign/src/button/__docs__/index.en-US.md
index 03bb132a..182a2065 100644
--- a/packages/opendesign/src/button/__docs__/index.en-US.md
+++ b/packages/opendesign/src/button/__docs__/index.en-US.md
@@ -13,3 +13,7 @@ sidebar: OButton
 <!-- @case BtnIconSize -->
 <!-- @case BtnLoading -->
 <!-- @case BtnRound -->
+
+## Api
+
+<!-- @api OButton -->
diff --git a/packages/opendesign/src/button/__docs__/index.zh-CN.md b/packages/opendesign/src/button/__docs__/index.zh-CN.md
index c1545ea6..d5d0f33a 100644
--- a/packages/opendesign/src/button/__docs__/index.zh-CN.md
+++ b/packages/opendesign/src/button/__docs__/index.zh-CN.md
@@ -13,3 +13,7 @@ sidebar: OButton 按钮
 <!-- @case BtnIconSize -->
 <!-- @case BtnLoading -->
 <!-- @case BtnRound -->
+
+## Api
+
+<!-- @api OButton -->
diff --git a/packages/opendesign/src/button/types.ts b/packages/opendesign/src/button/types.ts
index 08cc4d16..b27eb411 100644
--- a/packages/opendesign/src/button/types.ts
+++ b/packages/opendesign/src/button/types.ts
@@ -74,6 +74,6 @@ export const buttonProps = {
     type: String,
     default: 'button',
   },
-} as const;
+};
 
 export type ButtonPropsT = ExtractPropTypes<typeof buttonProps>;
-- 
Gitee


From 07f04777f7303faf4469deed3174b78d73d492cc Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Mon, 21 Jul 2025 15:41:17 +0800
Subject: [PATCH 10/17] =?UTF-8?q?fix:=20=E4=BF=AE=E5=A4=8DpropsToAttrStr?=
 =?UTF-8?q?=E5=87=BD=E6=95=B0=E7=9A=84bug?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/opendesign/src/_demo/utils.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/opendesign/src/_demo/utils.ts b/packages/opendesign/src/_demo/utils.ts
index a705eb0b..2b9e6e7c 100644
--- a/packages/opendesign/src/_demo/utils.ts
+++ b/packages/opendesign/src/_demo/utils.ts
@@ -27,7 +27,7 @@ export function propsToAttrStr(props: Record<string, any>, exclude = [] as strin
             return `${acc} :${key}="false"`;
           }
         case 'string':
-          return `${acc} ${key}="${value}"`;
+          return `${acc} ${key}="${value.replace(/"/g, '&quot;')}"`;
         case 'number':
         case 'bigint':
           return `${acc} :${key}="${value.toString()}"`;
-- 
Gitee


From 03842b746016aa16f7a1653b863dd6c5e5bc759f Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Mon, 21 Jul 2025 15:44:33 +0800
Subject: [PATCH 11/17] =?UTF-8?q?feat:=20=E6=A8=A1=E6=9D=BF=E7=BC=96?=
 =?UTF-8?q?=E8=AF=91=E6=96=B0=E5=A2=9E=E5=8F=AF=E5=9C=A8=E6=A8=A1=E6=9D=BF?=
 =?UTF-8?q?=E4=B8=AD=E4=BD=BF=E7=94=A8=E7=9A=84ctx=E5=8F=98=E9=87=8F?=
 =?UTF-8?q?=EF=BC=8CDemoUsage=E6=96=B0=E5=A2=9Etextarea=EF=BC=8Cradio?=
 =?UTF-8?q?=E6=8E=A7=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/docs/plugins/injectDemoAndApi.ts   | 25 ++------
 packages/docs/src/components/DemoUsage.vue  | 71 ++++++++++++++++++---
 packages/docs/src/utils/compileComponent.ts | 12 +++-
 3 files changed, 78 insertions(+), 30 deletions(-)

diff --git a/packages/docs/plugins/injectDemoAndApi.ts b/packages/docs/plugins/injectDemoAndApi.ts
index ba4e7781..54ffd40e 100644
--- a/packages/docs/plugins/injectDemoAndApi.ts
+++ b/packages/docs/plugins/injectDemoAndApi.ts
@@ -20,7 +20,7 @@ export function injectDemoAndApi(): Plugin {
       const lang = getLangByFileName(id);
       const imported: {
         default?: string;
-        named?: { name: string; alias?: string }[];
+        all?: string;
         path: string;
       }[] = [];
       // 将 <!-- @case CaseComponent --> 注释替换成 <DemoContainer :demo="AutoInjectCaseComponent" />
@@ -43,18 +43,12 @@ export function injectDemoAndApi(): Plugin {
             });
             return `<DemoContainer :demo="AutoInject${fileName}" />`;
           } else {
-            const docsAlias = `autoInject${fileName}Docs`;
-            const templateAlias = `autoInject${fileName}Template`;
-            const schemaAlias = `autoInject${fileName}Schema`;
+            
             imported.push({
               path: demoFile,
-              named: [
-                { name: 'docs', alias: docsAlias },
-                { name: 'template', alias: templateAlias },
-                { name: 'schema', alias: schemaAlias },
-              ],
+              all: 'autoInjectUsage'
             });
-            return `<DemoUsage :docs="${docsAlias}" :template="${templateAlias}" :schema="${schemaAlias}" />`;
+            return `<DemoUsage :docs="autoInjectUsage.docs" :template="autoInjectUsage.template" :schema="autoInjectUsage.schema" :ctx="autoInjectUsage.ctx" />`;
           }
         }
         return match;
@@ -67,15 +61,8 @@ export function injectDemoAndApi(): Plugin {
             if (item.default) {
               importStr += `${item.default} `;
             }
-            if (item.named) {
-              importStr += `{ ${item.named
-                .map((namedItem) => {
-                  if (namedItem.alias) {
-                    return `${namedItem.name} as ${namedItem.alias}`;
-                  }
-                  return namedItem.name;
-                })
-                .join(', ')} } `;
+            if (item.all) {
+              importStr += `* as ${item.all} `;
             }
             importStr += `from ${JSON.stringify(item.path)};`;
             return importStr;
diff --git a/packages/docs/src/components/DemoUsage.vue b/packages/docs/src/components/DemoUsage.vue
index 93ad017d..947c64ad 100644
--- a/packages/docs/src/components/DemoUsage.vue
+++ b/packages/docs/src/components/DemoUsage.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import { reactive, h, Fragment, ref, watchEffect, shallowRef, type VNode,type Component, shallowReactive } from 'vue';
-import { OSelect, OOption, OInput, OInputNumber, OCheckbox, OCheckboxGroup } from '@opensig/opendesign';
+import { reactive, h, Fragment, ref, watchEffect, shallowRef, type VNode, type Component, shallowReactive } from 'vue';
+import { OSelect, OOption, OInput, OInputNumber, OCheckbox, OCheckboxGroup, OTextarea, ORadio, ORadioGroup } from '@opensig/opendesign';
 import * as prettier from 'prettier';
 import htmlPlugin from 'prettier/plugins/html';
 import babelPlugin from 'prettier/plugins/babel';
@@ -15,15 +15,24 @@ export type SchemeT =
   | {
       type: 'boolean';
       default?: boolean;
+      label?: string;
     }
   | {
       type: 'list';
       list: Array<string | number>;
       default?: string | number;
+      label?: string;
     }
   | {
       type: 'string';
       default?: string;
+      label?: string;
+    }
+  | {
+      type: 'textarea';
+      default?: string;
+      label?: string;
+      row?: number;
     }
   | {
       type: 'number';
@@ -31,6 +40,12 @@ export type SchemeT =
       min?: number;
       max?: number;
       default?: number;
+      label?: string;
+    }
+  | {
+      type: 'radio';
+      default?: string | number;
+      list: Array<string | number>;
     };
 const props = defineProps<{
   /** markdown文档 */
@@ -39,6 +54,8 @@ const props = defineProps<{
   schema: Record<string, SchemeT>;
   /** vue 模板 */
   template: string | ((_props: Record<string, any>) => string);
+  /** 传给 template 的上下文，在模板中使用 */
+  ctx?: any;
 }>();
 /**
  * 通过表单控制数据，生成表单控件响应式变量的默认值
@@ -55,9 +72,11 @@ function getInitialValues(schema: Record<string, SchemeT>) {
           checkboxGroupDefaultValue.push(key);
         }
         break;
+      case 'radio':
       case 'list':
         state[key] = value.default ?? value.list[0];
         break;
+      case 'textarea':
       case 'string':
         state[key] = value.default ?? '';
         break;
@@ -83,16 +102,18 @@ function OperatorView({ schema }: { schema: Record<string, SchemeT> }) {
   const checkboxGroup: VNode[] = [];
   /** 选着框控件 */
   const selectionOrInputGroup: VNode[] = [];
+  /** 单选框控件 */
+  const radioGroup: VNode[] = [];
   const operatorGroup: VNode[] = [];
   Object.entries(schema).forEach(([key, value]) => {
     switch (value.type) {
       case 'boolean':
-        checkboxGroup.push(h(OCheckbox, { value: key }, { default: () => key }));
+        checkboxGroup.push(h(OCheckbox, { value: key }, { default: () => value.label || key }));
         break;
       case 'list':
         selectionOrInputGroup.push(
           h(Fragment, [
-            h('span', { class: 'props-playground-selector-name' }, key),
+            h('span', { class: 'props-playground-selector-name' }, value.label || key),
             h(
               OSelect,
               { modelValue: state[key], 'onUpdate:modelValue': (val) => (state[key] = val) },
@@ -106,15 +127,28 @@ function OperatorView({ schema }: { schema: Record<string, SchemeT> }) {
       case 'string':
         selectionOrInputGroup.push(
           h(Fragment, [
-            h('span', { class: 'props-playground-selector-name' }, key),
+            h('span', { class: 'props-playground-selector-name' }, value.label || key),
             h(OInput, { modelValue: state[key], 'onUpdate:modelValue': (val) => (state[key] = val) }),
           ]),
         );
         break;
+      case 'textarea':
+        selectionOrInputGroup.push(
+          h(Fragment, [
+            h('span', { class: 'props-playground-selector-name' }, value.label || key),
+            h(OTextarea, {
+              modelValue: state[key],
+              style: { '--row': value.row || 3 },
+              class: 'props-playground-textarea',
+              'onUpdate:modelValue': (val) => (state[key] = val),
+            }),
+          ]),
+        );
+        break;
       case 'number':
         selectionOrInputGroup.push(
           h(Fragment, [
-            h('span', { class: 'props-playground-selector-name' }, key),
+            h('span', { class: 'props-playground-selector-name' }, value.label || key),
             h(OInputNumber, {
               modelValue: state[key],
               'onUpdate:modelValue': (val) => (state[key] = val),
@@ -125,8 +159,20 @@ function OperatorView({ schema }: { schema: Record<string, SchemeT> }) {
           ]),
         );
         break;
+      case 'radio':
+        radioGroup.push(
+          h(
+            ORadioGroup,
+            { modelValue: state[key], class: 'radio-group', 'onUpdate:modelValue': (val) => (state[key] = val) },
+            { default: () => value.list.map((item) => h(ORadio, { value: item }, { default: () => item })) },
+          ),
+        );
+        break;
     }
   });
+  if (radioGroup.length) {
+    operatorGroup.push(h(Fragment, radioGroup));
+  }
   if (checkboxGroup.length) {
     operatorGroup.push(
       h(
@@ -179,7 +225,7 @@ function createShowcaseComponent(demoProps: Record<string, any>) {
       sourceCode.value = code;
       highlightedCode.value = highlight(code, 'vue');
     });
-  return compileComponent(template);
+  return compileComponent(template, props.ctx);
 }
 /**
  * 函数式组件，用来渲染 showcaseComponent 的演示组件，以及OperatorView表单控件
@@ -242,12 +288,14 @@ Demo.__docs = docs;
 :deep(.props-playground-operator) {
   padding: var(--o3-gap-4);
   border-left: 1px solid var(--o-color-control1-light);
+  max-width: 40%;
   @include respond-to('<=pad') {
+    max-width: none;
     border-top: 1px solid var(--o-color-control1-light);
     border-left: none;
   }
 }
-:deep(.checkbox-group) {
+:deep(.checkbox-group), :deep(.radio-group) {
   display: flex;
   flex-wrap: wrap;
   margin-bottom: var(--o3-gap-3);
@@ -267,4 +315,11 @@ Demo.__docs = docs;
   display: flex;
   align-items: center;
 }
+:deep(.o-input-number) {
+  width: 100%;
+}
+
+:deep(.props-playground-textarea) {
+  height: calc(var(--row) * var(--_box-text-height));
+}
 </style>
diff --git a/packages/docs/src/utils/compileComponent.ts b/packages/docs/src/utils/compileComponent.ts
index 21b2a488..9f1a10ff 100644
--- a/packages/docs/src/utils/compileComponent.ts
+++ b/packages/docs/src/utils/compileComponent.ts
@@ -1,12 +1,18 @@
 import * as Vue from 'vue';
 import { compile, type CompilerOptions } from '@vue/compiler-dom';
 
-export function compileComponent(template: string, options: Omit<CompilerOptions, 'filename' | 'mode'> = {}): Vue.Component {
+/**
+ * 将模板编译为组件
+ * @param template 模板字符串
+ * @param ctx 在模板中使用的数据
+ * @param options
+ * @returns 组件
+ */
+export function compileComponent(template: string, ctx: any, options: Omit<CompilerOptions, 'filename' | 'mode'> = {}): Vue.Component {
   const { code } = compile(template, {
     ...options,
     mode: 'function',
   });
-  console.log('Compiled code:', code);
-  const component = new Function('Vue', code)(Vue);
+  const component = new Function('Vue', 'ctx', code)(Vue, ctx);
   return component;
 }
-- 
Gitee


From 1f4d38c10a6072a668af54b1c7ea2112210ef3cf Mon Sep 17 00:00:00 2001
From: AC-0308 <pzzxtyh@qq.com>
Date: Mon, 21 Jul 2025 16:32:55 +0800
Subject: [PATCH 12/17] =?UTF-8?q?doc:=20=F0=9F=93=9D=20=E5=A2=9E=E5=8A=A0?=
 =?UTF-8?q?=E8=99=9A=E6=8B=9F=E6=BB=9A=E5=8A=A8(virtual-list)=E7=9A=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

---
 .../__docs__/__case__/VirtualListAPI.vue      |  92 +++++++++
 .../__docs__/__case__/VirtualListBasic.vue    | 190 ++++++++++++++++++
 .../__docs__/__case__/VirtualListDynamic.vue  |  82 ++++++++
 .../virtual-list/__docs__/__case__/style.scss |  39 ++++
 .../__docs__/__case__/virtualListUsage.ts     |  53 +++++
 .../src/virtual-list/__docs__/index.en-US.md  |  15 ++
 .../src/virtual-list/__docs__/index.zh-CN.md  |  15 ++
 7 files changed, 486 insertions(+)
 create mode 100644 packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListAPI.vue
 create mode 100644 packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListBasic.vue
 create mode 100644 packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListDynamic.vue
 create mode 100644 packages/opendesign/src/virtual-list/__docs__/__case__/style.scss
 create mode 100644 packages/opendesign/src/virtual-list/__docs__/__case__/virtualListUsage.ts
 create mode 100644 packages/opendesign/src/virtual-list/__docs__/index.en-US.md
 create mode 100644 packages/opendesign/src/virtual-list/__docs__/index.zh-CN.md

diff --git a/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListAPI.vue b/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListAPI.vue
new file mode 100644
index 00000000..47bd6f5e
--- /dev/null
+++ b/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListAPI.vue
@@ -0,0 +1,92 @@
+<docs lang="md">
+<!--zh-CN-->
+### API 调用
+
+<!--en-US-->
+### API Call
+</docs>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { OVirtualList } from '@opensig/opendesign';
+
+const list = ref(
+  new Array(50).fill(1).map((_, idx) => ({
+    label: idx + 1,
+    height: Math.floor(Math.random() * 80 + 40),
+  }))
+);
+
+const defaultStartIndex = 10;
+const index = ref(5);
+const virtualRef = ref<InstanceType<typeof OVirtualList>>();
+const virtualRef2 = ref<InstanceType<typeof OVirtualList>>();
+const onClick = () => {
+  const to = Math.max(index.value - 1, 0);
+  virtualRef.value?.scrollToView(to, 'center', 'smooth');
+  virtualRef2.value?.scrollToView(to, 'start');
+};
+</script>
+<template>
+  <div>
+    <div>
+      <input v-model="index" />
+      <button @click="onClick">滚动到</button>
+    </div>
+    <div class="row">
+      <div class="col">
+        <div>
+          <h5>高度固定且一致， 滚动到居中对齐： 'center'</h5>
+          <OVirtualList ref="virtualRef" class="container" :list="list" :default-start-index="defaultStartIndex" :item-size="80">
+            <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>
+        </div>
+      </div>
+      <div class="col">
+        <div>
+          <h5>动态高度，滚动到顶部对齐：'start'</h5>
+          <OVirtualList ref="virtualRef2" class="container" :list="list" :default-start-index="defaultStartIndex" :default-item-size="80">
+            <template #default="{ item, index }">
+              <div :key="item.label" class="section" :class="`item-${index + 1}`" :style="{ height: item.height + 'px' }">
+                <span>Row:</span> <span>{{ item.label }}</span
+                >------<span>Height:</span> <span>{{ item.height }}</span>
+              </div>
+            </template>
+          </OVirtualList>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+<style lang="scss" scoped>
+@use "sass:math";
+.container {
+  width: 400px;
+  height: 300px;
+  border: 2px solid rgb(111, 45, 234);
+  box-sizing: border-box;
+  display: flex;
+}
+
+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);
+  }
+}
+</style>
diff --git a/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListBasic.vue b/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListBasic.vue
new file mode 100644
index 00000000..47bde056
--- /dev/null
+++ b/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListBasic.vue
@@ -0,0 +1,190 @@
+<docs lang="md">
+<!--zh-CN-->
+### Scroller basic
+
+<!--en-US-->
+### Scroller basic
+</docs>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { OVirtualList, RenderIndexInfo, BaseScrollerPropsT } from '@opensig/opendesign';
+import { uniqueId } from '../../../_utils/helper';
+
+const list = ref(
+  new Array(50).fill(1).map((_, idx) => ({
+    label: idx + 1,
+    height: Math.floor(Math.random() * 80 + 40),
+  }))
+);
+
+const onClick = (item: any) => {
+  item.height -= 10;
+};
+
+const containerHeight = ref(300);
+const changeContainerSize = () => {
+  containerHeight.value += 100;
+};
+
+const list2 = ref(
+  new Array(20).fill(1).map((_, idx) => ({
+    id: uniqueId(),
+    label: `${idx + 1}`,
+    height: Math.floor(Math.random() * 80 + 40),
+  }))
+);
+const changeListData = () => {
+  const n = new Array(10).fill(1).map((_, idx) => ({
+    id: uniqueId(),
+    label: `add${idx + 1}`,
+    height: Math.floor(Math.random() * 80 + 40),
+  }));
+  list2.value = list2.value.concat(n);
+};
+
+const scrollbarProps: Partial<BaseScrollerPropsT> = {
+  showType: 'always',
+  size: 'medium',
+  autoUpdateOnScrollSize: true,
+};
+const onRenderChange = (params: RenderIndexInfo) => {
+  console.log(params.start, params.end, params.count, params.visible);
+};
+</script>
+<template>
+  <div class="row">
+    <div class="col">
+      <h5>高度固定且一致 default-start-index: 10</h5>
+      <OVirtualList class="container" :list="list" :default-start-index="10" :item-size="80" @render-change="onRenderChange">
+        <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>
+    </div>
+    <div class="col">
+      <h5>动态高度 default-start-index: 10</h5>
+      <OVirtualList class="container" :list="list" :default-start-index="10" @render-change="onRenderChange">
+        <template #default="{ item, index }">
+          <div :key="item.label" class="section" :class="`item-${index + 1}`" :style="{ height: item.height + 'px' }" @click="onClick(item)">
+            <span>Row:</span> <span>{{ item.label }}</span
+            >------<span>Height:</span> <span>{{ item.height }}</span>
+          </div>
+        </template>
+      </OVirtualList>
+    </div>
+  </div>
+
+  <h4>容器变化</h4>
+  <button @click="changeContainerSize">容器高度+20</button>
+
+  <div class="row">
+    <div class="col">
+      <OVirtualList
+        class="container2"
+        :list="list"
+        :default-start-index="10"
+        :style="{ height: containerHeight + 'px' }"
+        :item-size="80"
+        @render-change="onRenderChange"
+      >
+        <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>
+    </div>
+    <div class="col">
+      <OVirtualList class="container2" :list="list" :default-start-index="44" :style="{ height: containerHeight + 'px' }" @render-change="onRenderChange">
+        <template #default="{ item, index }">
+          <div :key="item.label" class="section" :class="`item-${index + 1}`" :style="{ height: item.height + 'px' }">
+            <span>Row:</span> <span>{{ item.label }}</span
+            >------<span>Height:</span> <span>80px</span>
+          </div>
+        </template>
+      </OVirtualList>
+    </div>
+  </div>
+  <h4>数据变化</h4>
+  <button @click="changeListData">数据变化 长度+10</button> <span> list length: {{ list2.length }}</span>
+
+  <div class="row">
+    <div class="col">
+      <OVirtualList
+        class="container2"
+        :list="list2"
+        :default-start-index="10"
+        :style="{ height: containerHeight + 'px' }"
+        :item-size="80"
+        :scrollbar="scrollbarProps"
+      >
+        <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>
+    </div>
+    <div class="col">
+      <OVirtualList
+        class="container2"
+        :list="list2"
+        :default-start-index="10"
+        :style="{ height: containerHeight + 'px' }"
+        :scrollbar="scrollbarProps"
+        @render-change="onRenderChange"
+      >
+        <template #default="{ item, index }">
+          <div :key="item.label" class="section" :class="`item-${index + 1}`" :style="{ height: item.height + 'px' }">
+            <span>Row:</span> <span>{{ item.label }}</span
+            >------<span>Height:</span> <span>{{ item.height }}</span>
+          </div>
+        </template>
+      </OVirtualList>
+    </div>
+  </div>
+</template>
+<style lang="scss" scoped>
+@use "sass:math";
+.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 50 {
+  .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);
+}
+</style>
diff --git a/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListDynamic.vue b/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListDynamic.vue
new file mode 100644
index 00000000..cae58a32
--- /dev/null
+++ b/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListDynamic.vue
@@ -0,0 +1,82 @@
+<docs lang="md">
+<!--zh-CN-->
+### 动态追加数据（支持头部或尾部追加数据）
+
+<!--en-US-->
+### Dynamically append data (supports adding to the head or tail)
+</docs>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { uniqueId } from '../../../_utils/helper';
+import { OVirtualList, RenderIndexInfo } from '@opensig/opendesign';
+
+const list = ref(
+  new Array(50).fill(1).map((_, idx) => ({
+    id: uniqueId(),
+    label: `${idx + 1}`,
+    height: Math.floor(Math.random() * 80 + 40),
+  }))
+);
+
+const onRenderChange = (renderIndex: RenderIndexInfo) => {
+  const { start, end, visible, count } = renderIndex;
+  console.log(start, end, visible, count);
+  if (start <= 5) {
+    const n = new Array(10).fill(1).map((_, idx) => ({
+      id: uniqueId(),
+      label: `add${idx + 1}`,
+      height: Math.floor(Math.random() * 80 + 40),
+    }));
+    list.value = n.concat(list.value);
+  } else if (start >= list.value.length - 5) {
+    const n = new Array(10).fill(1).map((_, idx) => ({
+      id: uniqueId(),
+      label: `add${idx + 1}`,
+      height: Math.floor(Math.random() * 80 + 40),
+    }));
+    list.value = list.value.concat(n);
+  }
+};
+</script>
+<template>
+  <div>
+    <h5>【数据添加id】根据滚动显示的位置，动态增加数据（向上滚动头部添加数据，向下滚动尾部追加数据）</h5>
+    <OVirtualList class="container" :list="list" :default-start-index="10" :item-size="80" @renderChange="onRenderChange">
+      <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>
+  </div>
+</template>
+<style lang="scss" scoped>
+@use "sass:math";
+
+.container {
+  width: 400px;
+  height: 300px;
+  border: 2px solid rgb(111, 45, 234);
+  box-sizing: border-box;
+  display: flex;
+}
+
+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);
+  }
+}
+</style>
diff --git a/packages/opendesign/src/virtual-list/__docs__/__case__/style.scss b/packages/opendesign/src/virtual-list/__docs__/__case__/style.scss
new file mode 100644
index 00000000..e2beaf55
--- /dev/null
+++ b/packages/opendesign/src/virtual-list/__docs__/__case__/style.scss
@@ -0,0 +1,39 @@
+@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__/__case__/virtualListUsage.ts b/packages/opendesign/src/virtual-list/__docs__/__case__/virtualListUsage.ts
new file mode 100644
index 00000000..d19e776f
--- /dev/null
+++ b/packages/opendesign/src/virtual-list/__docs__/__case__/virtualListUsage.ts
@@ -0,0 +1,53 @@
+import { propsToAttrStr } from '../../../_demo/utils';
+import './style.scss';
+
+// 该导出会作为该使用示例的文案，文案是markdown格式
+export const docs = {
+  'zh-CN':
+    '虚拟滚动用于控制列表中渲染项目的数量以达到优化渲染性能的目的。  \n' +
+    '可设置项包含  \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.  \n' +
+    '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',
+};
+
+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>`;
+};
+
+export const schema = {
+  defaultStartIndex: {
+    type: 'number',
+    default: 10
+  },
+  itemSize: {
+    type: 'number',
+    default: 80
+  },
+  buffer: {
+    type: 'number',
+    default: 1,
+  },
+};
\ 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
new file mode 100644
index 00000000..129f1a18
--- /dev/null
+++ b/packages/opendesign/src/virtual-list/__docs__/index.en-US.md
@@ -0,0 +1,15 @@
+---
+sidebar: OVirtualList
+---
+
+# virtual list
+
+## Usage
+
+<!-- @usage virtualUsage -->
+
+## Cases
+
+<!-- @case VirtualListAPI -->
+<!-- @case VirtualListBasic -->
+<!-- @case VirtualListDynamic -->
diff --git a/packages/opendesign/src/virtual-list/__docs__/index.zh-CN.md b/packages/opendesign/src/virtual-list/__docs__/index.zh-CN.md
new file mode 100644
index 00000000..b0fb6091
--- /dev/null
+++ b/packages/opendesign/src/virtual-list/__docs__/index.zh-CN.md
@@ -0,0 +1,15 @@
+---
+sidebar: OVirtualList 虚拟滚动
+---
+
+# 虚拟滚动
+
+## 使用
+
+<!-- @usage virtualListUsage -->
+
+## 示例
+
+<!-- @case VirtualListAPI -->
+<!-- @case VirtualListBasic -->
+<!-- @case VirtualListDynamic -->
-- 
Gitee


From c7e5b2493ec1a64738d8a147835badf73e3a3016 Mon Sep 17 00:00:00 2001
From: AC-0308 <pzzxtyh@qq.com>
Date: Mon, 21 Jul 2025 16:32:55 +0800
Subject: [PATCH 13/17] =?UTF-8?q?doc:=20=F0=9F=93=9D=20=E5=A2=9E=E5=8A=A0?=
 =?UTF-8?q?=E8=99=9A=E6=8B=9F=E6=BB=9A=E5=8A=A8(virtual-list)=E7=9A=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

---
 .../__docs__/__case__/VirtualListAPI.vue      |  92 +++++++++
 .../__docs__/__case__/VirtualListBasic.vue    | 190 ++++++++++++++++++
 .../__docs__/__case__/VirtualListDynamic.vue  |  82 ++++++++
 .../virtual-list/__docs__/__case__/style.scss |  39 ++++
 .../__docs__/__case__/virtualListUsage.ts     |  51 +++++
 .../src/virtual-list/__docs__/index.en-US.md  |  19 ++
 .../src/virtual-list/__docs__/index.zh-CN.md  |  19 ++
 7 files changed, 492 insertions(+)
 create mode 100644 packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListAPI.vue
 create mode 100644 packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListBasic.vue
 create mode 100644 packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListDynamic.vue
 create mode 100644 packages/opendesign/src/virtual-list/__docs__/__case__/style.scss
 create mode 100644 packages/opendesign/src/virtual-list/__docs__/__case__/virtualListUsage.ts
 create mode 100644 packages/opendesign/src/virtual-list/__docs__/index.en-US.md
 create mode 100644 packages/opendesign/src/virtual-list/__docs__/index.zh-CN.md

diff --git a/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListAPI.vue b/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListAPI.vue
new file mode 100644
index 00000000..47bd6f5e
--- /dev/null
+++ b/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListAPI.vue
@@ -0,0 +1,92 @@
+<docs lang="md">
+<!--zh-CN-->
+### API 调用
+
+<!--en-US-->
+### API Call
+</docs>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { OVirtualList } from '@opensig/opendesign';
+
+const list = ref(
+  new Array(50).fill(1).map((_, idx) => ({
+    label: idx + 1,
+    height: Math.floor(Math.random() * 80 + 40),
+  }))
+);
+
+const defaultStartIndex = 10;
+const index = ref(5);
+const virtualRef = ref<InstanceType<typeof OVirtualList>>();
+const virtualRef2 = ref<InstanceType<typeof OVirtualList>>();
+const onClick = () => {
+  const to = Math.max(index.value - 1, 0);
+  virtualRef.value?.scrollToView(to, 'center', 'smooth');
+  virtualRef2.value?.scrollToView(to, 'start');
+};
+</script>
+<template>
+  <div>
+    <div>
+      <input v-model="index" />
+      <button @click="onClick">滚动到</button>
+    </div>
+    <div class="row">
+      <div class="col">
+        <div>
+          <h5>高度固定且一致， 滚动到居中对齐： 'center'</h5>
+          <OVirtualList ref="virtualRef" class="container" :list="list" :default-start-index="defaultStartIndex" :item-size="80">
+            <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>
+        </div>
+      </div>
+      <div class="col">
+        <div>
+          <h5>动态高度，滚动到顶部对齐：'start'</h5>
+          <OVirtualList ref="virtualRef2" class="container" :list="list" :default-start-index="defaultStartIndex" :default-item-size="80">
+            <template #default="{ item, index }">
+              <div :key="item.label" class="section" :class="`item-${index + 1}`" :style="{ height: item.height + 'px' }">
+                <span>Row:</span> <span>{{ item.label }}</span
+                >------<span>Height:</span> <span>{{ item.height }}</span>
+              </div>
+            </template>
+          </OVirtualList>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+<style lang="scss" scoped>
+@use "sass:math";
+.container {
+  width: 400px;
+  height: 300px;
+  border: 2px solid rgb(111, 45, 234);
+  box-sizing: border-box;
+  display: flex;
+}
+
+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);
+  }
+}
+</style>
diff --git a/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListBasic.vue b/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListBasic.vue
new file mode 100644
index 00000000..47bde056
--- /dev/null
+++ b/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListBasic.vue
@@ -0,0 +1,190 @@
+<docs lang="md">
+<!--zh-CN-->
+### Scroller basic
+
+<!--en-US-->
+### Scroller basic
+</docs>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { OVirtualList, RenderIndexInfo, BaseScrollerPropsT } from '@opensig/opendesign';
+import { uniqueId } from '../../../_utils/helper';
+
+const list = ref(
+  new Array(50).fill(1).map((_, idx) => ({
+    label: idx + 1,
+    height: Math.floor(Math.random() * 80 + 40),
+  }))
+);
+
+const onClick = (item: any) => {
+  item.height -= 10;
+};
+
+const containerHeight = ref(300);
+const changeContainerSize = () => {
+  containerHeight.value += 100;
+};
+
+const list2 = ref(
+  new Array(20).fill(1).map((_, idx) => ({
+    id: uniqueId(),
+    label: `${idx + 1}`,
+    height: Math.floor(Math.random() * 80 + 40),
+  }))
+);
+const changeListData = () => {
+  const n = new Array(10).fill(1).map((_, idx) => ({
+    id: uniqueId(),
+    label: `add${idx + 1}`,
+    height: Math.floor(Math.random() * 80 + 40),
+  }));
+  list2.value = list2.value.concat(n);
+};
+
+const scrollbarProps: Partial<BaseScrollerPropsT> = {
+  showType: 'always',
+  size: 'medium',
+  autoUpdateOnScrollSize: true,
+};
+const onRenderChange = (params: RenderIndexInfo) => {
+  console.log(params.start, params.end, params.count, params.visible);
+};
+</script>
+<template>
+  <div class="row">
+    <div class="col">
+      <h5>高度固定且一致 default-start-index: 10</h5>
+      <OVirtualList class="container" :list="list" :default-start-index="10" :item-size="80" @render-change="onRenderChange">
+        <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>
+    </div>
+    <div class="col">
+      <h5>动态高度 default-start-index: 10</h5>
+      <OVirtualList class="container" :list="list" :default-start-index="10" @render-change="onRenderChange">
+        <template #default="{ item, index }">
+          <div :key="item.label" class="section" :class="`item-${index + 1}`" :style="{ height: item.height + 'px' }" @click="onClick(item)">
+            <span>Row:</span> <span>{{ item.label }}</span
+            >------<span>Height:</span> <span>{{ item.height }}</span>
+          </div>
+        </template>
+      </OVirtualList>
+    </div>
+  </div>
+
+  <h4>容器变化</h4>
+  <button @click="changeContainerSize">容器高度+20</button>
+
+  <div class="row">
+    <div class="col">
+      <OVirtualList
+        class="container2"
+        :list="list"
+        :default-start-index="10"
+        :style="{ height: containerHeight + 'px' }"
+        :item-size="80"
+        @render-change="onRenderChange"
+      >
+        <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>
+    </div>
+    <div class="col">
+      <OVirtualList class="container2" :list="list" :default-start-index="44" :style="{ height: containerHeight + 'px' }" @render-change="onRenderChange">
+        <template #default="{ item, index }">
+          <div :key="item.label" class="section" :class="`item-${index + 1}`" :style="{ height: item.height + 'px' }">
+            <span>Row:</span> <span>{{ item.label }}</span
+            >------<span>Height:</span> <span>80px</span>
+          </div>
+        </template>
+      </OVirtualList>
+    </div>
+  </div>
+  <h4>数据变化</h4>
+  <button @click="changeListData">数据变化 长度+10</button> <span> list length: {{ list2.length }}</span>
+
+  <div class="row">
+    <div class="col">
+      <OVirtualList
+        class="container2"
+        :list="list2"
+        :default-start-index="10"
+        :style="{ height: containerHeight + 'px' }"
+        :item-size="80"
+        :scrollbar="scrollbarProps"
+      >
+        <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>
+    </div>
+    <div class="col">
+      <OVirtualList
+        class="container2"
+        :list="list2"
+        :default-start-index="10"
+        :style="{ height: containerHeight + 'px' }"
+        :scrollbar="scrollbarProps"
+        @render-change="onRenderChange"
+      >
+        <template #default="{ item, index }">
+          <div :key="item.label" class="section" :class="`item-${index + 1}`" :style="{ height: item.height + 'px' }">
+            <span>Row:</span> <span>{{ item.label }}</span
+            >------<span>Height:</span> <span>{{ item.height }}</span>
+          </div>
+        </template>
+      </OVirtualList>
+    </div>
+  </div>
+</template>
+<style lang="scss" scoped>
+@use "sass:math";
+.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 50 {
+  .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);
+}
+</style>
diff --git a/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListDynamic.vue b/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListDynamic.vue
new file mode 100644
index 00000000..cae58a32
--- /dev/null
+++ b/packages/opendesign/src/virtual-list/__docs__/__case__/VirtualListDynamic.vue
@@ -0,0 +1,82 @@
+<docs lang="md">
+<!--zh-CN-->
+### 动态追加数据（支持头部或尾部追加数据）
+
+<!--en-US-->
+### Dynamically append data (supports adding to the head or tail)
+</docs>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { uniqueId } from '../../../_utils/helper';
+import { OVirtualList, RenderIndexInfo } from '@opensig/opendesign';
+
+const list = ref(
+  new Array(50).fill(1).map((_, idx) => ({
+    id: uniqueId(),
+    label: `${idx + 1}`,
+    height: Math.floor(Math.random() * 80 + 40),
+  }))
+);
+
+const onRenderChange = (renderIndex: RenderIndexInfo) => {
+  const { start, end, visible, count } = renderIndex;
+  console.log(start, end, visible, count);
+  if (start <= 5) {
+    const n = new Array(10).fill(1).map((_, idx) => ({
+      id: uniqueId(),
+      label: `add${idx + 1}`,
+      height: Math.floor(Math.random() * 80 + 40),
+    }));
+    list.value = n.concat(list.value);
+  } else if (start >= list.value.length - 5) {
+    const n = new Array(10).fill(1).map((_, idx) => ({
+      id: uniqueId(),
+      label: `add${idx + 1}`,
+      height: Math.floor(Math.random() * 80 + 40),
+    }));
+    list.value = list.value.concat(n);
+  }
+};
+</script>
+<template>
+  <div>
+    <h5>【数据添加id】根据滚动显示的位置，动态增加数据（向上滚动头部添加数据，向下滚动尾部追加数据）</h5>
+    <OVirtualList class="container" :list="list" :default-start-index="10" :item-size="80" @renderChange="onRenderChange">
+      <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>
+  </div>
+</template>
+<style lang="scss" scoped>
+@use "sass:math";
+
+.container {
+  width: 400px;
+  height: 300px;
+  border: 2px solid rgb(111, 45, 234);
+  box-sizing: border-box;
+  display: flex;
+}
+
+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);
+  }
+}
+</style>
diff --git a/packages/opendesign/src/virtual-list/__docs__/__case__/style.scss b/packages/opendesign/src/virtual-list/__docs__/__case__/style.scss
new file mode 100644
index 00000000..e2beaf55
--- /dev/null
+++ b/packages/opendesign/src/virtual-list/__docs__/__case__/style.scss
@@ -0,0 +1,39 @@
+@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__/__case__/virtualListUsage.ts b/packages/opendesign/src/virtual-list/__docs__/__case__/virtualListUsage.ts
new file mode 100644
index 00000000..e316e966
--- /dev/null
+++ b/packages/opendesign/src/virtual-list/__docs__/__case__/virtualListUsage.ts
@@ -0,0 +1,51 @@
+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',
+};
+
+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>`;
+};
+
+export const schema = {
+  defaultStartIndex: {
+    type: 'number',
+    default: 10
+  },
+  itemSize: {
+    type: 'number',
+    default: 80
+  },
+  buffer: {
+    type: 'number',
+    default: 1,
+  },
+};
\ 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
new file mode 100644
index 00000000..489e5597
--- /dev/null
+++ b/packages/opendesign/src/virtual-list/__docs__/index.en-US.md
@@ -0,0 +1,19 @@
+---
+sidebar: OVirtualList
+---
+
+# virtual list
+
+## Usage
+
+<!-- @usage virtualUsage -->
+
+## Cases
+
+<!-- @case VirtualListAPI -->
+<!-- @case VirtualListBasic -->
+<!-- @case VirtualListDynamic -->
+
+## Api
+
+<!-- @api OVirtualList -->
\ No newline at end of file
diff --git a/packages/opendesign/src/virtual-list/__docs__/index.zh-CN.md b/packages/opendesign/src/virtual-list/__docs__/index.zh-CN.md
new file mode 100644
index 00000000..195125e7
--- /dev/null
+++ b/packages/opendesign/src/virtual-list/__docs__/index.zh-CN.md
@@ -0,0 +1,19 @@
+---
+sidebar: OVirtualList 虚拟滚动
+---
+
+# 虚拟滚动
+
+## 使用
+
+<!-- @usage virtualListUsage -->
+
+## 示例
+
+<!-- @case VirtualListAPI -->
+<!-- @case VirtualListBasic -->
+<!-- @case VirtualListDynamic -->
+
+## Api
+
+<!-- @api OVirtualList -->
\ No newline at end of file
-- 
Gitee


From 1d25af7fc9edacfbc6c148abf2b471eea60e8b04 Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Tue, 22 Jul 2025 09:21:39 +0800
Subject: [PATCH 14/17] =?UTF-8?q?feat[doc]:=20=E8=B0=83=E6=95=B4=E6=9E=84?=
 =?UTF-8?q?=E4=BB=B6=E8=BE=93=E5=87=BA=E7=9B=AE=E5=BD=95=E5=92=8C=E6=9E=84?=
 =?UTF-8?q?=E4=BB=B6=E5=90=8D=E5=88=A9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/docs/package.json   | 3 ++-
 packages/docs/vite.config.ts | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/docs/package.json b/packages/docs/package.json
index 20d51206..3e831ee2 100644
--- a/packages/docs/package.json
+++ b/packages/docs/package.json
@@ -5,7 +5,8 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "vue-tsc && vite build",
+    "build": "vite build",
+    "type-check": "vue-tsc",
     "preview": "vite preview",
     "gen:api": "vite-node ./scripts/generateApi.ts"
   },
diff --git a/packages/docs/vite.config.ts b/packages/docs/vite.config.ts
index 7cbe9cf7..eeab8be2 100644
--- a/packages/docs/vite.config.ts
+++ b/packages/docs/vite.config.ts
@@ -14,7 +14,7 @@ export default defineConfig({
   base: './',
   build: {
     target: ['chrome74'],
-    outDir: '../../output/o',
+    outDir: './dist',
   },
   plugins: [
     vue({
-- 
Gitee


From 6f0b1d44a9f187eeb2c35d4e03f8bbcc092afa66 Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Tue, 22 Jul 2025 09:39:23 +0800
Subject: [PATCH 15/17] =?UTF-8?q?fix[doc]:=20=E8=B0=83=E6=95=B4injectDemoD?=
 =?UTF-8?q?ocs=E6=8F=92=E4=BB=B6=E4=BB=A5=E6=94=AF=E6=8C=81=E6=A8=A1?=
 =?UTF-8?q?=E5=9D=97=E7=9A=84=E7=9B=B8=E5=AF=B9=E8=B7=AF=E5=BE=84=E5=AF=BC?=
 =?UTF-8?q?=E5=85=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/docs/plugins/injectDemoDocs.ts | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/docs/plugins/injectDemoDocs.ts b/packages/docs/plugins/injectDemoDocs.ts
index 8ff49cf8..d196b25c 100644
--- a/packages/docs/plugins/injectDemoDocs.ts
+++ b/packages/docs/plugins/injectDemoDocs.ts
@@ -22,10 +22,9 @@ const parseVueQuery = (id: string) => {
   return { file, query: queryObj, queryExtension };
 };
 
-const VIRTUAL_PREFIX = 'virtual:demo-docs:';
 const virtualModules = new Map<string, { langCode: string; lang: string }>();
 const genVirtualId = (id: string, lang: string) => {
-  return `${VIRTUAL_PREFIX}${id.split('?')[0]}-${lang}.md`;
+  return `${id.split('?')[0]}-${lang}.md`;
 };
 /**
  * vite插件，将vue文件中的自定义块 docs 中的 markdown 保存到_sfc_main.__docs中，
-- 
Gitee


From aaa8b2ff5d19a92a16769838522d676f1a9fa602 Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Tue, 22 Jul 2025 09:40:53 +0800
Subject: [PATCH 16/17] =?UTF-8?q?fix[doc]:=20=E4=BC=98=E5=8C=96getHeads?=
 =?UTF-8?q?=E5=87=BD=E6=95=B0=EF=BC=8C=E7=94=9F=E6=88=90=E6=9B=B4=E6=98=93?=
 =?UTF-8?q?=E8=AF=BB=E7=9A=84id?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/docs/src/utils/getHeads.ts | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/packages/docs/src/utils/getHeads.ts b/packages/docs/src/utils/getHeads.ts
index ed91b967..4d8fbf65 100644
--- a/packages/docs/src/utils/getHeads.ts
+++ b/packages/docs/src/utils/getHeads.ts
@@ -1,3 +1,15 @@
+/**
+ * 将h标签的标题转换为规范的id（该id会作为h标签的id以及a便签的href）
+ * @param title 待转换的标题
+ * @returns id
+ */
+function escapeTitle(title: string) {
+  return title
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    // 转换特殊字符，但不转化 unicode 字符
+    .replace(/[;,/?:@&=+$#]/g, (char) => encodeURIComponent(char));
+}
 /**
  * 获取h标签
  * @param el h标签的父元素dom，用来限定h标签查找范围
@@ -26,7 +38,7 @@ export function getHeads(el: HTMLElement, minLevel = 2) {
     if (dom.id) {
       id = dom.id;
     } else {
-      id = encodeURIComponent(title.replace(/\s+/g, '-').toLowerCase());
+      id = escapeTitle(title);
     }
     // 判断是否有重名id，如果有则加上数字编号；该id会作为锚点的href
     if (headerId[id]) {
-- 
Gitee


From 062e3049ab0b57cf975c28107a77b6c6ee1df95a Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Tue, 22 Jul 2025 09:41:21 +0800
Subject: [PATCH 17/17] =?UTF-8?q?fix:=20=E4=BC=98=E5=8C=96DemoContainer?=
 =?UTF-8?q?=E7=BB=84=E4=BB=B6=E6=A0=B7=E5=BC=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/docs/src/components/DemoContainer.vue | 17 +++++++----------
 1 file changed, 7 insertions(+), 10 deletions(-)

diff --git a/packages/docs/src/components/DemoContainer.vue b/packages/docs/src/components/DemoContainer.vue
index 9f7ab5b0..caa17c59 100644
--- a/packages/docs/src/components/DemoContainer.vue
+++ b/packages/docs/src/components/DemoContainer.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { ref, h, type Component, PropType } from 'vue';
+import { ref, h, type Component, type PropType } from 'vue';
 import { OScroller, OButton, useI18n, OIconChevronUp } from '@opensig/opendesign';
 
 type DocT = Record<string, string | Component>;
@@ -36,11 +36,6 @@ const Docs = ({ docs, locale }: { docs?: DocT; locale: string }) => {
 
 <template>
   <div class="demo-container">
-    <Docs :docs="props.demo.__docs" :locale="locale" />
-    <div class="demo">
-      <Component :is="props.demo" />
-    </div>
-
     <div class="operator">
       <!-- 隐藏或显示代码块的按钮 -->
       <OButton variant="solid" size="small" @click="switchShowCode">
@@ -55,6 +50,10 @@ const Docs = ({ docs, locale }: { docs?: DocT; locale: string }) => {
         </template>
       </OButton>
     </div>
+    <Docs :docs="props.demo.__docs" :locale="locale" />
+    <div class="demo">
+      <Component :is="props.demo" />
+    </div>
     <!-- 代码块 -->
     <OScroller v-show="isShowCode" v-if="props.demo.DemoSource" class="source">
       <Component :is="props.demo.DemoSource" />
@@ -64,7 +63,6 @@ const Docs = ({ docs, locale }: { docs?: DocT; locale: string }) => {
 <style lang="scss" scoped>
 .demo-container {
   border: 1px solid var(--o-color-control1-light);
-  position: relative;
   & + .demo-container {
     margin-top: 12px;
   }
@@ -103,9 +101,8 @@ const Docs = ({ docs, locale }: { docs?: DocT; locale: string }) => {
   display: flex;
   justify-content: flex-end;
   align-items: center;
-  position: absolute;
-  right: var(--o3-gap-4);
-  top: var(--o3-gap-4);
+  float: right;
+  transform: translate3d(calc(var(--o3-gap-4) * -1), var(--o3-gap-4), 0);
 }
 .source {
   border-top: 1px solid var(--o-color-control1-light);
-- 
Gitee