From 0a48d5e830781a1aa6f2c3e946e06d78c8fb7e48 Mon Sep 17 00:00:00 2001
From: Charliechen114514 <725610365@qq.com>
Date: Tue, 1 Sep 2026 01:11:07 +0800
Subject: [PATCH] fix: sidebar session

---
 site/.vitepress/config/shared.ts              |   9 +-
 .../theme/components/ResizableSidebar.vue     | 162 ++++++-------
 .../theme/components/SidebarRail.vue          |  91 ++++++++
 site/.vitepress/theme/custom.css              | 213 +++++++++++++++++-
 site/.vitepress/theme/index.ts                |   4 +-
 5 files changed, 373 insertions(+), 106 deletions(-)
 create mode 100644 site/.vitepress/theme/components/SidebarRail.vue

diff --git a/site/.vitepress/config/shared.ts b/site/.vitepress/config/shared.ts
index 2a417a1..f122d7d 100644
--- a/site/.vitepress/config/shared.ts
+++ b/site/.vitepress/config/shared.ts
@@ -48,13 +48,14 @@ export const sharedBase = {
       {},
       `(function(){var m={xxsmall:'0.88',small:'0.94',normal:'1',large:'1.08',xxlarge:'1.16'};try{var s=localStorage.getItem('awesomeqt-font-size');document.documentElement.style.setProperty('--aq-font-scale',m[s]||'1');}catch(e){}})()`,
     ],
-    // 可拖拽侧栏首屏防闪：hydration 前从 localStorage 还原左右栏宽度 CSS 变量。
-    // 左栏 272 只是近似值——挂载后 ResizableSidebar 会按当前卷最长条目自适应实测（未存过宽度时）。
-    // 与 theme/components/ResizableSidebar.vue 的 CONF（key=vp-sidebar-width/vp-aside-width）一致。
+    // 可拖拽抽屉侧栏首屏防闪：hydration 前从 localStorage 还原宽度 CSS 变量。
+    // 272 只是近似值——挂载后 ResizableSidebar 会按当前卷最长条目自适应实测（未存过宽度时）。
+    // 与 theme/components/ResizableSidebar.vue 的 CONF（key=vp-sidebar-width）一致。
+    // （右大纲栏拖拽已砍，TOC 固定 256，不再注入 --vp-aside-width。）
     [
       'script',
       {},
-      `(function(){try{var w=parseInt(localStorage.getItem('vp-sidebar-width'));if(!w||w<200||w>480){w=272;}document.documentElement.style.setProperty('--vp-sidebar-width',w+'px');var a=parseInt(localStorage.getItem('vp-aside-width'));if(!a||a<180||a>360){a=256;}document.documentElement.style.setProperty('--vp-aside-width',a+'px');}catch(e){}})()`,
+      `(function(){try{var w=parseInt(localStorage.getItem('vp-sidebar-width'));if(!w||w<200||w>480){w=272;}document.documentElement.style.setProperty('--vp-sidebar-width',w+'px');}catch(e){}})()`,
     ],
   ],
 }
diff --git a/site/.vitepress/theme/components/ResizableSidebar.vue b/site/.vitepress/theme/components/ResizableSidebar.vue
index 28c0d60..acf2cc7 100644
--- a/site/.vitepress/theme/components/ResizableSidebar.vue
+++ b/site/.vitepress/theme/components/ResizableSidebar.vue
@@ -1,133 +1,111 @@
 <script setup lang="ts">
 import { onMounted, onBeforeUnmount, ref } from 'vue'
 
-// 可拖拽侧栏宽度:左导航树 + 右大纲栏(TOC)。
-// 左栏 --vp-sidebar-width 由 VitePress 全链路消费(sidebar 自身 / 正文 padding-left / 顶栏对齐),
-//   改这一个变量即全联动。但 handle 的定位与拖动计算必须读 .VPSidebar 的实际几何 —— 宽屏
-//   (≥1440px)布局居中,sidebar 左缘非 0、右缘带 (vw-maxW)/2 偏移,且受滚动条宽度影响,
-//   CSS 公式推算总有小偏差。故 left 一律用 JS 读 getBoundingClientRect 精确设定(与右 handle 同策略)。
-// 左栏默认宽度不写死:按当前卷 sidebar 最宽条目文字实测 + 留白 + buffer 动态求值
+// 可拖拽抽屉侧栏宽度(仅左栏;右大纲栏 TOC 固定 256px,不再提供拖拽——
+// 全视口抽屉化改版后右侧孤零零一条拖拽条被打回,功能低频直接砍掉)。
+// 左栏 --vp-sidebar-width 由 VitePress 全链路消费(sidebar 自身宽度),改这一个变量即联动。
+// handle 是 fixed 竖条、贴抽屉右缘:定位与拖动计算读 .VPSidebar 实际几何,仅抽屉
+//   打开时显示(class 感知靠单独的 VPSidebar attribute observer,它与 .VPContent 平级)。
+// 默认宽度不写死:按当前卷 sidebar 最宽条目文字实测 + 留白 + buffer 动态求值
 //   (用户拖过并存了宽度 = 有明确偏好,保存值优先;双击重置即恢复自适应并清掉保存值)。
-// 右栏 --vp-aside-width 自定义变量(在 custom.css 覆盖 aside max-width);右 handle absolute
-//   注入 aside 内,MutationObserver 在路由切换重建 aside 时重新注入。
 // 宽度持久化 localStorage;首屏防闪由 config head 内联脚本(hydration 前注入 272 近似值)负责。
 
-type Side = 'left' | 'right'
 interface Dim { min: number; max: number; def: number; key: string; cssVar: string }
 
-const CONF: Record<Side, Dim> = {
-  left: { min: 200, max: 480, def: 272, key: 'vp-sidebar-width', cssVar: '--vp-sidebar-width' },
-  right: { min: 180, max: 360, def: 256, key: 'vp-aside-width', cssVar: '--vp-aside-width' },
-}
+const CONF: Dim = { min: 200, max: 480, def: 272, key: 'vp-sidebar-width', cssVar: '--vp-sidebar-width' }
 
 const clamp = (v: number, min: number, max: number) => Math.min(max, Math.max(min, v))
 
 /** 读用户保存的宽度;没有或非法返回 null */
-function savedWidth(side: Side): number | null {
+function savedWidth(): number | null {
   try {
-    const v = parseInt(localStorage.getItem(CONF[side].key) || '')
-    return v >= CONF[side].min && v <= CONF[side].max ? v : null
+    const v = parseInt(localStorage.getItem(CONF.key) || '')
+    return v >= CONF.min && v <= CONF.max ? v : null
   } catch {
     return null
   }
 }
 
 /**
- * 左栏自适应默认宽度:实测当前 sidebar 最宽条目文字右缘(含嵌套缩进;text 带
+ * 自适应默认宽度:实测当前 sidebar 最宽条目文字右缘(含嵌套缩进;text 带
  * 省略号截断,scrollWidth-clientWidth 补回被截掉的部分)+ 右侧留白 32 + buffer 14
  * (字体渲染差异/滚动条余量),夹在 [min,max]。测不到回退 272。
  * 换卷 sidebar 内容不同,路由变化后要重测。
  */
 function measureLeftDefault(): number {
   const sb = document.querySelector('.VPSidebar') as HTMLElement | null
-  if (!sb) return CONF.left.def
+  if (!sb) return CONF.def
   const base = sb.getBoundingClientRect().left
   let maxRight = 0
   sb.querySelectorAll<HTMLElement>('.VPSidebarItem .text').forEach((t) => {
     const w = t.getBoundingClientRect().right + (t.scrollWidth - t.clientWidth) - base
     if (w > maxRight) maxRight = w
   })
-  if (maxRight <= 0) return CONF.left.def
-  return clamp(Math.ceil(maxRight + 32 + 14), CONF.left.min, CONF.left.max)
+  if (maxRight <= 0) return CONF.def
+  return clamp(Math.ceil(maxRight + 32 + 14), CONF.min, CONF.max)
 }
 
 const leftHandle = ref<HTMLElement | null>(null)
-const RIGHT_HANDLE_ID = 'rs-right-handle'
 
-const applyVar = (side: Side, px: number) =>
-  document.documentElement.style.setProperty(CONF[side].cssVar, px + 'px')
-const persist = (side: Side, px: number) => {
-  try { localStorage.setItem(CONF[side].key, String(px)) } catch { /* 隐私模式 / 配额 */ }
+const applyVar = (px: number) =>
+  document.documentElement.style.setProperty(CONF.cssVar, px + 'px')
+const persist = (px: number) => {
+  try { localStorage.setItem(CONF.key, String(px)) } catch { /* 隐私模式 / 配额 */ }
 }
 
-interface DragCtx {
-  side: Side
-  dim: Dim
+let drag: {
   lastV: number
   handle: HTMLElement
   onMove: (e: MouseEvent) => void
   onUp: () => void
-}
-let drag: DragCtx | null = null
+} | null = null
 
-function startDrag(side: Side, e: MouseEvent) {
+function startDrag(e: MouseEvent) {
   e.preventDefault()
-  const dim = CONF[side]
   const handle = e.currentTarget as HTMLElement
   handle.classList.add('is-active')
   document.body.classList.add('rs-resizing')
 
-  // 用「位移」而非「绝对坐标」算新宽度。居中布局(≥1440px)下 sidebar 容器 left:0 但视觉
-  // nav 树因居中留白偏右,getBoundingClientRect/offsetLeft 都是容器几何、不代表 nav 树视觉
-  // 位置,按绝对坐标算会多算居中偏移导致宽度暴涨(线上曾遮挡正文)。位移法与布局无关,恒正确。
+  // 用「位移」而非「绝对坐标」算新宽度,与布局无关恒正确。
   const startX = e.clientX
   const startWidth =
-    parseInt(getComputedStyle(document.documentElement).getPropertyValue(dim.cssVar)) || dim.def
+    parseInt(getComputedStyle(document.documentElement).getPropertyValue(CONF.cssVar)) || CONF.def
 
   const onMove = (ev: MouseEvent) => {
-    const delta = ev.clientX - startX
-    // 左栏:鼠标右移加宽;右栏:鼠标左移加宽(右栏左缘向左拖)
-    const v = clamp(
-      Math.round(side === 'left' ? startWidth + delta : startWidth - delta),
-      dim.min,
-      dim.max
-    )
+    const v = clamp(Math.round(startWidth + (ev.clientX - startX)), CONF.min, CONF.max)
     if (drag) drag.lastV = v
-    applyVar(side, v)
-    if (side === 'left' && drag?.handle) {
+    applyVar(v)
+    if (drag?.handle) {
       drag.handle.style.left = ev.clientX + 'px' // handle 跟随鼠标(按下点在右缘,故 = 新右缘)
     }
   }
   const onUp = () => {
-    if (drag) persist(side, drag.lastV)
+    if (drag) persist(drag.lastV)
     handle.classList.remove('is-active')
     document.body.classList.remove('rs-resizing')
     document.removeEventListener('mousemove', onMove)
     document.removeEventListener('mouseup', onUp)
     drag = null
-    if (side === 'left') updateLeftPosition() // 拖动结束重新精确对齐(offsetLeft+offsetWidth)
+    updateLeftPosition() // 拖动结束重新精确对齐(offsetLeft+offsetWidth)
   }
-  drag = { side, dim, lastV: startWidth, handle, onMove, onUp }
+  drag = { lastV: startWidth, handle, onMove, onUp }
   document.addEventListener('mousemove', onMove)
   document.addEventListener('mouseup', onUp)
 }
 
-function reset(side: Side) {
-  if (side === 'left') {
-    // 双击重置 = 回到自适应默认,并清掉保存值 → 内容增长后继续自适应
-    applyVar('left', measureLeftDefault())
-    try { localStorage.removeItem(CONF.left.key) } catch { /* 隐私模式 */ }
-  } else {
-    applyVar(side, CONF[side].def)
-    persist(side, CONF[side].def)
-  }
-  if (side === 'left') updateLeftPosition()
+function reset() {
+  // 双击重置 = 回到自适应默认,并清掉保存值 → 内容增长后继续自适应
+  applyVar(measureLeftDefault())
+  try { localStorage.removeItem(CONF.key) } catch { /* 隐私模式 */ }
+  updateLeftPosition()
 }
 
-// 仅在有侧栏的页(文档页)显示左 handle;首页等无侧栏页隐藏
+// 仅在抽屉打开时显示左 handle;收起时隐藏(侧栏在屏外,handle 不能悬在正文上)
 function updateLeftVisibility() {
   if (!leftHandle.value) return
-  leftHandle.value.style.display = document.querySelector('.VPSidebar') ? '' : 'none'
+  const sb = document.querySelector('.VPSidebar')
+  leftHandle.value.style.display =
+    sb && sb.classList.contains('open') ? '' : 'none'
 }
 
 // 左 handle 精确定位:用 offsetLeft + offsetWidth(不含 transform),避开 sidebar 入场过渡
@@ -138,53 +116,52 @@ function updateLeftPosition() {
   if (sb) leftHandle.value.style.left = (sb.offsetLeft + sb.offsetWidth) + 'px'
 }
 
-function injectRightHandle() {
-  const aside = document.querySelector('.VPDoc.has-aside .aside') as HTMLElement | null
-  if (!aside || aside.querySelector('#' + RIGHT_HANDLE_ID)) return
-  const handle = document.createElement('div')
-  handle.id = RIGHT_HANDLE_ID
-  handle.className = 'rs-handle rs-handle--right'
-  handle.setAttribute('role', 'separator')
-  handle.setAttribute('aria-orientation', 'vertical')
-  handle.setAttribute('aria-label', '拖动调整右侧大纲栏宽度(双击重置)')
-  handle.addEventListener('mousedown', (ev) => startDrag('right', ev))
-  handle.addEventListener('dblclick', () => reset('right'))
-  aside.style.position = 'relative'
-  aside.appendChild(handle)
-}
-
 let observer: MutationObserver | null = null
 let leftTimer = 0
 
+// 抽屉开合是 .VPSidebar 上的 class 切换(open),而它与 .VPContent 平级——
+// 下面的 VPContent observer 监听不到。单独给 .VPSidebar 挂 attribute 观察,
+// 元素重建时(v-if 切换)由 VPContent 的 childList 回调重新绑定。
+let sbObserver: MutationObserver | null = null
+let watchedSb: Element | null = null
+function watchSidebarElement() {
+  const sb = document.querySelector('.VPSidebar')
+  if (sb === watchedSb) return
+  watchedSb = sb
+  sbObserver?.disconnect()
+  if (sb && 'MutationObserver' in window) {
+    if (!sbObserver) sbObserver = new MutationObserver(onMutate)
+    sbObserver.observe(sb, { attributes: true, attributeFilter: ['class'] })
+  }
+}
+
 // 自适应默认宽度:rAF 去抖地重测(路由换卷 sidebar 重建时 MutationObserver 高频触发,
 // 每次都量 ~200 个 text 节点会抖布局)。用户存过宽度就不测。
 let measureQueued = false
 function queueMeasureLeftDefault() {
-  if (measureQueued || savedWidth('left') !== null) return
+  if (measureQueued || savedWidth() !== null) return
   measureQueued = true
   requestAnimationFrame(() => {
     measureQueued = false
-    applyVar('left', measureLeftDefault())
+    applyVar(measureLeftDefault())
     updateLeftPosition()
   })
 }
 
 const onMutate = () => {
+  watchSidebarElement()
   updateLeftVisibility()
   updateLeftPosition()
-  injectRightHandle()
   queueMeasureLeftDefault()
 }
 
 onMounted(() => {
-  // 恢复已存宽度(防闪脚本已在首屏注入近似值);左栏没存过 → 立即按内容实测自适应
-  ;(['left', 'right'] as Side[]).forEach((side) => {
-    const v = savedWidth(side)
-    if (v !== null) applyVar(side, v)
-  })
+  // 恢复已存宽度(防闪脚本已在首屏注入近似值);没存过 → 立即按内容实测自适应
+  const v = savedWidth()
+  if (v !== null) applyVar(v)
   queueMeasureLeftDefault()
   onMutate()
-  // sidebar 桌面端有 transform 入场过渡(translateX(-100%)→0,约 0.25s),过渡中
+  // sidebar 打开有 transform 入场过渡(translateX(-100%)→0,约 0.25s),过渡中
   // getBoundingClientRect 偏左,导致 handle 初始错位(拖动后才贴合)。
   // 多时机补校准,确保首屏即贴合:下一帧 / 过渡结束后(~350ms)/ 页面 load 后。
   requestAnimationFrame(updateLeftPosition)
@@ -196,17 +173,24 @@ onMounted(() => {
   const root = document.querySelector('.VPContent') || document.body
   if ('MutationObserver' in window) {
     observer = new MutationObserver(onMutate)
-    observer.observe(root, { childList: true, subtree: true })
+    observer.observe(root, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['class'],
+    })
   }
 })
 
 onBeforeUnmount(() => {
   observer?.disconnect()
   observer = null
+  sbObserver?.disconnect()
+  sbObserver = null
+  watchedSb = null
   window.clearTimeout(leftTimer)
   window.removeEventListener('resize', updateLeftPosition)
   window.removeEventListener('load', updateLeftPosition)
-  document.querySelectorAll('#' + RIGHT_HANDLE_ID).forEach((n) => n.remove())
   if (drag) {
     document.removeEventListener('mousemove', drag.onMove)
     document.removeEventListener('mouseup', drag.onUp)
@@ -221,8 +205,8 @@ onBeforeUnmount(() => {
     class="rs-handle rs-handle--left"
     role="separator"
     aria-orientation="vertical"
-    aria-label="拖动调整左侧导航栏宽度(双击重置)"
-    @mousedown="startDrag('left', $event)"
-    @dblclick="reset('left')"
+    aria-label="拖动调整侧栏宽度(双击重置)"
+    @mousedown="startDrag($event)"
+    @dblclick="reset"
   ></div>
 </template>
diff --git a/site/.vitepress/theme/components/SidebarRail.vue b/site/.vitepress/theme/components/SidebarRail.vue
new file mode 100644
index 0000000..820f550
--- /dev/null
+++ b/site/.vitepress/theme/components/SidebarRail.vue
@@ -0,0 +1,91 @@
+<script setup lang="ts">
+import { useSidebar } from 'vitepress/theme'
+
+// 左缘窄条把手：全视口抽屉侧栏（issue #20）的桌面/平板开关。
+// 点击转发给 VPLocalNav 的「菜单」按钮而不是直接 useSidebar().toggle()——
+// dev 预打包会把 'vitepress/theme' 单独 optimize，其内部 composables/sidebar
+// 与 Layout 所用分裂成两个实例，toggle 改不动真状态（线上实测孤儿 ref）。
+// 真按钮 emit open-menu 由 Layout 处理，Esc/路由切换/遮罩点击关闭全部原生继承；
+// ≥1280 时按钮虽 display:none，JS .click() 仍触发完整事件链。
+// 开合状态无需跟踪：抽屉 z-index 60 盖住窄条（30），关掉自然露出。
+const { hasSidebar } = useSidebar()
+
+function toggle() {
+  document.querySelector<HTMLButtonElement>('.VPLocalNav .menu')?.click()
+}
+</script>
+
+<template>
+  <button
+    v-if="hasSidebar"
+    class="sidebar-rail"
+    aria-controls="VPSidebarNav"
+    aria-label="展开教程目录"
+    @click="toggle"
+  >
+    <span class="sidebar-rail__icon"></span>
+    <span class="sidebar-rail__label">目录</span>
+  </button>
+</template>
+
+<style scoped>
+.sidebar-rail {
+  position: fixed;
+  top: 50%;
+  left: 0;
+  transform: translateY(-50%);
+  z-index: var(--vp-z-index-nav); /* 低于遮罩(50)/抽屉(60)，抽屉打开时自然被盖住 */
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  width: 32px;
+  height: 128px;
+  border: 1px solid var(--vp-c-border);
+  border-left: none;
+  border-radius: 0 12px 12px 0;
+  background: var(--vp-c-bg-elv);
+  box-shadow: 2px 0 10px rgba(0, 0, 0, 0.1);
+  color: var(--vp-c-text-2);
+  cursor: pointer;
+  opacity: 0.9;
+  transition: color 0.2s ease, border-color 0.2s ease, box-shadow 0.2s ease,
+    width 0.2s ease;
+}
+
+.sidebar-rail:hover {
+  color: var(--vp-c-brand-1);
+  border-color: var(--vp-c-brand-1);
+  box-shadow: 2px 0 14px var(--vp-c-brand-soft);
+  width: 36px;
+}
+
+/* 自绘箭头（vpi 图标字号上限太保守，把手要大要明显就用 SVG 级尺寸） */
+.sidebar-rail__icon {
+  width: 0;
+  height: 0;
+  border-top: 7px solid transparent;
+  border-bottom: 7px solid transparent;
+  border-left: 11px solid currentColor;
+  transition: transform 0.2s ease;
+}
+
+.sidebar-rail:hover .sidebar-rail__icon {
+  transform: translateX(2px);
+}
+
+.sidebar-rail__label {
+  writing-mode: vertical-rl;
+  font-size: 12px;
+  letter-spacing: 0.35em;
+  font-weight: 600;
+}
+
+/* <960px 有 VPLocalNav 菜单按钮，窄条不登场 */
+@media (max-width: 959.98px) {
+  .sidebar-rail {
+    display: none;
+  }
+}
+</style>
diff --git a/site/.vitepress/theme/custom.css b/site/.vitepress/theme/custom.css
index 92e0812..15bcc49 100644
--- a/site/.vitepress/theme/custom.css
+++ b/site/.vitepress/theme/custom.css
@@ -506,12 +506,12 @@ kbd {
    ================================================================ */
 :root {
   --vp-sidebar-width: 272px;
-  --vp-aside-width: 256px;
 }
 
+/* 右大纲栏(TOC)固定宽:右栏拖拽功能已砍(抽屉化改版后右侧拖拽条被打回),不再消费变量 */
 .VPDoc.has-aside .aside {
-  width: var(--vp-aside-width);
-  max-width: var(--vp-aside-width);
+  width: 256px;
+  max-width: 256px;
 }
 
 .rs-handle {
@@ -520,7 +520,8 @@ kbd {
   bottom: 0;
   width: 6px;
   cursor: col-resize;
-  z-index: 50;
+  /* 抽屉 z-index 60:handle 要在抽屉右缘之上才可拖(仅 open 时显示,平时无感) */
+  z-index: 65;
   background: transparent;
   transition: background 0.2s ease, opacity 0.2s ease;
 }
@@ -535,14 +536,6 @@ kbd {
   opacity: 0.65;
 }
 
-.rs-handle--right {
-  position: absolute;
-  top: 0;
-  right: -3px;
-  bottom: 0;
-  width: 6px;
-}
-
 body.rs-resizing {
   user-select: none;
   cursor: col-resize;
@@ -558,6 +551,202 @@ body.rs-resizing * {
   }
 }
 
+/* ================================================================
+   全视口抽屉侧栏（issue #20，2026-09）
+   桌面/平板不再常驻避让：撤销 theme-default 对 --vp-sidebar-width 的
+   全链路 padding 消费，侧栏统一回到移动端抽屉形态——平时收起在左缘外，
+   拉出后悬浮覆盖正文（不挤压内容，长标题自适应宽度也无害）。
+   开关：左缘窄条 SidebarRail.vue（≥960）+ VPLocalNav 菜单按钮（<1280）。
+   ⚠ 本段全部是对 theme-default scoped 样式的覆盖（双类写法补特异性，
+   依赖 custom.css 晚于组件样式加载），升级 vitepress 需回归本段。
+   ================================================================ */
+
+/* 1. 侧栏本体：全视口统一「浮起圆角 panel」几何——四边留缝 + 圆角 + 大阴影，
+   不再是贴死左缘的全高竖条。宽度上限与 ResizableSidebar CONF.left.max 一致 */
+.VPSidebar.VPSidebar {
+  top: calc(var(--vp-layout-top-height, 0px) + 10px);
+  bottom: 10px;
+  left: 10px;
+  width: calc(100vw - 20px);
+  max-width: 480px;
+  border-radius: 14px;
+  border: 1px solid var(--vp-c-border);
+  box-shadow: 0 16px 48px rgba(0, 0, 0, 0.22);
+}
+
+/* ≥960px 撤销常驻/居中容器宽，回到抽屉态（滑入滑出同移动端） */
+@media (min-width: 960px) {
+  :root:root {
+    /* 桌面常驻态会降为 25（低于遮罩 50），抽屉必须盖住正文与遮罩 */
+    --vp-z-index-sidebar: 60;
+  }
+
+  .VPSidebar.VPSidebar {
+    opacity: 0;
+    visibility: hidden;
+    transform: translateX(-100%);
+    transition: opacity 0.5s, transform 0.25s ease;
+  }
+
+  .VPSidebar.VPSidebar.open {
+    opacity: 1;
+    visibility: visible;
+    transform: translateX(0);
+    transition: opacity 0.25s,
+      transform 0.5s cubic-bezier(0.19, 1, 0.22, 1);
+  }
+
+  /* curtain 是常驻态把侧栏背景垫到顶栏下的补丁，抽屉模式用不上 */
+  .VPSidebar .curtain {
+    display: none;
+  }
+}
+
+/* ≥1440px 常驻态会把内容推到居中线，撤销大留白 padding */
+@media (min-width: 1440px) {
+  .VPSidebar.VPSidebar {
+    padding-left: 32px;
+  }
+}
+
+/* 2. 遮罩：≥1280px theme-default 会整个隐藏遮罩，放开让点击外部可关闭 */
+@media (min-width: 1280px) {
+  .VPBackdrop.VPBackdrop {
+    display: block;
+  }
+}
+:root:root {
+  /* 默认 0.6 太重，抽屉是轻量浮层，压到 0.3 */
+  --vp-backdrop-bg-color: rgba(0, 0, 0, 0.3);
+}
+
+/* 3. 正文避让清零：侧栏不再占位，VPContent 恢复无侧栏的居中布局 */
+.VPContent.VPContent.has-sidebar {
+  margin: var(--vp-layout-top-height, 0px) auto 0;
+}
+
+@media (min-width: 960px) {
+  .VPContent.VPContent.has-sidebar {
+    padding-left: 0;
+  }
+}
+
+@media (min-width: 1440px) {
+  .VPContent.VPContent.has-sidebar {
+    padding-left: 0;
+    padding-right: 0;
+  }
+}
+
+/* 正文行宽：常驻态行宽靠 VPContent 的 padding-left 控制，清零后正文可用全屏。
+   侧栏已悬浮不占位，行宽从原版 752/784 放宽到 864/896（中文 ~54 字/行），
+   并解除 has-aside 页 688px 的二次收紧。只限 content、不动 container——
+   container 在 ≥1280 是 flex（正文+右大纲栏），压它的 max-width 会让
+   两个 width:100% 的 flex 子项互相挤压，正文塌成 0px（实测）。 */
+@media (min-width: 960px) {
+  .VPDoc.VPDoc.has-sidebar .content.content {
+    max-width: 864px;
+  }
+}
+
+@media (min-width: 1440px) {
+  .VPDoc.VPDoc.has-sidebar .content.content {
+    max-width: 896px;
+  }
+}
+
+.VPDoc.VPDoc.has-aside .content-container.content-container {
+  max-width: 848px;
+}
+
+@media (min-width: 1440px) {
+  .VPDoc.VPDoc.has-aside .content-container.content-container {
+    max-width: 880px;
+  }
+}
+
+/* 4. 顶栏避让清零：logo 区从 absolute 叠在侧栏上方恢复回正常文档流 */
+@media (min-width: 960px) {
+  /* theme-default ≥960 让整条 navbar 透明、白底靠常驻侧栏+右侧 content-body 垫；
+     侧栏悬浮后没有东西垫底，logo 区透出页面灰底——navbar 自己给整条背景，
+     并撤掉 content-body 的垫底（避免双层） */
+  .VPNavBar.VPNavBar:not(.home) {
+    background-color: var(--vp-nav-bg-color);
+  }
+
+  .VPNavBar.VPNavBar:not(.home.top) .content-body.content-body {
+    background-color: transparent;
+  }
+
+  .VPNavBar.VPNavBar.has-sidebar .wrapper.wrapper {
+    padding: 0 32px;
+  }
+
+  .VPNavBar.VPNavBar.has-sidebar .container.container {
+    max-width: calc(var(--vp-layout-max-width) - 64px);
+  }
+
+  .VPNavBar.VPNavBar.has-sidebar .title.title {
+    position: static;
+    padding: 0;
+    width: auto;
+    height: auto;
+  }
+
+  .VPNavBar.VPNavBar.has-sidebar .content.content {
+    position: static;
+    padding-right: 32px;
+    padding-left: 0;
+  }
+
+  .VPNavBar.VPNavBar.has-sidebar .divider.divider {
+    padding-left: 0;
+  }
+}
+
+@media (min-width: 1440px) {
+  .VPNavBar.VPNavBar.has-sidebar .title.title {
+    padding: 0;
+    width: auto;
+  }
+
+  .VPNavBar.VPNavBar.has-sidebar .content.content {
+    padding-right: calc((100vw - var(--vp-layout-max-width)) / 2 + 32px);
+    padding-left: 0;
+  }
+
+  .VPNavBar.VPNavBar.has-sidebar .divider.divider {
+    padding-left: 0;
+  }
+}
+
+/* 文档页顶栏 logo（"AwesomeQt 教程"）收起：品牌已由 AppTitleBar（IDE 标题栏）
+   承载，navbar 再挂一行属于信息重复；且侧栏常驻时代它叠在侧栏上方、视觉有归属，
+   抽屉化后独占顶栏钉在左上角显得突兀（issue #20 改版反馈）。首页不动。 */
+@media (min-width: 960px) {
+  .VPNavBar.VPNavBar:not(.home) .title.title {
+    display: none;
+  }
+}
+
+/* 5. 本地导航条（960~1279 显示）：撤销侧栏避让，「菜单」按钮即抽屉开关 */
+@media (min-width: 960px) {
+  .VPLocalNav.VPLocalNav.has-sidebar {
+    padding-left: 0;
+  }
+}
+
+@media (min-width: 1440px) {
+  .VPLocalNav.VPLocalNav.has-sidebar {
+    padding-left: 0;
+  }
+
+  /* outline 下拉原本定位在常驻侧栏右侧，改回左缘 */
+  .VPLocalNavOutlineDropdown .items.items {
+    left: 32px;
+  }
+}
+
 /* ================================================================
    code-group tabs —— hover 着色（借 anatomy_gui）
    ================================================================ */
diff --git a/site/.vitepress/theme/index.ts b/site/.vitepress/theme/index.ts
index 70cee75..f95aaf7 100644
--- a/site/.vitepress/theme/index.ts
+++ b/site/.vitepress/theme/index.ts
@@ -12,6 +12,7 @@ import CardGrid from './components/CardGrid.vue'
 import CardLink from './components/CardLink.vue'
 import FontSizeSwitcher from './components/FontSizeSwitcher.vue'
 import ResizableSidebar from './components/ResizableSidebar.vue'
+import SidebarRail from './components/SidebarRail.vue'
 import ReadingProgress from './components/ReadingProgress.vue'
 import ModuleCard from './components/ModuleCard.vue'
 import ChapterHero from './components/ChapterHero.vue'
@@ -24,7 +25,8 @@ export default {
     return h(DefaultTheme.Layout, null, {
       // 工作台外壳：网站 = 一个 Qt 桌面应用。标题栏经 --vp-layout-top-height
       // 由 VitePress 原生机制全链避让；状态栏 fixed 钉底（.Layout 已留 26px）。
-      'layout-top': () => [h(ReadingProgress), h(AppTitleBar), h(ResizableSidebar)],
+      // SidebarRail：左缘窄条，抽屉侧栏的桌面开关（issue #20）
+      'layout-top': () => [h(ReadingProgress), h(AppTitleBar), h(ResizableSidebar), h(SidebarRail)],
       'layout-bottom': () => h(StatusBar),
       // 首页 = Welcome 欢迎屏（index.md 零 hero/features frontmatter，零覆盖战）：
       // 交互演示（signal→slot 真控件复刻）→ 三层卡 → 示例画廊 → 编译输出 → 生态行。