feat: 完善知识库预览功能与配置管理优化

2026-05-09 07:29:49 +00:00
parent d9133193e8
commit 94122fd34b
26 changed files with 20232 additions and 300 deletions
--- a/web/src/views/PoliciesView.vue
+++ b/web/src/views/PoliciesView.vue
@@ -1,15 +1,15 @@
 <template>
-  <section class="knowledge-page">
-    <div class="knowledge-grid" :class="{ 'has-preview': selectedDocument }">
-      <section class="knowledge-main">
-        <article class="library-panel panel">
-          <header class="panel-title">
-            <div>
-              <h2>文档库 / 文件夹</h2>
-              <p>默认展示文件列表，点击具体文件后可在右侧展开预览。</p>
-            </div>
-            <label class="file-search">
-              <i class="mdi mdi-magnify"></i>
+  <section class="knowledge-page">
+    <div class="knowledge-grid" :class="{ 'has-preview': previewLayoutState.usesSplitLayout }">
+      <section class="knowledge-main">
+        <article class="library-panel panel">
+          <header class="panel-title">
+            <div>
+              <h2>文档库 / 文件夹</h2>
+              <p>默认展示文件列表，点击具体文件后以弹窗方式展开预览。</p>
+            </div>
+            <label class="file-search">
+              <i class="mdi mdi-magnify"></i>
              <input v-model="documentSearch" type="search" placeholder="搜索当前文件夹内文件" />
            </label>
          </header>
@@ -159,18 +159,29 @@
              </footer>
            </section>
          </div>
-        </article>
-      </section>
-
-      <Transition name="preview-panel">
-        <aside v-if="selectedDocument" class="preview-column">
-          <article class="preview-panel panel">
-            <header class="preview-head">
-              <div class="preview-copy">
-                <h2>{{ selectedDocument.name }}</h2>
-                <p class="preview-summary-line">
-                  <span v-for="part in previewMetaLine" :key="part">{{ part }}</span>
-                </p>
+        </article>
+      </section>
+      <Teleport to="body">
+        <Transition name="preview-modal">
+          <div
+            v-if="previewLayoutState.isPreviewModalOpen"
+            class="preview-modal-overlay"
+            role="presentation"
+            @click.self="closePreview"
+          >
+            <aside class="preview-modal-shell" role="dialog" aria-modal="true" aria-labelledby="knowledge-preview-title">
+              <article
+                ref="previewDialogPanel"
+                class="preview-panel preview-modal-panel panel"
+                tabindex="-1"
+                @click.stop
+              >
+            <header class="preview-head">
+              <div class="preview-copy">
+                <h2 id="knowledge-preview-title">{{ selectedDocument.name }}</h2>
+                <p class="preview-summary-line">
+                  <span v-for="part in previewMetaLine" :key="part">{{ part }}</span>
+                </p>
                <div v-if="previewSecondaryMetaLine.length" class="preview-secondary-line">
                  <span v-for="part in previewSecondaryMetaLine" :key="part">{{ part }}</span>
                </div>
@@ -185,22 +196,30 @@
                  <i class="mdi mdi-close"></i>
                </button>
              </div>
-            </header>
-
-            <div class="preview-viewer">
-              <div v-if="previewLoading" class="preview-status">正在加载预览...</div>
-              <div v-else-if="previewError" class="preview-status error">{{ previewError }}</div>
+            </header>
+
+            <div class="preview-viewer">
+              <div v-if="shouldRenderOnlyOffice" class="onlyoffice-preview-wrap">
+                <div
+                  v-if="shouldRenderOnlyOfficeHostNode"
+                  :id="onlyOfficeHostId"
+                  class="onlyoffice-preview-host"
+                ></div>
+                <div v-if="onlyOfficeLoading" class="preview-status preview-status-overlay">
+                  正在加载 ONLYOFFICE 预览...
+                </div>
+                <div v-else-if="onlyOfficeError" class="preview-status error preview-status-overlay">
+                  {{ onlyOfficeError }}
+                </div>
+              </div>
+              <div v-else-if="previewLoading" class="preview-status">正在加载预览...</div>
+              <div v-else-if="previewError" class="preview-status error">{{ previewError }}</div>
              <div v-else-if="previewMode === 'pdf' && previewBlobUrl" class="preview-embed-wrap">
                <iframe :src="previewBlobUrl" class="preview-embed" title="PDF 预览"></iframe>
              </div>
              <div v-else-if="previewMode === 'image' && previewBlobUrl" class="preview-image-wrap">
                <img :src="previewBlobUrl" :alt="selectedDocument.name" class="preview-image" />
              </div>
-              <div v-else-if="shouldUseOnlyOffice" class="onlyoffice-preview-wrap">
-                <div v-if="onlyOfficeLoading" class="preview-status">正在加载 ONLYOFFICE 预览...</div>
-                <div v-else-if="onlyOfficeError" class="preview-status error">{{ onlyOfficeError }}</div>
-                <div v-else :id="onlyOfficeHostId" class="onlyoffice-preview-host"></div>
-              </div>
              <div v-else-if="previewMode === 'table'" class="excel-preview-wrap">
                <div v-if="selectedDocument.previewPages.length > 1" class="excel-sheet-tabs" role="tablist" aria-label="Excel 工作表页签">
                  <button
@@ -249,15 +268,17 @@
                </article>
                <div v-if="!selectedDocument.previewPages.length" class="preview-status">
                  当前文件暂未生成结构化预览，请下载后查看。
-                </div>
-              </div>
-            </div>
-          </article>
-        </aside>
-      </Transition>
-    </div>
-  </section>
-</template>
+                </div>
+              </div>
+            </div>
+              </article>
+            </aside>
+          </div>
+        </Transition>
+      </Teleport>
+    </div>
+  </section>
+</template>

 <script src="./scripts/PoliciesView.js"></script>

--- a/web/src/views/scripts/PoliciesView.js
+++ b/web/src/views/scripts/PoliciesView.js
@@ -17,7 +17,14 @@ import {
  buildPreviewMetaLine,
  buildPreviewSecondaryMetaLine
 } from './policiesPreviewFormatters.js'
-import { canUseOnlyOfficePreview, resolveKnowledgePreviewMode } from './knowledgePreviewMode.js'
+import {
+  canUseOnlyOfficePreview,
+  resolveKnowledgePreviewMode,
+  shouldRenderOnlyOfficeHost,
+  shouldRenderOnlyOfficePreview
+} from './knowledgePreviewMode.js'
+import { resolveKnowledgePreviewLayoutState } from './knowledgePreviewLayout.js'
+import { buildOnlyOfficePreviewConfig } from './onlyOfficePreviewConfig.js'

 function triggerFileDownload(blob, filename) {
  const url = URL.createObjectURL(blob)
@@ -27,6 +34,43 @@ function triggerFileDownload(blob, filename) {
  anchor.click()
  URL.revokeObjectURL(url)
 }
+
+let bodyOverflowSnapshot = ''
+let bodyOverscrollBehaviorSnapshot = ''
+
+function setBodyScrollLocked(isLocked) {
+  if (typeof document === 'undefined') {
+    return
+  }
+
+  const { body } = document
+  if (!body) {
+    return
+  }
+
+  if (isLocked) {
+    if (body.dataset.knowledgePreviewLocked === 'true') {
+      return
+    }
+
+    bodyOverflowSnapshot = body.style.overflow
+    bodyOverscrollBehaviorSnapshot = body.style.overscrollBehavior
+    body.style.overflow = 'hidden'
+    body.style.overscrollBehavior = 'contain'
+    body.dataset.knowledgePreviewLocked = 'true'
+    return
+  }
+
+  if (body.dataset.knowledgePreviewLocked !== 'true') {
+    return
+  }
+
+  body.style.overflow = bodyOverflowSnapshot
+  body.style.overscrollBehavior = bodyOverscrollBehaviorSnapshot
+  delete body.dataset.knowledgePreviewLocked
+  bodyOverflowSnapshot = ''
+  bodyOverscrollBehaviorSnapshot = ''
+}

 export default {
  name: 'PoliciesView',
@@ -56,7 +100,9 @@ export default {
    const onlyOfficeAvailable = ref(false)
    const onlyOfficeEditor = ref(null)
    const onlyOfficeHostId = ref('knowledge-onlyoffice-preview')
+    const onlyOfficeReadyTimeoutId = ref(0)
    const currentPreviewPageIndex = ref(0)
+    const previewDialogPanel = ref(null)

    const isAdmin = computed(() => isManagerUser(currentUser.value))
    const uploadHint = computed(() =>
@@ -88,15 +134,31 @@ export default {
      return pages[currentPreviewPageIndex.value] || pages[0] || null
    })
    const previewMetaLine = computed(() => buildPreviewMetaLine(selectedDocument.value))
-    const previewSecondaryMetaLine = computed(() =>
-      buildPreviewSecondaryMetaLine(selectedDocument.value, activePreviewPage.value)
-    )
+    const previewSecondaryMetaLine = computed(() =>
+      buildPreviewSecondaryMetaLine(selectedDocument.value, activePreviewPage.value)
+    )
+    const previewLayoutState = computed(() =>
+      resolveKnowledgePreviewLayoutState(selectedDocument.value)
+    )
    const previewMode = computed(() =>
      resolveKnowledgePreviewMode(selectedDocument.value, {
        onlyOfficeAvailable: onlyOfficeAvailable.value
      })
    )
-    const shouldUseOnlyOffice = computed(() => previewMode.value === 'onlyoffice')
+    const shouldRenderOnlyOffice = computed(() =>
+      shouldRenderOnlyOfficePreview(selectedDocument.value, {
+        onlyOfficeLoading: onlyOfficeLoading.value,
+        onlyOfficeAvailable: onlyOfficeAvailable.value,
+        onlyOfficeError: onlyOfficeError.value
+      })
+    )
+    const shouldRenderOnlyOfficeHostNode = computed(() =>
+      shouldRenderOnlyOfficeHost(selectedDocument.value, {
+        onlyOfficeLoading: onlyOfficeLoading.value,
+        onlyOfficeAvailable: onlyOfficeAvailable.value,
+        onlyOfficeError: onlyOfficeError.value
+      })
+    )
    const excelPreviewTable = computed(() =>
      selectedDocument.value?.previewKind === 'table'
        ? buildExcelPreviewTable(activePreviewPage.value)
@@ -110,12 +172,16 @@ export default {
      }
    }

-    function destroyOnlyOfficeEditor() {
-      if (onlyOfficeEditor.value?.destroyEditor) {
-        onlyOfficeEditor.value.destroyEditor()
-      }
-      onlyOfficeEditor.value = null
-    }
+    function destroyOnlyOfficeEditor() {
+      if (onlyOfficeReadyTimeoutId.value) {
+        window.clearTimeout(onlyOfficeReadyTimeoutId.value)
+        onlyOfficeReadyTimeoutId.value = 0
+      }
+      if (onlyOfficeEditor.value?.destroyEditor) {
+        onlyOfficeEditor.value.destroyEditor()
+      }
+      onlyOfficeEditor.value = null
+    }

    async function mountOnlyOfficeEditor(documentId) {
      onlyOfficeLoading.value = true
@@ -126,22 +192,63 @@ export default {
      try {
        const payload = await fetchKnowledgeOnlyOfficeConfig(documentId)
        await loadOnlyOfficeApi(payload.documentServerUrl)
-        await nextTick()
-
+        await nextTick()
+
        if (!window.DocsAPI?.DocEditor) {
          throw new Error('ONLYOFFICE 编辑器未正确加载。')
        }

        onlyOfficeHostId.value = `knowledge-onlyoffice-preview-${documentId}`
        await nextTick()
-        onlyOfficeEditor.value = new window.DocsAPI.DocEditor(onlyOfficeHostId.value, payload.config)
-        onlyOfficeAvailable.value = true
+        const config = buildOnlyOfficePreviewConfig(payload.config, {
+          viewportHeight: window.innerHeight
+        })
+        const upstreamEvents = config.events || {}
+        config.events = {
+          ...upstreamEvents,
+          onAppReady(event) {
+            if (onlyOfficeReadyTimeoutId.value) {
+              window.clearTimeout(onlyOfficeReadyTimeoutId.value)
+              onlyOfficeReadyTimeoutId.value = 0
+            }
+            onlyOfficeAvailable.value = true
+            onlyOfficeLoading.value = false
+            upstreamEvents.onAppReady?.(event)
+          },
+          onError(event) {
+            if (onlyOfficeReadyTimeoutId.value) {
+              window.clearTimeout(onlyOfficeReadyTimeoutId.value)
+              onlyOfficeReadyTimeoutId.value = 0
+            }
+            const errorCode = event?.data?.errorCode
+            const errorDescription = event?.data?.errorDescription
+            const message = errorDescription
+              ? `ONLYOFFICE 预览失败：${errorDescription}`
+              : `ONLYOFFICE 预览失败${errorCode ? `（错误码 ${errorCode}）` : '。'}`
+            onlyOfficeError.value = message
+            onlyOfficeLoading.value = false
+            console.error('ONLYOFFICE onError', event)
+            toast(message)
+            upstreamEvents.onError?.(event)
+          }
+        }
+        onlyOfficeEditor.value = new window.DocsAPI.DocEditor(onlyOfficeHostId.value, config)
+        onlyOfficeReadyTimeoutId.value = window.setTimeout(() => {
+          if (!onlyOfficeAvailable.value && !onlyOfficeError.value) {
+            onlyOfficeError.value = 'ONLYOFFICE 预览初始化超时。请检查浏览器是否拦截了 iframe 或混合内容。'
+            onlyOfficeLoading.value = false
+            toast(onlyOfficeError.value)
+          }
+        }, 10000)
        return true
      } catch (error) {
        onlyOfficeError.value = error.message || 'ONLYOFFICE 预览加载失败。'
+        toast(onlyOfficeError.value)
        return false
      } finally {
-        onlyOfficeLoading.value = false
+        if (onlyOfficeError.value) {
+          onlyOfficeLoading.value = false
+        }
      }
    }

@@ -158,13 +265,12 @@ export default {
          activeFolder.value = folders.value[0]?.name || ''
        }

-        if (options.preserveSelection && selectedDocument.value?.id) {
-          const exists = documents.value.some((doc) => doc.id === selectedDocument.value.id)
-          if (!exists) {
-            selectedDocument.value = null
-            revokePreviewBlob()
-          }
-        }
+        if (options.preserveSelection && selectedDocument.value?.id) {
+          const exists = documents.value.some((doc) => doc.id === selectedDocument.value.id)
+          if (!exists) {
+            closePreview()
+          }
+        }
      } catch (error) {
        emit('summary-change', { totalDocuments: 0 })
        toast(error.message || '知识库加载失败。')
@@ -187,7 +293,9 @@ export default {
        currentPreviewPageIndex.value = 0

        if (canUseOnlyOfficePreview(payload)) {
+          previewLoading.value = false
          await mountOnlyOfficeEditor(documentId)
+          return
        }

        if (payload.previewKind === 'pdf' || payload.previewKind === 'image') {
@@ -271,13 +379,12 @@ export default {

      deletingId.value = document.id
      try {
-        await deleteKnowledgeDocument(document.id)
-        if (selectedDocument.value?.id === document.id) {
-          selectedDocument.value = null
-          revokePreviewBlob()
-        }
-        await loadLibrary()
-        toast('知识库文件已删除。')
+        await deleteKnowledgeDocument(document.id)
+        if (selectedDocument.value?.id === document.id) {
+          closePreview()
+        }
+        await loadLibrary()
+        toast('知识库文件已删除。')
      } catch (error) {
        toast(error.message || '删除失败。')
      } finally {
@@ -291,15 +398,23 @@ export default {
      currentPage.value = 1
    }

-    function closePreview() {
-      selectedDocument.value = null
-      previewError.value = ''
-      currentPreviewPageIndex.value = 0
+    function closePreview() {
+      selectedDocument.value = null
+      previewLoading.value = false
+      previewError.value = ''
+      currentPreviewPageIndex.value = 0
      revokePreviewBlob()
      destroyOnlyOfficeEditor()
+      onlyOfficeLoading.value = false
      onlyOfficeError.value = ''
      onlyOfficeAvailable.value = false
    }
+
+    function handleWindowKeydown(event) {
+      if (event.key === 'Escape' && selectedDocument.value) {
+        closePreview()
+      }
+    }

    function selectPreviewPage(index) {
      currentPreviewPageIndex.value = index
@@ -314,20 +429,35 @@ export default {
      }
    })

-    watch(activeFolder, () => {
-      closePreview()
-    })
-
-    onMounted(() => {
-      loadLibrary()
-    })
-
+    watch(activeFolder, () => {
+      closePreview()
+    })
+
+    watch(
+      () => previewLayoutState.value.isPreviewModalOpen,
+      async (isPreviewModalOpen) => {
+        setBodyScrollLocked(isPreviewModalOpen)
+
+        if (isPreviewModalOpen) {
+          await nextTick()
+          previewDialogPanel.value?.focus?.()
+        }
+      }
+    )
+
+    onMounted(() => {
+      loadLibrary()
+      window.addEventListener('keydown', handleWindowKeydown)
+    })
+
    onBeforeUnmount(() => {
      revokePreviewBlob()
      destroyOnlyOfficeEditor()
+      setBodyScrollLocked(false)
+      window.removeEventListener('keydown', handleWindowKeydown)
    })
-
-    return {
+
+    return {
      activeFolder,
      activePreviewPage,
      changePageSize,
@@ -344,20 +474,23 @@ export default {
      handleFileInput,
      isAdmin,
      loading,
-      pageSize,
+      pageSize,
      pageSizeOpen,
      pageSizes,
      onlyOfficeError,
      onlyOfficeHostId,
      onlyOfficeLoading,
+      previewDialogPanel,
+      previewLayoutState,
      previewMode,
      previewMetaLine,
      previewSecondaryMetaLine,
      previewBlobUrl,
-      previewError,
-      previewLoading,
-      shouldUseOnlyOffice,
-      selectDocument,
+      previewError,
+      previewLoading,
+      shouldRenderOnlyOffice,
+      shouldRenderOnlyOfficeHostNode,
+      selectDocument,
      selectPreviewPage,
      selectedDocument,
      totalCount,
--- a/web/src/views/scripts/knowledgePreviewLayout.js
+++ b/web/src/views/scripts/knowledgePreviewLayout.js
@@ -0,0 +1,6 @@
+export function resolveKnowledgePreviewLayoutState(selectedDocument) {
+  return {
+    isPreviewModalOpen: Boolean(selectedDocument),
+    usesSplitLayout: false
+  }
+}
--- a/web/src/views/scripts/knowledgePreviewMode.js
+++ b/web/src/views/scripts/knowledgePreviewMode.js
@@ -4,6 +4,30 @@ function supportsOnlyOfficePreview(document) {
  return ONLYOFFICE_EXTENSIONS.has(String(document?.extension || '').toLowerCase())
 }

+export function shouldRenderOnlyOfficePreview(document, options = {}) {
+  if (!supportsOnlyOfficePreview(document)) {
+    return false
+  }
+
+  return (
+    Boolean(options.onlyOfficeLoading) ||
+    Boolean(options.onlyOfficeAvailable) ||
+    Boolean(options.onlyOfficeError)
+  )
+}
+
+export function shouldRenderOnlyOfficeHost(document, options = {}) {
+  if (!supportsOnlyOfficePreview(document)) {
+    return false
+  }
+
+  return (
+    Boolean(options.onlyOfficeLoading) ||
+    Boolean(options.onlyOfficeAvailable) ||
+    Boolean(options.onlyOfficeError)
+  )
+}
+
 export function resolveKnowledgePreviewMode(document, options = {}) {
  if (!document) {
    return 'none'
--- a/web/src/views/scripts/onlyOfficePreviewConfig.js
+++ b/web/src/views/scripts/onlyOfficePreviewConfig.js
@@ -0,0 +1,30 @@
+function clampHeight(viewportHeight) {
+  const numericHeight = Number(viewportHeight)
+  if (!Number.isFinite(numericHeight) || numericHeight <= 0) {
+    return 720
+  }
+
+  return Math.max(520, numericHeight - 220)
+}
+
+export function buildOnlyOfficePreviewConfig(config, options = {}) {
+  const viewportHeight = options.viewportHeight
+  const editorConfig = {
+    ...(config.editorConfig || {}),
+    embedded: {
+      embedUrl: '',
+      fullscreenUrl: '',
+      saveUrl: '',
+      shareUrl: '',
+      toolbarDocked: 'top'
+    }
+  }
+
+  return {
+    ...config,
+    type: 'embedded',
+    editorConfig,
+    width: '100%',
+    height: `${clampHeight(viewportHeight)}px`
+  }
+}