@bdsoft/fileviewer

文档预览组件，封装 @file-viewer/vue3，并默认接入 @file-viewer/preset-office。

纯前端解析、无需服务端转码，适用于 Word / Excel / PowerPoint / PDF / Markdown / 图片等常见文件预览场景。

安装

pnpm add @bdsoft/fileviewer vue

宿主需提供 vue@^3.3.0；@file-viewer/vue3@^2.4.0 和 @file-viewer/preset-office@^2.4.0 由组件包运行时依赖安装。

组件包构建与发布

• 在本包目录运行 npm run build：workspace 模式，minify: false，输出 dist/index.js。首次本地引用前需先构建。
• npm run build:publish：publish 模式，minify: 'esbuild'，用于检查发布产物。
• npm pack / npm publish（含 npm run pub）：prepack 自动生成压缩产物，正常打包结束后 postpack 恢复本地未压缩产物，不改变已打包的 npm 安装包。
• npm test：运行页码定位、旧浏览器兼容和 Worker 构建产物测试。原 check:vue3 指向的脚本不存在，已移除该失效命令。

不要使用 --ignore-scripts 跳过打包生命周期。手动执行发布构建或打包中断后，运行 npm run build 恢复本地产物。包根及已有的 @bdsoft/fileviewer/dist/index.js 导入均指向编译产物，预览组件、实例方法、事件和插槽保持不变。

PDF/PPTX Worker 均沿 Office preset 的真实依赖链定位，并作为独立资源写入 dist。PDF Worker 文件头包含 Chrome 90 所需的 .at() 兼容代码，PPTX Worker 保持原始内容；预览器 CSS 仍打包并随 JS 注入。发布文件包含整个 dist（含 Worker）和说明文档，不能只复制 dist/index.js。

业务项目无需在自己的 vite.config.ts 中复制 Worker、添加 alias 或配置 optimizeDeps；只需正常安装并完整发布本包。若业务通过 options.pdf.workerUrl 或 options.presentation.workerUrl 显式传入地址，则仍以业务配置为准。

本包不再提供独立 index.html、演示应用入口或 dev / preview 命令，交互示例保留在 packages/bd-docs/examples/fileviewer/fileviewer.vue。

注册（main.js）

import { useFileViewer } from '@bdsoft/fileviewer'

app.use(useFileViewer)

注册后即可在任意页面直接使用全局组件 <BdFileViewer>（或底层 <file-viewer>）。组件入口已引入 @file-viewer/vue3/dist/file-viewer3.css，业务项目无需额外引入样式文件。

使用

<template>
  <!-- 预览远程文件（注意：远程地址需目标侧配置 CORS） -->
  <BdFileViewer
    ref="viewerRef"
    :url="url"
    height="600px"
    @load-complete="jumpToThirdPage"
    @current-page-change="handleCurrentPageChange"
  />

  <!-- 预览本地文件（File 对象，优先级高于 url） -->
  <BdFileViewer :file="file" height="80vh" />
</template>

<script setup>
import { ref } from 'vue'

const url = ref('https://example.com/demo.pdf')
const file = ref(null) // 由 <input type="file"> 等途径获取的 File 对象
const viewerRef = ref(null)

// goToPage 默认接收 0 基索引，2 表示第 3 页。
const jumpToThirdPage = () => viewerRef.value?.goToPage(2, { behavior: 'smooth' })

const handleCurrentPageChange = ({ pageIndex, pageNumber }) => {
  console.log('当前页索引/页码：', pageIndex, pageNumber)
}
</script>

goToPage 会根据格式选择定位方式：PDF 优先使用底层原生页状态，DOC/DOCX、PPT/PPTX 使用实际渲染页节点计算内部滚动位置，不按固定页高推算。建议在 load-complete 后调用。

默认配置

BdFileViewer 会为底层 file-viewer 默认补充以下配置：

{
  preset: officePreset,
  rendererMode: 'replace',
  theme: 'light',
  styleIsolation: 'shadow',
  toolbar: {
    theme: false
  },
  pdf: {
    workerUrl: new URL('pdf.worker.mjs', import.meta.url).href
  },
  presentation: {
    workerUrl: new URL('pptx.worker.js', import.meta.url).href,
    workerType: 'module'
  }
}

这些默认值可以通过 options 覆盖；pdf、presentation 等嵌套项会分别合并。比如需要开启主题切换按钮：

<BdFileViewer
  :url="url"
  :options="{ toolbar: { theme: true } }"
/>

属性（Props）

| 参数名 | 类型 | 默认值 | 说明 | | ---------- | ---------------- | -------- | ------------------------------------------------------------ | | url | String | - | 远程文件地址（需目标侧支持 CORS） | | file | File | - | 本地文件对象，优先级高于 url | | fileName | String | - | 可选，显示用文件名 / 用于推断类型 | | options | Object | - | 透传给底层组件的配置，会与组件默认配置合并 | | height | String | Number | 600px | 预览容器高度（数字按 px 处理）。底层组件填充父级，必须给高度 |

除 height 外，其余属性/事件均透传给底层 @file-viewer/vue3 组件。

实例方法

通过模板 ref 获取 BdFileViewer 实例：

| 方法 | 返回值 | 说明 | | --- | --- | --- | | goToPage(pageIndex, options?) | Promise<boolean> | 跳转到指定渲染页；默认 0 基索引。options.indexBase 可设为 1，options.behavior 支持 auto / smooth | | collectDocumentAnchors() | Promise<Array> | 获取底层文档锚点 | | scrollToAnchor(anchor) | Promise<boolean> | 滚动到底层文档锚点 | | getScrollContainer() | HTMLElement \| null | 获取实际内部滚动容器 | | getViewState() | Object \| null | 获取底层视图状态 | | applyViewState(state, options?) | Promise<Object \| null> | 应用底层视图状态，PDF 支持 page 页码 |

事件

| 事件名 | 参数 | 说明 | | --- | --- | --- | | current-page-change | { pageIndex, pageNumber, source } | 主动跳页成功或底层返回页状态时触发；pageIndex 为 0 基，pageNumber 为 1 基 |

底层 load-start、load-complete、location-change、view-state-change 等事件继续透传。

插槽

组件会透传底层全部插槽，包括 toolbar-start 和 toolbar-end。

页码定位注意事项

• Chrome 90 等不支持 Array.prototype.at 的旧 Chromium 环境会由组件入口和 PDF Worker 自动补充兼容实现，无需业务侧全局引入 polyfill。
• 页码超出当前格式实际渲染页数量时，goToPage 返回 false。
• DOCX 未开启视觉分页时，定位单位是底层渲染出的文档 section，不等同于 Word 客户端重新排版后的物理纸张页。
• Excel、Markdown、纯文本等没有分页节点的格式不支持按页跳转，可改用 collectDocumentAnchors() 与 scrollToAnchor() 定位内容。

Monorepo 构建依赖

Vite、构建插件与 Sass 按配置需要使用仓库根目录 devDependencies 统一管理的版本，本包不重复声明这些工具。请在完整 monorepo 环境完成依赖安装后构建；单独复制本包源码不能视为已具备完整构建环境。根目录未声明 vue，包内保留其本地开发依赖；peerDependencies 继续约束宿主版本。原有构建插件配置、workspace／publish 压缩规则与打包生命周期保持不变。