@vthst/page-manual 1.0.0

package/skill/src/components/PageGuide.antd.vue

@@ -0,0 +1,534 @@
+<template>
+  <!-- 帮助文档按钮：放在 button-bar 末尾，margin-left:auto 推到行右端 -->
+  <a-button class="pg-trigger" @click="openDrawer">
+    <template #icon><QuestionCircleOutlined /></template>
+    帮助文档
+  </a-button>
+
+  <!-- 帮助抽屉：左侧弹出 -->
+  <a-drawer
+    v-model:open="drawerOpen"
+    placement="left"
+    :width="'70%'"
+  >
+    <template #title>
+      <div class="pg-title">
+        <span class="pg-title-main">帮助文档</span>
+      </div>
+    </template>
+    <div class="pg-body">
+      <div class="pg-scroll">
+        <div class="pg-doc-wrap">
+          <aside class="pg-toc">
+            <a-input v-model:value="tocKeyword" placeholder="搜索文档内容" allow-clear>
+              <template #prefix><SearchOutlined /></template>
+            </a-input>
+            <div v-if="tocKeyword.trim()" class="pg-toc-hit">
+              <template v-if="hitCount">
+                <span>{{ activeHit + 1 }} / {{ hitCount }}</span>
+                <span class="pg-toc-hit-nav">
+                  <UpOutlined class="pg-toc-hit-btn" @click="gotoHit(-1)" />
+                  <DownOutlined class="pg-toc-hit-btn" @click="gotoHit(1)" />
+                </span>
+              </template>
+              <template v-else>无匹配内容</template>
+            </div>
+            <nav class="pg-toc-list">
+              <div
+                v-for="item in tocItems"
+                :key="item.text"
+                :class="['pg-toc-item', item.sub ? 'pg-toc-sub' : '', activeToc === item.text ? 'pg-toc-active' : '']"
+                @click="scrollToSection(item)"
+              >{{ item.text }}</div>
+            </nav>
+          </aside>
+          <div ref="docRef" class="pg-doc" @scroll="handleDocScroll">
+            <slot name="doc"></slot>
+          </div>
+        </div>
+      </div>
+    </div>
+  </a-drawer>
+</template>
+
+<script setup>
+import { ref, nextTick, onMounted, watch } from 'vue'
+import {
+  QuestionCircleOutlined,
+  SearchOutlined,
+  UpOutlined,
+  DownOutlined,
+} from '@ant-design/icons-vue'
+
+/**
+ * 页面帮助组件（button-bar 末尾通用）— ant-design-vue 版本
+ *
+ * 依赖：ant-design-vue + @ant-design/icons-vue
+ * 配套模板：docs/page-guide-template.md
+ *
+ * 用法：
+ *   <PageGuide>
+ *     <template #doc> 操作文档内容（按 gd-* 类 + data-toc 标题约定书写） </template>
+ *   </PageGuide>
+ */
+const drawerOpen = ref(false)
+
+/** ===== 操作文档目录（TOC）+ 全文搜索高亮 ===== */
+const tocKeyword = ref('')
+const tocItems = ref([])
+const hitCount = ref(0)
+const activeHit = ref(-1)
+let hitRanges = []
+const activeToc = ref('')
+const docRef = ref(null)
+
+const collectToc = () => {
+  const root = docRef.value
+  if (!root) {
+    tocItems.value = []
+    return
+  }
+  tocItems.value = [...root.querySelectorAll('[data-toc]')].map((el) => ({
+    text: (el.textContent || '').trim(),
+    sub: el.hasAttribute('data-toc-sub'),
+    el,
+  }))
+}
+
+const runHighlight = () => {
+  const root = docRef.value
+  if (!root) return
+  const kw = tocKeyword.value.trim()
+  hitCount.value = 0
+  activeHit.value = -1
+  hitRanges = []
+  const supportsHighlight = typeof window.Highlight !== 'undefined' && window.CSS?.highlights
+  if (supportsHighlight) {
+    CSS.highlights.delete('pg-hit')
+    CSS.highlights.delete('pg-hit-active')
+  }
+  if (!kw) return
+
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+    acceptNode: (node) => {
+      const tag = node.parentElement?.tagName
+      if (tag === 'SCRIPT' || tag === 'STYLE') return NodeFilter.FILTER_REJECT
+      return node.nodeValue.includes(kw) ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP
+    },
+  })
+  const ranges = []
+  let textNode
+  while ((textNode = walker.nextNode())) {
+    let idx = textNode.nodeValue.indexOf(kw)
+    while (idx !== -1) {
+      const range = document.createRange()
+      range.setStart(textNode, idx)
+      range.setEnd(textNode, idx + kw.length)
+      ranges.push(range)
+      idx = textNode.nodeValue.indexOf(kw, idx + kw.length)
+    }
+  }
+  hitCount.value = ranges.length
+  if (ranges.length) {
+    hitRanges = ranges
+    if (supportsHighlight) CSS.highlights.set('pg-hit', new Highlight(...ranges))
+    activeHit.value = 0
+    applyActiveHighlight()
+  }
+}
+
+const applyActiveHighlight = () => {
+  const range = hitRanges[activeHit.value]
+  if (!range) return
+  if (typeof window.Highlight !== 'undefined' && window.CSS?.highlights) {
+    CSS.highlights.set('pg-hit-active', new Highlight(range))
+  }
+  range.startContainer.parentElement?.scrollIntoView({ behavior: 'smooth', block: 'center' })
+}
+
+const gotoHit = (dir) => {
+  if (!hitRanges.length) return
+  activeHit.value = (activeHit.value + dir + hitRanges.length) % hitRanges.length
+  applyActiveHighlight()
+}
+
+let highlightTimer = null
+watch(tocKeyword, () => {
+  clearTimeout(highlightTimer)
+  highlightTimer = setTimeout(runHighlight, 300)
+})
+
+const scrollToSection = (item) => {
+  item.el?.scrollIntoView({ behavior: 'smooth', block: 'start' })
+  activeToc.value = item.text
+}
+
+const updateActiveToc = () => {
+  const root = docRef.value
+  if (!root || !tocItems.value.length) return
+  if (!root.offsetHeight) {
+    activeToc.value = tocItems.value[0].text
+    return
+  }
+  const pos = root.scrollTop + 40
+  let current = ''
+  for (const t of tocItems.value) {
+    if (t.el && t.el.offsetTop <= pos) current = t.text
+  }
+  activeToc.value = current || tocItems.value[0].text
+}
+
+let spyTimer = null
+const handleDocScroll = () => {
+  clearTimeout(spyTimer)
+  spyTimer = setTimeout(updateActiveToc, 100)
+}
+
+onMounted(collectToc)
+
+const openDrawer = () => {
+  drawerOpen.value = true
+  nextTick(() => {
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        collectToc()
+        if (tocKeyword.value.trim()) runHighlight()
+        updateActiveToc()
+      })
+    })
+  })
+}
+</script>
+
+<style scoped>
+/* ===== 标题区 ===== */
+.pg-title {
+  display: flex;
+  align-items: center;
+}
+
+.pg-title-main {
+  font-size: 12px;
+  font-weight: 400;
+  color: #64748b;
+}
+
+/* 推到 button-bar 右端 */
+.pg-trigger {
+  margin-left: auto;
+}
+
+/* ===== 内容区布局 ===== */
+.pg-body {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+}
+
+.pg-scroll {
+  flex: 1;
+  min-height: 0;
+}
+
+/* ===== 操作文档双栏 ===== */
+.pg-doc-wrap {
+  display: flex;
+  gap: 16px;
+  height: 100%;
+}
+
+.pg-toc {
+  display: flex;
+  flex-direction: column;
+  width: 190px;
+  flex-shrink: 0;
+  border-right: 1px solid #e5e7eb;
+  padding-right: 8px;
+}
+
+.pg-toc-list {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  margin-top: 8px;
+}
+
+.pg-toc-item {
+  padding: 4px 8px;
+  font-size: 13px;
+  color: #64748b;
+  border-left: 3px solid transparent;
+  border-radius: 0 4px 4px 0;
+  cursor: pointer;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.pg-toc-item:hover {
+  color: #3B82F6;
+  background: rgba(59, 130, 246, 0.10);
+}
+
+.pg-toc-item.pg-toc-active {
+  color: #3B82F6;
+  border-left-color: #3B82F6;
+  background: rgba(59, 130, 246, 0.10);
+  font-weight: 600;
+}
+
+.pg-toc-sub {
+  padding-left: 16px;
+  font-size: 12px;
+}
+
+.pg-toc-hit {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 4px 4px 0;
+  font-size: 12px;
+  color: #94a3b8;
+}
+
+.pg-toc-hit-nav {
+  display: inline-flex;
+  gap: 4px;
+}
+
+.pg-toc-hit-btn {
+  padding: 2px;
+  font-size: 12px;
+  color: #64748b;
+  cursor: pointer;
+  border-radius: 4px;
+}
+
+.pg-toc-hit-btn:hover {
+  color: #3B82F6;
+  background: rgba(59, 130, 246, 0.10);
+}
+
+/* ===== 文档正文 ===== */
+.pg-doc {
+  position: relative;
+  flex: 1;
+  min-width: 0;
+  min-height: 0;
+  overflow-y: auto;
+  font-size: 15px;
+  color: #64748b;
+  line-height: 1.8;
+}
+
+.pg-doc :deep(p) {
+  margin: 0 0 8px;
+}
+.pg-doc :deep(p:last-child) {
+  margin-bottom: 0;
+}
+.pg-doc :deep(ul) {
+  margin: 0;
+  padding-left: 16px;
+}
+.pg-doc :deep(li) {
+  margin-bottom: 4px;
+}
+.pg-doc :deep(li:last-child) {
+  margin-bottom: 0;
+}
+.pg-doc :deep(b) {
+  color: #334155;
+  font-weight: 600;
+}
+
+.pg-doc :deep(.ant-image) {
+  display: flex;
+  justify-content: center;
+  margin: 8px 0 12px;
+}
+.pg-doc :deep(.ant-image-img) {
+  width: auto !important;
+  max-width: 100%;
+  max-height: 320px;
+  object-fit: contain;
+  border-radius: 8px;
+  border: 1px solid #e5e7eb;
+}
+
+/* ===== gd-* 类库（由页面 slot 使用） ===== */
+
+.pg-doc :deep(.gd-sec-title) {
+  display: flex;
+  align-items: center;
+  font-size: 17px;
+  font-weight: 700;
+  color: #334155;
+  margin: 26px 0 8px;
+  padding-left: 8px;
+  border-left: 3px solid #3B82F6;
+}
+.pg-doc :deep(.gd-sec-title:first-child) {
+  margin-top: 2px;
+}
+
+.pg-doc :deep(.gd-op) {
+  border: 1px solid #e5e7eb;
+  border-radius: 8px;
+  background: #fff;
+  padding: 12px 16px;
+  margin: 12px 0;
+}
+
+.pg-doc :deep(.gd-op-title) {
+  font-size: 16px;
+  font-weight: 700;
+  color: #334155;
+}
+
+.pg-doc :deep(.gd-op-goal) {
+  font-size: 14px;
+  color: #94a3b8;
+  margin: 2px 0 8px;
+}
+
+.pg-doc :deep(.gd-step) {
+  display: flex;
+  gap: 12px;
+  align-items: flex-start;
+  margin: 8px 0;
+}
+
+.pg-doc :deep(.gd-step-num) {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  border-radius: 50%;
+  background: #3B82F6;
+  color: #fff;
+  font-size: 12px;
+  font-weight: 600;
+  margin-top: 3px;
+}
+
+.pg-doc :deep(.gd-step-body) {
+  flex: 1;
+  min-width: 0;
+}
+
+.pg-doc :deep(.gd-step-title) {
+  font-weight: 600;
+  color: #334155;
+  margin-bottom: 2px;
+}
+
+.pg-doc :deep(.gd-callout) {
+  border: 1px solid #3B82F6;
+  border-left-width: 4px;
+  border-left-style: solid;
+  border-radius: 4px;
+  padding: 8px 12px;
+  margin: 8px 0;
+  font-size: 15px;
+  background: rgba(59, 130, 246, 0.10);
+  color: #2563eb;
+}
+
+.pg-doc :deep(.gd-callout-title) {
+  font-weight: 600;
+  margin-bottom: 2px;
+}
+
+.pg-doc :deep(.gd-tag-must),
+.pg-doc :deep(.gd-tag-opt),
+.pg-doc :deep(.gd-tag-role) {
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: 600;
+  line-height: 1.6;
+  white-space: nowrap;
+}
+.pg-doc :deep(.gd-tag-must) {
+  background: rgba(220, 38, 38, 0.06);
+  color: #b91c1c;
+}
+.pg-doc :deep(.gd-tag-opt) {
+  background: rgba(59, 130, 246, 0.10);
+  color: #2563eb;
+}
+.pg-doc :deep(.gd-tag-role) {
+  background: rgba(234, 88, 12, 0.08);
+  color: #c2410c;
+}
+
+.pg-doc :deep(table) {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 8px 0 12px;
+  font-size: 15px;
+}
+.pg-doc :deep(th),
+.pg-doc :deep(td) {
+  border: 1px solid #e5e7eb;
+  padding: 4px 12px;
+  text-align: left;
+  vertical-align: top;
+}
+.pg-doc :deep(th) {
+  background: #f8fafc;
+  color: #334155;
+  font-weight: 600;
+  white-space: nowrap;
+}
+.pg-doc :deep(tbody tr:nth-child(even)) {
+  background: rgba(148, 163, 184, 0.06);
+}
+
+.pg-doc :deep(.gd-fig-cap) {
+  text-align: center;
+  font-size: 12px;
+  color: #94a3b8;
+  margin: -2px 0 12px;
+}
+
+.pg-doc :deep(.gd-breadcrumb) {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  background: #f8fafc;
+  border: 1px solid #e5e7eb;
+  border-radius: 4px;
+  padding: 4px 12px;
+  font-size: 14px;
+  color: #334155;
+  margin: 4px 0 4px 12px;
+}
+
+.pg-doc :deep(code) {
+  font-family: monospace;
+  background: #f8fafc;
+  border: 1px solid #e5e7eb;
+  border-radius: 4px;
+  padding: 2px 8px;
+  font-size: 13px;
+  color: #2563eb;
+}
+
+</style>
+
+<style>
+/* 全文搜索命中高亮（CSS Custom Highlight API） */
+.pg-doc ::highlight(pg-hit) {
+  background-color: #fde68a;
+  color: inherit;
+}
+.pg-doc ::highlight(pg-hit-active) {
+  background-color: #fb923c;
+  color: #fff;
+}
+</style>