@flyfish-group/file-viewer3 1.0.20 → 1.0.22

package/README.en.md

@@ -0,0 +1,373 @@
+# Flyfish Viewer
+
+[Simplified Chinese](README.md) | [English](README.en.md)
+
+Bring Word, Excel, PowerPoint, PDF, Typst, archives, email, audio, ebooks, drawings, CAD, 3D models, Markdown, images, and source code preview into the browser with a clean, deployable viewer.
+
+`@flyfish-group/file-viewer3` is a pure frontend file preview component built with Vue 3, TypeScript, and Vite. Vue 2.7 projects should use the matching `@flyfish-group/file-viewer` package. The Vue 3 build is also the baseline runtime for the React, vanilla JavaScript, and iframe integration packages.
+
+The viewer does not require a backend conversion service. It is designed for OA systems, knowledge bases, attachment centers, workflow platforms, customer support portals, document approval flows, intranet systems, and offline-capable deployments where file preview should feel like a maintained product module rather than a temporary feature.
+
+- npm for Vue 3: [@flyfish-group/file-viewer3](https://www.npmjs.com/package/@flyfish-group/file-viewer3)
+- npm for Vue 2.7: [@flyfish-group/file-viewer](https://www.npmjs.com/package/@flyfish-group/file-viewer)
+- npm for React: [@flyfish-group/file-viewer-react](https://www.npmjs.com/package/@flyfish-group/file-viewer-react)
+- npm for vanilla JavaScript: [@flyfish-group/file-viewer-web](https://www.npmjs.com/package/@flyfish-group/file-viewer-web)
+- Official documentation: [doc.flyfish.dev](https://doc.flyfish.dev)
+- Online demo: [viewer.flyfish.dev](https://viewer.flyfish.dev)
+- Document comparison demo: [viewer.flyfish.dev/compare.html](https://viewer.flyfish.dev/compare.html)
+- GitHub artifact repository: [github.com/flyfish-dev/file-viewer](https://github.com/flyfish-dev/file-viewer)
+- Gitee artifact mirror: [gitee.com/flyfish-dev/file-viewer](https://gitee.com/flyfish-dev/file-viewer)
+- Source access and commercial customization: [https://dev.flyfish.group/shop](https://dev.flyfish.group/shop)
+
+## Current Packages
+
+| Stack | Package | Version | Recommended branch | Notes |
+| --- | --- | --- | --- | --- |
+| Vue 3 | `@flyfish-group/file-viewer3` | `1.0.22` | `v3` | Recommended version and the runtime baseline for React / vanilla JS iframe integrations |
+| Vue 2.7 | `@flyfish-group/file-viewer` | `1.0.22` | `main` | Vue 2 compatible package with the same format coverage and API semantics |
+| React 17 / 18 / 19 | `@flyfish-group/file-viewer-react` | `1.0.22` | adapter package | iframe component that loads `/file-viewer/index.html` by default |
+| Vanilla JavaScript | `@flyfish-group/file-viewer-web` | `1.0.22` | adapter package | iframe helpers and static viewer asset copier |
+
+For intranet or offline environments, this artifact repository also ships npm tarballs under `artifacts/`:
+
+```bash
+npm install ./artifacts/flyfish-group-file-viewer3-1.0.22.tgz
+npm install ./artifacts/flyfish-group-file-viewer-1.0.22.tgz
+npm install ./artifacts/flyfish-group-file-viewer-web-1.0.22.tgz
+npm install ./artifacts/flyfish-group-file-viewer-react-1.0.22.tgz
+```
+
+When installing the React tarball offline, install the same-version web tarball first because the React package depends on `@flyfish-group/file-viewer-web`.
+
+If you use pnpm 10 and see `Ignored build scripts: @flyfish-group/file-viewer-web`, run:
+
+```bash
+pnpm approve-builds
+```
+
+Then allow `@flyfish-group/file-viewer-web`, or manually copy the bundled viewer assets:
+
+```bash
+pnpm exec file-viewer-copy-assets ./public/file-viewer
+```
+
+![Flyfish Viewer demo](docs/_images/demo-main.png)
+
+## Why Use It
+
+- **Pure frontend and serverless.** File parsing and rendering happen in the browser. You do not need Office Server, a LibreOffice daemon, or a document conversion backend.
+- **Broad format coverage.** The current release maps 149 extensions across 20 preview pipelines, including Office, PDF, OFD, Typst, archives, email, EDA files, CAD, 3D models, Excalidraw, draw.io, EPUB, UMD, Markdown, images, audio, video, and source code.
+- **Lazy loaded renderers.** Heavy PDF, Office, OFD, Typst, archive, email, CAD, 3D, ebook, Markdown, and code highlighting dependencies are loaded only when the file type needs them.
+- **Production-ready operations.** The viewer includes original file download, full rendered printing, rendered HTML export, watermark options, theme options, lifecycle hooks, iframe events, and before-operation guards for permission checks.
+- **Better document reading.** Word and PDF keep a grey workspace, white paper surface, centered reading, width fitting, navigation, zoom, rotation, and complete print / HTML export paths.
+- **Controlled theming.** `options.theme` supports `light`, `dark`, and `system`. Light business UIs can lock the viewer to `light` even when the operating system is in dark mode.
+- **PDF toolbar ergonomics.** `toolbar.position` supports `auto`, `top`, and `bottom-right`. In `auto` mode, PDF uses a bottom-right floating operation bar to avoid duplicating the PDF navigation toolbar.
+- **Demo and comparison views.** The repository includes the main demo and a standalone `/compare.html` page for side-by-side document comparison.
+- **Component and standalone modes.** Use it as a Vue component, or deploy the static viewer and embed it through iframe in any system.
+- **Artifact-first delivery.** This public repository contains minified build artifacts, static demos, documentation output, sample files, Docker deployment assets, and npm tarballs. It does not contain the private source tree.
+
+## Supported Formats
+
+The viewer is organized around preview pipelines rather than one-off file extensions.
+
+| Category | Extensions | Rendering pipeline | Typical use |
+| --- | --- | --- | --- |
+| Word | `docx`, `docm`, `dotx`, `dotm` | `docx-preview`, read-only page preview, print and HTML export | Modern Word documents and templates |
+| Legacy Word | `doc`, `dot` | `msdoc-viewer` with Word-like paper surface and CFB tolerance fixes | Old Word 97-2003 files |
+| Excel | `xlsx`, `xltx` | `styled-exceljs` plus virtual table rendering, merged cells, styles, auto text color, workbook images | Business spreadsheets and templates |
+| Excel-compatible | `xlsm`, `xlsb`, `xls`, `xlt`, `xltm`, `csv`, `ods`, `fods`, `numbers` | Progressive spreadsheet parsing and virtual rendering | Legacy spreadsheets and lightweight data preview |
+| PowerPoint | `pptx`, `pptm`, `potx`, `potm`, `ppsx`, `ppsm` | Slide preview with images, shapes, theme backgrounds, clipping, and EMF fallback | Presentations, training decks, proposals |
+| PDF | `pdf` | `pdfjs-dist`, streaming same-origin loading, Range support, zoom, rotation, page thumbnails, outline tree, width fitting, print, HTML export | Contracts, invoices, official layout documents |
+| OFD | `ofd` | Browser-side OFD preview based on `DLTech21/ofd.js` source | Chinese e-invoices, government documents, archives |
+| Typst | `typ`, `typst` | Direct Typst source rendering with browser WASM compiler and SVG pages | Technical reports, papers, engineering documents |
+| Archives | `zip`, `zipx`, `7z`, `rar`, `tar`, `gz`, `tgz`, `bz2`, `xz`, `zst`, `cab`, `iso`, `jar`, `apk`, `cbz`, `cbr`, and more | `libarchive.js` Worker, directory listing, lazy extraction, IndexedDB cache | Attachment packages and internal document bundles |
+| Email | `eml`, `msg` | `postal-mime` for EML, `@kenjiuno/msgreader` for MSG, headers, HTML/text body, attachment preview | Email archives and support tickets |
+| EDA | `olb`, `dra` | CFB-based OrCAD / Allegro structure inspection, trees, symbols, footprints, padstack candidates, properties, strings, diagnostics | Component libraries and EDA attachments |
+| CAD | `dxf` | `@cadview/core` 2D CAD preview with pan, zoom, and layer controls | Engineering drawings |
+| DWG compatibility | `dwg` | Detects renamed DXF when possible; extracts embedded preview for true DWG and explains conversion boundaries | Upload compatibility for CAD workflows |
+| 3D models | `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 interactive preview, with conversion guidance for heavy CAD/BIM kernels | 3D assets, point clouds, design models |
+| Excalidraw | `excalidraw` | Official `@excalidraw/excalidraw` restore and `exportToSvg` read-only rendering | Whiteboard sketches and product diagrams |
+| draw.io | `drawio`, `dio` | Official diagrams.net `GraphViewer` | Flowcharts and architecture diagrams |
+| EPUB | `epub` | `epubjs` table of contents and scrolling reader | Ebooks and long training materials |
+| UMD ebook | `umd` | UMD metadata, chapters, offsets, zlib text blocks | Legacy mobile ebooks |
+| Markdown | `md`, `markdown` | Markdown reading surface with theme-aware styles | README files and knowledge base articles |
+| Images | `gif`, `jpg`, `jpeg`, `bmp`, `tiff`, `tif`, `png`, `svg`, `webp` | Native image preview | Image attachments and design assets |
+| Source and text | `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` | Lightweight `highlight.js` language-specific highlighting, HTML shown as source | Logs, configs, code snippets, API responses |
+| Audio | `mp3`, `mpeg`, `wav`, `ogg`, `oga`, `opus`, `m4a`, `aac`, `flac`, `weba` | Native browser audio player | Recordings and audio attachments |
+| Video | `mp4` | Native browser video player | Screen recordings and demo videos |
+
+## Vue 3 Integration
+
+```bash
+npm install @flyfish-group/file-viewer3
+```
+
+```ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import FileViewer from '@flyfish-group/file-viewer3'
+
+createApp(App).use(FileViewer).mount('#app')
+```
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const url = ref('/files/demo.pdf')
+
+const options = {
+  theme: 'light',
+  toolbar: { position: 'bottom-right', download: true, print: true, exportHtml: true },
+  watermark: { text: 'Internal Preview', opacity: 0.14 },
+  pdf: { streaming: 'same-origin', rangeChunkSize: 64 * 1024 }
+}
+</script>
+
+<template>
+  <div style="height: 100vh">
+    <file-viewer :url="url" :options="options" />
+  </div>
+</template>
+```
+
+For local files or authenticated downloads, pass a `File` object:
+
+```ts
+const response = await fetch('/api/files/contract', { credentials: 'include' })
+const blob = await response.blob()
+
+file.value = new File([blob], 'contract.pdf', { type: blob.type })
+```
+
+The filename matters. The viewer uses the extension to choose the correct rendering pipeline.
+
+## Vue 2.7 Integration
+
+```bash
+npm install @flyfish-group/file-viewer
+```
+
+```ts
+import Vue from 'vue'
+import FileViewer from '@flyfish-group/file-viewer'
+
+Vue.use(FileViewer)
+```
+
+```vue
+<template>
+  <div style="height: 100vh">
+    <file-viewer :url="url" :options="options" />
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      url: '/files/demo.pdf',
+      options: {
+        theme: 'light',
+        toolbar: { position: 'bottom-right' }
+      }
+    }
+  }
+}
+</script>
+```
+
+The Vue 2 and Vue 3 package lines share the same user-facing capabilities and option semantics.
+
+## React Integration
+
+The React package is an iframe adapter. It reuses the Vue 3 baseline viewer that is bundled by `@flyfish-group/file-viewer-web`.
+
+```bash
+npm install @flyfish-group/file-viewer-react
+```
+
+```tsx
+import FileViewer from '@flyfish-group/file-viewer-react'
+
+export function Preview() {
+  return (
+    <div style={{ height: '100vh' }}>
+      <FileViewer
+        url="/files/demo.pdf"
+        options={{
+          theme: 'light',
+          toolbar: { position: 'bottom-right' },
+          watermark: { text: 'Internal Preview', opacity: 0.14 }
+        }}
+        onViewerEvent={(event) => {
+          console.log(event.type, event.event, event.payload)
+        }}
+      />
+    </div>
+  )
+}
+```
+
+By default, the iframe loads `/file-viewer/index.html`. If your static assets are deployed elsewhere, pass `viewerUrl`.
+
+## Vanilla JavaScript Integration
+
+```bash
+npm install @flyfish-group/file-viewer-web
+```
+
+```html
+<div id="viewer" style="height: 100vh"></div>
+
+<script type="module">
+  import { mountViewerFrame } from '@flyfish-group/file-viewer-web'
+
+  mountViewerFrame(document.getElementById('viewer'), {
+    url: '/files/demo.pdf',
+    options: {
+      theme: 'light',
+      toolbar: { position: 'bottom-right' },
+      archive: { workerUrl: '/file-viewer/vendor/libarchive/worker-bundle.js', cache: true }
+    },
+    onEvent(event) {
+      console.log(event.type, event.event, event.payload)
+    }
+  })
+</script>
+```
+
+The web package copies the static viewer into `public/file-viewer` during installation. If your package manager blocks install scripts, run:
+
+```bash
+npx file-viewer-copy-assets ./public/file-viewer
+```
+
+## iframe Protocol
+
+If you cannot use npm helpers, deploy the static viewer and pass a file URL through query parameters:
+
+```html
+<iframe
+  src="/file-viewer/index.html?url=%2Ffiles%2Fdemo.pdf&options=%7B%22theme%22%3A%22light%22%2C%22toolbar%22%3A%7B%22position%22%3A%22bottom-right%22%7D%7D"
+  style="width: 100%; height: 100vh; border: 0"
+></iframe>
+```
+
+For authenticated files, download the file in the host system and push a `Blob` to the iframe:
+
+```ts
+const viewerUrl = '/file-viewer/index.html'
+const viewerOrigin = location.origin
+const filename = 'contract.pdf'
+const options = { theme: 'light', toolbar: { position: 'bottom-right' } }
+const frame = document.getElementById('viewer') as HTMLIFrameElement
+
+frame.src =
+  `${viewerUrl}?name=${encodeURIComponent(filename)}` +
+  `&from=${encodeURIComponent(location.origin)}` +
+  `&options=${encodeURIComponent(JSON.stringify(options))}`
+
+frame.onload = async () => {
+  const response = await fetch('/api/files/contract', { credentials: 'include' })
+  const blob = await response.blob()
+  frame.contentWindow?.postMessage(blob, viewerOrigin)
+}
+```
+
+The viewer validates `event.origin === from` and only accepts `Blob` messages from the declared origin.
+
+## Core Options
+
+| Option | Description |
+| --- | --- |
+| `theme` | `light`, `dark`, or `system`. Default is `system`. Use `light` when embedding in a fixed light UI. |
+| `toolbar` | `true`, `false`, or an object that controls download, print, HTML export, and toolbar position. |
+| `toolbar.position` | `auto`, `top`, or `bottom-right`. Default `auto` floats the operation bar at bottom right for PDF and keeps other formats at top. |
+| `watermark` | Text or image watermark configuration. Watermark participates in preview, print, and exported HTML. |
+| `archive.workerUrl` | Custom `libarchive.js` Worker URL for private deployment. |
+| `archive.cache` | Enables IndexedDB cache for extracted archive entries. |
+| `archive.maxArchiveSize` | Maximum archive size allowed for directory parsing. |
+| `archive.maxEntryPreviewSize` | Maximum extracted entry size allowed for online preview. |
+| `pdf.streaming` | PDF URL loading strategy. Same-origin streaming is enabled by default. |
+| `pdf.rangeChunkSize` | PDF.js Range request chunk size. |
+| `typst.compilerWasmUrl` | Custom Typst compiler WASM URL. |
+| `hooks` | Vue component lifecycle hooks for load and unload events. |
+| `beforeOperation` | Vue component guard before download, print, or HTML export. Return `false` to cancel. |
+
+React, vanilla JavaScript, and iframe integrations cannot serialize function hooks into query parameters. Use `onViewerEvent` or `onEvent` to receive lifecycle and operation events from the iframe.
+
+## Printing, Exporting, and Watermarks
+
+- Download keeps the original file bytes. It does not write rendered output back into the source file.
+- Print opens a print-only document containing the rendered body and watermark, without the demo shell or host UI.
+- PDF print and HTML export use a dedicated adapter that renders complete pages rather than only the visible canvas.
+- Word print and HTML export preserve the white paper surface and page sizing while removing preview-only layout wrappers.
+- Spreadsheet, archive, email, EPUB, audio, video, and 3D pipelines hide unreliable print buttons when the full document cannot be printed consistently.
+- HTML export clones the current rendered output and converts canvas content where possible.
+
+## Document Comparison
+
+The production demo includes a standalone comparison page:
+
+[https://viewer.flyfish.dev/compare.html](https://viewer.flyfish.dev/compare.html)
+
+It supports two-pane document preview, built-in samples, URL input, local upload, swapping panes, reset, and synchronized scrolling. The comparison page is intentionally separate from the main viewer entry so that the primary component API stays small and predictable.
+
+## Private Deployment
+
+For npm-based iframe integrations, make sure your final static output contains:
+
+```txt
+file-viewer/index.html
+file-viewer/assets/*
+file-viewer/vendor/libarchive/worker-bundle.js
+file-viewer/vendor/libarchive/libarchive.wasm
+```
+
+The artifact repository also contains:
+
+| Path | Purpose |
+| --- | --- |
+| `dist/` | Minified library build artifacts |
+| `demo/` | Static production demo, including `index.html` and `compare.html` |
+| `adapter-demo/` | React and vanilla JavaScript integration demo |
+| `docs/` | Static documentation site output |
+| `example/` | Sample files used by the demo |
+| `artifacts/` | npm tarballs and packaged static build archives |
+| `README.md` | Default Chinese documentation |
+| `README.en.md` | English documentation |
+| `LICENSE` | Apache-2.0 license |
+
+## Docker
+
+The project provides a static nginx runtime image and build scripts for `linux/amd64` and `linux/arm64`. A typical deployment can serve the demo and comparison page directly:
+
+```bash
+docker run --rm -p 8080:80 flyfishdev/file-viewer:1.0.22
+```
+
+Then open:
+
+```txt
+http://localhost:8080/
+http://localhost:8080/compare.html
+```
+
+If you build the image yourself, use the provided `Dockerfile` and keep the static viewer assets, examples, and vendor WASM files together.
+
+## Public Artifacts vs Source Code
+
+This public repository is for artifact delivery. It contains minified build output, static demo sites, sample files, documentation output, and npm tarballs. It intentionally does not include the private source tree.
+
+If you need source code access, second development resources, or commercial customization, use the self-service source access portal:
+
+[https://dev.flyfish.group/shop](https://dev.flyfish.group/shop)
+
+The self-service source access price is 4.99. It is designed to make legitimate second development and commercial evaluation straightforward without mixing source delivery into the public artifact repository.
+
+## License and Attribution
+
+Flyfish Viewer is distributed under the Apache-2.0 license. You may use the public artifacts according to that license.
+
+For second development or commercial use, please keep clear attribution to Flyfish Viewer and contribute useful fixes or compatibility improvements back whenever possible. This keeps the preview ecosystem healthier for everyone using the component in real business systems.

package/README.md

@@ -1,5 +1,7 @@
 # Flyfish Viewer
 
+[简体中文](README.md) | [English](README.en.md)
+
 把 Word、Excel、PPT、PDF、Typst、压缩包、邮件、音频和电子书稳稳带进浏览器里。
 
 `@flyfish-group/file-viewer3` 是一款基于 Vue 3、TypeScript 和 Vite 构建的纯前端文件预览组件。Vue2.7 项目请使用同能力包 `@flyfish-group/file-viewer`。两条 npm 包线保持一致的格式覆盖、示例体验和 API 语义，Vue3 构建产物作为 React、纯 Web 和其他适配层的统一预览基线。
@@ -12,25 +14,28 @@
 - npm(纯 JS): [@flyfish-group/file-viewer-web](https://www.npmjs.com/package/@flyfish-group/file-viewer-web)
 - 官方文档: [doc.flyfish.dev](https://doc.flyfish.dev)
 - 在线 Demo: [viewer.flyfish.dev](https://viewer.flyfish.dev)
-- 公开成品仓库: [github.com/flyfish-dev/file-viewer](https://github.com/flyfish-dev/file-viewer)
+- 文档比对 Demo: [viewer.flyfish.dev/compare.html](https://viewer.flyfish.dev/compare.html)
+- Docker 镜像发布目标: `flyfishdev/file-viewer:1.0.22`
+- 公开成品仓库(GitHub): [github.com/flyfish-dev/file-viewer](https://github.com/flyfish-dev/file-viewer)
+- 公开成品仓库(Gitee): [gitee.com/flyfish-dev/file-viewer](https://gitee.com/flyfish-dev/file-viewer)
 - 源码自助开通: [https://dev.flyfish.group/shop](https://dev.flyfish.group/shop)
 
 ## 当前发布版本
 
 | 技术栈 | npm 包 | 最新版本 | 推荐分支 | 说明 |
 | --- | --- | --- | --- | --- |
-| Vue3 | `@flyfish-group/file-viewer3` | `1.0.20` | `v3` | 主推版本，也是 React / 纯 Web 私有化 iframe 适配层的构建基线 |
-| Vue2.7 | `@flyfish-group/file-viewer` | `1.0.20` | `main` | 兼容 Vue2 项目，格式能力与 Vue3 保持一致 |
-| React 17 / 18 / 19 | `@flyfish-group/file-viewer-react` | `1.0.20` | 当前仓库子工程 | iframe 组件，默认加载 `/file-viewer/index.html` |
-| 纯 JS | `@flyfish-group/file-viewer-web` | `1.0.20` | 当前仓库子工程 | iframe helper 和 viewer 产物复制工具 |
+| Vue3 | `@flyfish-group/file-viewer3` | `1.0.22` | `v3` | 主推版本，也是 React / 纯 Web 私有化 iframe 适配层的构建基线 |
+| Vue2.7 | `@flyfish-group/file-viewer` | `1.0.22` | `main` | 兼容 Vue2 项目，格式能力与 Vue3 保持一致 |
+| React 17 / 18 / 19 | `@flyfish-group/file-viewer-react` | `1.0.22` | 当前仓库子工程 | iframe 组件，默认加载 `/file-viewer/index.html` |
+| 纯 JS | `@flyfish-group/file-viewer-web` | `1.0.22` | 当前仓库子工程 | iframe helper 和 viewer 产物复制工具 |
 
 如果你在内网、离线环境，或者 npm 发布权限还没有完成配置，也可以直接使用公开成品仓库 `artifacts/` 里的 tarball。离线安装 React 包时请先安装同版本 web 包:
 
 ```bash
-npm install ./artifacts/flyfish-group-file-viewer3-1.0.20.tgz
-npm install ./artifacts/flyfish-group-file-viewer-1.0.20.tgz
-npm install ./artifacts/flyfish-group-file-viewer-web-1.0.20.tgz
-npm install ./artifacts/flyfish-group-file-viewer-react-1.0.20.tgz
+npm install ./artifacts/flyfish-group-file-viewer3-1.0.22.tgz
+npm install ./artifacts/flyfish-group-file-viewer-1.0.22.tgz
+npm install ./artifacts/flyfish-group-file-viewer-web-1.0.22.tgz
+npm install ./artifacts/flyfish-group-file-viewer-react-1.0.22.tgz
 ```
 
 Vue3、Vue2、React 和纯 JS tarball 都会随公开成品仓库一起生成。离线安装 React 包时请先安装同版本 web 包；React / 纯 JS 包推荐用 `npm install` 获得安装即复制的体验。pnpm 10 默认会拦截依赖包的 `postinstall`，如果看到 `Ignored build scripts: @flyfish-group/file-viewer-web`，请执行 `pnpm approve-builds` 允许该包，或安装后运行 `pnpm exec file-viewer-copy-assets ./public/file-viewer`。
@@ -40,28 +45,30 @@ Vue3、Vue2、React 和纯 JS tarball 都会随公开成品仓库一起生成。
 ## 为什么值得接入
 
 - **纯前端 Serverless。** 文档解析和展示全部在浏览器内完成，部署简单，不依赖 Office 服务端、LibreOffice 守护进程或额外转码链路。
-- **格式覆盖完整。** 当前内置 137 个扩展名映射，覆盖 Word、Excel、PowerPoint、PDF、OFD、Typst、压缩包、邮件、OLB/DRA、CAD、3D 模型、Excalidraw、draw.io、EPUB、UMD、Markdown、图片、音频、代码/文本和 MP4，能覆盖绝大多数业务附件场景。
+- **格式覆盖完整。** 当前内置 149 个扩展名映射，覆盖 Word、Excel、PowerPoint、PDF、OFD、Typst、压缩包、邮件、OLB/DRA、CAD、3D 模型、Excalidraw、draw.io、EPUB、UMD、Markdown、图片、音频、代码/文本和 MP4，能覆盖绝大多数业务附件场景。
 - **按需异步加载。** PDF、OFD、Typst、压缩包、邮件、OLB/DRA、CAD、3D 模型、绘图、Office、EPUB、UMD、Markdown 和代码高亮渲染器都按需加载，重型解析依赖不会进入其他格式的首屏路径。
-- **预览器操作完整。** 内置下载原文件、打印完整渲染结果、导出渲染后 HTML、水印开关和水印 options；打印按钮会按当前格式和渲染链路动态显隐，Word / PDF 使用专属完整页导出适配器，不依赖当前视口，适合合同、归档和审批类场景。
+- **预览器操作完整。** 内置下载原文件、打印完整渲染结果、导出渲染后 HTML、水印开关、水印 options 和主题 options；`theme` 支持 `light`、`dark`、`system`，默认跟随系统，浅色业务 UI 可显式锁定 `light`；打印按钮会按当前格式和渲染链路动态显隐，Word / PDF 使用专属完整页导出适配器，不依赖当前视口，适合合同、归档和审批类场景。
 - **集成控制更完整。** 提供加载/卸载生命周期钩子、iframe 事件回传和按钮前置校验机制，下载、打印、导出前可以接入权限验证、审计确认或业务二次弹窗。
 - **阅读体验更像产品。** `.doc`、`.docx`、PDF 都保留灰色工作台、白色纸张、居中阅读和自适应缩放；PDF 兼容旋转页和页面 / 目录导航，Excel 会尽量还原图片和自动文本色，避免“内容能打开但不好读”的落差。
 - **明暗主题有边界。** Demo 外壳、Markdown 和代码预览会适配系统暗色模式；PDF、Word、Excel 等带原始版式的内容保持独立纸张或表格背景，避免全局主题污染文档。
 - **Demo 更适合验收。** 示例文件按文档、表格、图纸、代码、图片等类型分组展示，点击样例即可打开并自动收起选择器。
+- **独立文档比对入口。** 生产 Demo 额外提供 `/compare.html`，左右并排预览两份文档，支持示例、URL、本地上传、交换、重置和同步滚动，不污染主预览入口。
 - **Vue2 / Vue3 体验一致。** `main` 分支面向 Vue2.7，`v3` 分支面向 Vue3；两边共享完整格式覆盖、示例文件盒子、文档站和 iframe 集成体验。
 - **组件和独立站两用。** 既支持在 Vue 项目里直接作为组件使用，也支持独立部署后通过 iframe 嵌入到任意系统，方便多业务线复用。
+- **Docker 一键部署。** 提供 nginx 静态镜像、`Dockerfile` 和 buildx 发布脚本，发布镜像覆盖 `linux/amd64` 与 `linux/arm64`。
 - **适合成品交付。** 公开成品仓库、混淆压缩产物、npm tarball、静态部署产物和私有化 iframe 适配包都一起维护，便于下载、验收和二次接入。
 
 ## 支持格式
 
-当前版本内置 137 个扩展名映射，覆盖 20 条预览链路。
+当前版本内置 149 个扩展名映射，覆盖 20 条预览链路。
 
 | 类别 | 扩展名 | 当前表现 | 适合场景 |
 | --- | --- | --- | --- |
-| Word | `docx` | `docx-preview`，更适合保留文档结构和版式 | 新生成的 Word 文档、正式文档 |
-| Word | `doc` | `msdoc-viewer` + Word 风格页面容器，增强 CFB 容错和表格布局 | 历史 `.doc` 老文档 |
-| Excel | `xlsx` | `styled-exceljs` + 虚拟滚动，支持尺寸、合并、常见样式、自动文本色和 workbook drawing 图片；打印按钮按能力隐藏，避免只打印当前视口 | 需要保留表格结构和样式的业务 |
-| Excel 兼容格式 | `xlsm`、`xlsb`、`xls`、`csv`、`ods`、`fods`、`numbers` | 统一解析，按格式可用信息渐进还原样式；同样遵循虚拟表格打印边界 | 老表格、轻量数据查看 |
-| PowerPoint | `pptx` | 浏览幻灯片内容，增强组合图形、主题背景、图片裁剪与 EMF 矢量图预览 | 汇报材料、课件、方案 |
+| Word | `docx`、`docm`、`dotx`、`dotm` | `docx-preview`，更适合保留文档结构和版式，模板/宏格式按只读预览处理 | 新生成的 Word 文档、正式文档、Word 模板 |
+| Word | `doc`、`dot` | `msdoc-viewer` + Word 风格页面容器，增强 CFB 容错和表格布局 | 历史 `.doc` 老文档、Word 97-2003 模板 |
+| Excel | `xlsx`、`xltx` | `styled-exceljs` + 虚拟滚动，支持尺寸、合并、常见样式、自动文本色和 workbook drawing 图片；打印按钮按能力隐藏，避免只打印当前视口 | 需要保留表格结构和样式的业务、Excel 模板 |
+| Excel 兼容格式 | `xlsm`、`xlsb`、`xls`、`xlt`、`xltm`、`csv`、`ods`、`fods`、`numbers` | 统一解析，按格式可用信息渐进还原样式；同样遵循虚拟表格打印边界 | 老表格、轻量数据查看 |
+| PowerPoint | `pptx`、`pptm`、`potx`、`potm`、`ppsx`、`ppsm` | 浏览幻灯片内容，增强组合图形、主题背景、图片裁剪与 EMF 矢量图预览 | 汇报材料、课件、方案、演示模板 |
 | PDF | `pdf` | 基于 `pdfjs-dist` 预览，同源 URL 默认渐进读取；服务端支持 Range 时自动分片加载，支持缩放工具栏、旋转页、页侧边栏/目录树侧边栏切换、宽度自适应、完整打印和导出 HTML | 合同、票据、版式成品 |
 | OFD | `ofd` | 基于 `DLTech21/ofd.js` 仓库源码在线预览国产版式文档，避开 npm dist 授权 wasm 分支 | 电子发票、公文、归档材料 |
 | Typst | `typ`、`typst` | 直接读取 Typst 源文件，按需加载 `@myriaddreamin/typst.ts` 浏览器 WASM 编译器并按页 SVG 渲染；支持完整预览、打印和导出 HTML | 技术报告、论文草稿、工程文档模板 |
@@ -174,8 +181,8 @@ React 与纯 Web 适配层不再复制渲染器，只通过 iframe 加载 Vue3
 官网 Demo 可用于快速验证预览效果，但 React / 纯 JS 组件不会把官网 Demo 地址作为内置 viewer 地址。
 
 ```bash
-npm install @flyfish-group/file-viewer-react@1.0.20
-npm install @flyfish-group/file-viewer-web@1.0.20
+npm install @flyfish-group/file-viewer-react@1.0.22
+npm install @flyfish-group/file-viewer-web@1.0.22
 ```
 
 ```tsx
@@ -192,7 +199,7 @@ export function Preview() {
 }
 ```
 
-`@flyfish-group/file-viewer-react` 支持 React 17 / 18 / 19，内部复用 `@flyfish-group/file-viewer-web` 的 iframe 协议工具。鉴权文件仍建议由宿主系统先下载成 `Blob`，再用 `file` + `name` 推送给预览器。静态目录不是 `public/file-viewer` 时，可以运行 `npx file-viewer-copy-assets ./public/vendor/file-viewer` 并覆盖 `viewerUrl="/vendor/file-viewer/index.html"`。
+`@flyfish-group/file-viewer-react` 支持 React 17 / 18 / 19，内部复用 `@flyfish-group/file-viewer-web` 的 iframe 协议工具。鉴权文件仍建议由宿主系统先下载成 `Blob`，再用 `file` + `name` 推送给预览器。静态目录不是 `public/file-viewer` 时，可以运行 `npx file-viewer-copy-assets ./public/vendor/file-viewer`，并覆盖 `viewerUrl="/vendor/file-viewer/index.html"`。helper 会默认追加 `__flyfish_viewer_version`，避免旧入口 HTML 缓存继续引用已经不存在的 hash chunk。
 
 本仓库内置了一个私有化适配层演示应用，覆盖 React 组件和纯 Web helper 两种入口。调试时直接运行:
 
@@ -200,18 +207,43 @@ export function Preview() {
 pnpm dev:adapters
 ```
 
-它会先构建并同步 Vue3 基线预览器到演示应用的 `public/file-viewer`，打开本地地址即可看到预览效果。验证静态部署产物时运行:
+它会先构建并同步 Vue3 基线预览器到演示应用的 `public/file-viewer` 和 `public/vendor/file-viewer`，打开本地地址即可同时验证 React 组件和纯 JS `mountViewerFrame` 在自定义子路径下的 DOCX 预览效果。验证静态部署产物时运行:
 
 ```bash
 pnpm build:adapter-demo
 pnpm --filter @flyfish-group/file-viewer-demo preview
 ```
 
-确认无误后，`packages/demo/dist` 可以作为普通静态目录部署；其中已经包含 `file-viewer/index.html` 和演示文件。
+确认无误后，`packages/demo/dist` 可以作为普通静态目录部署；其中已经包含 `file-viewer/index.html`、`vendor/file-viewer/index.html` 和演示文件。
+
+### 5. Docker 一键部署
+
+适合内网、私有云、客户现场或希望直接运行完整 Demo 的场景。镜像发布后可直接运行:
+
+```bash
+docker run -d \
+  --name flyfish-viewer \
+  --restart unless-stopped \
+  -p 8080:80 \
+  flyfishdev/file-viewer:1.0.22
+```
+
+访问:
+
+- 主预览: `http://localhost:8080/`
+- 文档比对: `http://localhost:8080/compare.html`
+
+源码仓库内也提供 `Dockerfile`，本地构建运行:
+
+```bash
+pnpm docker:build
+docker run --rm -p 8080:80 flyfishdev/file-viewer:1.0.22
+```
 
 ## 使用说明
 
 - 组件支持两条主要输入路径: `url?: string` 与 `file?: File`
+- 独立文档比对页位于 `/compare.html`，可通过 `?left=/example/test.doc&right=/example/word.docx` 预置左右文件；它只做视觉并排预览，不做语义 diff，完整说明见 [Demo 文档](docs/guide/demo.md#文档比对页)
 - 当 `file` 和 `url` 同时存在时，会优先渲染 `file`
 - 如果业务侧拿到的是 `Blob` 或 `ArrayBuffer`，推荐先包装成带扩展名的 `File`
 - 预览器会填满父容器，请为父容器提供稳定高度
@@ -219,7 +251,7 @@ pnpm --filter @flyfish-group/file-viewer-demo preview
 - 如果下载地址本身没有明确扩展名，建议先在业务侧取回文件，再包装成 `File`
 - PPTX 渲染器会尽量还原常见组合图形、旋转/翻转、主题背景、图片裁剪和 EMF 矢量图片；复杂 Office 特效仍建议用真实业务文件做回归
 - OFD、Typst、压缩包、邮件、OLB/DRA、CAD、3D 模型、绘图、EPUB、UMD、PDF、Office、Markdown、音频和代码高亮渲染器都按需异步加载，只有命中格式时才拉取对应代码块；Typst compiler WASM 可通过 `options.typst.compilerWasmUrl` 指向自托管地址，默认仅在打开 `.typ` / `.typst` 时加载
-- `options.watermark` 支持文字或图片水印；`options.toolbar` 可控制下载原文件、打印完整渲染结果和导出 HTML；`options.hooks` 可接收加载/卸载生命周期；`options.beforeOperation` 可在下载、打印、导出前做权限校验；打印按钮会结合当前文件类型、渲染完成状态和导出适配器动态显隐，Word / PDF 会生成完整页面，Excel 等虚拟表格会隐藏打印按钮，避免只打印当前视口或第一页
+- `options.theme` 支持 `light`、`dark`、`system`，默认继续跟随系统；`options.watermark` 支持文字或图片水印；`options.toolbar` 可控制下载原文件、打印完整渲染结果、导出 HTML 和操作栏位置，`toolbar.position` 支持 `auto`、`top`、`bottom-right`，PDF 默认悬浮到右下角以避开自身导航栏；`options.hooks` 可接收加载/卸载生命周期；`options.beforeOperation` 可在下载、打印、导出前做权限校验；打印按钮会结合当前文件类型、渲染完成状态和导出适配器动态显隐，Word / PDF 会生成完整页面，Excel 等虚拟表格会隐藏打印按钮，避免只打印当前视口或第一页
 
 ```ts
 const blob = await response.blob()
@@ -228,7 +260,7 @@ const file = new File([blob], 'contract.pdf', { type: blob.type })
 
 ## 本地开发
 
-下面的命令适用于源码开通后的完整项目。公开 GitHub 成品仓库不包含源码目录，普通用户建议直接通过 npm、`dist/` 或 `artifacts/` 里的 tarball 使用。
+下面的命令适用于源码开通后的完整项目。公开 GitHub / Gitee 成品仓库不包含源码目录，普通用户建议直接通过 npm、`dist/` 或 `artifacts/` 里的 tarball 使用。
 
 ```bash
 pnpm install
@@ -244,6 +276,8 @@ pnpm dev
 - `pnpm type-check`: 执行 TypeScript 类型检查
 - `pnpm dev:adapters`: 启动 React + 纯 JS 适配层 Demo
 - `pnpm build:adapter-demo`: 构建适配层 Demo
+- `pnpm docker:build`: 构建本机架构 Docker 镜像
+- `pnpm docker:publish`: 推送 Docker Hub `linux/amd64` / `linux/arm64` 多架构镜像；可通过 `DOCKER_IMAGE` 替换命名空间
 - `pnpm release:adapters:pack`: 打包 React / 纯 JS npm tarball
 
 ## 打包发布
@@ -299,7 +333,7 @@ npm publish --access public
 
 如果 npm 账号启用了 MFA，请使用交互式终端完成浏览器确认后再等待发布结果。
 
-公开 GitHub 仓库只提交可直接使用的构建产物、示例、文档和 npm tarball，不提交当前源码目录。需要源码、二开包或商业自助开通的用户，可以前往 [https://dev.flyfish.group/shop](https://dev.flyfish.group/shop)，付费 4.99 后自助开通。
+公开 GitHub / Gitee 成品仓库只提交可直接使用的构建产物、示例、文档和 npm tarball，不提交当前源码目录。需要源码、二开包或商业自助开通的用户，可以前往 [https://dev.flyfish.group/shop](https://dev.flyfish.group/shop)，付费 4.99 后自助开通。
 
 ## 文档导航
 
@@ -309,6 +343,7 @@ npm publish --access public
 - [组件用法](docs/guide/usage.md)
 - [支持格式](docs/guide/formats.md)
 - [本地开发与打包](docs/guide/development.md)
+- [Docker 部署](docs/guide/docker.md)
 
 ## 开源说明