@file-viewer/web 3.2.2 → 3.3.0
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.en.md +3 -1
- package/README.md +237 -234
- package/README.zh-CN.md +465 -0
- package/dist/THIRD_PARTY_LICENSES.txt +1 -1
- package/dist/flyfish-file-viewer-web.amd.js +23 -23
- package/dist/flyfish-file-viewer-web.iife.js +23 -23
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
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
|
+
|
|
3
5
|
<!-- FILE_VIEWER_PACKAGE_HEADER -->
|
|
4
6
|
<p>
|
|
5
7
|
<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,16 +11,16 @@
|
|
|
9
11
|
</p>
|
|
10
12
|
|
|
11
13
|
<p>
|
|
12
|
-
<a href="https://github.com/flyfish-dev/file-viewer">GitHub</a> · <a href="https://doc.file-viewer.app/
|
|
14
|
+
<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
15
|
</p>
|
|
14
16
|
|
|
15
17
|
<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-
|
|
18
|
+
<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
19
|
</p>
|
|
18
20
|
|
|
19
|
-
> ⭐
|
|
21
|
+
> ⭐ If File Viewer helps you, please [star the repo on GitHub](https://github.com/flyfish-dev/file-viewer).
|
|
20
22
|
|
|
21
|
-
|
|
23
|
+
The standard pure web native component package for Flyfish File Viewer. It ships the `<flyfish-file-viewer>` Web Component, imperative `mountViewer` controller, IIFE global bundle, and asset-copy CLI for legacy admin pages, script-tag usage, micro-frontends, and framework-free systems.
|
|
22
24
|
|
|
23
25
|
```bash
|
|
24
26
|
npm install @file-viewer/web
|
|
@@ -46,13 +48,13 @@ viewer.addEventListener('viewer-event', event => {
|
|
|
46
48
|
viewer.zoomIn()
|
|
47
49
|
```
|
|
48
50
|
|
|
49
|
-
|
|
51
|
+
Use `mountViewer(container, options)` when you need a fully imperative controller.
|
|
50
52
|
|
|
51
|
-
##
|
|
53
|
+
## Style Isolation And Customization
|
|
52
54
|
|
|
53
|
-
`<flyfish-file-viewer>`
|
|
55
|
+
`<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
56
|
|
|
55
|
-
|
|
57
|
+
Use CSS variables and Shadow Parts for controlled customization:
|
|
56
58
|
|
|
57
59
|
```css
|
|
58
60
|
flyfish-file-viewer {
|
|
@@ -65,15 +67,15 @@ flyfish-file-viewer::part(toolbar) {
|
|
|
65
67
|
}
|
|
66
68
|
```
|
|
67
69
|
|
|
68
|
-
|
|
70
|
+
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
71
|
|
|
70
|
-
|
|
72
|
+
Use the asset copy command when you need to self-host workers, WASM files, and static examples:
|
|
71
73
|
|
|
72
74
|
```bash
|
|
73
75
|
npx --yes file-viewer-copy-assets ./public/file-viewer
|
|
74
76
|
```
|
|
75
77
|
|
|
76
|
-
|
|
78
|
+
No-build or legacy admin pages can copy `dist/flyfish-file-viewer-web.iife.js` and load it through a plain script tag:
|
|
77
79
|
|
|
78
80
|
```html
|
|
79
81
|
<script src="/vendor/file-viewer-web/flyfish-file-viewer-web.iife.js"></script>
|
|
@@ -84,99 +86,100 @@ npx --yes file-viewer-copy-assets ./public/file-viewer
|
|
|
84
86
|
></flyfish-file-viewer>
|
|
85
87
|
```
|
|
86
88
|
|
|
87
|
-
|
|
89
|
+
The historical package `@flyfish-group/file-viewer-web` remains supported for compatibility. New integrations should prefer the standard package `@file-viewer/web`.
|
|
88
90
|
|
|
89
|
-
##
|
|
91
|
+
## Capabilities
|
|
90
92
|
|
|
91
|
-
`@file-viewer/web`
|
|
93
|
+
`@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
94
|
|
|
93
95
|
## RequireJS
|
|
94
96
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
97
|
+
From 3.0.3, `dist/flyfish-file-viewer-web.amd.js` exports the light shell API as AMD,
|
|
98
|
+
without format renderers. For document preview without a bundler, use the
|
|
99
|
+
`@file-viewer/web-full` AMD entry and deploy its complete `dist/`.
|
|
100
|
+
[Integration example](https://doc.file-viewer.app/guide/quickstart-web#requirejs-amd).
|
|
98
101
|
|
|
99
102
|
<!-- FILE_VIEWER_GENERATED:START -->
|
|
100
|
-
##
|
|
103
|
+
## Ecosystem Matrix
|
|
101
104
|
|
|
102
|
-
|
|
105
|
+
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
106
|
|
|
104
|
-
|
|
|
107
|
+
| Framework | Standard npm package | Entrypoints | GitHub | Gitee | Historical aliases |
|
|
105
108
|
| --- | --- | --- | --- | --- | --- |
|
|
106
|
-
| Vanilla JS / Pure Web | `@file-viewer/web` | ESM,
|
|
107
|
-
| Vanilla JS / Pure Web Full | `@file-viewer/web-full` | ESM,
|
|
108
|
-
| Vue 3 | `@file-viewer/vue3` | ESM,
|
|
109
|
-
| Vue 3 Full | `@file-viewer/vue3-full` | ESM,
|
|
110
|
-
| Vue 2.7 | `@file-viewer/vue2.7` | ESM,
|
|
111
|
-
| Vue 2.7 Full | `@file-viewer/vue2.7-full` | ESM,
|
|
112
|
-
| Vue 2.6 | `@file-viewer/vue2.6` | ESM,
|
|
113
|
-
| Vue 2.6 Full | `@file-viewer/vue2.6-full` | ESM,
|
|
114
|
-
| React 18/19 | `@file-viewer/react` | ESM,
|
|
115
|
-
| React 18/19 Full | `@file-viewer/react-full` | ESM,
|
|
116
|
-
| React 16.8/17 | `@file-viewer/react-legacy` | ESM,
|
|
117
|
-
| React 16.8/17 Full | `@file-viewer/react-legacy-full` | ESM,
|
|
118
|
-
| jQuery | `@file-viewer/jquery` | ESM,
|
|
119
|
-
| jQuery Full | `@file-viewer/jquery-full` | ESM,
|
|
120
|
-
| Svelte | `@file-viewer/svelte` | Svelte
|
|
121
|
-
| Svelte Full | `@file-viewer/svelte-full` | Svelte
|
|
122
|
-
|
|
123
|
-
##
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
|
109
|
+
| 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` |
|
|
110
|
+
| 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 |
|
|
111
|
+
| 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` |
|
|
112
|
+
| 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 |
|
|
113
|
+
| 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` |
|
|
114
|
+
| 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 |
|
|
115
|
+
| 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 |
|
|
116
|
+
| 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 |
|
|
117
|
+
| 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` |
|
|
118
|
+
| 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 |
|
|
119
|
+
| 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 |
|
|
120
|
+
| 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 |
|
|
121
|
+
| 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 |
|
|
122
|
+
| 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 |
|
|
123
|
+
| 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 |
|
|
124
|
+
| 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 |
|
|
125
|
+
|
|
126
|
+
## Format Support Matrix
|
|
127
|
+
|
|
128
|
+
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.
|
|
129
|
+
|
|
130
|
+
| Preview pipeline | Category | Extensions | Level / status | Capabilities | Loading |
|
|
128
131
|
| --- | --- | --- | --- | --- | --- |
|
|
129
|
-
| Word OpenXML | office | `.docx`, `.docm`, `.dotx`, `.dotm` | high-fidelity / stable |
|
|
130
|
-
| Word Binary | office | `.doc`, `.dot` | structured / stable |
|
|
131
|
-
| PowerPoint 97–2003 | office | `.ppt`, `.pot` | structured / stable |
|
|
132
|
-
| PowerPoint OpenXML | office | `.pptx`, `.pptm`, `.potx`, `.potm`, `.ppsx`, `.ppsm` | high-fidelity / stable |
|
|
133
|
-
| Open Document | office | `.rtf`, `.odt`, `.odp` | structured / stable |
|
|
134
|
-
| Spreadsheet | office | `.xlsx`, `.xltx`, `.xlsm`, `.xlsb`, `.xls`, `.xlt`, `.xla`, `.xlam`, `.xltm`, `.csv`, `.tsv`, `.ods`, `.fods` | structured / stable |
|
|
135
|
-
| Apple Pages | office | `.pages` | high-fidelity / stable |
|
|
136
|
-
| Apple Numbers | office | `.numbers` | high-fidelity / stable |
|
|
137
|
-
| Apple Keynote | office | `.key` | high-fidelity / stable |
|
|
138
|
-
| WordPerfect | office | `.wpd`, `.wp`, `.wp5`, `.wp6` | structured / stable |
|
|
139
|
-
| dBASE Table | office | `.dbf` | structured / stable |
|
|
140
|
-
| PDF | document | `.pdf` | high-fidelity / stable |
|
|
141
|
-
| OFD | document | `.ofd` | structured / stable |
|
|
142
|
-
| Hancom Hangul | office | `.hwp`, `.hwpx` | structured / stable |
|
|
143
|
-
| Typst | document | `.typ`, `.typst` | high-fidelity / stable |
|
|
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 |
|
|
146
|
-
| Email | email | `.eml`, `.msg`, `.mbox` | structured / stable |
|
|
147
|
-
| EDA | eda | `.olb`, `.dra`, `.gds`, `.oas`, `.oasis` | structured / stable |
|
|
148
|
-
| CAD | cad | `.dxf`, `.dwg`, `.dwf`, `.dwfx`, `.xps` | high-fidelity / stable |
|
|
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 |
|
|
150
|
-
| Geospatial | geo | `.geojson`, `.kml`, `.gpx`, `.shp` | structured / stable |
|
|
151
|
-
| Drawing | drawing | `.excalidraw`, `.drawio`, `.dio`, `.mermaid`, `.mmd`, `.plantuml`, `.puml` | structured / stable |
|
|
152
|
-
| BPMN 2.0 | drawing | `.bpmn` | structured / experimental |
|
|
153
|
-
| Mind Map | mindmap | `.xmind` | structured / stable |
|
|
154
|
-
| EPUB | ebook | `.epub` | high-fidelity / stable |
|
|
155
|
-
| FictionBook | ebook | `.fb2` | structured / stable |
|
|
156
|
-
| UMD | ebook | `.umd` | structured / stable |
|
|
157
|
-
| Image | image | `.gif`, `.jpg`, `.jpeg`, `.bmp`, `.tiff`, `.tif`, `.png`, `.svg`, `.webp`, `.avif`, `.ico`, `.heic`, `.heif`, `.jxl` | high-fidelity / stable |
|
|
158
|
-
| DICOM | medical-image | `.dcm`, `.dicom` | basic / experimental |
|
|
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 |
|
|
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 |
|
|
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
|
|
165
|
-
| Adobe Illustrator AI/AIT | asset | `.ait`, `.ai
|
|
166
|
-
| Adobe InDesign IDML | asset | `.idml` | experimental / experimental |
|
|
167
|
-
| Adobe InCopy and InDesign Exchange | asset | `.icml`, `.idms`, `.inx` | structured / experimental |
|
|
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
|
|
172
|
-
| Adobe Color Palettes | asset | `.ase`, `.aco` | structured / stable |
|
|
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 |
|
|
175
|
-
| Binary Inspector | asset | `.bin`, `.hex`, `.elf`, `.exe`, `.dll`, `.class`, `.macho` | structured / experimental |
|
|
176
|
-
|
|
177
|
-
##
|
|
178
|
-
|
|
179
|
-
|
|
132
|
+
| Word OpenXML | office | `.docx`, `.docm`, `.dotx`, `.dotm` | high-fidelity / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
|
|
133
|
+
| Word Binary | office | `.doc`, `.dot` | structured / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
|
|
134
|
+
| PowerPoint 97–2003 | office | `.ppt`, `.pot` | structured / stable | download, print(adapter), HTML export(adapter), zoom(provider) | lazy async |
|
|
135
|
+
| PowerPoint OpenXML | office | `.pptx`, `.pptm`, `.potx`, `.potm`, `.ppsx`, `.ppsm` | high-fidelity / stable | download, print, HTML export, zoom(provider), search | lazy async |
|
|
136
|
+
| Open Document | office | `.rtf`, `.odt`, `.odp` | structured / stable | download, print, HTML export, zoom(provider), search | lazy async |
|
|
137
|
+
| Spreadsheet | office | `.xlsx`, `.xltx`, `.xlsm`, `.xlsb`, `.xls`, `.xlt`, `.xla`, `.xlam`, `.xltm`, `.csv`, `.tsv`, `.ods`, `.fods` | structured / stable | download, zoom(provider), search | lazy async |
|
|
138
|
+
| Apple Pages | office | `.pages` | high-fidelity / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
|
|
139
|
+
| Apple Numbers | office | `.numbers` | high-fidelity / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
|
|
140
|
+
| Apple Keynote | office | `.key` | high-fidelity / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
|
|
141
|
+
| WordPerfect | office | `.wpd`, `.wp`, `.wp5`, `.wp6` | structured / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
|
|
142
|
+
| dBASE Table | office | `.dbf` | structured / stable | download, zoom(provider), search | lazy async |
|
|
143
|
+
| PDF | document | `.pdf` | high-fidelity / stable | download, print(adapter), HTML export(adapter), zoom(provider), search(provider) | lazy async |
|
|
144
|
+
| OFD | document | `.ofd` | structured / stable | download, print, HTML export, zoom(provider), search | lazy async |
|
|
145
|
+
| Hancom Hangul | office | `.hwp`, `.hwpx` | structured / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
|
|
146
|
+
| Typst | document | `.typ`, `.typst` | high-fidelity / stable | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
|
|
147
|
+
| 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 |
|
|
148
|
+
| Compiled HTML Help | ebook | `.chm` | structured / stable | download, print(adapter), HTML export(adapter), search | lazy async |
|
|
149
|
+
| Email | email | `.eml`, `.msg`, `.mbox` | structured / stable | download, HTML export, search | lazy async |
|
|
150
|
+
| EDA | eda | `.olb`, `.dra`, `.gds`, `.oas`, `.oasis` | structured / stable | download, print, HTML export, search | lazy async |
|
|
151
|
+
| CAD | cad | `.dxf`, `.dwg`, `.dwf`, `.dwfx`, `.xps` | high-fidelity / stable | download, print, HTML export, zoom(provider) | lazy async |
|
|
152
|
+
| 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 |
|
|
153
|
+
| Geospatial | geo | `.geojson`, `.kml`, `.gpx`, `.shp` | structured / stable | download, print, HTML export, zoom(provider), search | lazy async |
|
|
154
|
+
| Drawing | drawing | `.excalidraw`, `.drawio`, `.dio`, `.mermaid`, `.mmd`, `.plantuml`, `.puml` | structured / stable | download, print, HTML export, zoom(provider), search | lazy async |
|
|
155
|
+
| BPMN 2.0 | drawing | `.bpmn` | structured / experimental | download, zoom(provider) | lazy async |
|
|
156
|
+
| Mind Map | mindmap | `.xmind` | structured / stable | download, print, HTML export, zoom(provider), search | lazy async |
|
|
157
|
+
| EPUB | ebook | `.epub` | high-fidelity / stable | download, HTML export, search(provider) | lazy async |
|
|
158
|
+
| FictionBook | ebook | `.fb2` | structured / stable | download, print, HTML export, search | lazy async |
|
|
159
|
+
| UMD | ebook | `.umd` | structured / stable | download, print, HTML export, zoom(provider), search | lazy async |
|
|
160
|
+
| 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 |
|
|
161
|
+
| DICOM | medical-image | `.dcm`, `.dicom` | basic / experimental | download, zoom(provider) | lazy async |
|
|
162
|
+
| 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 |
|
|
163
|
+
| Markdown | markdown | `.md`, `.markdown` | structured / stable | download, print, HTML export, search | lazy async |
|
|
164
|
+
| 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 |
|
|
165
|
+
| Video | media | `.mp4`, `.webm`, `.m3u8` | high-fidelity / stable | download | lazy async |
|
|
166
|
+
| Audio | media | `.mp3`, `.mpeg`, `.wav`, `.ogg`, `.oga`, `.opus`, `.m4a`, `.aac`, `.flac`, `.weba`, `.midi`, `.mid` | high-fidelity / stable | download | lazy async |
|
|
167
|
+
| Adobe Photoshop | asset | `.psb`, `.pdd`, `.psdt`, `.psd` (enhances `data-asset`) | experimental / experimental | download, print, zoom | lazy async |
|
|
168
|
+
| Adobe Illustrator AI/AIT | asset | `.ait`, `.ai` (enhances `data-asset`) | experimental / experimental | download, print, zoom, search | lazy async |
|
|
169
|
+
| Adobe InDesign IDML | asset | `.idml` | experimental / experimental | download, print, zoom | lazy async |
|
|
170
|
+
| Adobe InCopy and InDesign Exchange | asset | `.icml`, `.idms`, `.inx` | structured / experimental | download, print, HTML export, search | lazy async |
|
|
171
|
+
| Adobe Animate XFL | asset | `.fla`, `.xfl` | structured / experimental | download | lazy async |
|
|
172
|
+
| Adobe XD Package | asset | `.xd` | structured / experimental | download | lazy async |
|
|
173
|
+
| Adobe InDesign Native | asset | `.indd`, `.indt` | structured / experimental | download | lazy async |
|
|
174
|
+
| Adobe EPS and PostScript | asset | `.ps`, `.eps` (enhances `data-asset`) | experimental / experimental | download, print, zoom | lazy async |
|
|
175
|
+
| Adobe Color Palettes | asset | `.ase`, `.aco` | structured / stable | download, print, HTML export, search | lazy async |
|
|
176
|
+
| Adobe Photoshop Resources and Presets | asset | `.abr`, `.csh`, `.pat`, `.grd`, `.asl` | structured / experimental | download, print, search | lazy async |
|
|
177
|
+
| Data Asset | asset | `.ttf`, `.otf`, `.woff`, `.woff2`, `.psd`, `.ai`, `.eps`, `.sqlite`, `.wasm`, `.parquet`, `.avro`, `.webarchive` | structured / stable | download, HTML export, search | lazy async |
|
|
178
|
+
| Binary Inspector | asset | `.bin`, `.hex`, `.elf`, `.exe`, `.dll`, `.class`, `.macho` | structured / experimental | download | lazy async |
|
|
179
|
+
|
|
180
|
+
## Engineering-Grade On-Demand Renderer Assembly
|
|
181
|
+
|
|
182
|
+
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
183
|
|
|
181
184
|
```bash
|
|
182
185
|
npm i @file-viewer/web @file-viewer/preset-office
|
|
@@ -191,7 +194,7 @@ const options = {
|
|
|
191
194
|
}
|
|
192
195
|
```
|
|
193
196
|
|
|
194
|
-
|
|
197
|
+
When a product combines Office documents with engineering drawings, keep the same `preset` field and pass an array:
|
|
195
198
|
|
|
196
199
|
```ts
|
|
197
200
|
import officePreset from '@file-viewer/preset-office'
|
|
@@ -203,7 +206,7 @@ const options = {
|
|
|
203
206
|
}
|
|
204
207
|
```
|
|
205
208
|
|
|
206
|
-
|
|
209
|
+
For exact small cuts, install one renderer and pass it through `options.renderers`:
|
|
207
210
|
|
|
208
211
|
```ts
|
|
209
212
|
import { pdfRenderer } from '@file-viewer/renderer-pdf'
|
|
@@ -214,7 +217,7 @@ const options = {
|
|
|
214
217
|
}
|
|
215
218
|
```
|
|
216
219
|
|
|
217
|
-
Vite
|
|
220
|
+
Vite projects can add the plugin. It auto-discovers installed presets, injects the virtual module, and copies matching Worker / WASM / font / vendor assets:
|
|
218
221
|
|
|
219
222
|
```bash
|
|
220
223
|
npm i -D @file-viewer/vite-plugin
|
|
@@ -227,31 +230,31 @@ export default {
|
|
|
227
230
|
plugins: [
|
|
228
231
|
fileViewerRenderers({
|
|
229
232
|
copyAssets: true
|
|
230
|
-
//
|
|
233
|
+
// No preset option required: the plugin discovers installed @file-viewer/preset-office.
|
|
231
234
|
})
|
|
232
235
|
]
|
|
233
236
|
}
|
|
234
237
|
```
|
|
235
238
|
|
|
236
|
-
|
|
239
|
+
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
240
|
|
|
238
241
|
```bash
|
|
239
242
|
npm i @file-viewer/web @file-viewer/preset-all
|
|
240
243
|
```
|
|
241
244
|
|
|
242
|
-
|
|
245
|
+
Use explicit plugin options only when you need customization:
|
|
243
246
|
|
|
244
247
|
```ts
|
|
245
248
|
fileViewerRenderers({
|
|
246
|
-
preset: 'auto', //
|
|
247
|
-
scan: true, //
|
|
248
|
-
formats: ['pdf'], //
|
|
249
|
+
preset: 'auto', // keep installed preset auto-discovery while scanning source hints
|
|
250
|
+
scan: true, // detects fileViewerFormats, data-file-viewer-formats, and accept
|
|
251
|
+
formats: ['pdf'], // adds exact renderers outside the installed preset
|
|
249
252
|
copyAssets: true,
|
|
250
253
|
chunkStrategy: 'renderer'
|
|
251
254
|
})
|
|
252
255
|
```
|
|
253
256
|
|
|
254
|
-
|
|
257
|
+
For strict custom cuts or component-library tests, disable injection and pass the virtual module explicitly:
|
|
255
258
|
|
|
256
259
|
```ts
|
|
257
260
|
// vite.config.ts
|
|
@@ -259,7 +262,7 @@ fileViewerRenderers({ formats: ['pdf'], inject: false, copyAssets: true })
|
|
|
259
262
|
```
|
|
260
263
|
|
|
261
264
|
```ts
|
|
262
|
-
//
|
|
265
|
+
// Application viewer entry
|
|
263
266
|
import { configuredFileViewerRenderers } from 'virtual:file-viewer-renderers'
|
|
264
267
|
|
|
265
268
|
const options = {
|
|
@@ -268,79 +271,79 @@ const options = {
|
|
|
268
271
|
}
|
|
269
272
|
```
|
|
270
273
|
|
|
271
|
-
- Vue
|
|
272
|
-
- `preset-lite`
|
|
273
|
-
-
|
|
274
|
-
- `fileViewerRenderers()`
|
|
275
|
-
- `scan:true`
|
|
276
|
-
- `copyAssets:true`
|
|
277
|
-
- `builtinRenderers`
|
|
278
|
-
-
|
|
279
|
-
- `@file-viewer/preset-all`
|
|
274
|
+
- 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.
|
|
275
|
+
- `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.
|
|
276
|
+
- 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`.
|
|
277
|
+
- `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.
|
|
278
|
+
- `scan:true` detects `fileViewerFormats`, `data-file-viewer-formats`, and upload `accept` hints so development and production builds select matching renderers automatically.
|
|
279
|
+
- `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.
|
|
280
|
+
- `builtinRenderers` remains available for advanced baseline control or historical compatibility. Normal quick starts only need `preset` / `renderers` plus `rendererMode`.
|
|
281
|
+
- 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.
|
|
282
|
+
- `@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
283
|
|
|
281
|
-
##
|
|
284
|
+
## Shared Options And Events
|
|
282
285
|
|
|
283
|
-
|
|
286
|
+
Every ecosystem package uses the same `ViewerMountOptions` and `FileViewerOptions` semantics, mapped to framework-native props, events, refs, actions, or plugin APIs.
|
|
284
287
|
|
|
285
|
-
|
|
|
288
|
+
| Option | Description |
|
|
286
289
|
| --- | --- |
|
|
287
|
-
| `url` |
|
|
288
|
-
| `file` | `File
|
|
289
|
-
| `buffer` |
|
|
290
|
-
| `name` / `filename` |
|
|
291
|
-
| `type` |
|
|
292
|
-
| `size` |
|
|
293
|
-
| `options` |
|
|
294
|
-
| `options.styleIsolation` | `auto
|
|
295
|
-
| `onEvent` / `onStateChange` | Vanilla
|
|
290
|
+
| `url` | Remote file URL from object storage, business APIs, or intranet file services. |
|
|
291
|
+
| `file` | `File`, `Blob`, or `ArrayBuffer` for uploads, local selection, or already-fetched binary data. |
|
|
292
|
+
| `buffer` | Direct `ArrayBuffer` input after custom download, authorization, or decryption. |
|
|
293
|
+
| `name` / `filename` | Display name and extension hint. Pass it explicitly when the URL has no useful extension. |
|
|
294
|
+
| `type` | Explicit extension or MIME hint that overrides automatic detection. |
|
|
295
|
+
| `size` | File size hint used in lifecycle context, loading states, and safety limits. |
|
|
296
|
+
| `options` | The shared `FileViewerOptions` surface. Every component package keeps the same semantics. |
|
|
297
|
+
| `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`. |
|
|
298
|
+
| `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
299
|
|
|
297
|
-
##
|
|
300
|
+
## Actual Component Props
|
|
298
301
|
|
|
299
|
-
|
|
302
|
+
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
303
|
|
|
301
|
-
|
|
|
304
|
+
| Component | Actual props / entry | Event channel | Customization entry |
|
|
302
305
|
| --- | --- | --- | --- |
|
|
303
|
-
| Vanilla JS / Pure Web `@file-viewer/web` | `<flyfish-file-viewer>`
|
|
304
|
-
| Vue 3 `@file-viewer/vue3` | `url
|
|
305
|
-
| Vue 2.7 `@file-viewer/vue2.7` | `url
|
|
306
|
-
| Vue 2.6 `@file-viewer/vue2.6` |
|
|
307
|
-
| React `@file-viewer/react` | `ViewerMountOptions`
|
|
308
|
-
| React Legacy `@file-viewer/react-legacy` |
|
|
309
|
-
| jQuery `@file-viewer/jquery` | `$(el).fileViewer(ViewerMountOptions & { replace?: boolean })` | `onEvent
|
|
310
|
-
| Svelte `@file-viewer/svelte` | `ViewerMountOptions`
|
|
311
|
-
|
|
312
|
-
| Options
|
|
306
|
+
| 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. |
|
|
307
|
+
| 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. |
|
|
308
|
+
| 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. |
|
|
309
|
+
| 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. |
|
|
310
|
+
| 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. |
|
|
311
|
+
| React Legacy `@file-viewer/react-legacy` | Same as the React package | `onEvent`, `onStateChange` | Targets React 16.8 / 17 with a legacy-friendly component export. |
|
|
312
|
+
| 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. |
|
|
313
|
+
| 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`. |
|
|
314
|
+
|
|
315
|
+
| Options Field | Description |
|
|
313
316
|
| --- | --- |
|
|
314
|
-
| `theme` | `light
|
|
315
|
-
| `styleIsolation` | `auto
|
|
316
|
-
| `watermark` |
|
|
317
|
-
| `toolbar` |
|
|
318
|
-
| `search` |
|
|
319
|
-
| `ai` |
|
|
320
|
-
| `archive` |
|
|
321
|
-
| `pdf` |
|
|
322
|
-
| `docx` / `spreadsheet` | DOCX
|
|
323
|
-
| `iwork` |
|
|
324
|
-
| `hangul` |
|
|
325
|
-
| `wordPerfect` |
|
|
326
|
-
| `presentation` | standard/full
|
|
327
|
-
| `typst` / `data` / `cad` |
|
|
328
|
-
| `hooks` / `beforeOperation` |
|
|
329
|
-
|
|
330
|
-
##
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
|
317
|
+
| `theme` | `light`, `dark`, or `system`. This takes precedence over browser `prefers-color-scheme`. |
|
|
318
|
+
| `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`. |
|
|
319
|
+
| `watermark` | Text or image watermark with opacity, rotation, gap, size, font, and color controls. |
|
|
320
|
+
| `toolbar` | Controls the theme toggle, download, print, HTML export, zoom, item order, toolbar position, and operation-level preflight checks. |
|
|
321
|
+
| `search` | Document search, highlight class names, case sensitivity, whole-word matching, max matches, and debounce. |
|
|
322
|
+
| `ai` | Text collection, chunk size, and max text length for provenance, location, vectorization, and external AI workflows. |
|
|
323
|
+
| `archive` | Archive Worker/WASM URLs, timeout, cache, archive limits, nested entry preview limits, and legacy GBK/GB18030 ZIP filename decoding. |
|
|
324
|
+
| `pdf` | PDF.js worker, navigation pane, outline, thumbnails, rotation, streaming, range chunk size, and credentials. |
|
|
325
|
+
| `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. |
|
|
326
|
+
| `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. |
|
|
327
|
+
| `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. |
|
|
328
|
+
| `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. |
|
|
329
|
+
| `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. |
|
|
330
|
+
| `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. |
|
|
331
|
+
| `hooks` / `beforeOperation` | Shared lifecycle hooks and operation preflight checks for audit, permission, telemetry, and safety controls. |
|
|
332
|
+
|
|
333
|
+
## Style Isolation And Theme Customization
|
|
334
|
+
|
|
335
|
+
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.
|
|
336
|
+
|
|
337
|
+
| Mode | Description |
|
|
335
338
|
| --- | --- |
|
|
336
|
-
| `auto` |
|
|
337
|
-
| `shadow` |
|
|
338
|
-
| `scoped` |
|
|
339
|
-
| `none` |
|
|
339
|
+
| `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. |
|
|
340
|
+
| `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. |
|
|
341
|
+
| `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. |
|
|
342
|
+
| `none` | Historical light-DOM behavior for projects that depend on deep class overrides, old theme CSS, or snapshot tests. |
|
|
340
343
|
|
|
341
|
-
`styleIsolation`
|
|
344
|
+
`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
345
|
|
|
343
|
-
|
|
346
|
+
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
347
|
|
|
345
348
|
```css
|
|
346
349
|
flyfish-file-viewer {
|
|
@@ -360,7 +363,7 @@ flyfish-file-viewer::part(button) {
|
|
|
360
363
|
}
|
|
361
364
|
```
|
|
362
365
|
|
|
363
|
-
|
|
366
|
+
Framework packages use Shadow DOM without extra configuration; set it explicitly when you want to lock the policy:
|
|
364
367
|
|
|
365
368
|
```ts
|
|
366
369
|
const options = {
|
|
@@ -370,94 +373,94 @@ const options = {
|
|
|
370
373
|
}
|
|
371
374
|
```
|
|
372
375
|
|
|
373
|
-
##
|
|
376
|
+
## Toolbar Customization
|
|
374
377
|
|
|
375
|
-
|
|
|
378
|
+
| Config | Description |
|
|
376
379
|
| --- | --- |
|
|
377
|
-
| `toolbar: false` |
|
|
378
|
-
| `toolbar: true` |
|
|
379
|
-
| `download` / `print` / `exportHtml` / `zoom` |
|
|
380
|
-
| `theme` |
|
|
381
|
-
| `order` |
|
|
382
|
-
| `position` | `auto
|
|
383
|
-
| `beforeOperation` |
|
|
384
|
-
| `beforeDownload` / `beforePrint` / `beforeExportHtml` |
|
|
380
|
+
| `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. |
|
|
381
|
+
| `toolbar: true` | Uses the default built-in toolbar. The theme toggle is visible by default; download, print, HTML export, and zoom remain capability-aware. |
|
|
382
|
+
| `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. |
|
|
383
|
+
| `theme` | Controls the light/dark toggle and defaults to `true`. A change emits `theme-change`; set it to `false` to hide the button. |
|
|
384
|
+
| `order` | Orders built-in groups with `search`, `zoom`, `download`, `print`, `exportHtml`, and `theme`. Omitted items keep their default relative order. |
|
|
385
|
+
| `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. |
|
|
386
|
+
| `beforeOperation` | Toolbar-level preflight that runs after `options.beforeOperation`. Returning `false` or throwing cancels the operation. |
|
|
387
|
+
| `beforeDownload` / `beforePrint` / `beforeExportHtml` | Operation-specific preflight for download permission, print audit, export confirmation, and similar business rules. |
|
|
385
388
|
|
|
386
|
-
|
|
389
|
+
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
390
|
|
|
388
|
-
|
|
391
|
+
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
392
|
|
|
390
|
-
|
|
393
|
+
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
394
|
|
|
392
|
-
|
|
|
395
|
+
| Ecosystem | Recommended pattern |
|
|
393
396
|
| --- | --- |
|
|
394
|
-
| Vanilla JS / Pure Web | `<flyfish-file-viewer toolbar="false">`
|
|
395
|
-
| Vue 3 |
|
|
396
|
-
| Vue 2.7 / 2.6 |
|
|
397
|
-
| React / React Legacy |
|
|
398
|
-
| jQuery | `$("#viewer").fileViewer({ options:{ toolbar:false } })
|
|
399
|
-
| Svelte | `<FileViewer bind:this={viewer} options={{ toolbar:false }}
|
|
397
|
+
| 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. |
|
|
398
|
+
| 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`. |
|
|
399
|
+
| 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`. |
|
|
400
|
+
| 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`. |
|
|
401
|
+
| jQuery | Use `$("#viewer").fileViewer({ options:{ toolbar:false } })`; buttons can call `$("#viewer").fileViewer("zoomIn")` or read capability state through `getFileViewerController($("#viewer")).subscribe()`. |
|
|
402
|
+
| Svelte | Use `<FileViewer bind:this={viewer} options={{ toolbar:false }} />`; buttons call `viewer.zoomIn()` / `viewer.printRenderedHtml()`, with `on:viewerEvent` or `onStateChange` for state sync. |
|
|
400
403
|
|
|
401
|
-
##
|
|
404
|
+
## Lifecycle And Operation Events
|
|
402
405
|
|
|
403
|
-
|
|
|
406
|
+
| Event / hook | Description |
|
|
404
407
|
| --- | --- |
|
|
405
|
-
| `load-start` / `hooks.onLoadStart` |
|
|
406
|
-
| `load-complete` / `hooks.onLoadComplete` |
|
|
407
|
-
| `unload-start` / `hooks.onUnloadStart` |
|
|
408
|
-
| `unload-complete` / `hooks.onUnloadComplete` |
|
|
409
|
-
| `operation-before` / `operation-cancel` |
|
|
410
|
-
| `operation-availability-change` |
|
|
411
|
-
| `theme-change` |
|
|
412
|
-
| `search-change` / `location-change` / `zoom-change` / `view-state-change` |
|
|
413
|
-
|
|
414
|
-
##
|
|
415
|
-
|
|
416
|
-
| API |
|
|
408
|
+
| `load-start` / `hooks.onLoadStart` | Fires when parsing or downloading starts. Context includes filename, type, source, version, URL, File, and size. |
|
|
409
|
+
| `load-complete` / `hooks.onLoadComplete` | Fires when the current document has rendered. Context includes duration, source data, and version. |
|
|
410
|
+
| `unload-start` / `hooks.onUnloadStart` | Fires before replace, reset, or component unmount so external state or resources can be saved. |
|
|
411
|
+
| `unload-complete` / `hooks.onUnloadComplete` | Fires after the previous document is released. The reason is `replace`, `reset`, or `component-unmount`. |
|
|
412
|
+
| `operation-before` / `operation-cancel` | Fires around download, print, HTML export, and zoom actions. Returning `false` from `beforeOperation` cancels the action. |
|
|
413
|
+
| `operation-availability-change` | Fires when download, print, HTML export, or zoom support changes for the active format. |
|
|
414
|
+
| `theme-change` | Fires when the built-in control selects light or dark mode. The payload is `light` or `dark`. |
|
|
415
|
+
| `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. |
|
|
416
|
+
|
|
417
|
+
## Public Operation API
|
|
418
|
+
|
|
419
|
+
| API | Description |
|
|
417
420
|
| --- | --- |
|
|
418
|
-
| `load` / `update` / `reload` / `destroy` |
|
|
419
|
-
| `downloadOriginalFile()` |
|
|
420
|
-
| `printRenderedHtml(options?)` |
|
|
421
|
-
| `printWithMask(options?)` |
|
|
422
|
-
| `exportRenderedHtml()` |
|
|
423
|
-
| `zoomIn()` / `zoomOut()` / `resetZoom()` |
|
|
424
|
-
| `searchDocument()` / `nextSearchResult()` / `previousSearchResult()` |
|
|
425
|
-
| `collectDocumentAnchors()` / `scrollToAnchor()` / `scrollToLine()` |
|
|
426
|
-
| `getDocumentTextChunks()` |
|
|
427
|
-
| `getOperationAvailability()` / `getZoomState()` / `getSearchState()` |
|
|
428
|
-
|
|
429
|
-
##
|
|
430
|
-
|
|
431
|
-
|
|
|
421
|
+
| `load` / `update` / `reload` / `destroy` | Imperatively load, update, reload, and destroy the viewer. |
|
|
422
|
+
| `downloadOriginalFile()` | Downloads the original file while respecting toolbar and `beforeOperation` checks. |
|
|
423
|
+
| `printRenderedHtml(options?)` | Prints the complete rendered document using the best available per-format print adapter. Enabled watermarks are included; pass `mask` for cover regions. |
|
|
424
|
+
| `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. |
|
|
425
|
+
| `exportRenderedHtml()` | Exports rendered HTML for archiving, audit, or offline review. |
|
|
426
|
+
| `zoomIn()` / `zoomOut()` / `resetZoom()` | Uses the active renderer zoom provider instead of outer CSS transforms that can break coordinates. |
|
|
427
|
+
| `searchDocument()` / `nextSearchResult()` / `previousSearchResult()` | Runs document-level search and navigates highlighted matches. |
|
|
428
|
+
| `collectDocumentAnchors()` / `scrollToAnchor()` / `scrollToLine()` | Collects pages, outline items, headings, or code-line anchors and scrolls to them. |
|
|
429
|
+
| `getDocumentTextChunks()` | Returns structured text chunks for search, AI provenance, vectorization, and external indexes. |
|
|
430
|
+
| `getOperationAvailability()` / `getZoomState()` / `getSearchState()` | Reads current capability, zoom, and search state for custom toolbars. |
|
|
431
|
+
|
|
432
|
+
## Workers, WASM, And Private Deployment
|
|
433
|
+
|
|
434
|
+
| Asset | Description |
|
|
432
435
|
| --- | --- |
|
|
433
|
-
| Standard
|
|
434
|
-
|
|
|
435
|
-
| PDF / DOCX / Excel / PPTX |
|
|
436
|
-
| Archive /
|
|
437
|
-
| Draw.io |
|
|
438
|
-
|
|
|
439
|
-
|
|
|
436
|
+
| 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. |
|
|
437
|
+
| 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. |
|
|
438
|
+
| 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. |
|
|
439
|
+
| 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. |
|
|
440
|
+
| 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. |
|
|
441
|
+
| 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. |
|
|
442
|
+
| 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
443
|
|
|
441
444
|
|
|
442
|
-
##
|
|
445
|
+
## Quality Gates
|
|
443
446
|
|
|
444
|
-
-
|
|
445
|
-
-
|
|
446
|
-
-
|
|
447
|
+
- Component packages only depend on `@file-viewer/core` and their own ecosystem dependencies. They do not nest through another framework component package.
|
|
448
|
+
- Format parsing, search, zoom, print, export, watermark, lifecycle, and beforeOperation semantics all come from the same core.
|
|
449
|
+
- Releases should pass type checks, component API verification, README generation checks, format-matrix verification, standalone repository export, and browser smoke tests.
|
|
447
450
|
|
|
448
|
-
|
|
451
|
+
See the official documentation for options, lifecycle hooks, beforeOperation, theme, watermark, search, zoom, print, and export APIs: https://doc.file-viewer.app/
|
|
449
452
|
|
|
450
|
-
|
|
453
|
+
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
454
|
<!-- FILE_VIEWER_GENERATED:END -->
|
|
452
455
|
|
|
453
|
-
##
|
|
456
|
+
## Formats and related packages
|
|
454
457
|
|
|
455
|
-
File Viewer
|
|
458
|
+
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
459
|
|
|
457
|
-
-
|
|
458
|
-
-
|
|
459
|
-
-
|
|
460
|
+
- 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
|
|
461
|
+
- Presets: `@file-viewer/preset-lite`, `@file-viewer/preset-office`, `@file-viewer/preset-engineering`, `@file-viewer/preset-all`
|
|
462
|
+
- Build: `@file-viewer/vite-plugin`, `file-viewer-copy-assets`
|
|
460
463
|
|
|
461
|
-
##
|
|
464
|
+
## License
|
|
462
465
|
|
|
463
|
-
|
|
466
|
+
This package is Apache-2.0. See [LICENSE](https://github.com/flyfish-dev/file-viewer/blob/main/LICENSE).
|