web-reviewer

Vue 3 文档预览组件，包含 WordViewer（Word）、PdfOfdViewer（PDF / OFD）、ExcelViewer（Excel）三个组件。

安装与引入

npm install web-reviewer vue

样式会在引入组件时自动注入，不需要单独引入 CSS 文件，也不需要在应用里注册全局组件：

<script setup>
import { WordViewer, PdfOfdViewer, ExcelViewer } from 'web-reviewer'
</script>

<template>
  <div class="reviewer-container">
    <ExcelViewer
      v-if="fileInfo.type === 'table'"
      :src="fileInfo.src"
      :file-name="fileInfo.fileName"
    />
  </div>
</template>

也可以全量注册（可选）：

import { createApp } from 'vue'
import WebReviewer from 'web-reviewer'

const app = createApp(App)
app.use(WebReviewer)
// 之后可在模板中直接使用 <WordViewer /> <PdfOfdViewer /> <ExcelViewer />

通用行为

样式：组件导入时自动注入自己的样式，无需引入 CSS；也不会向宿主页面注入 :root、body、* 等全局样式。

尺寸：组件宽度始终等于宿主容器宽度。内部内容保持文档原始排版不变，只按容器宽度做整体等比缩放（类似 PDF 的「适应宽度」）：容器变窄时内容等比例缩小，不会重新断行或改变列宽 / 页宽。

高度：height 不传时默认为 100%，即撑满宿主容器；宿主容器需要有确定高度，若容器高度为自适应则由内容撑开。getInfo() 返回的 clientHeight 即该容器的可视高度。

背景：组件本身不设置容器背景色，业务容器可自行设置背景、边框和尺寸。

通用参数

三个组件都支持以下参数。

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | src | String\|Blob\|ArrayBuffer\|Uint8Array | 必填 | 文件地址或二进制数据 | | fileName | String | '' | 二进制数据对应的文件名，用于识别扩展名 | | height | String\|Number | '100%' | 阅读区域高度；不传时撑满宿主容器 | | hideScrollbar | Boolean | false | 仅隐藏滚动条外观，不影响滚动 | | pageGap | String\|Number | 15 | 页面 / 工作表之间的间距，单位 px | | paddingX | String\|Number | 0 | 内容与容器的左右边距，单位 px | | paddingY | String\|Number | 0 | 内容与容器的上下边距，单位 px | | paperColor | String | '#ffffff' | 纸张背景颜色 |

组件差异参数

| 参数 | 类型 | 默认值 | 支持的组件 | 说明 | | --- | --- | --- | --- | --- | | shadowColor | String | 'rgba(0, 0, 0, 0.35)' | WordViewer、PdfOfdViewer | 纸张阴影颜色 | | textColor | String | '#000000' | WordViewer、ExcelViewer | 页面 / 表格文字颜色。强制覆盖（含文档内单独设置过颜色的文本）；传空字符串 '' 表示不覆盖，保留原始文字颜色 | | borderColor | String | WordViewer：''；ExcelViewer：'#d9e0e8' | WordViewer、ExcelViewer | 表格边框颜色。Word 留空表示保持文档原始边框颜色；Excel 留空回退为默认色 | | showThumbnails | Boolean | false | PdfOfdViewer | 是否显示左侧缩略图栏 | | showSidebar | Boolean | false | PdfOfdViewer | showThumbnails 的语义化别名 | | showSheetTabs | Boolean | true | ExcelViewer | 是否显示工作表标签 |

PDF 的正文由 canvas 绘制，无法通过 CSS 覆盖字体颜色与边框颜色，因此 PdfOfdViewer 不提供 textColor、borderColor。

事件

三个组件都会触发以下事件：

| 事件 | 参数 | 说明 | | --- | --- | --- | | ready | info | 文件首次渲染成功后触发，内容与 getInfo() 一致 | | error | error | 加载或渲染失败时触发，参数为原始 Error 对象 |

<WordViewer src="/a.docx" @ready="onReady" @error="onError" />

方法

通过模板 ref 调用。三个组件共有的方法：

| 方法 | 参数 | 说明 | | --- | --- | --- | | getInfo() | 无 | 返回当前阅读信息 | | scrollTo(position) | number | 滚动到指定垂直位置 | | nextPage() | 无 | 翻到下一页 / 向下滚动一屏 | | previousPage() | 无 | 翻到上一页 / 向上滚动一屏 |

各组件额外方法：

| 方法 | 组件 | 说明 | | --- | --- | --- | | goToPage(page) | WordViewer、PdfOfdViewer | 跳转到指定页，页码从 1 开始 | | goToSheet(index) | ExcelViewer | 切换到指定工作表，序号从 0 开始 |

const viewer = ref(null)
viewer.value.getInfo()
viewer.value.scrollTo(200)
viewer.value.nextPage()
viewer.value.previousPage()
viewer.value.goToPage?.(2)   // Word / PDF
viewer.value.goToSheet?.(1)  // Excel

getInfo() 返回字段

通用字段：

| 字段 | 类型 | 说明 | | --- | --- | --- | | state | string | idle、loading、ready 或 error | | scrollHeight | number | 阅读容器可滚动总高度（px） | | scrollTop | number | 当前垂直滚动位置（px） | | clientHeight | number | 阅读容器可视高度（px） |

额外字段：

| 字段 | 组件 | 说明 | | --- | --- | --- | | pageCount | WordViewer、PdfOfdViewer | 页数 | | sheetCount | ExcelViewer | 工作表数量 | | sheetNames | ExcelViewer | 工作表名称数组 | | activeSheet | ExcelViewer | 当前工作表序号 |

WordViewer

<script setup>
import { WordViewer } from 'web-reviewer'
</script>

<template>
  <WordViewer
    src="/documents/example.docx"
    height="calc(100vh - 120px)"
    :page-gap="15"
    :padding-x="0"
    :padding-y="0"
    paper-color="#ffffff"
    shadow-color="rgba(0, 0, 0, 0.35)"
    text-color="#000000"
    border-color="#d9e0e8"
    ref="wordViewer"
    @ready="onReady"
    @error="onError"
  />
</template>

• 支持 .docx；旧版 .doc 会提示先转换为 .docx。
• 未设置 paddingX 时纸张宽度等于容器宽度；容器宽度变化时整篇文档等比缩放，排版保持不变。
• borderColor 会覆盖文档内表格的边框颜色；不传时保留文档自身的边框颜色。
• textColor 会强制覆盖页面内所有文字颜色，包括文档中单独设置过颜色的文字（如红色标题）；若希望保留文档原始文字颜色，传空字符串 text-color=""。
• getInfo() 额外返回 pageCount。

PdfOfdViewer

<script setup>
import { PdfOfdViewer } from 'web-reviewer'
</script>

<template>
  <PdfOfdViewer
    src="/documents/example.pdf"
    :show-thumbnails="true"
    :padding-x="0"
    paper-color="#ffffff"
    ref="pdfViewer"
  />
</template>

• 支持 .pdf 与 .ofd。
• showThumbnails（默认 false）与 showSidebar（别名）控制左侧缩略图栏。
• PDF 使用 PDF.js 逐页渲染为纸张 canvas，不显示浏览器阅读器外壳；页面按容器宽度等比渲染，缩放不改变排版。
• OFD 提供下载入口；网页端精确渲染需要有商业授权的 OFD 引擎或服务端转换。
• getInfo() 额外返回 pageCount。

ExcelViewer

<script setup>
import { ExcelViewer } from 'web-reviewer'
</script>

<template>
  <ExcelViewer
    src="/documents/example.xlsx"
    :show-sheet-tabs="true"
    :padding-x="0"
    paper-color="#ffffff"
    text-color="#000000"
    border-color="#d9e0e8"
    ref="excelViewer"
  />
</template>

• 支持 .xlsx、.xls、.csv。
• showSheetTabs（默认 true）控制工作表标签。
• 表格保持原始列宽与排版，按容器宽度整体等比缩放，不会为适应宽度而挤压单元格。
• textColor 会强制覆盖单元格内所有文字颜色（含单元格自身设置的颜色）；传空字符串 text-color="" 可保留原始颜色。borderColor 同理用于单元格边框。
• 额外方法：excelViewer.value.goToSheet(1)。
• getInfo() 额外返回 sheetCount、sheetNames、activeSheet。

开发预览页

npm run dev

开发页包含 Word、PDF/OFD、Excel 三个 Tab。选择本地文件或输入地址后，侧栏可编辑各参数、执行翻页 / 切换工作表，并读取 getInfo()。也可通过 ?doc=/demo/example.pdf 直接打开指定文件。

商用许可

项目运行时使用 docx-preview、pdfjs-dist、xlsx 及其依赖。发布组件时请同时分发根目录 THIRD-PARTY-NOTICES.md 和 licenses/ 中的许可证文本，并保留原作者版权及许可声明。