Ecosystem

生态组件总览

Native Ecosystem Packages

Flyfish Viewer 的 2.x 架构把底层预览能力、重型渲染引擎和各框架组件拆清楚了。 新项目优先选择 @file-viewer/* 标准包名；历史 @flyfish-group/* 包名仍同步维护，用于平滑升级旧项目。 生态目标是让每个技术栈都有原生接入体验，同时通过 preset 或 renderer 明确控制格式能力和安装边界。

导览

技术栈 / 场景	推荐入口
无框架页面、微前端壳、script 标签	纯 JS / Pure Web 集成
Vue 3 项目	Vue3 集成
Vue 2.7 / 2.6 项目	Vue2.7 / 2.6 集成
React 18 / 19 项目	React 集成
React 16.8 / 17 老项目	React Legacy 集成
传统 jQuery 后台	jQuery 集成
Svelte / SvelteKit 项目	Svelte 集成
自研组件或深度二开	Core 自定义接入
单独验证 PPTX 渲染能力	PPTX 引擎接入

安装策略

标准组件包是最轻入口。直接安装 @file-viewer/vue3、@file-viewer/react、@file-viewer/web、@file-viewer/svelte、@file-viewer/jquery 或 Vue2 组件包时，只会获得对应生态的原生组件体验、类型声明、controller 和 core 基础能力；具体格式能力由 preset 或单个 renderer 装配。

策略	安装方式	说明
最轻组件入口	npm i @file-viewer/vue3	适合先接入组件壳、再按业务选择格式能力
常见轻附件	npm i @file-viewer/vue3 @file-viewer/preset-lite	文本、Markdown、代码、图片、音频、视频，通过 options.preset 注入
办公文档平台	npm i @file-viewer/vue3 @file-viewer/preset-office	PDF、Word、Excel、PowerPoint、OFD、RTF、OpenDocument，推荐业务默认路线
工程附件平台	npm i @file-viewer/vue3 @file-viewer/preset-engineering	CAD、3D、绘图、XMind、Geo、Typst、Archive、Data、EDA
完整 Demo 能力	npm i @file-viewer/vue3 @file-viewer/preset-all	全量一键安装，适合演示站、后台运维和内部全格式附件中心
完整 full 包	npm i @file-viewer/vue3-full	默认启用 preset-all，不需要手动传 options.preset
CDN 完整体验	https://cdn.jsdelivr.net/npm/@file-viewer/web-full@latest/dist/flyfish-file-viewer-web-full.iife.js	无需本地安装，适合纯 JS / script 标签快速试跑完整格式矩阵
极致裁剪	npm i @file-viewer/vue3 @file-viewer/renderer-pdf	只安装需要的 renderer，并通过 options.renderers 注入

options.preset 是跨构建工具的稳定装配方式。Webpack、Rspack、Rollup、Umi、传统多页应用、微前端壳和内部组件库都可以显式 import preset，然后传给当前生态组件:

import officePreset from '@file-viewer/preset-office'

const viewerOptions = {
  preset: officePreset,
  rendererMode: 'replace'
}

Vite 项目可以额外安装 @file-viewer/vite-plugin 省去手动 import。Vite 不会因为安装了插件包就自动运行，仍需要在 vite.config.ts 注册一次；注册后 fileViewerRenderers() 或 fileViewerRenderers({ copyAssets:true }) 会自动发现已安装的 @file-viewer/preset-*，并把生成的 virtual module 注入 Vite HTML 入口。组件默认 autoRenderers:true，所以 Vue、React、Svelte、jQuery 和 Vanilla JS / Pure Web 都能直接获得对应预览能力。preset-all 能力最完整，但安装依赖也最多；生产业务建议优先选择 preset-lite、preset-office、preset-engineering 或单个 renderer。

// vite.config.ts
import { fileViewerRenderers } from '@file-viewer/vite-plugin'

export default {
  plugins: [
    fileViewerRenderers({
      copyAssets: true
      // 已安装的 preset 会自动激活，不需要手写 import 或 renderers。
    })
  ]
}

选型一览

场景	推荐包	适合项目	入口能力
底层能力	@file-viewer/core	自研组件、二次封装、框架适配	纯 TypeScript 预览能力、格式矩阵、事件、搜索、缩放、打印、导出和共享类型
PPTX 引擎	@file-viewer/pptx	单独优化或验证 PPTX 渲染	独立原生 PPTX renderer、Worker 渐进解析和样式文件
轻量 preset	@file-viewer/preset-lite	常见轻附件预览	文本、Markdown、代码、图片、音频和视频的轻量组合
文档 preset	@file-viewer/preset-office	PDF / Office / OFD 文档平台	PDF、Word、Excel、PowerPoint、OFD、RTF 和 OpenDocument
工程 preset	@file-viewer/preset-engineering	CAD、研发、设计、工程和 EDA 附件平台	CAD、3D、绘图、XMind、Geo、Typst、Archive、Data 和 EDA
全量 preset	@file-viewer/preset-all	官方 Demo、内部全格式附件中心	当前完整格式矩阵
Word renderer	@file-viewer/renderer-word	只需要 DOCX/DOC/RTF/ODT 的业务	标准 renderer 插件，按需加载自研 DOCX、老 DOC 和 RTF/OpenDocument 链路
Vanilla JS / Pure Web	@file-viewer/web	无框架页面、微前端壳、传统系统	<flyfish-file-viewer> 原生组件、mountViewer(container, options)、IIFE script 标签包、资源复制 CLI
Vanilla JS / Pure Web Full	@file-viewer/web-full	script 标签、POC、全格式传统页面	默认启用完整矩阵的 Custom Element、IIFE 和命令式挂载
Vue 3	@file-viewer/vue3	Vue 3.3+	Vue 插件、<file-viewer> 组件、props、事件、ref/controller 和完整类型
Vue 3 Full	@file-viewer/vue3-full	Vue 3 全格式附件中心	默认启用完整矩阵，组件 API 与 @file-viewer/vue3 一致
Vue 2.7	@file-viewer/vue2.7	Vue 2.7 项目	Vue.use(FileViewer) 插件式注册，能力与 Vue 3 线保持一致
Vue 2.7 Full	@file-viewer/vue2.7-full	Vue 2.7 全格式附件中心	默认启用完整矩阵，适合存量 Vue2.7 项目快速升级
Vue 2.6	@file-viewer/vue2.6	仍停留在 Vue 2.6 的老项目	Vue 2.6 专线，避免强迫业务升级到 2.7
Vue 2.6 Full	@file-viewer/vue2.6-full	Vue 2.6 全格式附件中心	默认启用完整矩阵
React 18/19	@file-viewer/react	React 18 / 19，也兼容 React 17	原生 React 组件、useFileViewer、useFileViewerState 和 ref handle
React 18/19 Full	@file-viewer/react-full	React 全格式附件中心	默认启用完整矩阵，组件和 hooks 体验与标准包一致
React 16.8/17	@file-viewer/react-legacy	旧 React hooks 项目	面向 React 16.8 / 17 的独立组件包
React 16.8/17 Full	@file-viewer/react-legacy-full	旧 React 全格式附件中心	默认启用完整矩阵
jQuery	@file-viewer/jquery	传统后台、jQuery 插件体系	$(el).fileViewer(options) 和插件方法调用
jQuery Full	@file-viewer/jquery-full	传统后台全格式附件中心	默认启用完整矩阵
Svelte	@file-viewer/svelte	Svelte / SvelteKit	Svelte 组件、action、事件和 controller 方法
Svelte Full	@file-viewer/svelte-full	Svelte 全格式附件中心	默认启用完整矩阵，组件与 action 入口保持一致

历史兼容包继续发布: @flyfish-group/file-viewer3、file-viewer3、@flyfish-group/file-viewer、@flyfish-group/file-viewer-react、@flyfish-group/file-viewer-web。新系统建议使用标准包名，便于理解依赖边界和后续迁移。

架构边界

• @file-viewer/core 是 framework-neutral 底座，不依赖 Vue、React、Svelte 或 jQuery。
• 各标准组件包只依赖 core 和自己的生态依赖，不嵌套其他框架实现。
• 所有组件包共享同一套 ViewerMountOptions、FileViewerOptions、生命周期事件、操作回调、搜索、缩放、水印、打印和导出语义。
• Office、PDF、OFD、Typst、CAD、压缩包、邮件、3D、绘图、数据文件等重型链路按格式异步加载，未命中的格式不会进入首屏。常见业务优先选 preset-lite、preset-office、preset-engineering，极致裁剪再安装单个 renderer。
• 私有化或内网部署时，运行 file-viewer-copy-assets 复制 Worker、WASM、PDF.js、Draw.io、Typst WASM/字体、CAD、SQLite、压缩包和 Office 静态资源，运行时默认不依赖公共 CDN。
• 样式隔离由同一套 options.styleIsolation 控制。Pure Web / IIFE / Web full 默认使用 Shadow DOM，框架组件默认保持兼容；宿主全局 CSS 不可控时传 styleIsolation:'shadow'，主题定制使用 --file-viewer-* tokens 和 ::part()。完整说明见 样式隔离与主题定制。

组件属性与定制入口

下面是各标准组件包当前实际暴露的属性、事件和控制入口。需要 buffer、name、type、size 这类命令式挂载参数时，优先使用 Vanilla JS / Pure Web、React、Svelte、jQuery 或 Vue2 组件；Vue3 声明式组件保持 url / file / options 的轻入口，二进制来源建议包装成带扩展名的 File 后传入。

组件	实际属性 / 入口	事件入口	控制与定制入口
Vanilla JS / Pure Web @file-viewer/web	<flyfish-file-viewer> 属性 src/url、filename/name、type、size、theme、toolbar、toolbar-position、watermark、search、options；也支持 mountViewer(...)	viewer-ready、viewer-event、viewer-state-change、viewer-error、onEvent、onStateChange、controller.subscribe()	Custom Element 实例暴露完整 controller handle；IIFE script 标签自动注册元素，同时保留命令式挂载和资源复制 CLI
Vue 3 @file-viewer/vue3	url、file、options	load-start、load-complete、unload-start、unload-complete、operation-before、operation-cancel、operation-availability-change、search-change、location-change、zoom-change	模板 ref 暴露 FileViewerExpose，可调用下载、打印、导出、缩放、搜索、定位和文本切片 API
Vue 2.7 @file-viewer/vue2.7	url、file、buffer、name、filename、type、size、options、containerClass、containerStyle	viewer-event / viewerEvent	组件实例暴露 controller handle 全量方法
Vue 2.6 @file-viewer/vue2.6	同 Vue 2.7	viewer-event / viewerEvent	独立 Vue 2.6 构建，不要求业务升级到 Vue 2.7
React @file-viewer/react	ViewerMountOptions + div 原生属性，如 className、style、data-*、aria-*	onEvent、onStateChange	ref 暴露 FileViewerHandle；useFileViewer() 返回 ref、props、state、handle
React Legacy @file-viewer/react-legacy	同 React 标准包	onEvent、onStateChange	面向 React 16.8 / 17 的独立组件包
jQuery @file-viewer/jquery	$(el).fileViewer(ViewerMountOptions & { replace?: boolean })	onEvent、onStateChange 或 getFileViewerController(el).subscribe()	插件方法支持 zoomIn、printRenderedHtml、searchDocument 等；replace:false 可原地更新
Svelte @file-viewer/svelte	ViewerMountOptions + className、containerStyle	on:viewerEvent、onEvent、onStateChange	bind:this 暴露 controller handle；use:fileViewer action 额外支持 replace

工具栏定制

内置工具栏适合大多数后台和附件中心场景；如果业务需要权限按钮、审计提示、设计系统菜单或移动端悬浮操作区，可以关闭内置工具栏，改用各生态原生 UI 调用同一套 controller API。

配置	说明
toolbar: false	隐藏内置工具栏，但不关闭下载、打印、导出、缩放等 API，适合完全自定义工具栏
toolbar: true	使用默认工具栏，按钮仍按当前格式能力动态显隐
toolbar.download / print / exportHtml / zoom	表达业务是否允许展示对应按钮；最终还会结合文件类型、渲染完成状态、导出适配器和缩放 provider 计算真实可用性
toolbar.order	调整内置工具栏分组顺序，默认 ['search', 'zoom', 'download', 'print', 'exportHtml']；例如 ['zoom', 'search', 'download', 'print'] 可让缩放排在搜索前，未列出的项按默认顺序追加
toolbar.position	auto、top、top-center、bottom-right。默认 auto，PDF 自动悬浮右下角，其他格式保持顶部靠右；需要顶部水平居中时传 top-center
toolbar.beforeOperation	工具栏层统一前置校验，会在 options.beforeOperation 后执行
toolbar.beforeDownload / beforePrint / beforeExportHtml	单按钮前置校验，适合下载权限、打印审计和导出确认

自定义工具栏不要在预览器外层套 transform: scale()。PDF、Excel、CAD、canvas 和文本层格式都要通过内部缩放 provider 保持坐标正确。外部按钮应读取 operation-availability-change / onStateChange / subscribe() 的能力状态，动态禁用不可用操作。

Vue 3 自定义工具栏

<script setup lang="ts">
import { computed, ref } from 'vue'
import type { FileViewerExpose, FileViewerOperationAvailability } from '@file-viewer/vue3'

const viewer = ref<FileViewerExpose | null>(null)
const availability = ref<FileViewerOperationAvailability | null>(null)
const canPrint = computed(() => !!availability.value?.print)

async function checkPrintPermission(filename: string) {
  return window.confirm(`确认打印 ${filename}？`)
}

const options = {
  theme: 'light',
  toolbar: false,
  async beforeOperation(context) {
    if (context.operation === 'print') {
      return await checkPrintPermission(context.filename)
    }
    return true
  }
}
</script>

<template>
  <div class="preview-shell">
    <div class="business-toolbar">
      <button @click="viewer?.downloadOriginalFile()" :disabled="!availability?.download">下载</button>
      <button @click="viewer?.printRenderedHtml()" :disabled="!canPrint">打印</button>
      <button @click="viewer?.exportRenderedHtml()" :disabled="!availability?.exportHtml">HTML</button>
      <button @click="viewer?.zoomOut()" :disabled="!availability?.zoomOut">-</button>
      <button @click="viewer?.resetZoom()" :disabled="!availability?.zoomReset">100%</button>
      <button @click="viewer?.zoomIn()" :disabled="!availability?.zoomIn">+</button>
    </div>

    <file-viewer
      ref="viewer"
      url="/files/report.pdf"
      :options="options"
      @operation-availability-change="availability = $event"
    />
  </div>
</template>

React 自定义工具栏

import FileViewer, { useFileViewer } from '@file-viewer/react'

export function Preview() {
  const viewer = useFileViewer({
    url: '/files/report.docx',
    options: { theme: 'light', toolbar: false }
  })
  const availability = viewer.state.availability

  return (
    <section className="preview-shell">
      <div className="business-toolbar">
        <button disabled={!availability?.download} onClick={() => viewer.handle.downloadOriginalFile()}>下载</button>
        <button disabled={!availability?.print} onClick={() => viewer.handle.printRenderedHtml()}>打印</button>
        <button disabled={!availability?.exportHtml} onClick={() => viewer.handle.exportRenderedHtml()}>HTML</button>
        <button disabled={!availability?.zoomOut} onClick={() => viewer.handle.zoomOut()}>-</button>
        <button disabled={!availability?.zoomReset} onClick={() => viewer.handle.resetZoom()}>100%</button>
        <button disabled={!availability?.zoomIn} onClick={() => viewer.handle.zoomIn()}>+</button>
      </div>
      <FileViewer ref={viewer.ref} {...viewer.props} />
    </section>
  )
}

Vanilla JS / Pure Web / Script 标签

<div id="toolbar">
  <button data-action="download">下载</button>
  <button data-action="print">打印</button>
  <button data-action="zoom-in">放大</button>
</div>
<flyfish-file-viewer id="viewer" style="height: 80vh"></flyfish-file-viewer>

<script type="module">
  import { defineFileViewerElement } from '@file-viewer/web'

  defineFileViewerElement()

  const viewer = document.getElementById('viewer')
  viewer.src = '/files/demo.pdf'
  viewer.options = { toolbar: false }

  const buttons = {
    download: document.querySelector('[data-action="download"]'),
    print: document.querySelector('[data-action="print"]'),
    zoomIn: document.querySelector('[data-action="zoom-in"]')
  }

  viewer.addEventListener('viewer-state-change', event => {
    const state = event.detail.state
    buttons.download.disabled = !state.availability?.download
    buttons.print.disabled = !state.availability?.print
    buttons.zoomIn.disabled = !state.availability?.zoomIn
  })

  buttons.download.onclick = () => viewer.downloadOriginalFile()
  buttons.print.onclick = () => viewer.printRenderedHtml()
  buttons.zoomIn.onclick = () => viewer.zoomIn()
</script>

无构建工具时，引入 IIFE 后直接写 <flyfish-file-viewer> 即可；window.FlyfishFileViewerWeb.mountViewer(...) 仍可用于完全命令式场景。

Vue 2、jQuery 和 Svelte

<!-- Vue 2.7 / 2.6 -->
<file-viewer
  ref="viewer"
  url="/files/report.pdf"
  :options="{ toolbar: false }"
  @viewer-event="handleViewerEvent"
/>

// jQuery
import { getFileViewerController } from '@file-viewer/jquery'

$('#viewer').fileViewer({
  url: '/files/report.xlsx',
  options: { toolbar: false }
})

$('#zoomIn').on('click', () => $('#viewer').fileViewer('zoomIn'))
getFileViewerController($('#viewer'))?.subscribe((state) => {
  $('#zoomIn').prop('disabled', !state.availability?.zoomIn)
})

<script lang="ts">
  import FileViewer from '@file-viewer/svelte'

  let viewer
  let availability
</script>

<button disabled={!availability?.print} on:click={() => viewer.printRenderedHtml()}>打印</button>
<FileViewer
  bind:this={viewer}
  url="/files/report.pdf"
  options={{ toolbar: false }}
  on:viewerEvent={(event) => {
    if (event.detail.type === 'operation-availability-change') {
      availability = event.detail.payload
    }
  }}
/>

Vue 3

pnpm add @file-viewer/vue3

import { createApp } from 'vue'
import App from './App.vue'
import FileViewer from '@file-viewer/vue3'

createApp(App).use(FileViewer).mount('#app')

<script setup lang="ts">
const options = {
  theme: 'light',
  toolbar: { position: 'bottom-right', zoom: true },
  watermark: { text: '内部预览', opacity: 0.14 }
}
</script>

<template>
  <div style="height: 100vh">
    <file-viewer url="/files/demo.docx" :options="options" />
  </div>
</template>

Vue 2.7 / Vue 2.6

Vue 2.7:

pnpm add @file-viewer/vue2.7

Vue 2.6:

pnpm add @file-viewer/vue2.6

import Vue from 'vue'
import App from './App.vue'
import FileViewer from '@file-viewer/vue2.7'

Vue.use(FileViewer)

new Vue({
  render: h => h(App)
}).$mount('#app')

历史 Vue 2 包 @flyfish-group/file-viewer 仍对应 Vue 2.7 线。新项目如果无法升级 Vue，先按运行时版本选择 @file-viewer/vue2.7 或 @file-viewer/vue2.6。

React

npm install @file-viewer/react

import { useRef } from 'react'
import FileViewer, { type FileViewerHandle } from '@file-viewer/react'

export function Preview() {
  const viewerRef = useRef<FileViewerHandle | null>(null)

  return (
    <div style={{ height: '100vh' }}>
      <FileViewer
        ref={viewerRef}
        url="/files/demo.pdf"
        options={{ theme: 'light', toolbar: { position: 'bottom-right' } }}
        onEvent={(event) => console.log(event.type, event.payload)}
      />
    </div>
  )
}

需要状态同步时可以使用 useFileViewer:

import FileViewer, { useFileViewer } from '@file-viewer/react'

export function SearchablePreview() {
  const viewer = useFileViewer({
    url: '/files/report.docx',
    options: { search: true }
  })

  return (
    <>
      <button onClick={() => viewer.handle.searchDocument('合同')}>搜索</button>
      <div style={{ height: '70vh' }}>
        <FileViewer ref={viewer.ref} {...viewer.props} />
      </div>
    </>
  )
}

React Legacy

React 16.8 / 17 的旧项目可改用 @file-viewer/react-legacy，API 保持同一套 props 与 controller 语义。

Vanilla JS / Pure Web

npm install @file-viewer/web

<flyfish-file-viewer
  id="viewer"
  src="/files/demo.xlsx"
  theme="light"
  toolbar-position="bottom-right"
  style="display:block;height:100vh"
></flyfish-file-viewer>

<script type="module">
  import { defineFileViewerElement } from '@file-viewer/web'

  defineFileViewerElement()

  window.zoomIn = () => document.getElementById('viewer').zoomIn()
</script>

无构建工具页面可以使用 IIFE:

<link rel="stylesheet" href="/file-viewer/viewer/style.css" />
<script src="/file-viewer/viewer/flyfish-file-viewer-web.iife.js"></script>
<flyfish-file-viewer
  src="/files/demo.pdf"
  theme="light"
  style="display:block;height:100vh"
></flyfish-file-viewer>

@file-viewer/web 还提供 file-viewer-copy-assets，用于把离线资源复制到业务静态目录。

jQuery

npm install jquery @file-viewer/jquery

import $ from 'jquery'
import { installJQueryFileViewer } from '@file-viewer/jquery'

installJQueryFileViewer($)

$('#viewer').fileViewer({
  url: '/files/demo.pdf',
  options: {
    theme: 'light',
    toolbar: { position: 'bottom-right' }
  }
})

$('#viewer').fileViewer('searchDocument', '发票')
$('#viewer').fileViewer('zoomIn')

如果页面已经有全局 jQuery，插件包会尽量自动挂载；显式调用 installJQueryFileViewer($) 更稳，也更适合模块化项目。

Svelte

npm install @file-viewer/svelte

<script lang="ts">
  import FileViewer from '@file-viewer/svelte'

  let viewer
  const options = {
    theme: 'light',
    toolbar: { position: 'bottom-right' },
    search: true
  }

  function searchContract() {
    viewer.searchDocument('合同')
  }
</script>

<button on:click={searchContract}>搜索合同</button>
<div style="height: 80vh">
  <FileViewer
    bind:this={viewer}
    url="/files/demo.docx"
    {options}
    on:viewerEvent={(event) => console.log(event.detail.type)}
  />
</div>

也可以在普通 DOM 节点上使用 action:

<script lang="ts">
  import { fileViewer } from '@file-viewer/svelte/action'

  const viewerOptions = {
    url: '/files/demo.pdf',
    options: { theme: 'light' }
  }
</script>

<div use:fileViewer={viewerOptions} style="height: 100vh" />

SvelteKit 中请确保预览器只在浏览器端挂载，并给容器稳定高度；服务端渲染阶段不要访问 window、document 或真实文件对象。

Core 自定义接入

业务如果要做自己的组件层，可以直接依赖 @file-viewer/core，但建议只有在标准组件包无法覆盖交互模型时才这么做。

npm install @file-viewer/core

Core 暴露格式矩阵、资源路径解析、搜索/缩放/打印导出工具、生命周期上下文和渲染器注册能力。上层组件应只负责容器、状态管理、事件桥接和生态交互，不要把 Vue / React / Svelte 运行时下沉到 core。

PPTX 引擎接入

npm install @file-viewer/pptx

@file-viewer/pptx 是从主预览器中独立出来的 PPTX 渲染引擎包，适合单独验证 PPTX 渲染、在自研预览器中复用幻灯片解析能力，或配合 @file-viewer/core 做更深的二次封装。标准 Vanilla JS / Pure Web、Vue、React、jQuery 和 Svelte 组件包默认只依赖轻量 core；需要 PowerPoint 预览时，请安装 @file-viewer/renderer-presentation 并通过 renderers 传入，或直接使用 @file-viewer/preset-all 获得与官方 Demo 一致的完整格式矩阵。

离线资源

所有生态包都可以使用同一套离线资源复制流程:

npx file-viewer-copy-assets ./public/file-viewer

发布后确认这些路径能直接访问，并且 .wasm、.mjs、Worker 脚本不会被网关回退为 HTML:

资源	默认目录
PDF.js worker / CMap / WASM / standard fonts	file-viewer/vendor/pdf/
Draw.io 官方离线 viewer	file-viewer/vendor/drawio/
CAD DWG / DWF / DWFx WASM	file-viewer/wasm/cad/
Typst compiler / renderer WASM / 默认字体	file-viewer/wasm/typst/、file-viewer/wasm/typst/fonts/
SQLite WASM	file-viewer/wasm/sqlite/
libarchive Worker / WASM	file-viewer/vendor/libarchive/
Office Worker	file-viewer/vendor/docx/、file-viewer/vendor/xlsx/

统一 API

能力	说明
输入	url、file、buffer、name、filename、type、size
事件	onEvent / viewerEvent，包含加载开始、加载完成、卸载开始、卸载完成、错误、搜索、缩放、fit、位置变化等上下文
状态	React useFileViewerState、controller subscribe()，其他生态可通过事件和 controller 获取
操作	downloadOriginalFile()、printRenderedHtml()、exportRenderedHtml()、zoomIn()、zoomOut()、resetZoom()、fitToView()
搜索定位	searchDocument()、clearDocumentSearch()、nextSearchResult()、previousSearchResult()、collectDocumentAnchors()、scrollToAnchor()、scrollToLine()
AI 友好能力	getDocumentTextChunks() 返回文本块、页码、行号、锚点和 label 上下文，业务侧可用于向量化、溯源和召回高亮
权限前置	options.beforeOperation 可在下载、打印、导出、缩放等操作前返回 true / false 或 Promise，便于做权限校验

推荐决策

• Vue 项目优先使用对应 Vue 标准包，不建议把 Vanilla JS / Pure Web 包再包一层组件。
• React 项目优先使用 @file-viewer/react；React 16.8 / 17 老项目用 @file-viewer/react-legacy。
• Svelte、jQuery 和普通 HTML 页面都有独立入口，不需要借用 Vue 组件。
• 内网部署先把 viewer assets 复制到业务静态目录，再根据网关路径覆盖 options.pdf.*、options.cad.*、options.typst.*、options.archive.* 等资源地址。
• 所有生态都要给父容器稳定高度；如果传入 Blob / ArrayBuffer，请同时提供带扩展名的 name 或包装成 File。