From a310c587ce807d85f279460d661b1726578f81da Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Thu, 6 Nov 2025 11:03:53 +0800
Subject: [PATCH 1/4] =?UTF-8?q?feat(doc-TheAside):=20=E7=BB=99=E7=BB=84?=
 =?UTF-8?q?=E4=BB=B6=E6=B7=BB=E5=8A=A0=E5=9E=82=E7=9B=B4=E6=BB=9A=E5=8A=A8?=
 =?UTF-8?q?=E5=8A=9F=E8=83=BD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/docs/src/components/TheAside.vue | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/packages/docs/src/components/TheAside.vue b/packages/docs/src/components/TheAside.vue
index 5cc6cef00..293ae9e12 100644
--- a/packages/docs/src/components/TheAside.vue
+++ b/packages/docs/src/components/TheAside.vue
@@ -2,7 +2,7 @@
 import { h, ref, watch } from 'vue';
 import { useRouter, useRoute } from 'vue-router';
 import { useSidebarStore, type NavItem } from '@/stores/sidebar';
-import { OMenu, OSubMenu, OMenuItem } from '@opensig/opendesign';
+import { OMenu, OSubMenu, OMenuItem, vScrollbar } from '@opensig/opendesign';
 const router = useRouter();
 const route = useRoute();
 
@@ -36,7 +36,7 @@ watch(path, (newPath) => {
 </script>
 <template>
   <aside class="the-aside">
-    <OMenu v-model="path" v-model:expanded="expand" size="small" class="nav-list">
+    <OMenu v-model="path" v-model:expanded="expand" v-scrollbar size="small" class="nav-list">
       <RecursiveMenu v-for="item in sidebarStore.navList" :key="item.value" v-bind="item" />
     </OMenu>
     <div class="controller" @click="emits('clickSidebar')">
@@ -53,6 +53,11 @@ watch(path, (newPath) => {
 .nav-list {
   margin-left: auto;
   --menu-width: auto;
+  overflow-y: auto;
+  overflow-x: hidden;
+  max-height: 100%;
+  // 防止滚动穿透到 body 元素上
+  overscroll-behavior: contain;
   @include respond-to('>pc') {
     --menu-width: var(--app-aside-static-width);
   }
-- 
Gitee


From 55c07002919234b5659983c8e8fe8cf050047e7a Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Thu, 6 Nov 2025 11:05:20 +0800
Subject: [PATCH 2/4] =?UTF-8?q?fix(doc-TheAnchor):=20=E6=B7=BB=E5=8A=A0?=
 =?UTF-8?q?=E5=9E=82=E7=9B=B4=E6=BB=9A=E5=8A=A8=E5=8A=9F=E8=83=BD=EF=BC=8C?=
 =?UTF-8?q?=E4=BC=98=E5=8C=96=E6=A0=B7=E5=BC=8F=EF=BC=8C=E4=BC=98=E5=8C=96?=
 =?UTF-8?q?=E7=BB=84=E4=BB=B6=E6=B8=B2=E6=9F=93?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/docs/src/App.vue                 | 20 +++--
 packages/docs/src/components/TheAnchor.ts | 89 ++++++++++++++---------
 2 files changed, 71 insertions(+), 38 deletions(-)

diff --git a/packages/docs/src/App.vue b/packages/docs/src/App.vue
index 38ea127ae..35beb917b 100644
--- a/packages/docs/src/App.vue
+++ b/packages/docs/src/App.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
-import { watchEffect, useTemplateRef, onMounted, shallowReactive, nextTick, ref, computed, watch } from 'vue';
+import { watchEffect, useTemplateRef, onMounted, shallowReactive, nextTick, ref, computed } from 'vue';
 import { useRoute, useRouter } from 'vue-router';
+import { OScroller } from '@opensig/opendesign';
 import TheHeader from './components/TheHeader.vue';
 import TheAside from './components/TheAside.vue';
 import { changeLocale, locales, LOCALE_COOKIE_KEY } from './lang';
@@ -121,7 +122,9 @@ router.beforeEach((to) => {
     >
       <TheHeader class="app-header" />
       <TheAside v-if="sidebarStore.hasData" class="app-aside" @click-sidebar="handleAsideClick" />
-      <TheAnchor v-if="heads.length" :heads="heads" :target-offset="60" class="app-anchor" />
+      <OScroller v-if="heads.length" disabled-x class="app-anchor-wrapper">
+        <TheAnchor :heads="heads" :target-offset="60" />
+      </OScroller>
       <div ref="appBodyDom" class="app-body">
         <router-view />
       </div>
@@ -161,19 +164,26 @@ router.beforeEach((to) => {
     transform: translateX(-100%);
   }
 }
-.app-anchor {
+.app-anchor-wrapper {
   position: fixed;
-  left: calc(50vw + var(--layout-content-width) / 2 - var(--app-anchor-width));
+  left: calc(50vw + var(--layout-content-width) / 2  - var(--app-anchor-width));
+  right: 0;
   top: calc(var(--app-header-height) + var(--app-header-margin));
   max-height: calc(100vh - var(--app-header-height) - var(--app-header-margin));
-  width: var(--app-anchor-width);
   z-index: 8;
   .o-anchor-line {
     flex-shrink: 0;
   }
+  .o-scroller-container {
+    overscroll-behavior: contain;
+  }
   @include respond-to('<=pad_v') {
     display: none;
   }
+  @include respond-to('>pc') {
+    right: auto;
+    width: var(--app-anchor-width);
+  }
 }
 .app-body {
   margin-top: calc(var(--app-header-height) + var(--app-header-margin));
diff --git a/packages/docs/src/components/TheAnchor.ts b/packages/docs/src/components/TheAnchor.ts
index 3a7cb341c..8741c03e9 100644
--- a/packages/docs/src/components/TheAnchor.ts
+++ b/packages/docs/src/components/TheAnchor.ts
@@ -1,4 +1,4 @@
-import { defineComponent, h, VNode, type PropType } from 'vue';
+import { defineComponent, h, VNode, type PropType, type ComponentPublicInstance } from 'vue';
 import { OAnchor, OAnchorItem } from '@opensig/opendesign';
 
 type Header = { title: string; level: number; id: string; children?: Header[]; parent?: Header };
@@ -38,42 +38,65 @@ export default defineComponent({
   },
 
   setup({ heads, targetOffset }) {
-    return () => {
-      if (!heads.length) {
-        return null;
+    let anchorContainer: HTMLElement | null = null;
+
+    const setAnchorContainer = (inst: ComponentPublicInstance | Element | null) => {
+      if (!inst) {
+        return;
       }
-      const root: Header = {
-        title: '',
-        level: 0,
-        id: '',
-      };
-      let current: Header = root;
-      // 锚点数据从平铺结构构造为树状结构，以便生成VNode
-      for (const _item of heads) {
-        // 浅拷贝数据，避免此处修改响应式对象而造成组件意外更新
-        const item = { ..._item } as Header;
-        if (item.level > current.level) {
-          current.children = current.children || [];
-          current.children.push(item);
-          item.parent = current;
-          current = item;
-        } else {
-          while (current.level > item.level && current.parent) {
-            current = current.parent;
-          }
-          if (current && current.parent) {
-            current.parent.children = current.parent.children || [];
-            current.parent.children.push(item);
-            item.parent = current.parent;
+      if (inst instanceof Element) {
+        anchorContainer = inst as HTMLElement;
+      } else if (inst.$el) {
+        anchorContainer = inst.$el;
+      }
+    };
+    const handleAnchorChange = (href: string) => {
+      anchorContainer?.querySelector(`.o-anchor-item-link[href="${href}"]`)?.scrollIntoView({
+        behavior: 'smooth',
+        block: 'nearest',
+      });
+    };
+    return () => {
+      // OAnchor 的默认插槽回调函数。
+      // heads 变量不应在 TheAnchor 组件中访问，这会造成 TheAnchor + OAnchor 同时组件更新，
+      // 而是应该封装在插槽函数中这样只更新 OAnchor 组件
+      const anchorDefaultSlot = () => {
+        if (!heads.length) {
+          return null;
+        }
+        const root: Header = {
+          title: '',
+          level: 0,
+          id: '',
+        };
+        let current: Header = root;
+        // 锚点数据从平铺结构构造为树状结构，以便生成VNode
+        for (const _item of heads) {
+          // 浅拷贝数据，避免此处修改响应式对象而造成组件意外更新
+          const item = { ..._item } as Header;
+          if (item.level > current.level) {
+            current.children = current.children || [];
+            current.children.push(item);
+            item.parent = current;
             current = item;
+          } else {
+            while (current.level > item.level && current.parent) {
+              current = current.parent;
+            }
+            if (current && current.parent) {
+              current.parent.children = current.parent.children || [];
+              current.parent.children.push(item);
+              item.parent = current.parent;
+              current = item;
+            }
           }
         }
-      }
-      if (!root.children) {
-        return null;
-      }
-      const vNodes = createAnchorItems(root.children);
-      return h(OAnchor, { targetOffset }, { default: () => vNodes });
+        if (!root.children) {
+          return null;
+        }
+        return createAnchorItems(root.children);
+      };
+      return h(OAnchor, { targetOffset, onChange: handleAnchorChange, ref: setAnchorContainer }, { default: anchorDefaultSlot });
     };
   },
 });
-- 
Gitee


From beda2ae79d8900473890644c6ed174ade24ffb25 Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Mon, 10 Nov 2025 17:35:03 +0800
Subject: [PATCH 3/4] =?UTF-8?q?fix(doc):=20=E4=BC=98=E5=8C=96=20highlight?=
 =?UTF-8?q?=20=E5=87=BD=E6=95=B0=EF=BC=8C=E9=81=BF=E5=85=8D=E5=9C=A8?=
 =?UTF-8?q?=E7=94=9F=E4=BA=A7=E4=BB=A3=E7=A0=81=E4=B8=AD=E5=AF=BC=E5=85=A5?=
 =?UTF-8?q?=E4=BD=93=E7=A7=AF=E5=BE=88=E5=A4=A7=E7=9A=84=20@vue/compiler-s?=
 =?UTF-8?q?fc=20=E5=8C=85?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/docs/helper/vue-utils.ts           | 108 ++++++++++++++++++++
 packages/docs/plugins/markdown/highlight.ts |   8 +-
 2 files changed, 112 insertions(+), 4 deletions(-)
 create mode 100644 packages/docs/helper/vue-utils.ts

diff --git a/packages/docs/helper/vue-utils.ts b/packages/docs/helper/vue-utils.ts
new file mode 100644
index 000000000..f3bcb2be6
--- /dev/null
+++ b/packages/docs/helper/vue-utils.ts
@@ -0,0 +1,108 @@
+import { parse, NodeTypes, type ElementNode } from '@vue/compiler-dom';
+import { type SFCDescriptor, type SFCBlock, type SFCStyleBlock, type SFCTemplateBlock, type SFCScriptBlock } from '@vue/compiler-sfc';
+
+function hasSrc(node: ElementNode) {
+  return node.props.some((p) => {
+    if (p.type !== NodeTypes.ATTRIBUTE) {
+      return false;
+    }
+    return p.name === 'src';
+  });
+}
+
+function isEmpty(node: ElementNode) {
+  for (let i = 0; i < node.children.length; i++) {
+    const child = node.children[i];
+    if (child.type !== NodeTypes.TEXT || child.content.trim() !== '') {
+      return false;
+    }
+  }
+  return true;
+}
+
+function createBlock(node: ElementNode, source: string): SFCBlock {
+  const type = node.tag;
+  const loc = node.innerLoc!;
+  const attrs: Record<string, string | true> = {};
+  const block: SFCBlock = {
+    type,
+    content: source.slice(loc.start.offset, loc.end.offset),
+    loc,
+    attrs,
+  };
+  node.props.forEach((p) => {
+    if (p.type === NodeTypes.ATTRIBUTE) {
+      const name = p.name;
+      attrs[name] = p.value ? p.value.content || true : true;
+      if (name === 'lang') {
+        block.lang = p.value && p.value.content;
+      } else if (name === 'src') {
+        block.src = p.value && p.value.content;
+      } else if (type === 'style') {
+        if (name === 'scoped') {
+          (block as SFCStyleBlock).scoped = true;
+        } else if (name === 'module') {
+          (block as SFCStyleBlock).module = attrs[name];
+        }
+      } else if (type === 'script' && name === 'setup') {
+        (block as SFCScriptBlock).setup = attrs.setup;
+      }
+    }
+  });
+  return block;
+}
+
+const sfcCache = new Map<string, any>();
+// 由于 @vue/compiler-sfc 包体积过大，且当前只需要使用其 parse 函数，因此创建一个简单的 parse 函数
+// 该函数省略了报错，仅返回解析结果
+export function parseSfc(source: string) {
+  const cache = sfcCache.get(source);
+  if (cache) {
+    return cache;
+  }
+  const descriptor: Pick<SFCDescriptor, 'template' | 'script' | 'scriptSetup' | 'styles' | 'customBlocks'> = {
+    template: null,
+    script: null,
+    scriptSetup: null,
+    styles: [],
+    customBlocks: [],
+  };
+
+  const ast = parse(source, {
+    parseMode: 'sfc',
+    prefixIdentifiers: true,
+  });
+
+  ast.children.forEach((node) => {
+    if (node.type !== NodeTypes.ELEMENT) {
+      return;
+    }
+    if (node.tag !== 'template' && isEmpty(node) && !hasSrc(node)) {
+      return;
+    }
+    switch (node.tag) {
+      case 'template':
+        descriptor.template = createBlock(node, source) as SFCTemplateBlock;
+        break;
+      case 'script': {
+        const scriptBlock = createBlock(node, source) as SFCScriptBlock;
+        if (scriptBlock.attrs.setup) {
+          descriptor.scriptSetup = scriptBlock;
+        } else {
+          descriptor.script = scriptBlock;
+        }
+        break;
+      }
+      case 'style': {
+        const styleBlock = createBlock(node, source) as SFCStyleBlock;
+        descriptor.styles.push(styleBlock);
+        break;
+      }
+      default:
+        descriptor.customBlocks.push(createBlock(node, source));
+        break;
+    }
+  });
+  sfcCache.set(source, descriptor);
+  return descriptor;
+}
diff --git a/packages/docs/plugins/markdown/highlight.ts b/packages/docs/plugins/markdown/highlight.ts
index 010ed5950..cd2624bbb 100644
--- a/packages/docs/plugins/markdown/highlight.ts
+++ b/packages/docs/plugins/markdown/highlight.ts
@@ -1,7 +1,8 @@
-// 优化后代码结构示例
 import { escapeHtml } from 'markdown-it/lib/common/utils.mjs';
 import { createHighlighterCore, createJavaScriptRegexEngine } from 'shiki';
 import { generateCode } from '../../helper/utils';
+// 由于 @vue/compiler-sfc 包体积过大，因此使用简化的 parseSfc 函数
+import { parseSfc } from '../../helper/vue-utils';
 
 const baseConfig = {
   themes: [import('@shikijs/themes/light-plus'), import('@shikijs/themes/dark-plus')],
@@ -12,7 +13,7 @@ const baseConfig = {
  * @returns 高亮函数
  */
 export const createHighlighter = async () => {
-  const [mainHighlighter, vueTemplateHighlighter, parse] = await Promise.all([
+  const [mainHighlighter, vueTemplateHighlighter] = await Promise.all([
     createHighlighterCore({
       ...baseConfig,
       langs: [
@@ -44,7 +45,6 @@ export const createHighlighter = async () => {
         import('@shikijs/langs/css'),
       ],
     }),
-    import('@vue/compiler-sfc').then((r) => r.parse),
   ]);
 
   const stripPreCodeReg = /<pre.*?><code.*?>([\s\S]*?)<\/code><\/pre>/;
@@ -86,7 +86,7 @@ export const createHighlighter = async () => {
     }
 
     if (lang === 'vue') {
-      const { descriptor } = parse(code);
+      const descriptor = parseSfc(code);
       // vue的template模块需要单独处理，因此分块高亮
       const blocks = [descriptor.script, ...descriptor.styles, descriptor.scriptSetup, ...descriptor.customBlocks, descriptor.template]
         .filter(Boolean)
-- 
Gitee


From 809d7c2b66963427adcc79b4ffc755c10c43e154 Mon Sep 17 00:00:00 2001
From: sakurayinfei <970412446@qq.com>
Date: Tue, 11 Nov 2025 09:52:15 +0800
Subject: [PATCH 4/4] =?UTF-8?q?fix(doc):=20=E4=BC=98=E5=8C=96=E5=AD=97?=
 =?UTF-8?q?=E4=BD=93=E6=96=87=E4=BB=B6=E7=BD=91=E7=BB=9C=E7=BC=93=E5=AD=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../assets/fonts/HarmonyOS_Hans_Bold.woff2}       | Bin
 .../assets/fonts/HarmonyOS_Hans_Medium.woff2}     | Bin
 .../assets/fonts/HarmonyOS_Hans_Regular.woff2}    | Bin
 .../fonts/HarmonyOS_Sans_Bold_Italic.woff2}       | Bin
 .../fonts/HarmonyOS_Sans_Medium_Italic.woff2}     | Bin
 .../fonts/HarmonyOS_Sans_Regular_Italic.woff2}    | Bin
 packages/docs/src/assets/style/font-family.scss   |  14 ++++++++------
 7 files changed, 8 insertions(+), 6 deletions(-)
 rename packages/docs/{public/HarmonyOS_Hans_Bold.CLKfZ-3Y.woff2 => src/assets/fonts/HarmonyOS_Hans_Bold.woff2} (100%)
 rename packages/docs/{public/HarmonyOS_Hans_Medium.Bmj-cXYg.woff2 => src/assets/fonts/HarmonyOS_Hans_Medium.woff2} (100%)
 rename packages/docs/{public/HarmonyOS_Hans_Regular.9I7L7rbq.woff2 => src/assets/fonts/HarmonyOS_Hans_Regular.woff2} (100%)
 rename packages/docs/{public/HarmonyOS_Sans_Bold_Italic.Bvb9oWs-.woff2 => src/assets/fonts/HarmonyOS_Sans_Bold_Italic.woff2} (100%)
 rename packages/docs/{public/HarmonyOS_Sans_Medium_Italic.DL_MEPRF.woff2 => src/assets/fonts/HarmonyOS_Sans_Medium_Italic.woff2} (100%)
 rename packages/docs/{public/HarmonyOS_Sans_Regular_Italic.CWzBs7-y.woff2 => src/assets/fonts/HarmonyOS_Sans_Regular_Italic.woff2} (100%)

diff --git a/packages/docs/public/HarmonyOS_Hans_Bold.CLKfZ-3Y.woff2 b/packages/docs/src/assets/fonts/HarmonyOS_Hans_Bold.woff2
similarity index 100%
rename from packages/docs/public/HarmonyOS_Hans_Bold.CLKfZ-3Y.woff2
rename to packages/docs/src/assets/fonts/HarmonyOS_Hans_Bold.woff2
diff --git a/packages/docs/public/HarmonyOS_Hans_Medium.Bmj-cXYg.woff2 b/packages/docs/src/assets/fonts/HarmonyOS_Hans_Medium.woff2
similarity index 100%
rename from packages/docs/public/HarmonyOS_Hans_Medium.Bmj-cXYg.woff2
rename to packages/docs/src/assets/fonts/HarmonyOS_Hans_Medium.woff2
diff --git a/packages/docs/public/HarmonyOS_Hans_Regular.9I7L7rbq.woff2 b/packages/docs/src/assets/fonts/HarmonyOS_Hans_Regular.woff2
similarity index 100%
rename from packages/docs/public/HarmonyOS_Hans_Regular.9I7L7rbq.woff2
rename to packages/docs/src/assets/fonts/HarmonyOS_Hans_Regular.woff2
diff --git a/packages/docs/public/HarmonyOS_Sans_Bold_Italic.Bvb9oWs-.woff2 b/packages/docs/src/assets/fonts/HarmonyOS_Sans_Bold_Italic.woff2
similarity index 100%
rename from packages/docs/public/HarmonyOS_Sans_Bold_Italic.Bvb9oWs-.woff2
rename to packages/docs/src/assets/fonts/HarmonyOS_Sans_Bold_Italic.woff2
diff --git a/packages/docs/public/HarmonyOS_Sans_Medium_Italic.DL_MEPRF.woff2 b/packages/docs/src/assets/fonts/HarmonyOS_Sans_Medium_Italic.woff2
similarity index 100%
rename from packages/docs/public/HarmonyOS_Sans_Medium_Italic.DL_MEPRF.woff2
rename to packages/docs/src/assets/fonts/HarmonyOS_Sans_Medium_Italic.woff2
diff --git a/packages/docs/public/HarmonyOS_Sans_Regular_Italic.CWzBs7-y.woff2 b/packages/docs/src/assets/fonts/HarmonyOS_Sans_Regular_Italic.woff2
similarity index 100%
rename from packages/docs/public/HarmonyOS_Sans_Regular_Italic.CWzBs7-y.woff2
rename to packages/docs/src/assets/fonts/HarmonyOS_Sans_Regular_Italic.woff2
diff --git a/packages/docs/src/assets/style/font-family.scss b/packages/docs/src/assets/style/font-family.scss
index fe868ade7..6bfc052d6 100644
--- a/packages/docs/src/assets/style/font-family.scss
+++ b/packages/docs/src/assets/style/font-family.scss
@@ -5,7 +5,9 @@
   font-weight: 400;
   src:
     local('HarmonyOSHans'),
-    url(/HarmonyOS_Hans_Regular.9I7L7rbq.woff2) format('woff2');
+    // 将字体文件从 public/ 中移到 src/assets/fonts/ 文件夹中
+    // 根据当前的 nginx 配置，src/assets/ 中的文件有缓存，public/ 文件夹中的文件不会被缓存
+    url(../fonts/HarmonyOS_Hans_Regular.woff2) format('woff2');
 }
 
 @font-face {
@@ -15,7 +17,7 @@
   font-weight: 500;
   src:
     local('HarmonyOSHans Medium'),
-    url(/HarmonyOS_Hans_Medium.Bmj-cXYg.woff2) format('woff2');
+    url(../fonts/HarmonyOS_Hans_Medium.woff2) format('woff2');
 }
 
 @font-face {
@@ -25,7 +27,7 @@
   font-weight: 700;
   src:
     local('HarmonyOSHans Bold'),
-    url(/HarmonyOS_Hans_Bold.CLKfZ-3Y.woff2) format('woff2');
+    url(../fonts/HarmonyOS_Hans_Bold.woff2) format('woff2');
 }
 
 @font-face {
@@ -35,7 +37,7 @@
   font-weight: 400;
   src:
     local('HarmonyOSSans'),
-    url(/HarmonyOS_Sans_Regular_Italic.CWzBs7-y.woff2) format('woff2');
+    url(../fonts/HarmonyOS_Sans_Regular_Italic.woff2) format('woff2');
 }
 
 @font-face {
@@ -45,7 +47,7 @@
   font-weight: 500;
   src:
     local('HarmonyOSSans Medium'),
-    url(/HarmonyOS_Sans_Medium_Italic.DL_MEPRF.woff2) format('woff2');
+    url(../fonts/HarmonyOS_Sans_Medium_Italic.woff2) format('woff2');
 }
 
 @font-face {
@@ -55,5 +57,5 @@
   font-weight: 700;
   src:
     local('HarmonyOSSans Bold'),
-    url(/HarmonyOS_Sans_Bold_Italic.Bvb9oWs-.woff2) format('woff2');
+    url(../fonts/HarmonyOS_Sans_Bold_Italic.woff2) format('woff2');
 }
-- 
Gitee