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/assets/styles/views/policies-view.css
+++ b/web/src/assets/styles/views/policies-view.css
@@ -5,22 +5,20 @@
  animation: fadeUp 220ms var(--ease) both;
 }

-.knowledge-grid {
-  height: 100%;
-  min-height: 0;
-  display: grid;
-  grid-template-columns: minmax(0, 1fr) 0;
-  gap: 0;
-  transition: grid-template-columns 320ms var(--ease), gap 320ms var(--ease);
-}
-
-.knowledge-grid.has-preview {
-  grid-template-columns: minmax(560px, 1fr) minmax(420px, 0.82fr);
-  gap: 16px;
-}
-
-.knowledge-main,
-.preview-column {
+.knowledge-grid {
+  height: 100%;
+  min-height: 0;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 0;
+}
+
+.knowledge-grid.has-preview {
+  grid-template-columns: minmax(0, 1fr);
+}
+
+.knowledge-main,
+.preview-column {
  min-width: 0;
  min-height: 0;
 }
@@ -470,17 +468,11 @@ th {
  color: #fff;
 }

-.preview-column {
-  min-width: 0;
-  min-height: 0;
-  overflow: hidden;
-}
-
-.preview-panel {
-  height: 100%;
-  min-height: 0;
-  display: grid;
-  grid-template-rows: auto minmax(0, 1fr);
+.preview-panel {
+  height: 100%;
+  min-height: 0;
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr);
  padding: 20px 22px;
  overflow: hidden;
 }
@@ -555,13 +547,46 @@ th {
  line-height: 1.5;
 }

-.preview-viewer {
-  min-height: 0;
-  margin-top: 18px;
-}
-
-.preview-status {
-  display: grid;
+.preview-viewer {
+  min-height: 0;
+  margin-top: 18px;
+  display: grid;
+}
+
+.preview-modal-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 2000;
+  display: grid;
+  place-items: center;
+  padding: 3vh 2vw;
+  background:
+    radial-gradient(circle at top, rgba(37, 99, 235, 0.12), transparent 32%),
+    rgba(15, 23, 42, 0.56);
+  backdrop-filter: blur(10px);
+}
+
+.preview-modal-shell {
+  width: min(96vw, 1600px);
+  height: min(94vh, 1180px);
+  min-height: 0;
+}
+
+.preview-modal-panel {
+  height: 100%;
+  border-radius: 24px;
+  box-shadow: 0 30px 90px rgba(15, 23, 42, 0.24);
+}
+
+.preview-modal-panel:focus {
+  outline: none;
+  box-shadow:
+    0 0 0 4px rgba(96, 165, 250, 0.22),
+    0 30px 90px rgba(15, 23, 42, 0.24);
+}
+
+.preview-status {
+  display: grid;
  place-items: center;
  min-height: 180px;
  padding: 24px;
@@ -580,21 +605,22 @@ th {
  color: #dc2626;
 }

-.preview-embed-wrap,
-.preview-image-wrap {
-  min-height: 0;
-  overflow: hidden;
-  border: 1px solid #edf2f7;
-  border-radius: 12px;
-  background: #fff;
+.preview-embed-wrap,
+.preview-image-wrap {
+  min-height: 0;
+  height: 100%;
+  overflow: hidden;
+  border: 1px solid #edf2f7;
+  border-radius: 12px;
+  background: #fff;
 }

-.preview-embed {
-  width: 100%;
-  height: 100%;
-  min-height: 560px;
-  border: 0;
-}
+.preview-embed {
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  border: 0;
+}

 .preview-image-wrap {
  display: grid;
@@ -608,25 +634,38 @@ th {
  object-fit: contain;
 }

-.onlyoffice-preview-wrap {
-  min-height: 0;
-  overflow: hidden;
-  border: 1px solid #dbe4ee;
-  border-radius: 12px;
-  background: #fff;
-}
+.onlyoffice-preview-wrap {
+  position: relative;
+  min-height: 0;
+  height: 100%;
+  overflow: hidden;
+  border: 1px solid #dbe4ee;
+  border-radius: 12px;
+  background: #fff;
+}
+
+.onlyoffice-preview-host {
+  width: 100%;
+  height: 100%;
+  min-height: 720px;
+}
+
+.preview-status-overlay {
+  position: absolute;
+  inset: 0;
+  margin: 0;
+  border: 0;
+  border-radius: 0;
+  background: rgba(248, 250, 252, 0.92);
+}

-.onlyoffice-preview-host {
-  width: 100%;
-  min-height: 720px;
-}
-
-.excel-preview-wrap {
-  min-height: 0;
-  overflow: hidden;
-  border: 1px solid #dbe4ee;
-  border-radius: 12px;
-  background: #fff;
+.excel-preview-wrap {
+  min-height: 0;
+  height: 100%;
+  overflow: hidden;
+  border: 1px solid #dbe4ee;
+  border-radius: 12px;
+  background: #fff;
 }

 .excel-sheet-tabs {
@@ -707,13 +746,18 @@ th {
  border-bottom: 0;
 }

-.page-stage {
-  min-height: 0;
-  overflow: auto;
-  display: grid;
-  gap: 20px;
-  padding-right: 6px;
-}
+.page-stage {
+  min-height: 0;
+  height: 100%;
+  overflow: auto;
+  display: grid;
+  gap: 20px;
+  padding-right: 6px;
+  border: 1px solid #e2e8f0;
+  border-radius: 12px;
+  background: linear-gradient(180deg, #ffffff 0%, #f8fafc 100%);
+  padding: 18px 18px 18px 18px;
+}

 .page-sheet {
  display: grid;
@@ -807,16 +851,26 @@ th {
  line-height: 1.75;
 }

-.preview-panel-enter-active,
-.preview-panel-leave-active {
-  transition: opacity 240ms ease, transform 320ms var(--ease);
-}
-
-.preview-panel-enter-from,
-.preview-panel-leave-to {
-  opacity: 0;
-  transform: translateX(24px) scale(0.98);
-}
+.preview-modal-enter-active,
+.preview-modal-leave-active {
+  transition: opacity 220ms ease;
+}
+
+.preview-modal-enter-active .preview-modal-shell,
+.preview-modal-leave-active .preview-modal-shell {
+  transition: transform 320ms var(--ease), opacity 220ms ease;
+}
+
+.preview-modal-enter-from,
+.preview-modal-leave-to {
+  opacity: 0;
+}
+
+.preview-modal-enter-from .preview-modal-shell,
+.preview-modal-leave-to .preview-modal-shell {
+  opacity: 0;
+  transform: translateY(24px) scale(0.985);
+}

@keyframes previewSheetIn {
  from {
@@ -829,15 +883,9 @@ th {
  }
 }

-@media (max-width: 1320px) {
-  .knowledge-grid.has-preview {
-    grid-template-columns: minmax(0, 1fr) minmax(360px, 0.78fr);
-  }
-}
-
-@media (max-width: 1080px) {
-  .knowledge-grid,
-  .knowledge-grid.has-preview {
+@media (max-width: 1080px) {
+  .knowledge-grid,
+  .knowledge-grid.has-preview {
    grid-template-columns: 1fr;
    gap: 16px;
    overflow-y: auto;
@@ -854,9 +902,9 @@ th {
  }
 }

-@media (max-width: 760px) {
-  .panel-title,
-  .preview-head,
+@media (max-width: 760px) {
+  .panel-title,
+  .preview-head,
  .viewer-toolbar {
    flex-direction: column;
    align-items: stretch;
@@ -872,9 +920,31 @@ th {
    justify-items: stretch;
  }

-  .pager,
-  .page-size-wrap,
-  .page-size {
-    justify-self: stretch;
-  }
-}
+  .pager,
+  .page-size-wrap,
+  .page-size {
+    justify-self: stretch;
+  }
+
+  .preview-modal-overlay {
+    padding: 8px;
+  }
+
+  .preview-modal-shell {
+    width: calc(100vw - 16px);
+    height: calc(100vh - 16px);
+  }
+
+  .preview-modal-panel {
+    border-radius: 18px;
+    padding: 16px;
+  }
+
+  .preview-head {
+    padding-bottom: 12px;
+  }
+
+  .preview-viewer {
+    margin-top: 14px;
+  }
+}
--- 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`
+  }
+}
--- a/web/tests/knowledge-preview-layout.test.mjs
+++ b/web/tests/knowledge-preview-layout.test.mjs
@@ -0,0 +1,25 @@
+import assert from 'node:assert/strict'
+
+import { resolveKnowledgePreviewLayoutState } from '../src/views/scripts/knowledgePreviewLayout.js'
+
+function testUsesLibraryOnlyLayoutWithoutSelection() {
+  assert.deepEqual(resolveKnowledgePreviewLayoutState(null), {
+    isPreviewModalOpen: false,
+    usesSplitLayout: false
+  })
+}
+
+function testUsesModalPreviewLayoutWhenDocumentIsSelected() {
+  assert.deepEqual(resolveKnowledgePreviewLayoutState({ id: 'doc-1' }), {
+    isPreviewModalOpen: true,
+    usesSplitLayout: false
+  })
+}
+
+function run() {
+  testUsesLibraryOnlyLayoutWithoutSelection()
+  testUsesModalPreviewLayoutWhenDocumentIsSelected()
+  console.log('knowledge preview layout tests passed')
+}
+
+run()
--- a/web/tests/knowledge-preview-mode.test.mjs
+++ b/web/tests/knowledge-preview-mode.test.mjs
@@ -1,6 +1,10 @@
 import assert from 'node:assert/strict'

-import { resolveKnowledgePreviewMode } from '../src/views/scripts/knowledgePreviewMode.js'
+import {
+  resolveKnowledgePreviewMode,
+  shouldRenderOnlyOfficeHost,
+  shouldRenderOnlyOfficePreview
+} from '../src/views/scripts/knowledgePreviewMode.js'

 function testPrefersOnlyOfficeForSupportedOfficeFileWhenAvailable() {
  const document = {
@@ -29,10 +33,108 @@ function testUsesPreviewKindForNonOnlyOfficeFile() {
  assert.equal(resolveKnowledgePreviewMode(document, { onlyOfficeAvailable: false }), 'pdf')
 }

+function testRendersOnlyOfficeContainerWhileOfficePreviewIsLoading() {
+  const document = {
+    extension: 'docx',
+    previewKind: 'text'
+  }
+
+  assert.equal(
+    shouldRenderOnlyOfficePreview(document, {
+      onlyOfficeLoading: true,
+      onlyOfficeAvailable: false
+    }),
+    true
+  )
+}
+
+function testKeepsOnlyOfficeContainerVisibleWhenOfficePreviewHasError() {
+  const document = {
+    extension: 'docx',
+    previewKind: 'text'
+  }
+
+  assert.equal(
+    shouldRenderOnlyOfficePreview(document, {
+      onlyOfficeLoading: false,
+      onlyOfficeAvailable: false,
+      onlyOfficeError: 'timeout'
+    }),
+    true
+  )
+}
+
+function testDoesNotRenderOnlyOfficeContainerAfterFailedMount() {
+  const document = {
+    extension: 'xlsx',
+    previewKind: 'table'
+  }
+
+  assert.equal(
+    shouldRenderOnlyOfficePreview(document, {
+      onlyOfficeLoading: false,
+      onlyOfficeAvailable: false
+    }),
+    false
+  )
+}
+
+function testRendersOnlyOfficeHostWhileOfficePreviewIsLoading() {
+  const document = {
+    extension: 'pptx',
+    previewKind: 'slides'
+  }
+
+  assert.equal(
+    shouldRenderOnlyOfficeHost(document, {
+      onlyOfficeLoading: true,
+      onlyOfficeAvailable: false
+    }),
+    true
+  )
+}
+
+function testKeepsOnlyOfficeHostVisibleWhenOfficePreviewHasError() {
+  const document = {
+    extension: 'xlsx',
+    previewKind: 'table'
+  }
+
+  assert.equal(
+    shouldRenderOnlyOfficeHost(document, {
+      onlyOfficeLoading: false,
+      onlyOfficeAvailable: false,
+      onlyOfficeError: 'timeout'
+    }),
+    true
+  )
+}
+
+function testDoesNotRenderOnlyOfficeHostForNonOfficeDocuments() {
+  const document = {
+    extension: 'pdf',
+    previewKind: 'pdf'
+  }
+
+  assert.equal(
+    shouldRenderOnlyOfficeHost(document, {
+      onlyOfficeLoading: true,
+      onlyOfficeAvailable: false
+    }),
+    false
+  )
+}
+
 function run() {
  testPrefersOnlyOfficeForSupportedOfficeFileWhenAvailable()
  testFallsBackToStructuredPreviewForOfficeFileWhenOnlyOfficeUnavailable()
  testUsesPreviewKindForNonOnlyOfficeFile()
+  testRendersOnlyOfficeContainerWhileOfficePreviewIsLoading()
+  testKeepsOnlyOfficeContainerVisibleWhenOfficePreviewHasError()
+  testDoesNotRenderOnlyOfficeContainerAfterFailedMount()
+  testRendersOnlyOfficeHostWhileOfficePreviewIsLoading()
+  testKeepsOnlyOfficeHostVisibleWhenOfficePreviewHasError()
+  testDoesNotRenderOnlyOfficeHostForNonOfficeDocuments()
  console.log('knowledge preview mode tests passed')
 }

--- a/web/tests/onlyoffice-preview-config.test.mjs
+++ b/web/tests/onlyoffice-preview-config.test.mjs
@@ -0,0 +1,54 @@
+import assert from 'node:assert/strict'
+
+import { buildOnlyOfficePreviewConfig } from '../src/views/scripts/onlyOfficePreviewConfig.js'
+
+function testUsesExplicitPixelHeightFromViewport() {
+  const config = buildOnlyOfficePreviewConfig({ width: '50%', height: '100%' }, { viewportHeight: 900 })
+
+  assert.equal(config.width, '100%')
+  assert.equal(config.height, '680px')
+}
+
+function testFallsBackToSafeDefaultHeight() {
+  const config = buildOnlyOfficePreviewConfig({}, {})
+
+  assert.equal(config.height, '720px')
+}
+
+function testClampsSmallViewportHeight() {
+  const config = buildOnlyOfficePreviewConfig({}, { viewportHeight: 600 })
+
+  assert.equal(config.height, '520px')
+}
+
+function testUsesEmbeddedPreviewModeWithMinimalToolbar() {
+  const config = buildOnlyOfficePreviewConfig(
+    {
+      editorConfig: {
+        customization: {
+          compactHeader: true
+        }
+      }
+    },
+    {}
+  )
+
+  assert.equal(config.type, 'embedded')
+  assert.deepEqual(config.editorConfig.embedded, {
+    embedUrl: '',
+    fullscreenUrl: '',
+    saveUrl: '',
+    shareUrl: '',
+    toolbarDocked: 'top'
+  })
+}
+
+function run() {
+  testUsesExplicitPixelHeightFromViewport()
+  testFallsBackToSafeDefaultHeight()
+  testClampsSmallViewportHeight()
+  testUsesEmbeddedPreviewModeWithMinimalToolbar()
+  console.log('onlyoffice preview config tests passed')
+}
+
+run()