@file-viewer/web 3.2.2 → 3.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # @file-viewer/web
2
2
 
3
+ [English](https://github.com/flyfish-dev/file-viewer/blob/main/packages/components/web/README.md) · [简体中文](https://github.com/flyfish-dev/file-viewer/blob/main/packages/components/web/README.zh-CN.md)
4
+
5
+ Browser-side file preview for Vanilla JS / Pure Web. Use one component API for loading, search, zoom, page navigation, print and export where supported by the selected format. This is the lightweight package: add renderer presets for PDF, Office and other document formats.
6
+
3
7
  <!-- FILE_VIEWER_PACKAGE_HEADER -->
4
8
  <p>
5
9
  <a href="https://www.npmjs.com/package/@file-viewer/web"><img src="https://img.shields.io/npm/v/@file-viewer%2Fweb?logo=npm" alt="npm version"></a>
@@ -9,50 +13,56 @@
9
13
  </p>
10
14
 
11
15
  <p>
12
- <a href="https://github.com/flyfish-dev/file-viewer">GitHub</a> · <a href="https://doc.file-viewer.app/zh/">文档</a> · <a href="https://demo.file-viewer.app/">在线 Demo</a> · <a href="https://doc.file-viewer.app/guide/formats">格式矩阵</a> · <a href="https://github.com/flyfish-dev/file-viewer/issues">问题反馈</a> · <a href="https://github.com/flyfish-dev/file-viewer/blob/main/packages/components/web/README.en.md">English</a>
16
+ <a href="https://github.com/flyfish-dev/file-viewer">GitHub</a> · <a href="https://doc.file-viewer.app/">Docs</a> · <a href="https://demo.file-viewer.app/">Live demo</a> · <a href="https://doc.file-viewer.app/guide/formats">Format matrix</a> · <a href="https://github.com/flyfish-dev/file-viewer/issues">Issues</a> · <a href="https://github.com/flyfish-dev/file-viewer/blob/main/packages/components/web/README.zh-CN.md">简体中文</a>
13
17
  </p>
14
18
 
15
19
  <p>
16
- <a href="https://demo.file-viewer.app/"><img src="https://raw.githubusercontent.com/flyfish-dev/file-viewer/main/docs/public/_media/file-viewer-demo-v3-zh.webp" width="760" alt="File Viewer 在线演示:Word、Excel、PPT、3D 模型、CAD 图纸与二进制检查器"></a>
20
+ <a href="https://demo.file-viewer.app/"><img src="https://raw.githubusercontent.com/flyfish-dev/file-viewer/main/docs/public/_media/file-viewer-demo-v3-en.webp" width="760" alt="File Viewer live demo: Word, Excel, PowerPoint, 3D model, CAD drawing and binary inspector"></a>
17
21
  </p>
18
22
 
19
- > ⭐ 如果 File Viewer 对你有帮助,欢迎到 [GitHub](https://github.com/flyfish-dev/file-viewer) 点个 Star。
23
+ > ⭐ If File Viewer helps you, please [star the repo on GitHub](https://github.com/flyfish-dev/file-viewer).
24
+
25
+ ## Quick start
26
+
27
+ Create an application with renderers and local assets configured:
28
+
29
+ ```bash
30
+ npx file-viewer-cli@latest create my-viewer --framework web --profile standard
31
+ ```
32
+
33
+ For an existing project, use `npx file-viewer-cli@latest add .`, or follow the [manual integration guide](https://doc.file-viewer.app/guide/on-demand-renderers). The component alone does not install document engines or deploy their Worker/WASM files.
34
+
35
+ ## Manual integration
20
36
 
21
- 标准纯 Web native 组件包。它提供 `<flyfish-file-viewer>` 原生 Web Component、`mountViewer` 命令式 controller、IIFE 全局脚本和资源复制 CLI,适合传统后台页面、script 标签接入、微前端壳和无框架系统集成。
37
+ The examples below require the matching renderer preset and self-hosted assets. The CLI configures these for you; a bare component install is not a PDF or Office viewer.
22
38
 
23
39
  ```bash
24
- npm install @file-viewer/web
40
+ npm install @file-viewer/web @file-viewer/preset-standard file-viewer-copy-assets
41
+ npx --no-install file-viewer-copy-assets ./public/file-viewer
25
42
  ```
26
43
 
27
44
  ```html
28
- <flyfish-file-viewer
29
- id="viewer"
30
- src="/example/demo.pdf"
31
- theme="light"
32
- toolbar-position="bottom-right"
33
- style="display:block;height:720px"
34
- ></flyfish-file-viewer>
45
+ <div id="viewer" style="height:720px"></div>
35
46
  ```
36
47
 
37
48
  ```ts
38
- import { defineFileViewerElement } from '@file-viewer/web'
39
-
40
- defineFileViewerElement()
49
+ import { mountViewer } from '@file-viewer/web'
50
+ import standardRenderers from '@file-viewer/preset-standard'
41
51
 
42
- const viewer = document.getElementById('viewer')
43
- viewer.addEventListener('viewer-event', event => {
44
- console.log(event.detail.type)
52
+ const viewer = mountViewer(document.getElementById('viewer')!, {
53
+ url: '/example/demo.pdf',
54
+ options: { preset: standardRenderers, theme: 'light' },
55
+ onEvent: event => console.log(event.type)
45
56
  })
46
- viewer.zoomIn()
47
57
  ```
48
58
 
49
- 需要完全命令式场景时,仍可使用 `mountViewer(container, options)` 返回完整 controller。
59
+ `mountViewer(container, options)` returns the controller API. For declarative markup, the same package also provides `<flyfish-file-viewer>`; see the [Web Component guide](https://doc.file-viewer.app/guide/quickstart-web).
50
60
 
51
- ## 样式隔离与定制
61
+ ## Style Isolation And Customization
52
62
 
53
- `<flyfish-file-viewer>` 和 Web/IIFE 默认使用 Shadow DOM 隔离组件壳与预览内容,适合 OA、低代码、微前端和后台系统这类宿主 CSS 不可控的页面。需要历史 light DOM 行为时,可传 `options: { styleIsolation: 'none' }` 或 `<flyfish-file-viewer style-isolation="none">`。
63
+ `<flyfish-file-viewer>` and Web/IIFE mounts use Shadow DOM by default to protect the viewer shell and rendered content from host-page CSS. This is the recommended path for admin systems, low-code shells, micro-frontends, and pages where global CSS is hard to control. For the historical light-DOM behavior, pass `options: { styleIsolation: 'none' }` or `<flyfish-file-viewer style-isolation="none">`.
54
64
 
55
- 推荐通过 CSS 变量和 Shadow Parts 做受控定制:
65
+ Use CSS variables and Shadow Parts for controlled customization:
56
66
 
57
67
  ```css
58
68
  flyfish-file-viewer {
@@ -65,15 +75,15 @@ flyfish-file-viewer::part(toolbar) {
65
75
  }
66
76
  ```
67
77
 
68
- 稳定 parts 包括 `host`、`shell`、`toolbar`、`toolbar-group`、`toolbar-status`、`button`、`input` 和 `content`。所有标准组件默认使用 Shadow DOM;主题定制优先使用 tokens 和 `::part()`,仅旧版深层覆盖场景显式使用 `options.styleIsolation: 'none'`。完整模式和 hostile CSS 验证见官方文档: https://doc.file-viewer.app/
78
+ Stable parts include `host`, `shell`, `toolbar`, `toolbar-group`, `toolbar-status`, `button`, `input`, and `content`. Every standard component defaults to Shadow DOM. Customize with tokens and `::part()`; use `options.styleIsolation: 'none'` only for legacy deep overrides. See the official documentation for modes and hostile CSS verification: https://doc.file-viewer.app/
69
79
 
70
- 如需自托管 Worker、WASM 和静态示例资源,可以使用资源复制命令:
80
+ Use the asset copy command when you need to self-host workers, WASM files, and static examples:
71
81
 
72
82
  ```bash
73
83
  npx --yes file-viewer-copy-assets ./public/file-viewer
74
84
  ```
75
85
 
76
- 无构建工具或传统后台页面可以复制 `dist/flyfish-file-viewer-web.iife.js` 并直接用普通 `<script>` 引入:
86
+ No-build or legacy admin pages can copy `dist/flyfish-file-viewer-web.iife.js` and load it through a plain script tag:
77
87
 
78
88
  ```html
79
89
  <script src="/vendor/file-viewer-web/flyfish-file-viewer-web.iife.js"></script>
@@ -84,99 +94,100 @@ npx --yes file-viewer-copy-assets ./public/file-viewer
84
94
  ></flyfish-file-viewer>
85
95
  ```
86
96
 
87
- 历史包名 `@flyfish-group/file-viewer-web` 会继续同步维护;新项目建议优先使用标准包 `@file-viewer/web`。English README: [README.en.md](./README.en.md)。
97
+ The historical package `@flyfish-group/file-viewer-web` remains supported for compatibility. New integrations should prefer the standard package `@file-viewer/web`.
88
98
 
89
- ## 能力范围
99
+ ## Capabilities
90
100
 
91
- `@file-viewer/web` 与其他标准组件包共享同一套 core 接口和 renderer/preset 装配模型;完整能力可通过按需 renderer 或 `@file-viewer/preset-all` 覆盖 PDF、Word、Excel、PPT、OFD、CAD/DWG/DXF/DWF、EPUB/UMD、压缩包、邮件、Markdown、代码高亮、图片、音频、视频、3D 模型、地理数据和结构化数据资产等预览链路。完整格式矩阵和参数说明见官方文档: https://doc.file-viewer.app/guide/formats
101
+ `@file-viewer/web` shares the same core contract and renderer/preset assembly model with the other standard component packages; full capability can be assembled with on-demand renderers or `@file-viewer/preset-all`, including PDF, Word, Excel, PowerPoint, OFD, CAD/DWG/DXF/DWF, EPUB/UMD, archives, email, Markdown, highlighted code, images, audio, video, 3D models, geospatial files, and structured data assets. See the complete format matrix and option reference at https://doc.file-viewer.app/guide/formats
92
102
 
93
103
  ## RequireJS
94
104
 
95
- 从 3.0.3 起,`dist/flyfish-file-viewer-web.amd.js` 提供轻量组件壳的 AMD API,
96
- 不自动包含格式渲染器。要直接预览文档,使用 `@file-viewer/web-full` 的 AMD 入口并完整部署其 `dist/`。
97
- [接入示例](https://doc.file-viewer.app/zh/guide/quickstart-web#requirejsamd)。
105
+ From 3.0.3, `dist/flyfish-file-viewer-web.amd.js` exports the light shell API as AMD,
106
+ without format renderers. For document preview without a bundler, use the
107
+ `@file-viewer/web-full` AMD entry and deploy its complete `dist/`.
108
+ [Integration example](https://doc.file-viewer.app/guide/quickstart-web#requirejs-amd).
98
109
 
99
110
  <!-- FILE_VIEWER_GENERATED:START -->
100
- ## 生态包矩阵
111
+ ## Ecosystem Matrix
101
112
 
102
- 所有标准组件包都只共享 `@file-viewer/core` 这个总底座,不依赖其他框架组件实现。core 负责格式矩阵、资源解析、renderer 协议、事件、操作 API、搜索、缩放、打印和导出;PDF、Word、PPT/PPTX、CAD、Typst 等重型链路通过独立 renderer 或 preset 显式装配;各框架组件包自己维护本地 controller、组件生命周期、类型出口和生态交互。
113
+ Every standard component package shares `@file-viewer/core` as the only common foundation, and no framework component package depends on another framework implementation. Core owns format metadata, source loading, the renderer protocol, events, operation APIs, search, zoom, print, export, and the framework-neutral browser shell. Heavy PDF, Word, PPT/PPTX, CAD, Typst, and similar pipelines are assembled explicitly through renderer packages or presets; each framework package owns its component lifecycle, type exports, compatibility defaults, and ecosystem-specific interaction layer.
103
114
 
104
- | 框架 | 标准 npm 包 | 入口格式 | GitHub | Gitee | 兼容历史包 |
115
+ | Framework | Standard npm package | Entrypoints | GitHub | Gitee | Historical aliases |
105
116
  | --- | --- | --- | --- | --- | --- |
106
- | Vanilla JS / Pure Web | `@file-viewer/web` | ESM, 类型声明, script 标签 IIFE, RequireJS AMD | [file-viewer-web](https://github.com/flyfish-dev/file-viewer-web) | [file-viewer-web](https://gitee.com/flyfish-dev/file-viewer-web) | `@flyfish-group/file-viewer-web` |
107
- | Vanilla JS / Pure Web Full | `@file-viewer/web-full` | ESM, 类型声明, script 标签 IIFE, RequireJS AMD | [file-viewer-web-full](https://github.com/flyfish-dev/file-viewer-web-full) | [file-viewer-web-full](https://gitee.com/flyfish-dev/file-viewer-web-full) | 无 |
108
- | Vue 3 | `@file-viewer/vue3` | ESM, 类型声明 | [file-viewer-vue3](https://github.com/flyfish-dev/file-viewer-vue3) | [file-viewer-vue3](https://gitee.com/flyfish-dev/file-viewer-vue3) | `@flyfish-group/file-viewer3`, `file-viewer3` |
109
- | Vue 3 Full | `@file-viewer/vue3-full` | ESM, 类型声明 | [file-viewer-vue3-full](https://github.com/flyfish-dev/file-viewer-vue3-full) | [file-viewer-vue3-full](https://gitee.com/flyfish-dev/file-viewer-vue3-full) | 无 |
110
- | Vue 2.7 | `@file-viewer/vue2.7` | ESM, 类型声明 | [file-viewer-vue2.7](https://github.com/flyfish-dev/file-viewer-vue2.7) | [file-viewer-vue2.7](https://gitee.com/flyfish-dev/file-viewer-vue2.7) | `@flyfish-group/file-viewer` |
111
- | Vue 2.7 Full | `@file-viewer/vue2.7-full` | ESM, 类型声明 | [file-viewer-vue2.7-full](https://github.com/flyfish-dev/file-viewer-vue2.7-full) | [file-viewer-vue2.7-full](https://gitee.com/flyfish-dev/file-viewer-vue2.7-full) | 无 |
112
- | Vue 2.6 | `@file-viewer/vue2.6` | ESM, 类型声明 | [file-viewer-vue2.6](https://github.com/flyfish-dev/file-viewer-vue2.6) | [file-viewer-vue2.6](https://gitee.com/flyfish-dev/file-viewer-vue2.6) | 无 |
113
- | Vue 2.6 Full | `@file-viewer/vue2.6-full` | ESM, 类型声明 | [file-viewer-vue2.6-full](https://github.com/flyfish-dev/file-viewer-vue2.6-full) | [file-viewer-vue2.6-full](https://gitee.com/flyfish-dev/file-viewer-vue2.6-full) | 无 |
114
- | React 18/19 | `@file-viewer/react` | ESM, 类型声明 | [file-viewer-react](https://github.com/flyfish-dev/file-viewer-react) | [file-viewer-react](https://gitee.com/flyfish-dev/file-viewer-react) | `@flyfish-group/file-viewer-react` |
115
- | React 18/19 Full | `@file-viewer/react-full` | ESM, 类型声明 | [file-viewer-react-full](https://github.com/flyfish-dev/file-viewer-react-full) | [file-viewer-react-full](https://gitee.com/flyfish-dev/file-viewer-react-full) | 无 |
116
- | React 16.8/17 | `@file-viewer/react-legacy` | ESM, 类型声明 | [file-viewer-react-legacy](https://github.com/flyfish-dev/file-viewer-react-legacy) | [file-viewer-react-legacy](https://gitee.com/flyfish-dev/file-viewer-react-legacy) | 无 |
117
- | React 16.8/17 Full | `@file-viewer/react-legacy-full` | ESM, 类型声明 | [file-viewer-react-legacy-full](https://github.com/flyfish-dev/file-viewer-react-legacy-full) | [file-viewer-react-legacy-full](https://gitee.com/flyfish-dev/file-viewer-react-legacy-full) | 无 |
118
- | jQuery | `@file-viewer/jquery` | ESM, 类型声明 | [file-viewer-jquery](https://github.com/flyfish-dev/file-viewer-jquery) | [file-viewer-jquery](https://gitee.com/flyfish-dev/file-viewer-jquery) | 无 |
119
- | jQuery Full | `@file-viewer/jquery-full` | ESM, 类型声明 | [file-viewer-jquery-full](https://github.com/flyfish-dev/file-viewer-jquery-full) | [file-viewer-jquery-full](https://gitee.com/flyfish-dev/file-viewer-jquery-full) | 无 |
120
- | Svelte | `@file-viewer/svelte` | Svelte 组件, ESM, 类型声明 | [file-viewer-svelte](https://github.com/flyfish-dev/file-viewer-svelte) | [file-viewer-svelte](https://gitee.com/flyfish-dev/file-viewer-svelte) | 无 |
121
- | Svelte Full | `@file-viewer/svelte-full` | Svelte 组件, ESM, 类型声明 | [file-viewer-svelte-full](https://github.com/flyfish-dev/file-viewer-svelte-full) | [file-viewer-svelte-full](https://gitee.com/flyfish-dev/file-viewer-svelte-full) | 无 |
122
-
123
- ## 格式支持矩阵
124
-
125
- 共享格式目录当前注册 275 个扩展名(225 个稳定、50 个实验),映射到 47 条预览链路。实验格式不计入稳定支持数量;完整能力通过 renderer / preset 按需装配。
126
-
127
- | 预览链路 | 分类 | 扩展名 | 等级 / 状态 | 能力 | 加载 |
117
+ | Vanilla JS / Pure Web | `@file-viewer/web` | ESM, type declarations, script tag IIFE, RequireJS AMD | [file-viewer-web](https://github.com/flyfish-dev/file-viewer-web) | [file-viewer-web](https://gitee.com/flyfish-dev/file-viewer-web) | `@flyfish-group/file-viewer-web` |
118
+ | Vanilla JS / Pure Web Full | `@file-viewer/web-full` | ESM, type declarations, script tag IIFE, RequireJS AMD | [file-viewer-web-full](https://github.com/flyfish-dev/file-viewer-web-full) | [file-viewer-web-full](https://gitee.com/flyfish-dev/file-viewer-web-full) | none |
119
+ | Vue 3 | `@file-viewer/vue3` | ESM, type declarations | [file-viewer-vue3](https://github.com/flyfish-dev/file-viewer-vue3) | [file-viewer-vue3](https://gitee.com/flyfish-dev/file-viewer-vue3) | `@flyfish-group/file-viewer3`, `file-viewer3` |
120
+ | Vue 3 Full | `@file-viewer/vue3-full` | ESM, type declarations | [file-viewer-vue3-full](https://github.com/flyfish-dev/file-viewer-vue3-full) | [file-viewer-vue3-full](https://gitee.com/flyfish-dev/file-viewer-vue3-full) | none |
121
+ | Vue 2.7 | `@file-viewer/vue2.7` | ESM, type declarations | [file-viewer-vue2.7](https://github.com/flyfish-dev/file-viewer-vue2.7) | [file-viewer-vue2.7](https://gitee.com/flyfish-dev/file-viewer-vue2.7) | `@flyfish-group/file-viewer` |
122
+ | Vue 2.7 Full | `@file-viewer/vue2.7-full` | ESM, type declarations | [file-viewer-vue2.7-full](https://github.com/flyfish-dev/file-viewer-vue2.7-full) | [file-viewer-vue2.7-full](https://gitee.com/flyfish-dev/file-viewer-vue2.7-full) | none |
123
+ | Vue 2.6 | `@file-viewer/vue2.6` | ESM, type declarations | [file-viewer-vue2.6](https://github.com/flyfish-dev/file-viewer-vue2.6) | [file-viewer-vue2.6](https://gitee.com/flyfish-dev/file-viewer-vue2.6) | none |
124
+ | Vue 2.6 Full | `@file-viewer/vue2.6-full` | ESM, type declarations | [file-viewer-vue2.6-full](https://github.com/flyfish-dev/file-viewer-vue2.6-full) | [file-viewer-vue2.6-full](https://gitee.com/flyfish-dev/file-viewer-vue2.6-full) | none |
125
+ | React 18/19 | `@file-viewer/react` | ESM, type declarations | [file-viewer-react](https://github.com/flyfish-dev/file-viewer-react) | [file-viewer-react](https://gitee.com/flyfish-dev/file-viewer-react) | `@flyfish-group/file-viewer-react` |
126
+ | React 18/19 Full | `@file-viewer/react-full` | ESM, type declarations | [file-viewer-react-full](https://github.com/flyfish-dev/file-viewer-react-full) | [file-viewer-react-full](https://gitee.com/flyfish-dev/file-viewer-react-full) | none |
127
+ | React 16.8/17 | `@file-viewer/react-legacy` | ESM, type declarations | [file-viewer-react-legacy](https://github.com/flyfish-dev/file-viewer-react-legacy) | [file-viewer-react-legacy](https://gitee.com/flyfish-dev/file-viewer-react-legacy) | none |
128
+ | React 16.8/17 Full | `@file-viewer/react-legacy-full` | ESM, type declarations | [file-viewer-react-legacy-full](https://github.com/flyfish-dev/file-viewer-react-legacy-full) | [file-viewer-react-legacy-full](https://gitee.com/flyfish-dev/file-viewer-react-legacy-full) | none |
129
+ | jQuery | `@file-viewer/jquery` | ESM, type declarations | [file-viewer-jquery](https://github.com/flyfish-dev/file-viewer-jquery) | [file-viewer-jquery](https://gitee.com/flyfish-dev/file-viewer-jquery) | none |
130
+ | jQuery Full | `@file-viewer/jquery-full` | ESM, type declarations | [file-viewer-jquery-full](https://github.com/flyfish-dev/file-viewer-jquery-full) | [file-viewer-jquery-full](https://gitee.com/flyfish-dev/file-viewer-jquery-full) | none |
131
+ | Svelte | `@file-viewer/svelte` | Svelte component, ESM, type declarations | [file-viewer-svelte](https://github.com/flyfish-dev/file-viewer-svelte) | [file-viewer-svelte](https://gitee.com/flyfish-dev/file-viewer-svelte) | none |
132
+ | Svelte Full | `@file-viewer/svelte-full` | Svelte component, ESM, type declarations | [file-viewer-svelte-full](https://github.com/flyfish-dev/file-viewer-svelte-full) | [file-viewer-svelte-full](https://gitee.com/flyfish-dev/file-viewer-svelte-full) | none |
133
+
134
+ ## Format Support Matrix
135
+
136
+ The shared catalog registers 275 file extensions (225 stable and 50 experimental) across 47 preview pipelines. Experimental formats do not count toward stable support; full capability is assembled through renderer packages or presets.
137
+
138
+ | Preview pipeline | Category | Extensions | Level / status | Capabilities | Loading |
128
139
  | --- | --- | --- | --- | --- | --- |
129
- | Word OpenXML | office | `.docx`, `.docm`, `.dotx`, `.dotm` | high-fidelity / stable | 下载, 打印(适配器), HTML(适配器), 缩放(Provider), 搜索 | 按需异步 |
130
- | Word Binary | office | `.doc`, `.dot` | structured / stable | 下载, 打印(适配器), HTML(适配器), 缩放(Provider), 搜索 | 按需异步 |
131
- | PowerPoint 97–2003 | office | `.ppt`, `.pot` | structured / stable | 下载, 打印(适配器), HTML(适配器), 缩放(Provider) | 按需异步 |
132
- | PowerPoint OpenXML | office | `.pptx`, `.pptm`, `.potx`, `.potm`, `.ppsx`, `.ppsm` | high-fidelity / stable | 下载, 打印, HTML, 缩放(Provider), 搜索 | 按需异步 |
133
- | Open Document | office | `.rtf`, `.odt`, `.odp` | structured / stable | 下载, 打印, HTML, 缩放(Provider), 搜索 | 按需异步 |
134
- | Spreadsheet | office | `.xlsx`, `.xltx`, `.xlsm`, `.xlsb`, `.xls`, `.xlt`, `.xla`, `.xlam`, `.xltm`, `.csv`, `.tsv`, `.ods`, `.fods` | structured / stable | 下载, 缩放(Provider), 搜索 | 按需异步 |
135
- | Apple Pages | office | `.pages` | high-fidelity / stable | 下载, 打印(适配器), HTML(适配器), 缩放(Provider), 搜索 | 按需异步 |
136
- | Apple Numbers | office | `.numbers` | high-fidelity / stable | 下载, 打印(适配器), HTML(适配器), 缩放(Provider), 搜索 | 按需异步 |
137
- | Apple Keynote | office | `.key` | high-fidelity / stable | 下载, 打印(适配器), HTML(适配器), 缩放(Provider), 搜索 | 按需异步 |
138
- | WordPerfect | office | `.wpd`, `.wp`, `.wp5`, `.wp6` | structured / stable | 下载, 打印(适配器), HTML(适配器), 缩放(Provider), 搜索 | 按需异步 |
139
- | dBASE Table | office | `.dbf` | structured / stable | 下载, 缩放(Provider), 搜索 | 按需异步 |
140
- | PDF | document | `.pdf` | high-fidelity / stable | 下载, 打印(适配器), HTML(适配器), 缩放(Provider), 搜索(Provider) | 按需异步 |
141
- | OFD | document | `.ofd` | structured / stable | 下载, 打印, HTML, 缩放(Provider), 搜索 | 按需异步 |
142
- | Hancom Hangul | office | `.hwp`, `.hwpx` | structured / stable | 下载, 打印(适配器), HTML(适配器), 缩放(Provider), 搜索 | 按需异步 |
143
- | Typst | document | `.typ`, `.typst` | high-fidelity / stable | 下载, 打印(适配器), HTML(适配器), 缩放(Provider), 搜索 | 按需异步 |
144
- | Archive | archive | `.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` | structured / stable | 下载, 搜索 | 按需异步 |
145
- | Compiled HTML Help | ebook | `.chm` | structured / stable | 下载, 打印(适配器), HTML(适配器), 搜索 | 按需异步 |
146
- | Email | email | `.eml`, `.msg`, `.mbox` | structured / stable | 下载, HTML, 搜索 | 按需异步 |
147
- | EDA | eda | `.olb`, `.dra`, `.gds`, `.oas`, `.oasis` | structured / stable | 下载, 打印, HTML, 搜索 | 按需异步 |
148
- | CAD | cad | `.dxf`, `.dwg`, `.dwf`, `.dwfx`, `.xps` | high-fidelity / stable | 下载, 打印, HTML, 缩放(Provider) | 按需异步 |
149
- | 3D Model | model | `.glb`, `.gltf`, `.obj`, `.stl`, `.ply`, `.fbx`, `.dae`, `.3ds`, `.3mf`, `.amf`, `.usd`, `.usda`, `.usdc`, `.usdz`, `.kmz`, `.step`, `.stp`, `.iges`, `.igs`, `.ifc`, `.3dm`, `.brep`, `.pcd`, `.wrl`, `.vrml`, `.xyz`, `.vtk`, `.vtp` | structured / stable | 下载, 缩放(Provider) | 按需异步 |
150
- | Geospatial | geo | `.geojson`, `.kml`, `.gpx`, `.shp` | structured / stable | 下载, 打印, HTML, 缩放(Provider), 搜索 | 按需异步 |
151
- | Drawing | drawing | `.excalidraw`, `.drawio`, `.dio`, `.mermaid`, `.mmd`, `.plantuml`, `.puml` | structured / stable | 下载, 打印, HTML, 缩放(Provider), 搜索 | 按需异步 |
152
- | BPMN 2.0 | drawing | `.bpmn` | structured / experimental | 下载, 缩放(Provider) | 按需异步 |
153
- | Mind Map | mindmap | `.xmind` | structured / stable | 下载, 打印, HTML, 缩放(Provider), 搜索 | 按需异步 |
154
- | EPUB | ebook | `.epub` | high-fidelity / stable | 下载, HTML, 搜索(Provider) | 按需异步 |
155
- | FictionBook | ebook | `.fb2` | structured / stable | 下载, 打印, HTML, 搜索 | 按需异步 |
156
- | UMD | ebook | `.umd` | structured / stable | 下载, 打印, HTML, 缩放(Provider), 搜索 | 按需异步 |
157
- | Image | image | `.gif`, `.jpg`, `.jpeg`, `.bmp`, `.tiff`, `.tif`, `.png`, `.svg`, `.webp`, `.avif`, `.ico`, `.heic`, `.heif`, `.jxl` | high-fidelity / stable | 下载, 打印, HTML, 缩放(Provider) | 按需异步 |
158
- | DICOM | medical-image | `.dcm`, `.dicom` | basic / experimental | 下载, 缩放(Provider) | 按需异步 |
159
- | Digital signatures and evidence containers | cryptographic-container | `.p7m`, `.p7s`, `.p7c`, `.p7b`, `.pkcs7`, `.cms`, `.cmsc`, `.tsd`, `.tst`, `.tsq`, `.tsr`, `.asics`, `.scs`, `.asice`, `.sce`, `.ers`, `.asc`, `.sig`, `.pgp`, `.gpg`, `.jws` | structured / experimental | 下载 | 按需异步 |
160
- | Markdown | markdown | `.md`, `.markdown` | structured / stable | 下载, 打印, HTML, 搜索 | 按需异步 |
161
- | Code and Text | code | `.txt`, `.lrc`, `.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`, `.patch`, `.bundle`, `.bdl`, `.jsonc`, `.json5`, `.ipynb`, `.toml`, `.proto`, `.hcl`, `.tex`, `.gv`, `.http`, `.react`, `.rb`, `.swift`, `.kt` | structured / stable | 下载, 打印, HTML, 搜索 | 按需异步 |
162
- | Video | media | `.mp4`, `.webm`, `.m3u8` | high-fidelity / stable | 下载 | 按需异步 |
163
- | Audio | media | `.mp3`, `.mpeg`, `.wav`, `.ogg`, `.oga`, `.opus`, `.m4a`, `.aac`, `.flac`, `.weba`, `.midi`, `.mid` | high-fidelity / stable | 下载 | 按需异步 |
164
- | Adobe Photoshop | asset | `.psb`, `.pdd`, `.psdt`, `.psd`(增强 `data-asset`) | experimental / experimental | 下载, 打印, 缩放 | 按需异步 |
165
- | Adobe Illustrator AI/AIT | asset | `.ait`, `.ai`(增强 `data-asset`) | experimental / experimental | 下载, 打印, 缩放, 搜索 | 按需异步 |
166
- | Adobe InDesign IDML | asset | `.idml` | experimental / experimental | 下载, 打印, 缩放 | 按需异步 |
167
- | Adobe InCopy and InDesign Exchange | asset | `.icml`, `.idms`, `.inx` | structured / experimental | 下载, 打印, HTML, 搜索 | 按需异步 |
168
- | Adobe Animate XFL | asset | `.fla`, `.xfl` | structured / experimental | 下载 | 按需异步 |
169
- | Adobe XD Package | asset | `.xd` | structured / experimental | 下载 | 按需异步 |
170
- | Adobe InDesign Native | asset | `.indd`, `.indt` | structured / experimental | 下载 | 按需异步 |
171
- | Adobe EPS and PostScript | asset | `.ps`, `.eps`(增强 `data-asset`) | experimental / experimental | 下载, 打印, 缩放 | 按需异步 |
172
- | Adobe Color Palettes | asset | `.ase`, `.aco` | structured / stable | 下载, 打印, HTML, 搜索 | 按需异步 |
173
- | Adobe Photoshop Resources and Presets | asset | `.abr`, `.csh`, `.pat`, `.grd`, `.asl` | structured / experimental | 下载, 打印, 搜索 | 按需异步 |
174
- | Data Asset | asset | `.ttf`, `.otf`, `.woff`, `.woff2`, `.psd`, `.ai`, `.eps`, `.sqlite`, `.wasm`, `.parquet`, `.avro`, `.webarchive` | structured / stable | 下载, HTML, 搜索 | 按需异步 |
175
- | Binary Inspector | asset | `.bin`, `.hex`, `.elf`, `.exe`, `.dll`, `.class`, `.macho` | structured / experimental | 下载 | 按需异步 |
176
-
177
- ## 工程级按需 renderer 装配
178
-
179
- 快速开始的核心是先跑通组件,再明确格式能力边界。推荐先安装当前生态组件包,再按产品形态选择 `@file-viewer/preset-lite`、`@file-viewer/preset-office`、`@file-viewer/preset-engineering` 或 `@file-viewer/preset-all`。Webpack、Rspack、Rollup、Umi、传统多页应用等非 Vite 项目,优先通过 `options.preset` 或 `options.renderers` 显式注入能力;Vite 插件只是进一步省掉手动 import 并复制离线资产。
140
+ | Word OpenXML | office | `.docx`, `.docm`, `.dotx`, `.dotm` | high-fidelity / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
141
+ | Word Binary | office | `.doc`, `.dot` | structured / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
142
+ | PowerPoint 97–2003 | office | `.ppt`, `.pot` | structured / stable | download, print(adapter), HTML export(adapter), zoom(provider) | lazy async |
143
+ | PowerPoint OpenXML | office | `.pptx`, `.pptm`, `.potx`, `.potm`, `.ppsx`, `.ppsm` | high-fidelity / stable | download, print, HTML export, zoom(provider), search | lazy async |
144
+ | Open Document | office | `.rtf`, `.odt`, `.odp` | structured / stable | download, print, HTML export, zoom(provider), search | lazy async |
145
+ | Spreadsheet | office | `.xlsx`, `.xltx`, `.xlsm`, `.xlsb`, `.xls`, `.xlt`, `.xla`, `.xlam`, `.xltm`, `.csv`, `.tsv`, `.ods`, `.fods` | structured / stable | download, zoom(provider), search | lazy async |
146
+ | Apple Pages | office | `.pages` | high-fidelity / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
147
+ | Apple Numbers | office | `.numbers` | high-fidelity / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
148
+ | Apple Keynote | office | `.key` | high-fidelity / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
149
+ | WordPerfect | office | `.wpd`, `.wp`, `.wp5`, `.wp6` | structured / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
150
+ | dBASE Table | office | `.dbf` | structured / stable | download, zoom(provider), search | lazy async |
151
+ | PDF | document | `.pdf` | high-fidelity / stable | download, print(adapter), HTML export(adapter), zoom(provider), search(provider) | lazy async |
152
+ | OFD | document | `.ofd` | structured / stable | download, print, HTML export, zoom(provider), search | lazy async |
153
+ | Hancom Hangul | office | `.hwp`, `.hwpx` | structured / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
154
+ | Typst | document | `.typ`, `.typst` | high-fidelity / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
155
+ | Archive | archive | `.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` | structured / stable | download, search | lazy async |
156
+ | Compiled HTML Help | ebook | `.chm` | structured / stable | download, print(adapter), HTML export(adapter), search | lazy async |
157
+ | Email | email | `.eml`, `.msg`, `.mbox` | structured / stable | download, HTML export, search | lazy async |
158
+ | EDA | eda | `.olb`, `.dra`, `.gds`, `.oas`, `.oasis` | structured / stable | download, print, HTML export, search | lazy async |
159
+ | CAD | cad | `.dxf`, `.dwg`, `.dwf`, `.dwfx`, `.xps` | high-fidelity / stable | download, print, HTML export, zoom(provider) | lazy async |
160
+ | 3D Model | model | `.glb`, `.gltf`, `.obj`, `.stl`, `.ply`, `.fbx`, `.dae`, `.3ds`, `.3mf`, `.amf`, `.usd`, `.usda`, `.usdc`, `.usdz`, `.kmz`, `.step`, `.stp`, `.iges`, `.igs`, `.ifc`, `.3dm`, `.brep`, `.pcd`, `.wrl`, `.vrml`, `.xyz`, `.vtk`, `.vtp` | structured / stable | download, zoom(provider) | lazy async |
161
+ | Geospatial | geo | `.geojson`, `.kml`, `.gpx`, `.shp` | structured / stable | download, print, HTML export, zoom(provider), search | lazy async |
162
+ | Drawing | drawing | `.excalidraw`, `.drawio`, `.dio`, `.mermaid`, `.mmd`, `.plantuml`, `.puml` | structured / stable | download, print, HTML export, zoom(provider), search | lazy async |
163
+ | BPMN 2.0 | drawing | `.bpmn` | structured / experimental | download, zoom(provider) | lazy async |
164
+ | Mind Map | mindmap | `.xmind` | structured / stable | download, print, HTML export, zoom(provider), search | lazy async |
165
+ | EPUB | ebook | `.epub` | high-fidelity / stable | download, HTML export, search(provider) | lazy async |
166
+ | FictionBook | ebook | `.fb2` | structured / stable | download, print, HTML export, search | lazy async |
167
+ | UMD | ebook | `.umd` | structured / stable | download, print, HTML export, zoom(provider), search | lazy async |
168
+ | Image | image | `.gif`, `.jpg`, `.jpeg`, `.bmp`, `.tiff`, `.tif`, `.png`, `.svg`, `.webp`, `.avif`, `.ico`, `.heic`, `.heif`, `.jxl` | high-fidelity / stable | download, print, HTML export, zoom(provider) | lazy async |
169
+ | DICOM | medical-image | `.dcm`, `.dicom` | basic / experimental | download, zoom(provider) | lazy async |
170
+ | Digital signatures and evidence containers | cryptographic-container | `.p7m`, `.p7s`, `.p7c`, `.p7b`, `.pkcs7`, `.cms`, `.cmsc`, `.tsd`, `.tst`, `.tsq`, `.tsr`, `.asics`, `.scs`, `.asice`, `.sce`, `.ers`, `.asc`, `.sig`, `.pgp`, `.gpg`, `.jws` | structured / experimental | download | lazy async |
171
+ | Markdown | markdown | `.md`, `.markdown` | structured / stable | download, print, HTML export, search | lazy async |
172
+ | Code and Text | code | `.txt`, `.lrc`, `.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`, `.patch`, `.bundle`, `.bdl`, `.jsonc`, `.json5`, `.ipynb`, `.toml`, `.proto`, `.hcl`, `.tex`, `.gv`, `.http`, `.react`, `.rb`, `.swift`, `.kt` | structured / stable | download, print, HTML export, search | lazy async |
173
+ | Video | media | `.mp4`, `.webm`, `.m3u8` | high-fidelity / stable | download | lazy async |
174
+ | Audio | media | `.mp3`, `.mpeg`, `.wav`, `.ogg`, `.oga`, `.opus`, `.m4a`, `.aac`, `.flac`, `.weba`, `.midi`, `.mid` | high-fidelity / stable | download | lazy async |
175
+ | Adobe Photoshop | asset | `.psb`, `.pdd`, `.psdt`, `.psd` (enhances `data-asset`) | experimental / experimental | download, print, zoom | lazy async |
176
+ | Adobe Illustrator AI/AIT | asset | `.ait`, `.ai` (enhances `data-asset`) | experimental / experimental | download, print, zoom, search | lazy async |
177
+ | Adobe InDesign IDML | asset | `.idml` | experimental / experimental | download, print, zoom | lazy async |
178
+ | Adobe InCopy and InDesign Exchange | asset | `.icml`, `.idms`, `.inx` | structured / experimental | download, print, HTML export, search | lazy async |
179
+ | Adobe Animate XFL | asset | `.fla`, `.xfl` | structured / experimental | download | lazy async |
180
+ | Adobe XD Package | asset | `.xd` | structured / experimental | download | lazy async |
181
+ | Adobe InDesign Native | asset | `.indd`, `.indt` | structured / experimental | download | lazy async |
182
+ | Adobe EPS and PostScript | asset | `.ps`, `.eps` (enhances `data-asset`) | experimental / experimental | download, print, zoom | lazy async |
183
+ | Adobe Color Palettes | asset | `.ase`, `.aco` | structured / stable | download, print, HTML export, search | lazy async |
184
+ | Adobe Photoshop Resources and Presets | asset | `.abr`, `.csh`, `.pat`, `.grd`, `.asl` | structured / experimental | download, print, search | lazy async |
185
+ | Data Asset | asset | `.ttf`, `.otf`, `.woff`, `.woff2`, `.psd`, `.ai`, `.eps`, `.sqlite`, `.wasm`, `.parquet`, `.avro`, `.webarchive` | structured / stable | download, HTML export, search | lazy async |
186
+ | Binary Inspector | asset | `.bin`, `.hex`, `.elf`, `.exe`, `.dll`, `.class`, `.macho` | structured / experimental | download | lazy async |
187
+
188
+ ## Engineering-Grade On-Demand Renderer Assembly
189
+
190
+ The quickstart flow is: get the component running first, then make the format boundary explicit. Install the component package for the current ecosystem, then choose `@file-viewer/preset-lite`, `@file-viewer/preset-office`, `@file-viewer/preset-engineering`, or `@file-viewer/preset-all`. For Webpack, Rspack, Rollup, Umi, classic multi-page apps, and other non-Vite stacks, pass capability explicitly through `options.preset` or `options.renderers`. The Vite plugin is an optional convenience layer that removes manual imports and copies offline assets.
180
191
 
181
192
  ```bash
182
193
  npm i @file-viewer/web @file-viewer/preset-office
@@ -191,7 +202,7 @@ const options = {
191
202
  }
192
203
  ```
193
204
 
194
- 需要组合办公文档与工程图纸等能力时,继续使用同一个 `preset` 字段传数组即可:
205
+ When a product combines Office documents with engineering drawings, keep the same `preset` field and pass an array:
195
206
 
196
207
  ```ts
197
208
  import officePreset from '@file-viewer/preset-office'
@@ -203,7 +214,7 @@ const options = {
203
214
  }
204
215
  ```
205
216
 
206
- 如果只需要少数格式,也可以安装单 renderer 并传给 `options.renderers`:
217
+ For exact small cuts, install one renderer and pass it through `options.renderers`:
207
218
 
208
219
  ```ts
209
220
  import { pdfRenderer } from '@file-viewer/renderer-pdf'
@@ -214,7 +225,7 @@ const options = {
214
225
  }
215
226
  ```
216
227
 
217
- Vite 项目可以再加插件,插件会免配置发现已安装 preset、注入 virtual module,并按命中格式复制 Worker / WASM / 字体 / vendor 资源:
228
+ Vite projects can add the plugin. It auto-discovers installed presets, injects the virtual module, and copies matching Worker / WASM / font / vendor assets:
218
229
 
219
230
  ```bash
220
231
  npm i -D @file-viewer/vite-plugin
@@ -227,31 +238,31 @@ export default {
227
238
  plugins: [
228
239
  fileViewerRenderers({
229
240
  copyAssets: true
230
- // 无需 preset 配置:插件会自动发现已安装的 @file-viewer/preset-office。
241
+ // No preset option required: the plugin discovers installed @file-viewer/preset-office.
231
242
  })
232
243
  ]
233
244
  }
234
245
  ```
235
246
 
236
- 重度用户需要一次拥有官方 Demo 的完整能力时,直接把 preset 换成全量包;非 Vite 项目继续传 `options.preset`,Vite 配置也保持不变:
247
+ Heavy users that want the complete official demo capability can switch to the full preset. Non-Vite projects keep `options.preset`; the Vite config stays the same:
237
248
 
238
249
  ```bash
239
250
  npm i @file-viewer/web @file-viewer/preset-all
240
251
  ```
241
252
 
242
- 需要自定义装配时,再显式配置插件:
253
+ Use explicit plugin options only when you need customization:
243
254
 
244
255
  ```ts
245
256
  fileViewerRenderers({
246
- preset: 'auto', // 同时开启源码扫描时,仍自动发现已安装 preset
247
- scan: true, // 识别 fileViewerFormats、data-file-viewer-formats、accept
248
- formats: ['pdf'], // 在已安装 preset 之外额外补充精确 renderer
257
+ preset: 'auto', // keep installed preset auto-discovery while scanning source hints
258
+ scan: true, // detects fileViewerFormats, data-file-viewer-formats, and accept
259
+ formats: ['pdf'], // adds exact renderers outside the installed preset
249
260
  copyAssets: true,
250
261
  chunkStrategy: 'renderer'
251
262
  })
252
263
  ```
253
264
 
254
- 严格裁剪或组件库内部测试时,可以关闭自动注入并显式传入 virtual module:
265
+ For strict custom cuts or component-library tests, disable injection and pass the virtual module explicitly:
255
266
 
256
267
  ```ts
257
268
  // vite.config.ts
@@ -259,7 +270,7 @@ fileViewerRenderers({ formats: ['pdf'], inject: false, copyAssets: true })
259
270
  ```
260
271
 
261
272
  ```ts
262
- // 业务组件入口
273
+ // Application viewer entry
263
274
  import { configuredFileViewerRenderers } from 'virtual:file-viewer-renderers'
264
275
 
265
276
  const options = {
@@ -268,79 +279,79 @@ const options = {
268
279
  }
269
280
  ```
270
281
 
271
- - Vue、React、Svelte、jQuery、Vanilla JS / Pure Web 都传同一份 `options`,只是在各自生态中映射为 props、hook、action、plugin 或 `mountViewer(...)` 参数。
272
- - `preset-lite` 面向文本、Markdown、代码、图片和音视频;`preset-office` 面向 PDF / Word / Excel / PowerPoint / OFD;`preset-engineering` 面向 CAD / 3D / 绘图 / XMind / Geo / Typst / EDA / Data。
273
- - 想要最小包体时,可以不用 preset,直接安装 `@file-viewer/renderer-pdf`、`@file-viewer/renderer-word` 等单个 renderer,并通过 `options.renderers` 手动注入。
274
- - `fileViewerRenderers()` 或 `fileViewerRenderers({ copyAssets:true })` 会免配置自动发现已安装 preset;如果同时开启 `scan:true`,请使用 `preset:'auto'` 或 `autoPresets:true` 保留 preset 自动发现。
275
- - `scan:true` 会识别 `fileViewerFormats`、`data-file-viewer-formats` 和上传控件 `accept`,调试与打包时自动选择 renderer。
276
- - `copyAssets:true` 会复制 PDF/CAD/Typst/Archive/Data 等 worker、WASM 和 vendor 资源,满足离线和企业内网部署;压缩包目录会优先使用 `vendor/libarchive/worker-bundle.js` / `libarchive.wasm`,Worker 不可用时只对 ZIP/TAR/GZIP 进入兼容路径。
277
- - `builtinRenderers` 仍可用于高级基线控制或历史兼容;普通快速接入只需要 `preset` / `renderers` 与 `rendererMode`。
278
- - 如果打开的是支持矩阵内但未装配的格式,预览器会提示应安装的 preset / renderer;只有真正不在矩阵中的扩展名才提示不支持。
279
- - `@file-viewer/preset-all` 提供完整 renderer 矩阵;Worker、WASM、字体和 vendor 资源仍需通过 Vite 插件或 `file-viewer-copy-assets` 发布。`*-full` 包已内置该 preset,不要重复安装。
282
+ - Vue, React, Svelte, jQuery, and Vanilla JavaScript / Pure Web all receive the same `options`; each package maps them to native props, hooks, actions, plugins, or `mountViewer(...)` parameters.
283
+ - `preset-lite` covers text, Markdown, code, images, audio, and video; `preset-office` covers PDF / Word / Excel / PowerPoint / OFD; `preset-engineering` covers CAD / 3D / drawing / XMind / Geo / Typst / EDA / Data.
284
+ - For the smallest custom bundle, skip presets, install individual renderers such as `@file-viewer/renderer-pdf` or `@file-viewer/renderer-word`, and pass them through `options.renderers`.
285
+ - `fileViewerRenderers()` or `fileViewerRenderers({ copyAssets:true })` auto-discovers installed presets without explicit configuration. When `scan:true` is also enabled, use `preset:'auto'` or `autoPresets:true` to keep preset auto-discovery.
286
+ - `scan:true` detects `fileViewerFormats`, `data-file-viewer-formats`, and upload `accept` hints so development and production builds select matching renderers automatically.
287
+ - `copyAssets:true` copies PDF/CAD/Typst/Archive/Data workers, WASM, and vendor assets for offline and enterprise intranet deployment; archive directories use `vendor/libarchive/worker-bundle.js` / `libarchive.wasm` first, while the compatibility path only covers ZIP/TAR/GZIP when the Worker cannot start.
288
+ - `builtinRenderers` remains available for advanced baseline control or historical compatibility. Normal quick starts only need `preset` / `renderers` plus `rendererMode`.
289
+ - If a file is in the supported matrix but its renderer is not assembled, the viewer shows the recommended preset / renderer package. Truly unknown extensions still show an unsupported-format state.
290
+ - `@file-viewer/preset-all` provides the published compatibility renderer matrix; Worker, WASM, font, and vendor assets still need to be deployed by the Vite plugin or `file-viewer-copy-assets`. `*-full` packages already include this preset and must not install it again. DICOM and signature containers are later explicit opt-ins.
280
291
 
281
- ## 统一参数与事件
292
+ ## Shared Options And Events
282
293
 
283
- 所有生态组件都围绕同一套 `ViewerMountOptions` 与 `FileViewerOptions` 工作,只是映射到各自框架的 props、事件、ref、action 或插件 API。
294
+ Every ecosystem package uses the same `ViewerMountOptions` and `FileViewerOptions` semantics, mapped to framework-native props, events, refs, actions, or plugin APIs.
284
295
 
285
- | 参数 | 说明 |
296
+ | Option | Description |
286
297
  | --- | --- |
287
- | `url` | 远程文件地址,适合对象存储、业务接口或内网文件服务返回的文件链接。 |
288
- | `file` | `File`、`Blob` 或 `ArrayBuffer`,适合上传、本地选择和业务接口已取回的二进制。 |
289
- | `buffer` | 直接传入 `ArrayBuffer`,适合解密、鉴权或自定义下载后再预览。 |
290
- | `name` / `filename` | 显示文件名并辅助推断扩展名;当 URL 不含扩展名时建议显式传入。 |
291
- | `type` | 显式指定扩展名或 MIME 线索,覆盖自动识别结果。 |
292
- | `size` | 文件大小提示,用于生命周期上下文、加载状态和安全限制展示。 |
293
- | `options` | 完整 `FileViewerOptions`,所有框架包保持同一套参数语义。 |
294
- | `options.styleIsolation` | `auto`、`shadow`、`scoped` 或 `none`。所有标准组件的 `auto` 默认使用 Shadow DOM,阻止宿主全局样式破坏工具栏和正文;旧项目可显式使用 `none`。 |
295
- | `onEvent` / `onStateChange` | Vanilla JS / Pure Web、React、Svelte 等命令式包装层的统一事件和状态订阅;Vue 组件会映射为原生 emit。 |
298
+ | `url` | Remote file URL from object storage, business APIs, or intranet file services. |
299
+ | `file` | `File`, `Blob`, or `ArrayBuffer` for uploads, local selection, or already-fetched binary data. |
300
+ | `buffer` | Direct `ArrayBuffer` input after custom download, authorization, or decryption. |
301
+ | `name` / `filename` | Display name and extension hint. Pass it explicitly when the URL has no useful extension. |
302
+ | `type` | Explicit extension or MIME hint that overrides automatic detection. |
303
+ | `size` | File size hint used in lifecycle context, loading states, and safety limits. |
304
+ | `options` | The shared `FileViewerOptions` surface. Every component package keeps the same semantics. |
305
+ | `options.styleIsolation` | `auto`, `shadow`, `scoped`, or `none`. `auto` uses Shadow DOM for every standard component so host-page global CSS cannot break the toolbar or document; legacy projects can explicitly use `none`. |
306
+ | `onEvent` / `onStateChange` | Unified event and state subscriptions for imperative wrappers such as Vanilla JavaScript / Pure Web, React, and Svelte. Vue maps the same events to native emits. |
296
307
 
297
- ## 实际组件属性
308
+ ## Actual Component Props
298
309
 
299
- 下面列的是每个标准组件包当前真实暴露的属性、事件和控制入口。需要 `buffer`、`name`、`type`、`size` 这类命令式挂载参数时,优先选择 Vanilla JS / Pure Web、React、Svelte、jQuery 或 Vue2 组件;Vue3 声明式组件保持 `url` / `file` / `options` 的简洁入口,复杂二进制来源请包装成带文件名的 `File`。
310
+ The table below lists the real props, event channel, and customization entry for every standard package. If you need imperative mount fields such as `buffer`, `name`, `type`, or `size`, prefer Vanilla JavaScript / Pure Web, React, Svelte, jQuery, or Vue 2. The Vue 3 declarative component intentionally keeps the compact `url` / `file` / `options` entry; wrap raw binary input as a named `File` when extension detection matters.
300
311
 
301
- | 组件 | 实际属性 / 入口 | 事件入口 | 定制入口 |
312
+ | Component | Actual props / entry | Event channel | Customization entry |
302
313
  | --- | --- | --- | --- |
303
- | 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 标签会自动注册元素,同时保留 `mountViewer` 命令式挂载和资源复制 CLI。 |
304
- | 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`、`view-state-change`、`theme-change` | 模板 `ref` 暴露 `FileViewerExpose`;适合声明式接入。`Blob` / `ArrayBuffer` 建议包装成带扩展名的 `File` 后传给 `file`。 |
305
- | Vue 2.7 `@file-viewer/vue2.7` | `url`、`file`、`buffer`、`name`、`filename`、`type`、`size`、`options`、`containerClass`、`containerStyle` | `viewer-event` / `viewerEvent` | 组件实例暴露 controller handle 全量方法;适合 Vue 2.7 项目和历史 `@flyfish-group/file-viewer` 平滑升级。 |
306
- | Vue 2.6 `@file-viewer/vue2.6` | 同 Vue 2.7 | `viewer-event` / `viewerEvent` | 独立 Vue 2.6 构建,不要求业务升级到 Vue 2.7。 |
307
- | React `@file-viewer/react` | `ViewerMountOptions` + `div` 原生属性,如 `className`、`style`、`data-*`、`aria-*` | `onEvent`、`onStateChange` | `ref` 暴露 `FileViewerHandle`;`useFileViewer()` 会返回 `ref`、`props`、`state`、`handle`,便于自定义工具栏。 |
308
- | React Legacy `@file-viewer/react-legacy` | 同 React 标准包 | `onEvent`、`onStateChange` | 面向 React 16.8 / 17;组件名和默认导出保持 legacy 生态友好。 |
309
- | jQuery `@file-viewer/jquery` | `$(el).fileViewer(ViewerMountOptions & { replace?: boolean })` | `onEvent`、`onStateChange` 或 `getFileViewerController(el).subscribe()` | 插件方法支持 `zoomIn`、`printRenderedHtml`、`searchDocument` 等;`replace:false` 可在同一节点上原地更新。 |
310
- | Svelte `@file-viewer/svelte` | `ViewerMountOptions` + `className`、`containerStyle` | `on:viewerEvent`、`onEvent`、`onStateChange` | `bind:this` 暴露 controller handle;也提供 `use:fileViewer` action,action 额外支持 `replace`。 |
311
-
312
- | Options 字段 | 说明 |
314
+ | Vanilla JS / Pure Web `@file-viewer/web` | `<flyfish-file-viewer>` attributes: `src/url`, `filename/name`, `type`, `size`, `theme`, `toolbar`, `toolbar-position`, `watermark`, `search`, `options`; also supports `mountViewer(...)` | `viewer-ready`, `viewer-event`, `viewer-state-change`, `viewer-error`, `onEvent`, `onStateChange`, `controller.subscribe()` | The Custom Element instance exposes the full controller handle; the IIFE script auto-registers it while keeping imperative `mountViewer` and the asset copy CLI. |
315
+ | 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`, `view-state-change`, `theme-change` | Template refs expose `FileViewerExpose`. For `Blob` / `ArrayBuffer`, prefer wrapping it as a named `File` so extension detection stays deterministic. |
316
+ | Vue 2.7 `@file-viewer/vue2.7` | `url`, `file`, `buffer`, `name`, `filename`, `type`, `size`, `options`, `containerClass`, `containerStyle` | `viewer-event` / `viewerEvent` | The component instance exposes the full controller handle. This is the Vue 2.7 line behind the historical `@flyfish-group/file-viewer` package. |
317
+ | Vue 2.6 `@file-viewer/vue2.6` | Same as Vue 2.7 | `viewer-event` / `viewerEvent` | Separate Vue 2.6 build for long-lived applications that cannot move to Vue 2.7. |
318
+ | React `@file-viewer/react` | `ViewerMountOptions` plus native `div` props such as `className`, `style`, `data-*`, and `aria-*` | `onEvent`, `onStateChange` | `ref` exposes `FileViewerHandle`; `useFileViewer()` returns `ref`, `props`, `state`, and `handle` for custom toolbars. |
319
+ | React Legacy `@file-viewer/react-legacy` | Same as the React package | `onEvent`, `onStateChange` | Targets React 16.8 / 17 with a legacy-friendly component export. |
320
+ | jQuery `@file-viewer/jquery` | `$(el).fileViewer(ViewerMountOptions & { replace?: boolean })` | `onEvent`, `onStateChange`, or `getFileViewerController(el).subscribe()` | Plugin methods include `zoomIn`, `printRenderedHtml`, and `searchDocument`; `replace:false` updates the same node in place. |
321
+ | Svelte `@file-viewer/svelte` | `ViewerMountOptions` plus `className` and `containerStyle` | `on:viewerEvent`, `onEvent`, `onStateChange` | `bind:this` exposes the controller handle; the `use:fileViewer` action is also available and adds `replace`. |
322
+
323
+ | Options Field | Description |
313
324
  | --- | --- |
314
- | `theme` | `light`、`dark` 或 `system`,优先级高于浏览器 `prefers-color-scheme`。 |
315
- | `styleIsolation` | `auto`、`shadow`、`scoped` 或 `none`。`auto` 下 Web Component、IIFE、Vue、React、Svelte、jQuery 和 full 包均默认使用 Shadow DOM;依赖深层 class 覆盖的旧项目可显式使用 `none`。 |
316
- | `watermark` | 开启文字或图片水印,可设置透明度、旋转、间距、尺寸、字体和颜色。 |
317
- | `toolbar` | 控制主题切换、下载、打印、HTML 导出、缩放、按钮顺序和工具栏位置,并支持操作级前置校验。 |
318
- | `search` | 配置文档搜索、高亮 class、大小写、整词匹配、最大命中数和 debounce。 |
319
- | `ai` | 控制文本结构采集、分块大小和最大文本长度,为溯源、定位、向量化和外部 AI 流程提供基础。 |
320
- | `archive` | 配置压缩包 Worker/WASM、超时、缓存、包体限制和压缩包内单文件预览大小;旧 ZIP 中文文件名会自动按 GBK/GB18030 兼容解码。 |
321
- | `pdf` | 配置 PDF.js Worker、导航栏、目录、缩略图、旋转、流式读取、Range chunk 和凭据。 |
322
- | `docx` / `spreadsheet` | DOCX 由 @file-viewer/renderer-word 承接并使用自研 @file-viewer/docx,默认自动选择 Worker 或主线程解析,连续流式阅读和异步分批渲染,可按需显式开启视觉分页;表格由 @file-viewer/renderer-spreadsheet 承接,默认保真解析,大文件自动启用 Worker,表头拖拽调列宽可按需显式开启。 |
323
- | `iwork` | 显式安装 iWork capability 后,配置 Pages / Numbers / Keynote 的模块 Worker、超时、ZIP/Snappy/IWA 安全上限与 Quick Look 降级策略;它不属于 standard/full 默认闭包。 |
324
- | `hangul` | 显式安装 Hangul capability 后,配置 HWP/HWPX 模块 Worker、超时、ZIP 解压/压缩率/条目数与 HWP 记录数安全上限;它不属于 standard/full 默认闭包。 |
325
- | `wordPerfect` | 显式安装 WordPerfect capability 后,配置 Worker、libwpd/librevenge WASM 地址与超时;它不属于 standard/full 默认闭包。 |
326
- | `presentation` | standard/full 默认只装配 PPTX/OpenXML 的 `@file-viewer/pptx` Worker,可通过 `workerUrl` / `workerType` 覆盖。PowerPoint 97–2003 `.ppt` 是独立重型 capability,需用 `file-viewer add ppt --write` 显式安装其 Worker/WASM 和资产。 |
327
- | `typst` / `data` / `cad` | 显式安装相应 capability 后,配置 Typst、SQLite、CAD/DWG/DXF/DWF 等 WASM、Worker、编码和渲染策略;这些能力不属于 standard/full 默认闭包。 |
328
- | `hooks` / `beforeOperation` | 统一生命周期 hooks 和操作前置校验,可用于审计、权限、埋点和安全控制。 |
329
-
330
- ## 样式隔离与主题定制
331
-
332
- 所有标准组件默认使用 Shadow DOM 强隔离。宿主页面里的 `*`、`button`、`table`、`img`、`svg`、`canvas` 等全局样式不会直接侵入预览器工具栏和正文;预览器也不会把局部 reset 粗暴写到业务页面。
333
-
334
- | 模式 | 说明 |
325
+ | `theme` | `light`, `dark`, or `system`. This takes precedence over browser `prefers-color-scheme`. |
326
+ | `styleIsolation` | `auto`, `shadow`, `scoped`, or `none`. With `auto`, Web Component, IIFE, Vue, React, Svelte, jQuery, and full packages all use Shadow DOM by default. Legacy integrations that depend on deep class overrides can explicitly use `none`. |
327
+ | `watermark` | Text or image watermark with opacity, rotation, gap, size, font, and color controls. |
328
+ | `toolbar` | Controls the theme toggle, download, print, HTML export, zoom, item order, toolbar position, and operation-level preflight checks. |
329
+ | `search` | Document search, highlight class names, case sensitivity, whole-word matching, max matches, and debounce. |
330
+ | `ai` | Text collection, chunk size, and max text length for provenance, location, vectorization, and external AI workflows. |
331
+ | `archive` | Archive Worker/WASM URLs, timeout, cache, archive limits, nested entry preview limits, and legacy GBK/GB18030 ZIP filename decoding. |
332
+ | `pdf` | PDF.js worker, navigation pane, outline, thumbnails, rotation, streaming, range chunk size, and credentials. |
333
+ | `docx` / `spreadsheet` | DOCX is provided by @file-viewer/renderer-word and uses the self-maintained @file-viewer/docx engine with automatic worker/main-thread selection, continuous flow reading, and async rendering by default; visual pagination is opt-in. Spreadsheet is provided by @file-viewer/renderer-spreadsheet with fidelity-first parsing, automatic Worker use for large files, and opt-in header drag column resizing. |
334
+ | `iwork` | After explicitly installing the iWork capability, configure its Pages / Numbers / Keynote module Worker, timeout, ZIP/Snappy/IWA safety limits, and Quick Look fallback policy. It is not in the standard/full default closure. |
335
+ | `hangul` | After explicitly installing the Hangul capability, configure its HWP/HWPX module Worker, timeout, ZIP limits, and HWP record limits. It is not in the standard/full default closure. |
336
+ | `wordPerfect` | After explicitly installing the WordPerfect capability, configure its Worker, libwpd/librevenge WASM URL, and timeout. It is not in the standard/full default closure. |
337
+ | `presentation` | The standard/full default includes only the PPTX/OpenXML `@file-viewer/pptx` Worker, with optional `workerUrl` / `workerType` overrides. Binary PowerPoint 97–2003 `.ppt` is a separate heavy capability; run `file-viewer add ppt --write` to install its Worker/WASM and assets explicitly. |
338
+ | `typst` / `data` / `cad` | After explicitly installing the matching capability, configure Typst, SQLite, or CAD/DWG/DXF/DWF WASM, worker, encoding, and rendering options. These capabilities are not in the standard/full default closure. |
339
+ | `hooks` / `beforeOperation` | Shared lifecycle hooks and operation preflight checks for audit, permission, telemetry, and safety controls. |
340
+
341
+ ## Style Isolation And Theme Customization
342
+
343
+ Every standard component uses strong Shadow DOM isolation by default. Host-page global rules for `*`, `button`, `table`, `img`, `svg`, `canvas`, and similar selectors should not leak into the viewer toolbar or rendered content, and viewer resets should not pollute the host page.
344
+
345
+ | Mode | Description |
335
346
  | --- | --- |
336
- | `auto` | 默认值。Web Component、IIFE、Vue、React、Svelte、jQuery 和 full 包均走 Shadow DOM,保护工具栏与 renderer 内容不受宿主全局 CSS 影响。 |
337
- | `shadow` | 显式创建 ShadowRoot 作为渲染面,适合宿主 CSS 不可控、微前端混挂、低代码平台和设计系统全局 reset 很强的页面。 |
338
- | `scoped` | 不创建 ShadowRoot,使用稳定根选择器和局部 reset 约束影响范围,适合需要被外层 CSS 轻度继承的场景。 |
339
- | `none` | 历史 light DOM 行为,保留给依赖深度 class 覆盖、旧主题 CSS 或自动化测试快照的项目。 |
347
+ | `auto` | Default. Web Component, IIFE, Vue, React, Svelte, jQuery, and full packages all use Shadow DOM so host-page CSS cannot break the toolbar or renderer content. |
348
+ | `shadow` | Creates an explicit ShadowRoot render surface. Use it when host CSS is uncontrolled, micro-frontends are mixed, low-code platforms inject global resets, or design systems have aggressive base styles. |
349
+ | `scoped` | Does not create a ShadowRoot. Uses a stable root selector and local resets to limit its impact while keeping controlled inheritance from the host. |
350
+ | `none` | Historical light-DOM behavior for projects that depend on deep class overrides, old theme CSS, or snapshot tests. |
340
351
 
341
- `styleIsolation` 是挂载边界配置;运行时切换模式时请重新挂载组件。`scoped` 与 `none` 都属于 Light DOM,仍可能被宿主的高权重或 `!important` 全局规则覆盖。
352
+ `styleIsolation` is a mount-time boundary. Remount the component when changing modes. Both `scoped` and `none` use Light DOM, so high-specificity or `!important` host rules can still override them.
342
353
 
343
- 定制优先级建议是:先使用 `--file-viewer-*` CSS 变量覆盖颜色、字体、间距、圆角、工具栏和按钮;需要命中内部结构时再使用稳定 Shadow Parts。当前 Web shell 暴露 `host`、`shell`、`toolbar`、`toolbar-group`、`toolbar-status`、`button`、`input` 和 `content`,后续 renderer 扩展应继续使用 `state-panel`、`watermark` 这类稳定命名。不要依赖内部 class 名,它们只服务实现细节。
354
+ Customization should start with `--file-viewer-*` CSS variables for color, typography, spacing, radius, toolbar, and button styling. Use stable Shadow Parts only when a specific internal surface needs styling. The current Web shell exposes `host`, `shell`, `toolbar`, `toolbar-group`, `toolbar-status`, `button`, `input`, and `content`; renderer extensions should keep using stable names such as `state-panel` and `watermark`. Do not depend on internal class names; they are implementation details.
344
355
 
345
356
  ```css
346
357
  flyfish-file-viewer {
@@ -360,7 +371,7 @@ flyfish-file-viewer::part(button) {
360
371
  }
361
372
  ```
362
373
 
363
- 框架组件无需额外配置即可使用 Shadow DOM;也可以在 `options` 中显式声明以固定策略:
374
+ Framework packages use Shadow DOM without extra configuration; set it explicitly when you want to lock the policy:
364
375
 
365
376
  ```ts
366
377
  const options = {
@@ -370,94 +381,94 @@ const options = {
370
381
  }
371
382
  ```
372
383
 
373
- ## 工具栏定制
384
+ ## Toolbar Customization
374
385
 
375
- | 配置 | 说明 |
386
+ | Config | Description |
376
387
  | --- | --- |
377
- | `toolbar: false` | 隐藏内置工具栏,但不关闭下载、打印、导出、缩放等 controller API,适合完全自定义业务工具栏。 |
378
- | `toolbar: true` | 使用默认内置工具栏;主题切换默认显示,下载、打印、HTML 导出和缩放按钮按能力动态显隐。 |
379
- | `download` / `print` / `exportHtml` / `zoom` | 表达业务是否允许展示对应按钮;最终仍会结合文件类型、渲染完成状态、导出适配器和缩放 provider 计算真实可用性。 |
380
- | `theme` | 控制浅色/深色切换按钮,默认 `true`;切换后触发 `theme-change`,传 `false` 可隐藏。 |
381
- | `order` | 设置内置分组顺序,可使用 `search`、`zoom`、`download`、`print`、`exportHtml`、`theme`;遗漏项保持默认相对顺序。 |
382
- | `position` | `auto`、`top`、`top-center`、`bottom-right`。默认 `auto`,PDF 自动悬浮右下角,其他格式保持顶部靠右;需要顶部水平居中时传 `top-center`。 |
383
- | `beforeOperation` | 工具栏层统一前置校验,会在 `options.beforeOperation` 后执行。返回 `false` 或抛错都会取消本次操作。 |
384
- | `beforeDownload` / `beforePrint` / `beforeExportHtml` | 单按钮前置校验;适合下载权限、打印审计、导出水印确认等细粒度业务规则。 |
388
+ | `toolbar: false` | Hides the built-in toolbar without disabling controller APIs such as download, print, export, and zoom. Use this for a fully custom business toolbar. |
389
+ | `toolbar: true` | Uses the default built-in toolbar. The theme toggle is visible by default; download, print, HTML export, and zoom remain capability-aware. |
390
+ | `download` / `print` / `exportHtml` / `zoom` | Expresses whether the host allows a button. Final availability is still computed from file type, render readiness, export adapter, and zoom provider state. |
391
+ | `theme` | Controls the light/dark toggle and defaults to `true`. A change emits `theme-change`; set it to `false` to hide the button. |
392
+ | `order` | Orders built-in groups with `search`, `zoom`, `download`, `print`, `exportHtml`, and `theme`. Omitted items keep their default relative order. |
393
+ | `position` | `auto`, `top`, `top-center`, or `bottom-right`. The default `auto` floats PDF actions at bottom right and keeps other formats top-right; use `top-center` for a centered top toolbar. |
394
+ | `beforeOperation` | Toolbar-level preflight that runs after `options.beforeOperation`. Returning `false` or throwing cancels the operation. |
395
+ | `beforeDownload` / `beforePrint` / `beforeExportHtml` | Operation-specific preflight for download permission, print audit, export confirmation, and similar business rules. |
385
396
 
386
- 完全自定义工具栏时,推荐关闭内置工具栏并使用组件 ref / controller 暴露的标准 API。不要在预览器外层用 CSS `transform: scale()` 做缩放;PDF、Excel、CAD、canvas 和文本层格式都应通过内部缩放 provider 保持坐标正确。
397
+ For fully custom toolbars, hide the built-in toolbar and call the standard ref / controller APIs from your own UI. Do not implement zoom with an outer CSS `transform: scale()`; PDF, Excel, CAD, canvas-based, and text-layer renderers should use their internal zoom providers to keep coordinates correct.
387
398
 
388
- 缩放状态由各格式 renderer 的内部 provider 上报。首屏自适应、容器尺寸变化或 PDF / Word / 图片等异步布局完成后,内置工具栏会显示真实缩放比例,而不是固定显示 `100%`;自定义工具栏也应监听 `zoom-change` / `operation-availability-change`,或读取 `getZoomState()` / `getOperationAvailability()`。
399
+ Zoom state is reported by each renderer provider. After first-screen fit, container resize, or asynchronous PDF / Word / image layout, built-in toolbars show the real scale instead of assuming `100%`. Custom toolbars should listen to `zoom-change` / `operation-availability-change`, or read `getZoomState()` / `getOperationAvailability()`.
389
400
 
390
- 视图状态同步用于投屏、双端协同和恢复阅读进度。所有标准 renderer loader 都会获得通用 view-state provider,至少记录 `renderer`、缩放和滚动位置;PDF、XMind、Geo、3D、CAD 等高交互路径会补充页码、导航、画布 pan、地图中心、相机视角或底层视图快照。初始化可传 `options.initialViewState`,运行中监听 `view-state-change`;Pure Web / Vue3 controller 还可直接调用 `getViewState()` 与 `applyViewState(state, { source: "api", action: "restore" })`。
401
+ View-state sync is designed for projection systems, remote-control displays, side-by-side review, and reading-position restore. Every standard renderer loader gets a generic view-state provider that records at least `renderer`, zoom, and scroll position; PDF, XMind, Geo, 3D, and CAD add page, navigation, canvas pan, map center, camera, or native view snapshots. Pass `options.initialViewState` for first render, listen to `view-state-change` while running, and use `getViewState()` / `applyViewState(state, { source: "api", action: "restore" })` on Pure Web / Vue3 controllers when an imperative restore API is needed.
391
402
 
392
- | 生态 | 推荐方式 |
403
+ | Ecosystem | Recommended pattern |
393
404
  | --- | --- |
394
- | Vanilla JS / Pure Web | `<flyfish-file-viewer toolbar="false">` 或 `mountViewer(container, { options:{ toolbar:false }, onStateChange })`;外部 DOM 按钮可直接调用元素实例 / controller 的 `zoomIn()`、`printRenderedHtml()`、`searchDocument()` 等方法,复杂场景用 `viewer-state-change` 或 `controller.subscribe()` 同步状态。 |
395
- | Vue 3 | 传 `:options="{ toolbar: false }"` 隐藏内置工具栏,通过模板 `ref` 调用 `downloadOriginalFile()`、`printRenderedHtml()`、`exportRenderedHtml()`、`zoomIn()`、`zoomOut()`、`resetZoom()`;用 `@operation-availability-change` 和 `@zoom-change` 同步按钮显隐与比例。 |
396
- | Vue 2.7 / 2.6 | 同样设置 `toolbar:false`,通过 `$refs.viewer` 调用实例方法;监听 `@viewer-event`,在 `event.type === "operation-availability-change"` 或 `event.type === "zoom-change"` 时更新外部工具栏。 |
397
- | React / React Legacy | 推荐 `useFileViewer({ options:{ toolbar:false } })`,把 `viewer.props` 传给组件,把按钮绑定到 `viewer.handle`,并读取 `viewer.state.availability` / `viewer.state.zoom` 控制禁用状态。 |
398
- | jQuery | `$("#viewer").fileViewer({ options:{ toolbar:false } })`;按钮调用 `$("#viewer").fileViewer("zoomIn")` 或通过 `getFileViewerController($("#viewer")).subscribe()` 获取能力状态。 |
399
- | Svelte | `<FileViewer bind:this={viewer} options={{ toolbar:false }} />`;按钮直接调用 `viewer.zoomIn()`、`viewer.printRenderedHtml()`,并用 `on:viewerEvent` / `onStateChange` 同步状态。 |
405
+ | Vanilla JS / Pure Web | Use `<flyfish-file-viewer toolbar="false">` or `mountViewer(container, { options:{ toolbar:false }, onStateChange })`; custom DOM buttons can call `zoomIn()`, `printRenderedHtml()`, `searchDocument()`, and other element / controller methods directly. Use `viewer-state-change` or `controller.subscribe()` for advanced state sync. |
406
+ | Vue 3 | Pass `:options="{ toolbar: false }"`, call `downloadOriginalFile()`, `printRenderedHtml()`, `exportRenderedHtml()`, `zoomIn()`, `zoomOut()`, and `resetZoom()` through the template ref, and sync buttons with `@operation-availability-change` plus `@zoom-change`. |
407
+ | Vue 2.7 / 2.6 | Use `toolbar:false`, call instance methods through `$refs.viewer`, and listen to `@viewer-event` for `operation-availability-change` or `zoom-change`. |
408
+ | React / React Legacy | Prefer `useFileViewer({ options:{ toolbar:false } })`; pass `viewer.props` to the component, bind custom buttons to `viewer.handle`, and read `viewer.state.availability` / `viewer.state.zoom`. |
409
+ | jQuery | Use `$("#viewer").fileViewer({ options:{ toolbar:false } })`; buttons can call `$("#viewer").fileViewer("zoomIn")` or read capability state through `getFileViewerController($("#viewer")).subscribe()`. |
410
+ | Svelte | Use `<FileViewer bind:this={viewer} options={{ toolbar:false }} />`; buttons call `viewer.zoomIn()` / `viewer.printRenderedHtml()`, with `on:viewerEvent` or `onStateChange` for state sync. |
400
411
 
401
- ## 生命周期与操作事件
412
+ ## Lifecycle And Operation Events
402
413
 
403
- | 事件 / hook | 说明 |
414
+ | Event / hook | Description |
404
415
  | --- | --- |
405
- | `load-start` / `hooks.onLoadStart` | 开始解析或下载文档时触发,包含文件名、类型、来源、版本、URL、File 和 size。 |
406
- | `load-complete` / `hooks.onLoadComplete` | 当前文档完成渲染时触发,包含耗时、来源上下文和版本号。 |
407
- | `unload-start` / `hooks.onUnloadStart` | 替换、重置或组件卸载前触发,可用于保存状态或释放外部资源。 |
408
- | `unload-complete` / `hooks.onUnloadComplete` | 旧文档释放完成后触发,reason 会标识 `replace`、`reset` 或 `component-unmount`。 |
409
- | `operation-before` / `operation-cancel` | 下载、打印、HTML 导出和缩放前后触发;`beforeOperation` 返回 `false` 可取消操作。 |
410
- | `operation-availability-change` | 当前格式是否可下载、可打印、可导出 HTML、可缩放发生变化时触发。 |
411
- | `theme-change` | 用户通过内置按钮切换浅色或深色模式时触发,payload 为 `light` 或 `dark`。 |
412
- | `search-change` / `location-change` / `zoom-change` / `view-state-change` | 搜索命中、定位锚点、缩放状态和完整视图快照变化时触发,用于外层同步 UI、投屏或恢复阅读进度。 |
413
-
414
- ## 公共操作 API
415
-
416
- | API | 说明 |
416
+ | `load-start` / `hooks.onLoadStart` | Fires when parsing or downloading starts. Context includes filename, type, source, version, URL, File, and size. |
417
+ | `load-complete` / `hooks.onLoadComplete` | Fires when the current document has rendered. Context includes duration, source data, and version. |
418
+ | `unload-start` / `hooks.onUnloadStart` | Fires before replace, reset, or component unmount so external state or resources can be saved. |
419
+ | `unload-complete` / `hooks.onUnloadComplete` | Fires after the previous document is released. The reason is `replace`, `reset`, or `component-unmount`. |
420
+ | `operation-before` / `operation-cancel` | Fires around download, print, HTML export, and zoom actions. Returning `false` from `beforeOperation` cancels the action. |
421
+ | `operation-availability-change` | Fires when download, print, HTML export, or zoom support changes for the active format. |
422
+ | `theme-change` | Fires when the built-in control selects light or dark mode. The payload is `light` or `dark`. |
423
+ | `search-change` / `location-change` / `zoom-change` / `view-state-change` | Fires when search matches, document anchors, zoom state, or full view-state snapshots change so host UIs, display screens, and reading-position restore flows can stay in sync. |
424
+
425
+ ## Public Operation API
426
+
427
+ | API | Description |
417
428
  | --- | --- |
418
- | `load` / `update` / `reload` / `destroy` | 命令式控制文档加载、参数更新、重新加载和销毁。 |
419
- | `downloadOriginalFile()` | 下载原始文件,遵循 toolbar 与 `beforeOperation` 权限校验。 |
420
- | `printRenderedHtml(options?)` | 打印当前完整渲染内容,优先使用各格式的高保真打印适配器;开启水印时会一并输出,也可传入 `mask` 遮盖区域。 |
421
- | `printWithMask(options?)` | 打开掩膜设计器拖拽黑色遮盖块,确认后打印;设计器由 core 异步加载,组件开箱即用。 |
422
- | `exportRenderedHtml()` | 导出当前渲染后的 HTML,用于归档、审计和离线查看。 |
423
- | `zoomIn()` / `zoomOut()` / `resetZoom()` | 调用当前格式自己的缩放 provider,避免外层 CSS 缩放导致坐标偏移。 |
424
- | `searchDocument()` / `nextSearchResult()` / `previousSearchResult()` | 打开文档级搜索并在命中之间导航,保持高亮状态。 |
425
- | `collectDocumentAnchors()` / `scrollToAnchor()` / `scrollToLine()` | 采集页面、目录、标题或代码行锚点,并执行定位跳转。 |
426
- | `getDocumentTextChunks()` | 获取结构化文本块,便于搜索、AI 溯源、向量化和外部索引。 |
427
- | `getOperationAvailability()` / `getZoomState()` / `getSearchState()` | 读取当前能力、缩放和搜索状态,便于自定义工具栏。 |
428
-
429
- ## Worker、WASM 与私有化部署
430
-
431
- | 资源 | 说明 |
429
+ | `load` / `update` / `reload` / `destroy` | Imperatively load, update, reload, and destroy the viewer. |
430
+ | `downloadOriginalFile()` | Downloads the original file while respecting toolbar and `beforeOperation` checks. |
431
+ | `printRenderedHtml(options?)` | Prints the complete rendered document using the best available per-format print adapter. Enabled watermarks are included; pass `mask` for cover regions. |
432
+ | `printWithMask(options?)` | Opens the black-cover mask designer, then prints. The designer is async-loaded inside core and works out of the box with component packages. |
433
+ | `exportRenderedHtml()` | Exports rendered HTML for archiving, audit, or offline review. |
434
+ | `zoomIn()` / `zoomOut()` / `resetZoom()` | Uses the active renderer zoom provider instead of outer CSS transforms that can break coordinates. |
435
+ | `searchDocument()` / `nextSearchResult()` / `previousSearchResult()` | Runs document-level search and navigates highlighted matches. |
436
+ | `collectDocumentAnchors()` / `scrollToAnchor()` / `scrollToLine()` | Collects pages, outline items, headings, or code-line anchors and scrolls to them. |
437
+ | `getDocumentTextChunks()` | Returns structured text chunks for search, AI provenance, vectorization, and external indexes. |
438
+ | `getOperationAvailability()` / `getZoomState()` / `getSearchState()` | Reads current capability, zoom, and search state for custom toolbars. |
439
+
440
+ ## Workers, WASM, And Private Deployment
441
+
442
+ | Asset | Description |
432
443
  | --- | --- |
433
- | Standard 资产 | `@file-viewer/assets-standard` 只复制 PDF、DOCX、PPTX、Excel/OpenXML 与 Archive 等冻结 standard 所需 Worker、WASM、字体和 vendor 文件;事务收据记录包版本、profile hash、逐文件 SHA-256 和 owner。 |
434
- | 专用资产 owner | CAD、Typst、iWork、3D、Data、Drawing、Hangul、WordPerfect 和旧版 PPT 各自使用独立 `@file-viewer/assets-*` 包。`@file-viewer/cli add <format> --write` 只选择该能力及其资产,不下载旁系格式。 |
435
- | PDF / DOCX / Excel / PPTX | standard 支持自托管 PDF.js Worker/字体、DOCX Worker、Spreadsheet Worker 与 PPTX Worker。PPTX 图表和 PDF Identity-font repair 属于正确性能力,已明确纳入 standard;不会静默省略图表或字体修复。 |
436
- | Archive / Email / 原生媒体 | Archive 的 libarchive Worker/WASM 属于 standard 资产;Email、常见图片和浏览器原生音视频按需加载代码。HLS、MIDI、RTF、Mermaid、patch/git bundle 是显式 capability,不会因 npm peer 自动安装。 |
437
- | Draw.io | 安全自研 Drawing fallback 随 renderer 提供;diagrams.net official viewer 是独立 `drawio-official` 重型 capability,不进入新项目的 standard 默认闭包。历史 `*-full` 包的已发布能力边界保持兼容。 |
438
- | 离线部署 | 运行时不依赖公共 CDN。Vite `copyAssets:true` 按已安装 asset owner 发布;其它构建工具运行 `file-viewer install --yes` 或 `file-viewer assets --write`。所有 owner 事务性合并为稳定运行时 manifest,安装顺序不影响结果。 |
439
- | 部署原则 | 新格式默认 opt-in,不会自动扩张已发布的 `*-full` 包。只有命中特定格式时才加载对应 Worker、WASM 或解析库;新项目优先使用 standard 或按需 capability,历史 full 集成继续保留原能力矩阵。 |
444
+ | Standard assets | `@file-viewer/assets-standard` copies only the workers, WASM, fonts, and vendor files required by the frozen standard profile: PDF, DOCX, PPTX, spreadsheet/OpenXML, and archives. Its transactional receipt records package version, profile hash, per-file SHA-256, and ownership. |
445
+ | Specialist asset owners | CAD, Typst, iWork, 3D, Data, Drawing, Hangul, WordPerfect, and legacy PPT each use an independent `@file-viewer/assets-*` package. `@file-viewer/cli add <format> --write` selects only that capability and its assets. |
446
+ | PDF / DOCX / Excel / PPTX | Standard self-hosts the PDF.js worker/fonts, DOCX worker, spreadsheet worker, and PPTX worker. PPTX charts and PDF Identity-font repair are explicit standard correctness capabilities, so charts and font repair are never silently omitted. |
447
+ | Archive / email / native media | The archive libarchive Worker/WASM is in standard assets. Email, common images, and browser-native media use lazy-loaded code. HLS, MIDI, RTF, Mermaid, patch, and git bundle remain explicit capabilities and are not auto-installed as npm peers. |
448
+ | Draw.io | The safe project-maintained Drawing fallback ships with its renderer. The official diagrams.net viewer is a separate heavy `drawio-official` capability and is not in the standard profile for new projects. The published capability boundary of historical `*-full` packages remains compatible. |
449
+ | Offline deployment | Runtime code does not use public CDNs. Vite `copyAssets:true` publishes installed asset owners; other tools use `file-viewer install --yes` or `file-viewer assets --write`. Owners merge transactionally into one deterministic runtime manifest independent of install order. |
450
+ | Deployment principle | New formats are opt-in by default and never expand an already published `*-full` package automatically. Specialist workers, WASM, and parsers load only when their format is used. New projects should prefer standard or selected capabilities; historical full integrations retain their existing matrix. |
440
451
 
441
452
 
442
- ## 质量门禁
453
+ ## Quality Gates
443
454
 
444
- - 组件包只依赖 `@file-viewer/core` 和自身生态依赖,不嵌套引用其他框架组件包。
445
- - 格式解析、搜索、缩放、打印、导出、水印、生命周期和 beforeOperation 语义全部来自同一个 core。
446
- - 发布前需通过类型检查、组件 API 校验、README 生成校验、格式矩阵校验、独立仓库导出和浏览器 smoke。
455
+ - Component packages only depend on `@file-viewer/core` and their own ecosystem dependencies. They do not nest through another framework component package.
456
+ - Format parsing, search, zoom, print, export, watermark, lifecycle, and beforeOperation semantics all come from the same core.
457
+ - Releases should pass type checks, component API verification, README generation checks, format-matrix verification, standalone repository export, and browser smoke tests.
447
458
 
448
- 完整参数、生命周期 hooks、beforeOperation、主题、水印、搜索、缩放、打印和导出说明见官方文档: https://doc.file-viewer.app/
459
+ See the official documentation for options, lifecycle hooks, beforeOperation, theme, watermark, search, zoom, print, and export APIs: https://doc.file-viewer.app/
449
460
 
450
- 在线 Demo: https://demo.file-viewer.app/ 。File Viewer 自身源码与本仓生成的组件包使用 Apache-2.0;发行物若包含 `@file-viewer/ppt` 运行时,该运行时保留其独立 LICENSE 与 NOTICE,不被 Apache-2.0 重新许可。二开或商用请保留 Flyfish Viewer 来源说明;如果修复了通用兼容问题,也欢迎贡献回对应组件仓库。
461
+ Online demo: https://demo.file-viewer.app/. File Viewer-authored source and component packages generated by this repository use Apache-2.0. Any distribution that includes the `@file-viewer/ppt` runtime retains its independent LICENSE and NOTICE and does not relicense it under Apache-2.0. For derivative or commercial use, keep clear Flyfish Viewer attribution; shared compatibility fixes are welcome in the matching component repository.
451
462
  <!-- FILE_VIEWER_GENERATED:END -->
452
463
 
453
- ## 格式与相关包
464
+ ## Formats and related packages
454
465
 
455
- File Viewer 在浏览器内预览 275+ 种扩展名,覆盖 Office、PDF/OFD、CAD、3D、压缩包、邮件、图片、音视频和代码,无需服务端转码;完整清单见 [格式矩阵](https://doc.file-viewer.app/guide/formats)。
466
+ File Viewer previews 275+ file extensions in the browser, covering Office, PDF/OFD, CAD, 3D, archives, email, images, media and code, without server-side conversion. See the [format matrix](https://doc.file-viewer.app/guide/formats) for the full list.
456
467
 
457
- - 组件:`@file-viewer/web`、`@file-viewer/vue3`、`@file-viewer/vue2.7`、`@file-viewer/vue2.6`、`@file-viewer/react`、`@file-viewer/react-legacy`、`@file-viewer/svelte`、`@file-viewer/jquery`,以及对应的 `-full` 包
458
- - 能力组合:`@file-viewer/preset-lite`、`@file-viewer/preset-office`、`@file-viewer/preset-engineering`、`@file-viewer/preset-all`
459
- - 构建:`@file-viewer/vite-plugin`、`file-viewer-copy-assets`
468
+ - Components: `@file-viewer/web`, `@file-viewer/vue3`, `@file-viewer/vue2.7`, `@file-viewer/vue2.6`, `@file-viewer/react`, `@file-viewer/react-legacy`, `@file-viewer/svelte`, `@file-viewer/jquery`, plus their `-full` packages
469
+ - Presets: `@file-viewer/preset-lite`, `@file-viewer/preset-office`, `@file-viewer/preset-engineering`, `@file-viewer/preset-all`
470
+ - Build: `@file-viewer/vite-plugin`, `file-viewer-copy-assets`
460
471
 
461
- ## 许可证
472
+ ## License
462
473
 
463
- 本包采用 Apache-2.0。详见 [LICENSE](https://github.com/flyfish-dev/file-viewer/blob/main/LICENSE)。
474
+ This package is Apache-2.0. See [LICENSE](https://github.com/flyfish-dev/file-viewer/blob/main/LICENSE).