md2ui 1.0.19 → 1.0.21

package/src/composables/useScroll.js

@@ -1,5 +1,10 @@
 import { ref } from 'vue'
 
+// ===== 常量 =====
+// smooth 滚动锁定超时（scrollend 事件优先解锁，此值仅作兜底）
+// 低性能设备或长文档上 smooth 滚动可能超过 800ms，拉长到 1500ms 确保安全
+const SCROLL_LOCK_TIMEOUT_MS = 1500
+
 // 单例状态，确保多处调用共享同一份
 const scrollProgress = ref(0)
 const showBackToTop = ref(false)
@@ -8,6 +13,24 @@ const activeHeading = ref('')
 // 外部注入的 tocItems 引用，用于编辑模式下通过文本匹配标题
 let _tocItemsRef = null
 
+// 点击目录项后锁定，防止滚动检测覆盖 activeHeading 导致闪动
+let _locked = false
+let _lockTimer = null
+
+// 标题元素缓存
+let _headingsCache = null
+
+// MutationObserver：监听 .markdown-content 子树变化，自动失效标题缓存
+let _mutationObserver = null
+
+// 标记：true 表示 activeHeading 被文档切换清空，不应同步到 URL
+let _suppressHashClear = false
+
+// IntersectionObserver 实例
+let _observer = null
+// 记录当前在视口中的标题（id → IntersectionObserverEntry）
+const _visibleHeadings = new Map()
+
 export function useScroll() {
 
   // 注入 tocItems 引用（由 useDocManager 调用一次）
@@ -15,18 +38,246 @@ export function useScroll() {
     _tocItemsRef = tocItems
   }
 
-  // 监听滚动
+  // 重建标题缓存并重新设置 IntersectionObserver
+  let _rebuildRetryTimer = null
+  function rebuildHeadingsCache() {
+    if (_rebuildRetryTimer) { clearTimeout(_rebuildRetryTimer); _rebuildRetryTimer = null }
+    _headingsCache = null
+    _setupMutationObserver()
+    _setupObserver()
+    // 如果 tocItems 有内容但 DOM 中没查到标题（编辑器还没渲染完），延迟重试
+    const headings = _headingsCache || []
+    const hasTocItems = _tocItemsRef && _tocItemsRef.value && _tocItemsRef.value.length > 0
+    if (headings.length === 0 && hasTocItems) {
+      _rebuildRetryTimer = setTimeout(() => {
+        _headingsCache = null
+        _setupMutationObserver()
+        _setupObserver()
+      }, 200)
+    }
+  }
+
+  // 设置 MutationObserver 监听内容区子树变化，自动失效标题缓存
+  let _mutationDebounce = null
+  function _setupMutationObserver() {
+    if (_mutationObserver) {
+      _mutationObserver.disconnect()
+      _mutationObserver = null
+    }
+    // 监听 .content 容器，兼容预览模式和编辑模式（编辑模式下可能有多个 .markdown-content）
+    const container = document.querySelector('.content')
+    if (!container) return
+    _mutationObserver = new MutationObserver(() => {
+      // 子树变化时失效缓存，下次 _getHeadings 会重新查询
+      _headingsCache = null
+      // 编辑模式下 tiptap 频繁修改 DOM，跳过 IntersectionObserver 重建避免抖动
+      const container = document.querySelector('.content')
+      if (container && container.classList.contains('editor-content')) return
+      // 防抖重建 IntersectionObserver，确保新增/删除的标题也能被监听
+      if (_mutationDebounce) clearTimeout(_mutationDebounce)
+      _mutationDebounce = setTimeout(() => {
+        _setupObserver()
+      }, 800)
+    })
+    _mutationObserver.observe(container, { childList: true, subtree: true })
+  }
+
+  function _getHeadings() {
+    if (_headingsCache) return _headingsCache
+    const content = document.querySelector('.content')
+    if (!content) return []
+    _headingsCache = [...content.querySelectorAll(
+      '.markdown-content h1, .markdown-content h2, .markdown-content h3, .markdown-content h4, .markdown-content h5, .markdown-content h6'
+    )]
+    // 编辑模式下 tiptap 渲染的标题没有 id，通过 tocItems 文本匹配注入 id
+    // 使注入后的标题能直接复用预览模式的 getElementById 锚点逻辑
+    _syncHeadingIds(_headingsCache)
+    return _headingsCache
+  }
+
+  // 为缺少 id 的标题元素注入 id（基于 tocItems 文本匹配）
+  function _syncHeadingIds(headings) {
+    if (!_tocItemsRef || !_tocItemsRef.value || !_tocItemsRef.value.length) return
+    // 构建 text → id 的映射（处理重复文本：按出现顺序依次匹配）
+    const tocQueue = new Map()
+    for (const item of _tocItemsRef.value) {
+      if (!tocQueue.has(item.text)) {
+        tocQueue.set(item.text, [])
+      }
+      tocQueue.get(item.text).push(item.id)
+    }
+    for (const heading of headings) {
+      if (heading.id) continue // 已有 id，跳过
+      const text = getHeadingText(heading)
+      const ids = tocQueue.get(text)
+      if (ids && ids.length > 0) {
+        heading.id = ids.shift()
+      }
+    }
+  }
+
+  // 设置 IntersectionObserver 监听标题元素
+  function _setupObserver() {
+    // 清理旧的 observer
+    if (_observer) {
+      _observer.disconnect()
+      _observer = null
+    }
+    _visibleHeadings.clear()
+
+    const content = document.querySelector('.content')
+    if (!content) return
+
+    const headings = _getHeadings()
+    if (!headings.length) return
+
+    // rootMargin: 顶部 0px，底部 -70%，即标题进入视口上方 30% 区域时触发
+    _observer = new IntersectionObserver(
+      (entries) => {
+        if (_locked) return
+
+        for (const entry of entries) {
+          const id = entry.target.id || findTocIdByText(getHeadingText(entry.target))
+          if (!id) continue
+          if (entry.isIntersecting) {
+            _visibleHeadings.set(id, entry)
+          } else {
+            _visibleHeadings.delete(id)
+          }
+        }
+
+        _resolveActiveHeading()
+      },
+      {
+        root: content,
+        // 上方全部可见，下方只保留 30%（裁掉底部 70%）
+        rootMargin: '0px 0px -70% 0px',
+        threshold: 0
+      }
+    )
+
+    for (const heading of headings) {
+      _observer.observe(heading)
+    }
+  }
+
+  // 根据可见标题集合确定当前激活标题
+  // 策略：取文档顺序中最后一个进入检测区域的标题
+  function _resolveActiveHeading() {
+    if (_locked) return
+
+    const headings = _getHeadings()
+    if (!headings.length) return
+
+    const content = document.querySelector('.content')
+
+    // 边界处理：滚动到底部时，强制激活最后一个标题
+    if (content) {
+      const atBottom = content.scrollTop + content.clientHeight >= content.scrollHeight - 10
+      if (atBottom) {
+        // 从后往前找最后一个有 id 的标题
+        for (let i = headings.length - 1; i >= 0; i--) {
+          const id = headings[i].id || findTocIdByText(getHeadingText(headings[i]))
+          if (id) {
+            if (!activeHeading.value) _suppressHashClear = false
+            activeHeading.value = id
+            return
+          }
+        }
+      }
+    }
+
+    // 正常情况：从可见标题中取文档顺序最后一个
+    if (_visibleHeadings.size > 0) {
+      let lastId = ''
+      for (const heading of headings) {
+        const id = heading.id || findTocIdByText(getHeadingText(heading))
+        if (id && _visibleHeadings.has(id)) {
+          lastId = id
+        }
+      }
+      if (lastId) {
+        activeHeading.value = lastId
+        return
+      }
+    }
+
+    // 没有可见标题时，用传统方式兜底（滚动位置在第一个标题之前）
+    if (content && content.scrollTop < 100) {
+      if (activeHeading.value) _suppressHashClear = false
+      activeHeading.value = ''
+    }
+  }
+
+  // 编辑模式下基于滚动位置计算当前激活标题
+  // tiptap 会频繁替换 DOM 元素导致 IntersectionObserver 失效，改用传统方式
+  function _resolveActiveHeadingByScroll(container) {
+    if (_locked) return
+    // 每次都重新查询标题元素，因为 tiptap 可能已替换 DOM
+    _headingsCache = null
+    const headings = _getHeadings()
+    if (!headings.length) return
+
+    const scrollTop = container.scrollTop
+    // 检测区域：视口上方 30%（与 IO 的 rootMargin 策略一致）
+    const threshold = container.clientHeight * 0.3
+
+    // 滚动到底部时，强制激活最后一个标题
+    const atBottom = scrollTop + container.clientHeight >= container.scrollHeight - 10
+    if (atBottom) {
+      for (let i = headings.length - 1; i >= 0; i--) {
+        const id = headings[i].id || findTocIdByText(getHeadingText(headings[i]))
+        if (id) {
+          activeHeading.value = id
+          return
+        }
+      }
+    }
+
+    // 从后往前找最后一个滚过检测线的标题
+    let lastId = ''
+    for (const heading of headings) {
+      // offsetTop 是相对于 offsetParent 的，需要计算相对于滚动容器的位置
+      const headingTop = heading.getBoundingClientRect().top - container.getBoundingClientRect().top
+      if (headingTop <= threshold) {
+        const id = heading.id || findTocIdByText(getHeadingText(heading))
+        if (id) lastId = id
+      }
+    }
+
+    if (lastId) {
+      activeHeading.value = lastId
+    } else if (scrollTop < 100) {
+      activeHeading.value = ''
+    }
+  }
+
+  // 监听滚动：更新进度条、返回顶部按钮，以及处理底部边界
   function handleScroll(e) {
     const element = e.target
     const scrollTop = element.scrollTop
     const scrollHeight = element.scrollHeight - element.clientHeight
-    
+
     if (scrollHeight > 0) {
       scrollProgress.value = Math.round((scrollTop / scrollHeight) * 100)
       showBackToTop.value = scrollTop > 300
     }
-    
-    updateActiveHeading()
+
+    // 编辑模式下 tiptap 会替换 DOM 元素导致 IO 失效，改用滚动位置计算
+    if (element.classList.contains('editor-content')) {
+      if (!_locked) {
+        _resolveActiveHeadingByScroll(element)
+      }
+      return
+    }
+
+    // 底部边界检测（IO 的 rootMargin 裁掉了底部 70%，滚到底时可能漏掉）
+    if (!_locked) {
+      const atBottom = scrollTop + element.clientHeight >= element.scrollHeight - 10
+      if (atBottom) {
+        _resolveActiveHeading()
+      }
+    }
   }
 
   // 提取标题纯文本（去掉锚点图标等子元素）
@@ -43,49 +294,52 @@ export function useScroll() {
     return item ? item.id : ''
   }
 
-  // 更新当前激活的标题
-  function updateActiveHeading() {
-    const content = document.querySelector('.content')
-    if (!content) return
-    
-    const headings = content.querySelectorAll('.markdown-content h1, .markdown-content h2, .markdown-content h3, .markdown-content h4, .markdown-content h5, .markdown-content h6')
-    const scrollTop = content.scrollTop
-    
-    let currentId = ''
-    headings.forEach(heading => {
-      const rect = heading.getBoundingClientRect()
-      const contentRect = content.getBoundingClientRect()
-      const offsetTop = rect.top - contentRect.top + scrollTop
-      
-      if (offsetTop <= scrollTop + 100) {
-        // 优先用 id，没有 id 时通过文本匹配 tocItems
-        currentId = heading.id || findTocIdByText(getHeadingText(heading))
-      }
-    })
-    
-    activeHeading.value = currentId
+  // 解锁函数
+  function _unlock() {
+    _locked = false
+    if (_lockTimer) { clearTimeout(_lockTimer); _lockTimer = null }
+    // 解锁后立即重新解析一次，确保 IO 状态同步
+    _resolveActiveHeading()
   }
 
-  // 滚动到指定标题（支持编辑模式下通过文本匹配定位）
+  // 滚动到指定标题
   function scrollToHeading(id) {
-    // 优先通过 id 定位
+    activeHeading.value = id
+    // 锁定，防止 smooth 滚动期间检测覆盖
+    _locked = true
+    if (_lockTimer) clearTimeout(_lockTimer)
+
+    const content = document.querySelector('.content')
+
+    // 优先用 scrollend 事件解锁，SCROLL_LOCK_TIMEOUT_MS 兜底
+    if (content) {
+      content.addEventListener('scrollend', _unlock, { once: true })
+    }
+    _lockTimer = setTimeout(() => {
+      _unlock()
+      if (content) content.removeEventListener('scrollend', _unlock)
+    }, SCROLL_LOCK_TIMEOUT_MS)
+
     let el = document.getElementById(id)
     if (el) {
       el.scrollIntoView({ behavior: 'smooth', block: 'start' })
-      activeHeading.value = id
+      // 触发高亮闪烁动画
+      _flashHeading(el)
       return
     }
     // 编辑模式下标题无 id，通过 tocItems 找到文本再匹配 DOM
+    // 注意：不调用 _getHeadings() 避免 _syncHeadingIds 修改 tiptap DOM 导致节点重建
     if (_tocItemsRef && _tocItemsRef.value) {
       const tocItem = _tocItemsRef.value.find(t => t.id === id)
       if (tocItem) {
-        const content = document.querySelector('.content')
         if (!content) return
-        const headings = content.querySelectorAll('.markdown-content h1, .markdown-content h2, .markdown-content h3, .markdown-content h4, .markdown-content h5, .markdown-content h6')
+        const headings = [...content.querySelectorAll(
+          '.markdown-content h1, .markdown-content h2, .markdown-content h3, .markdown-content h4, .markdown-content h5, .markdown-content h6'
+        )]
         for (const heading of headings) {
           if (getHeadingText(heading) === tocItem.text) {
             heading.scrollIntoView({ behavior: 'smooth', block: 'start' })
-            activeHeading.value = id
+            _flashHeading(heading)
             return
           }
         }
@@ -93,6 +347,33 @@ export function useScroll() {
     }
   }
 
+  // 触发标题高亮闪烁动画
+  function _flashHeading(el) {
+    el.classList.remove('heading-flash')
+    void el.offsetWidth // 强制 reflow 重置动画
+    el.classList.add('heading-flash')
+    el.addEventListener('animationend', () => el.classList.remove('heading-flash'), { once: true })
+  }
+
+  // 锁定 activeHeading 一段时间（供外部在非 smooth 滚动场景使用，如页面刷新定位锚点）
+  function lockHeading(id, durationMs = SCROLL_LOCK_TIMEOUT_MS) {
+    activeHeading.value = id
+    _locked = true
+    if (_lockTimer) clearTimeout(_lockTimer)
+    _lockTimer = setTimeout(_unlock, durationMs)
+  }
+
+  // 文档切换时清空 activeHeading（标记为文档切换，不同步清除 URL hash）
+  function clearActiveHeading() {
+    _suppressHashClear = true
+    activeHeading.value = ''
+  }
+
+  // 查询当前是否为文档切换导致的清空
+  function isSuppressHashClear() {
+    return _suppressHashClear
+  }
+
   // 返回顶部
   function scrollToTop() {
     const content = document.querySelector('.content')
@@ -108,6 +389,10 @@ export function useScroll() {
     handleScroll,
     scrollToHeading,
     scrollToTop,
-    setTocItems
+    setTocItems,
+    rebuildHeadingsCache,
+    clearActiveHeading,
+    isSuppressHashClear,
+    lockHeading
   }
 }

package/src/composables/useSearch.js

@@ -42,24 +42,25 @@ export function useSearch() {
     indexBuilding.value = true
 
     const docs = flattenDocs(pendingDocsList)
-    const documents = []
 
-    for (const doc of docs) {
-      try {
-        const response = await fetch(doc.path)
-        if (response.ok) {
+    // 并发加载所有文档内容，大幅提升索引构建速度
+    const documents = (await Promise.all(
+      docs.map(async (doc) => {
+        try {
+          const response = await fetch(doc.path)
+          if (!response.ok) return null
           const content = await response.text()
-          documents.push({
+          return {
             id: doc.key,
             title: doc.label,
             content: content.replace(/^---[\s\S]*?---\n?/, ''), // 去掉 frontmatter
             path: doc.path
-          })
+          }
+        } catch {
+          return null // 忽略加载失败的文档
         }
-      } catch {
-        // 忽略加载失败的文档
-      }
-    }
+      })
+    )).filter(Boolean)
 
     searchIndex = new MiniSearch({
       fields: ['title', 'content'],

package/src/config.js

@@ -1,8 +1,5 @@
-// 共享配置 - vite.config.js 和 DocService.js 共用
+// 共享配置 - vite.config.js 共用
 export const config = {
   // 默认端口
   defaultPort: 3000,
-  
-  // 文件夹默认展开状态
-  folderExpanded: false
 }

package/src/services/DocService.js

@@ -76,9 +76,6 @@ export async function pollDocContent(docPath) {
     if (res.status === 304) return null
     if (res.status === 200) {
       _contentEtag = res.headers.get('etag')
-      // 捕获最后修改时间
-      const lm = res.headers.get('x-last-modified')
-      if (lm) _lastModified = lm
       return await res.text()
     }
   } catch { /* 静默忽略 */ }
@@ -96,19 +93,6 @@ export function resetListEtag() {
   _listEtag = null
 }
 
-// ===== 文档最后修改时间 =====
-let _lastModified = null
-
-/** 获取当前文档的最后修改时间 */
-export function getLastModified() {
-  return _lastModified
-}
-
-/** 重置最后修改时间 */
-export function resetLastModified() {
-  _lastModified = null
-}
-
 // ===== 写操作 API =====
 
 async function postJson(url, body) {