[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-82639":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":16,"starSnapshotCount":16,"syncStatus":17,"lastSyncTime":30,"discoverSource":31},82639,"file-viewer","flyfish-dev\u002Ffile-viewer","flyfish-dev","Ready-to-use Flyfish File Viewer artifacts for online preview of Office, PDF\u002FOFD, CAD\u002F3D, diagrams, images\u002Faudio\u002Fvideo, code\u002FMarkdown, archives, email, and ebooks.","https:\u002F\u002Fviewer.flyfish.dev",null,"HTML",155,23,1,3,0,2,28,46,15,66.74,"Apache License 2.0",false,"main",true,[],"2026-06-12 04:01:38","# Flyfish Viewer\n\n把 Word、Excel、PPT、PDF、压缩包、邮件、音频和电子书稳稳带进浏览器里。\n\n`@flyfish-group\u002Ffile-viewer3` 是一款基于 Vue 3、TypeScript 和 Vite 构建的纯前端文件预览组件。Vue2.7 项目请使用同能力包 `@flyfish-group\u002Ffile-viewer`。两条 npm 包线保持一致的格式覆盖、示例体验和 API 语义，Vue3 构建产物作为 React、纯 Web 和其他适配层的统一预览基线。\n\n它不依赖后端转码服务，适合接入 OA、知识库、附件中心、流程系统和需要离线能力的业务场景。这个项目的目标很直接: 让文档预览不再像临时拼出来的功能，而是像一个可以放心交付、能独立演示、能持续维护的产品模块。\n\n- npm(Vue3): [@flyfish-group\u002Ffile-viewer3](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@flyfish-group\u002Ffile-viewer3)\n- npm(Vue2): [@flyfish-group\u002Ffile-viewer](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@flyfish-group\u002Ffile-viewer)\n- npm(React): [@flyfish-group\u002Ffile-viewer-react](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@flyfish-group\u002Ffile-viewer-react)\n- npm(纯 JS): [@flyfish-group\u002Ffile-viewer-web](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@flyfish-group\u002Ffile-viewer-web)\n- 官方文档: [doc.flyfish.dev](https:\u002F\u002Fdoc.flyfish.dev)\n- 在线 Demo: [viewer.flyfish.dev](https:\u002F\u002Fviewer.flyfish.dev)\n- 公开成品仓库: [github.com\u002Fflyfish-dev\u002Ffile-viewer](https:\u002F\u002Fgithub.com\u002Fflyfish-dev\u002Ffile-viewer)\n- 源码自助开通: [https:\u002F\u002Fdev.flyfish.group\u002Fshop](https:\u002F\u002Fdev.flyfish.group\u002Fshop)\n\n## 当前发布版本\n\n| 技术栈 | npm 包 | 最新版本 | 推荐分支 | 说明 |\n| --- | --- | --- | --- | --- |\n| Vue3 | `@flyfish-group\u002Ffile-viewer3` | `1.0.16` | `v3` | 主推版本，也是 React \u002F 纯 Web 私有化 iframe 适配层的构建基线 |\n| Vue2.7 | `@flyfish-group\u002Ffile-viewer` | `1.0.16` | `main` | 兼容 Vue2 项目，格式能力与 Vue3 保持一致 |\n| React 17 \u002F 18 \u002F 19 | `@flyfish-group\u002Ffile-viewer-react` | `1.0.16` | 当前仓库子工程 | iframe 组件，默认加载 `\u002Ffile-viewer\u002Findex.html` |\n| 纯 JS | `@flyfish-group\u002Ffile-viewer-web` | `1.0.16` | 当前仓库子工程 | iframe helper 和 viewer 产物复制工具 |\n\n如果你在内网、离线环境，或者 npm 发布权限还没有完成配置，也可以直接使用公开成品仓库 `artifacts\u002F` 里的 tarball。离线安装 React 包时请先安装同版本 web 包:\n\n```bash\nnpm install .\u002Fartifacts\u002Fflyfish-group-file-viewer-web-1.0.16.tgz\nnpm install .\u002Fartifacts\u002Fflyfish-group-file-viewer-react-1.0.16.tgz\n```\n\nReact \u002F 纯 JS 包推荐用 `npm install` 获得安装即复制的体验。pnpm 10 默认会拦截依赖包的 `postinstall`，如果看到 `Ignored build scripts: @flyfish-group\u002Ffile-viewer-web`，请执行 `pnpm approve-builds` 允许该包，或安装后运行 `pnpm exec file-viewer-copy-assets .\u002Fpublic\u002Ffile-viewer`。\n\n![Flyfish Viewer demo](docs\u002F_images\u002Fdemo-main.png)\n\n## 为什么值得接入\n\n- **纯前端 Serverless。** 文档解析和展示全部在浏览器内完成，部署简单，不依赖 Office 服务端、LibreOffice 守护进程或额外转码链路。\n- **格式覆盖完整。** 当前内置 135 个扩展名映射，覆盖 Word、Excel、PowerPoint、PDF、OFD、压缩包、邮件、OLB\u002FDRA、CAD、3D 模型、Excalidraw、draw.io、EPUB、UMD、Markdown、图片、音频、代码\u002F文本和 MP4，能覆盖绝大多数业务附件场景。\n- **按需异步加载。** PDF、OFD、压缩包、邮件、OLB\u002FDRA、CAD、3D 模型、绘图、Office、EPUB、UMD、Markdown 和代码高亮渲染器都按需加载，重型解析依赖不会进入其他格式的首屏路径。\n- **预览器操作完整。** 内置下载原文件、打印完整渲染结果、导出渲染后 HTML、水印开关和水印 options；PDF 会逐页输出完整页面，不依赖当前视口，适合合同、归档和审批类场景。\n- **集成控制更完整。** 提供加载\u002F卸载生命周期钩子、iframe 事件回传和按钮前置校验机制，下载、打印、导出前可以接入权限验证、审计确认或业务二次弹窗。\n- **阅读体验更像产品。** `.doc`、`.docx`、PDF 都保留灰色工作台、白色纸张、居中阅读和自适应缩放，避免“内容能打开但不好读”的落差。\n- **Demo 更适合验收。** 示例文件按文档、表格、图纸、代码、图片等类型分组展示，点击样例即可打开并自动收起选择器。\n- **Vue2 \u002F Vue3 体验一致。** `main` 分支面向 Vue2.7，`v3` 分支面向 Vue3；两边共享完整格式覆盖、示例文件盒子、文档站和 iframe 集成体验。\n- **组件和独立站两用。** 既支持在 Vue 项目里直接作为组件使用，也支持独立部署后通过 iframe 嵌入到任意系统，方便多业务线复用。\n- **适合成品交付。** 公开成品仓库、混淆压缩产物、npm tarball、静态部署产物和私有化 iframe 适配包都一起维护，便于下载、验收和二次接入。\n\n## 支持格式\n\n当前版本内置 135 个扩展名映射，覆盖 19 条预览链路。\n\n| 类别 | 扩展名 | 当前表现 | 适合场景 |\n| --- | --- | --- | --- |\n| Word | `docx` | `docx-preview`，更适合保留文档结构和版式 | 新生成的 Word 文档、正式文档 |\n| Word | `doc` | `msdoc-viewer` + Word 风格页面容器 | 历史 `.doc` 老文档 |\n| Excel | `xlsx` | `styled-exceljs` + 虚拟滚动，支持尺寸、合并和常见样式 | 需要保留表格结构和样式的业务 |\n| Excel 兼容格式 | `xlsm`、`xlsb`、`xls`、`csv`、`ods`、`fods`、`numbers` | 统一解析，按格式可用信息渐进还原样式 | 老表格、轻量数据查看 |\n| PowerPoint | `pptx` | 浏览幻灯片内容，增强组合图形、主题背景、图片裁剪与 EMF 矢量图预览 | 汇报材料、课件、方案 |\n| PDF | `pdf` | 基于 `pdfjs-dist` 预览，支持缩放工具栏、页侧边栏\u002F目录树侧边栏切换、宽度自适应、完整打印和导出 HTML | 合同、票据、版式成品 |\n| OFD | `ofd` | 基于 `DLTech21\u002Fofd.js` 仓库源码在线预览国产版式文档，避开 npm dist 授权 wasm 分支 | 电子发票、公文、归档材料 |\n| 压缩包 | `zip`、`zipx`、`7z`、`rar`、`tar`、`gz`、`gzip`、`tgz`、`bz2`、`bzip2`、`tbz`、`tbz2`、`xz`、`txz`、`lzma`、`zst`、`tzst`、`cab`、`ar`、`cpio`、`iso`、`xar`、`lha`、`lzh`、`jar`、`war`、`ear`、`apk`、`cbz`、`cbr` | 基于 `libarchive.js` 的 WASM Worker 读取目录，点击后按需解压内部文件并复用统一预览器，支持 IndexedDB 缓存和体积上限 | 归档附件、批量交付包、压缩包内文档快速查看 |\n| 邮件 | `eml`、`msg` | EML 使用 `postal-mime`，MSG 使用 `@kenjiuno\u002Fmsgreader`，支持头信息、HTML\u002F文本正文、附件下载与附件预览 | 邮件归档、工单邮件、客户来信附件 |\n| EDA | `olb`、`dra` | 使用 `cfb` 解析 OrCAD\u002FAllegro 常见 CFB 容器，展示结构树、元件\u002F封装\u002FPadstack 候选、属性、诊断和可读字符串；退化时提供安全二进制索引 | 元件库、封装图纸、EDA 附件初筛 |\n| CAD | `dxf` | 基于 `@cadview\u002Fcore` 预览图纸，支持缩放、平移、图层控制 | 工程图纸、二维 CAD 附件 |\n| CAD 兼容入口 | `dwg` | 优先识别误命名 DXF；真实 DWG 会尽量提取内嵌预览图，并说明未完整解析几何的原因 | 需要兼容上传入口的业务 |\n| 3D 模型 | `glb`、`gltf`、`obj`、`stl`、`ply`、`fbx`、`dae`、`3ds`、`3mf`、`amf`、`usd`、`usda`、`usdc`、`usdz`、`kmz`、`pcd`、`wrl`、`vrml`、`xyz`、`vtk`、`vtp`、`step`、`stp`、`iges`、`igs`、`ifc`、`3dm` | 基于 Three.js 交互预览；工程 CAD\u002FBIM 格式会给出不内置几何内核的原因和转换建议 | 设计模型、点云、三维资产、工程模型 |\n| Excalidraw | `excalidraw` | 基于官方 `@excalidraw\u002Fexcalidraw` 的 `restore` + `exportToSvg` 输出只读预览 | 白板草图、流程草稿、产品沟通图 |\n| draw.io | `drawio`、`dio` | 基于官方 diagrams.net `GraphViewer` 预览 mxGraphModel \u002F mxfile | 流程图、架构图、业务泳道图 |\n| 电子书 | `epub` | 基于 `epubjs` 解析目录和章节资源，使用兼容性更好的滚动阅读 | 电子书、培训手册、长篇阅读材料 |\n| 电子书 | `umd` | 按 UMD 移动电子书结构解析元数据、目录和 zlib 压缩正文 | 旧移动电子书、历史小说附件 |\n| Markdown | `md`、`markdown` | Markdown 阅读样式 | README、知识文档、说明文档 |\n| 图片 | `gif`、`jpg`、`jpeg`、`bmp`、`tiff`、`tif`、`png`、`svg`、`webp` | 原生图片浏览 | 图片附件、设计稿、Logo |\n| 代码\u002F文本 | `txt`、`json`、`js`、`mjs`、`cjs`、`css`、`java`、`py`、`html`、`htm`、`jsx`、`ts`、`tsx`、`xml`、`log`、`vue`、`yaml`、`yml`、`ini`、`sh`、`bash`、`sql`、`go`、`rs`、`php`、`c`、`cpp`、`cc`、`h`、`hpp`、`cs`、`diff` | 使用 `highlight.js` 轻量高亮，HTML 按源码展示 | 日志、配置、代码片段、接口响应 |\n| 音频 | `mp3`、`mpeg`、`wav`、`ogg`、`oga`、`opus`、`m4a`、`aac`、`flac`、`weba` | 浏览器原生音频播放，带控制条和基础进度信息 | 录音、播客、语音附件、音效素材 |\n| 视频 | `mp4` | 浏览器原生视频播放 | 演示视频、录屏 |\n\n## 接入路线\n\n### 1. Vue 3 组件集成\n\n适合已经在 Vue 3 项目里开发，希望最短路径完成接入的团队。React、纯 Web 和后续其他框架适配层都以这套 Vue3 构建产物作为 iframe 预览基线。\n\n```bash\npnpm add @flyfish-group\u002Ffile-viewer3\n```\n\n```ts\nimport { createApp } from 'vue'\nimport App from '.\u002FApp.vue'\nimport FileViewer from '@flyfish-group\u002Ffile-viewer3'\n\ncreateApp(App).use(FileViewer).mount('#app')\n```\n\nVue3 入口会把样式一起带到安装器里，所以这里不需要再额外引入 `dist\u002Ffile-viewer3.css`。\n\n```vue\n\u003Cscript setup lang=\"ts\">\nimport { ref } from 'vue'\n\nconst url = ref('https:\u002F\u002Fexample.com\u002Fdemo.pdf')\n\u003C\u002Fscript>\n\n\u003Ctemplate>\n  \u003Cdiv style=\"height: 100vh\">\n    \u003Cfile-viewer :url=\"url\" \u002F>\n  \u003C\u002Fdiv>\n\u003C\u002Ftemplate>\n```\n\n### 2. Vue 2 组件集成\n\n适合仍在 Vue2.7 技术栈上，希望直接以内嵌组件方式完成接入的团队。Vue2 入口也会自动带上样式，不需要再额外 import CSS。\n\n```bash\npnpm add @flyfish-group\u002Ffile-viewer\n```\n\n```ts\nimport Vue from 'vue'\nimport App from '.\u002FApp.vue'\nimport FileViewer from '@flyfish-group\u002Ffile-viewer'\n\nVue.use(FileViewer)\n\nnew Vue({\n  render: h => h(App)\n}).$mount('#app')\n```\n\n```vue\n\u003Ctemplate>\n  \u003Cdiv style=\"height: 100vh\">\n    \u003Cfile-viewer :url=\"url\" \u002F>\n  \u003C\u002Fdiv>\n\u003C\u002Ftemplate>\n\n\u003Cscript>\nexport default {\n  data() {\n    return {\n      url: 'https:\u002F\u002Fexample.com\u002Fdemo.pdf'\n    }\n  }\n}\n\u003C\u002Fscript>\n```\n\n### 3. Iframe 嵌入\n\n适合多系统共用一套预览器、想把预览能力独立部署、或者不希望把解析依赖带进业务包的场景。\n\n```html\n\u003Ciframe\n  id=\"viewer\"\n  src=\"\u002Ffile-viewer\u002Findex.html?url=https%3A%2F%2Fexample.com%2Fdemo.docx\"\n  style=\"width: 100%; height: 100%; border: 0\"\n>\u003C\u002Fiframe>\n```\n\n更完整的二进制推送方案、`from` 安全校验和宿主页面示例，请查看仓库内的 [Iframe 嵌入说明](docs\u002Fguide\u002Fiframe.md)。\n\n### 4. React \u002F 纯 Web 子工程\n\nReact 与纯 Web 适配层不再复制渲染器，只通过 iframe 加载 Vue3 基线预览器产物。包里会携带主工程构建产物，安装后复制到宿主项目 `public\u002Ffile-viewer`，组件默认加载 `\u002Ffile-viewer\u002Findex.html`，只提供私有化静态部署路线:\n\n官网 Demo 可用于快速验证预览效果，但 React \u002F 纯 JS 组件不会把官网 Demo 地址作为内置 viewer 地址。\n\n```bash\nnpm install @flyfish-group\u002Ffile-viewer-react@1.0.16\nnpm install @flyfish-group\u002Ffile-viewer-web@1.0.16\n```\n\n```tsx\nimport FileViewer from '@flyfish-group\u002Ffile-viewer-react'\n\nexport function Preview() {\n  return (\n    \u003Cdiv style={{ height: '100vh' }}>\n      \u003CFileViewer\n        url=\"https:\u002F\u002Fexample.com\u002Fdemo.docx\"\n      \u002F>\n    \u003C\u002Fdiv>\n  )\n}\n```\n\n`@flyfish-group\u002Ffile-viewer-react` 支持 React 17 \u002F 18 \u002F 19，内部复用 `@flyfish-group\u002Ffile-viewer-web` 的 iframe 协议工具。鉴权文件仍建议由宿主系统先下载成 `Blob`，再用 `file` + `name` 推送给预览器。静态目录不是 `public\u002Ffile-viewer` 时，可以运行 `npx file-viewer-copy-assets .\u002Fpublic\u002Fvendor\u002Ffile-viewer` 并覆盖 `viewerUrl=\"\u002Fvendor\u002Ffile-viewer\u002Findex.html\"`。\n\n本仓库内置了一个私有化适配层演示应用，覆盖 React 组件和纯 Web helper 两种入口。调试时直接运行:\n\n```bash\npnpm dev:adapters\n```\n\n它会先构建并同步 Vue3 基线预览器到演示应用的 `public\u002Ffile-viewer`，打开本地地址即可看到预览效果。验证静态部署产物时运行:\n\n```bash\npnpm build:adapter-demo\npnpm --filter @flyfish-group\u002Ffile-viewer-demo preview\n```\n\n确认无误后，`packages\u002Fdemo\u002Fdist` 可以作为普通静态目录部署；其中已经包含 `file-viewer\u002Findex.html` 和演示文件。\n\n## 使用说明\n\n- 组件支持两条主要输入路径: `url?: string` 与 `file?: File`\n- 当 `file` 和 `url` 同时存在时，会优先渲染 `file`\n- 如果业务侧拿到的是 `Blob` 或 `ArrayBuffer`，推荐先包装成带扩展名的 `File`\n- 预览器会填满父容器，请为父容器提供稳定高度\n- 使用 `url` 预览时，目标资源需要允许浏览器访问；跨域场景下需要正确配置 CORS\n- 如果下载地址本身没有明确扩展名，建议先在业务侧取回文件，再包装成 `File`\n- PPTX 渲染器会尽量还原常见组合图形、旋转\u002F翻转、主题背景、图片裁剪和 EMF 矢量图片；复杂 Office 特效仍建议用真实业务文件做回归\n- OFD、压缩包、邮件、OLB\u002FDRA、CAD、3D 模型、绘图、EPUB、UMD、PDF、Office、Markdown、音频和代码高亮渲染器都按需异步加载，只有命中格式时才拉取对应代码块\n- `options.watermark` 支持文字或图片水印；`options.toolbar` 可控制下载原文件、打印完整渲染结果和导出 HTML；`options.hooks` 可接收加载\u002F卸载生命周期；`options.beforeOperation` 可在下载、打印、导出前做权限校验；PDF 和 Word 打印会尽量生成完整页面，避免只打印当前视口\n\n```ts\nconst blob = await response.blob()\nconst file = new File([blob], 'contract.pdf', { type: blob.type })\n```\n\n## 本地开发\n\n下面的命令适用于源码开通后的完整项目。公开 GitHub 成品仓库不包含源码目录，普通用户建议直接通过 npm、`dist\u002F` 或 `artifacts\u002F` 里的 tarball 使用。\n\n```bash\npnpm install\npnpm dev\n```\n\n常用脚本:\n\n- `pnpm build`: 构建示例站点\n- `pnpm build-lib`: 构建组件库产物\n- `pnpm docs:dev`: 启动 VitePress 文档站\n- `pnpm docs:build`: 构建文档站\n- `pnpm type-check`: 执行 TypeScript 类型检查\n- `pnpm dev:adapters`: 启动 React + 纯 JS 适配层 Demo\n- `pnpm build:adapter-demo`: 构建适配层 Demo\n- `pnpm release:adapters:pack`: 打包 React \u002F 纯 JS npm tarball\n\n## 打包发布\n\nVue3 和 Vue2 发包时分别在对应分支执行同一套发布链路:\n\n| 包 | 分支 | npm 名称 |\n| --- | --- | --- |\n| Vue3 | `v3` | `@flyfish-group\u002Ffile-viewer3` |\n| Vue2.7 | `main` | `@flyfish-group\u002Ffile-viewer` |\n| React | 当前仓库子工程 | `@flyfish-group\u002Ffile-viewer-react` |\n| 纯 JS | 当前仓库子工程 | `@flyfish-group\u002Ffile-viewer-web` |\n\n建议在发布前执行下面这组命令:\n\n```bash\npnpm type-check\npnpm build\npnpm build-lib\npnpm obfuscate\npnpm docs:build\nnpm pack\n```\n\n其中:\n\n- `dist\u002F` 是库构建产物；执行 `pnpm obfuscate` 后会对其中的 `.js` \u002F `.mjs` 进行压缩混淆\n- `pnpm build` 会生成可独立部署的 Demo 静态站点产物\n- `docs\u002F.vitepress\u002Fdist\u002F` 是文档站静态产物\n- `npm pack` 会生成可直接发布或分发的 npm 包 tarball\n\n如果只是准备 npm 包，可以直接执行:\n\n```bash\npnpm release:pack\n```\n\nReact 和纯 JS 适配包发布前执行:\n\n```bash\npnpm type-check:adapters\npnpm build:adapter-demo\npnpm release:adapters:pack\npnpm release:adapters:publish\n```\n\n发布到 npm:\n\n```bash\nnpm publish --dry-run --access public\nnpm publish --access public\n```\n\n如果 npm 账号启用了 MFA，请使用交互式终端完成浏览器确认后再等待发布结果。\n\n公开 GitHub 仓库只提交可直接使用的构建产物、示例、文档和 npm tarball，不提交当前源码目录。需要源码、二开包或商业自助开通的用户，可以前往 [https:\u002F\u002Fdev.flyfish.group\u002Fshop](https:\u002F\u002Fdev.flyfish.group\u002Fshop)，付费 4.99 后自助开通。\n\n## 文档导航\n\n- [文档导览](docs\u002Fguide\u002Findex.md)\n- [快速开始](docs\u002Fguide\u002Fquickstart.md)\n- [Demo 说明](docs\u002Fguide\u002Fdemo.md)\n- [组件用法](docs\u002Fguide\u002Fusage.md)\n- [支持格式](docs\u002Fguide\u002Fformats.md)\n- [本地开发与打包](docs\u002Fguide\u002Fdevelopment.md)\n\n## 开源说明\n\n本项目使用 `Apache-2.0` 许可证。\n\n二开或商用时，请按许可证要求保留版权、许可证和来源说明，并注明项目来源为 Flyfish Viewer \u002F `@flyfish-group\u002Ffile-viewer3` 或 `@flyfish-group\u002Ffile-viewer`。如果你基于本项目修复了通用问题或增强了通用能力，也欢迎通过 issue \u002F PR 一起贡献回来，让这套预览能力继续变得更稳。\n","Flyfish Viewer 是一个用于在线预览多种文件格式（如Office、PDF\u002FOFD、CAD\u002F3D、图表、图像\u002F音频\u002F视频、代码\u002FMarkdown、压缩包、邮件和电子书）的前端组件。它基于Vue 3、TypeScript 和 Vite构建，支持Vue 2.7及React等多技术栈，并提供纯Web版本。其核心功能包括无需后端转码服务即可实现文档解析与展示、全面覆盖135种文件扩展名、按需异步加载以优化性能、以及丰富的预览器操作选项如下载、打印、导出等。适用于OA系统、知识库、附件中心、流程管理系统及需要离线能力的应用场景中，旨在提供稳定可靠的文件预览解决方案。","2026-06-11 04:08:48","CREATED_QUERY"]