@file-viewer/react-full 2.1.3
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/LICENSE +160 -0
- package/README.en.md +280 -0
- package/README.md +280 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +3 -0
- package/package.json +72 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction, and
|
|
10
|
+
distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by the copyright
|
|
13
|
+
owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all other entities
|
|
16
|
+
that control, are controlled by, or are under common control with that entity.
|
|
17
|
+
For the purposes of this definition, "control" means (i) the power, direct or
|
|
18
|
+
indirect, to cause the direction or management of such entity, whether by
|
|
19
|
+
contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
20
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
21
|
+
|
|
22
|
+
"You" (or "Your") shall mean an individual or Legal Entity exercising
|
|
23
|
+
permissions granted by this License.
|
|
24
|
+
|
|
25
|
+
"Source" form shall mean the preferred form for making modifications, including
|
|
26
|
+
but not limited to software source code, documentation source, and configuration
|
|
27
|
+
files.
|
|
28
|
+
|
|
29
|
+
"Object" form shall mean any form resulting from mechanical transformation or
|
|
30
|
+
translation of a Source form, including but not limited to compiled object code,
|
|
31
|
+
generated documentation, and conversions to other media types.
|
|
32
|
+
|
|
33
|
+
"Work" shall mean the work of authorship, whether in Source or Object form,
|
|
34
|
+
made available under the License, as indicated by a copyright notice that is
|
|
35
|
+
included in or attached to the work.
|
|
36
|
+
|
|
37
|
+
"Derivative Works" shall mean any work, whether in Source or Object form, that
|
|
38
|
+
is based on (or derived from) the Work and for which the editorial revisions,
|
|
39
|
+
annotations, elaborations, or other modifications represent, as a whole, an
|
|
40
|
+
original work of authorship. For the purposes of this License, Derivative Works
|
|
41
|
+
shall not include works that remain separable from, or merely link (or bind by
|
|
42
|
+
name) to the interfaces of, the Work and Derivative Works thereof.
|
|
43
|
+
|
|
44
|
+
"Contribution" shall mean any work of authorship, including the original version
|
|
45
|
+
of the Work and any modifications or additions to that Work or Derivative Works
|
|
46
|
+
thereof, that is intentionally submitted to Licensor for inclusion in the Work by
|
|
47
|
+
the copyright owner or by an individual or Legal Entity authorized to submit on
|
|
48
|
+
behalf of the copyright owner. For the purposes of this definition, "submitted"
|
|
49
|
+
means any form of electronic, verbal, or written communication sent to the
|
|
50
|
+
Licensor or its representatives, including but not limited to communication on
|
|
51
|
+
electronic mailing lists, source code control systems, and issue tracking systems
|
|
52
|
+
that are managed by, or on behalf of, the Licensor for the purpose of discussing
|
|
53
|
+
and improving the Work, but excluding communication that is conspicuously marked
|
|
54
|
+
or otherwise designated in writing by the copyright owner as "Not a
|
|
55
|
+
Contribution."
|
|
56
|
+
|
|
57
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
|
|
58
|
+
of whom a Contribution has been received by Licensor and subsequently
|
|
59
|
+
incorporated within the Work.
|
|
60
|
+
|
|
61
|
+
2. Grant of Copyright License. Subject to the terms and conditions of this
|
|
62
|
+
License, each Contributor hereby grants to You a perpetual, worldwide,
|
|
63
|
+
non-exclusive, no-charge, royalty-free, irrevocable copyright license to
|
|
64
|
+
reproduce, prepare Derivative Works of, publicly display, publicly perform,
|
|
65
|
+
sublicense, and distribute the Work and such Derivative Works in Source or
|
|
66
|
+
Object form.
|
|
67
|
+
|
|
68
|
+
3. Grant of Patent License. Subject to the terms and conditions of this License,
|
|
69
|
+
each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
|
|
70
|
+
no-charge, royalty-free, irrevocable (except as stated in this section) patent
|
|
71
|
+
license to make, have made, use, offer to sell, sell, import, and otherwise
|
|
72
|
+
transfer the Work, where such license applies only to those patent claims
|
|
73
|
+
licensable by such Contributor that are necessarily infringed by their
|
|
74
|
+
Contribution(s) alone or by combination of their Contribution(s) with the Work to
|
|
75
|
+
which such Contribution(s) was submitted. If You institute patent litigation
|
|
76
|
+
against any entity (including a cross-claim or counterclaim in a lawsuit)
|
|
77
|
+
alleging that the Work or a Contribution incorporated within the Work
|
|
78
|
+
constitutes direct or contributory patent infringement, then any patent licenses
|
|
79
|
+
granted to You under this License for that Work shall terminate as of the date
|
|
80
|
+
such litigation is filed.
|
|
81
|
+
|
|
82
|
+
4. Redistribution. You may reproduce and distribute copies of the Work or
|
|
83
|
+
Derivative Works thereof in any medium, with or without modifications, and in
|
|
84
|
+
Source or Object form, provided that You meet the following conditions:
|
|
85
|
+
|
|
86
|
+
(a) You must give any other recipients of the Work or Derivative Works a copy of
|
|
87
|
+
this License; and
|
|
88
|
+
|
|
89
|
+
(b) You must cause any modified files to carry prominent notices stating that
|
|
90
|
+
You changed the files; and
|
|
91
|
+
|
|
92
|
+
(c) You must retain, in the Source form of any Derivative Works that You
|
|
93
|
+
distribute, all copyright, patent, trademark, and attribution notices from the
|
|
94
|
+
Source form of the Work, excluding those notices that do not pertain to any part
|
|
95
|
+
of the Derivative Works; and
|
|
96
|
+
|
|
97
|
+
(d) If the Work includes a "NOTICE" text file as part of its distribution, then
|
|
98
|
+
any Derivative Works that You distribute must include a readable copy of the
|
|
99
|
+
attribution notices contained within such NOTICE file, excluding those notices
|
|
100
|
+
that do not pertain to any part of the Derivative Works, in at least one of the
|
|
101
|
+
following places: within a NOTICE text file distributed as part of the Derivative
|
|
102
|
+
Works; within the Source form or documentation, if provided along with the
|
|
103
|
+
Derivative Works; or, within a display generated by the Derivative Works, if and
|
|
104
|
+
wherever such third-party notices normally appear. The contents of the NOTICE
|
|
105
|
+
file are for informational purposes only and do not modify the License. You may
|
|
106
|
+
add Your own attribution notices within Derivative Works that You distribute,
|
|
107
|
+
alongside or as an addendum to the NOTICE text from the Work, provided that such
|
|
108
|
+
additional attribution notices cannot be construed as modifying the License.
|
|
109
|
+
|
|
110
|
+
You may add Your own copyright statement to Your modifications and may provide
|
|
111
|
+
additional or different license terms and conditions for use, reproduction, or
|
|
112
|
+
distribution of Your modifications, or for any such Derivative Works as a whole,
|
|
113
|
+
provided Your use, reproduction, and distribution of the Work otherwise complies
|
|
114
|
+
with the conditions stated in this License.
|
|
115
|
+
|
|
116
|
+
5. Submission of Contributions. Unless You explicitly state otherwise, any
|
|
117
|
+
Contribution intentionally submitted for inclusion in the Work by You to the
|
|
118
|
+
Licensor shall be under the terms and conditions of this License, without any
|
|
119
|
+
additional terms or conditions. Notwithstanding the above, nothing herein shall
|
|
120
|
+
supersede or modify the terms of any separate license agreement you may have
|
|
121
|
+
executed with Licensor regarding such Contributions.
|
|
122
|
+
|
|
123
|
+
6. Trademarks. This License does not grant permission to use the trade names,
|
|
124
|
+
trademarks, service marks, or product names of the Licensor, except as required
|
|
125
|
+
for reasonable and customary use in describing the origin of the Work and
|
|
126
|
+
reproducing the content of the NOTICE file.
|
|
127
|
+
|
|
128
|
+
7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
|
|
129
|
+
writing, Licensor provides the Work (and each Contributor provides its
|
|
130
|
+
Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
|
131
|
+
KIND, either express or implied, including, without limitation, any warranties or
|
|
132
|
+
conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
133
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
134
|
+
appropriateness of using or redistributing the Work and assume any risks
|
|
135
|
+
associated with Your exercise of permissions under this License.
|
|
136
|
+
|
|
137
|
+
8. Limitation of Liability. In no event and under no legal theory, whether in
|
|
138
|
+
tort (including negligence), contract, or otherwise, unless required by
|
|
139
|
+
applicable law (such as deliberate and grossly negligent acts) or agreed to in
|
|
140
|
+
writing, shall any Contributor be liable to You for damages, including any
|
|
141
|
+
direct, indirect, special, incidental, or consequential damages of any character
|
|
142
|
+
arising as a result of this License or out of the use or inability to use the
|
|
143
|
+
Work (including but not limited to damages for loss of goodwill, work stoppage,
|
|
144
|
+
computer failure or malfunction, or any and all other commercial damages or
|
|
145
|
+
losses), even if such Contributor has been advised of the possibility of such
|
|
146
|
+
damages.
|
|
147
|
+
|
|
148
|
+
9. Accepting Warranty or Additional Liability. While redistributing the Work or
|
|
149
|
+
Derivative Works thereof, You may choose to offer, and charge a fee for,
|
|
150
|
+
acceptance of support, warranty, indemnity, or other liability obligations and/or
|
|
151
|
+
rights consistent with this License. However, in accepting such obligations, You
|
|
152
|
+
may act only on Your own behalf and on Your sole responsibility, not on behalf of
|
|
153
|
+
any other Contributor, and only if You agree to indemnify, defend, and hold each
|
|
154
|
+
Contributor harmless for any liability incurred by, or claims asserted against,
|
|
155
|
+
such Contributor by reason of your accepting any such warranty or additional
|
|
156
|
+
liability.
|
|
157
|
+
|
|
158
|
+
END OF TERMS AND CONDITIONS
|
|
159
|
+
|
|
160
|
+
Copyright 2026 Flyfish Viewer
|
package/README.en.md
ADDED
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
# @file-viewer/react-full
|
|
2
|
+
|
|
3
|
+
Full-format React package. The release scripts replace this placeholder with the complete package README.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm install @file-viewer/react-full
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
<!-- FILE_VIEWER_GENERATED:START -->
|
|
10
|
+
## Ecosystem Matrix
|
|
11
|
+
|
|
12
|
+
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, and export. Heavy PDF, Word, PPTX, CAD, Typst, and similar pipelines are assembled explicitly through renderer packages or presets; each framework package owns its local controller, component lifecycle, type exports, and ecosystem-specific interaction layer.
|
|
13
|
+
|
|
14
|
+
| Framework | Standard npm package | Entrypoints | GitHub | Gitee | Historical aliases |
|
|
15
|
+
| --- | --- | --- | --- | --- | --- |
|
|
16
|
+
| Vanilla JS / Pure Web | `@file-viewer/web` | ESM, type declarations, script tag IIFE, worker/WASM viewer assets, asset copy CLI | [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` |
|
|
17
|
+
| Vanilla JS / Pure Web Full | `@file-viewer/web-full` | ESM, type declarations, script tag IIFE | [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 |
|
|
18
|
+
| 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` |
|
|
19
|
+
| 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 |
|
|
20
|
+
| 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` |
|
|
21
|
+
| 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 |
|
|
22
|
+
| 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 |
|
|
23
|
+
| 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 |
|
|
24
|
+
| 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` |
|
|
25
|
+
| 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 |
|
|
26
|
+
| 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 |
|
|
27
|
+
| 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 |
|
|
28
|
+
| 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 |
|
|
29
|
+
| 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 |
|
|
30
|
+
| 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 |
|
|
31
|
+
| 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 |
|
|
32
|
+
|
|
33
|
+
## Format Support Matrix
|
|
34
|
+
|
|
35
|
+
The shared format matrix currently covers 24 preview pipelines and 206 file extensions. Full capability is assembled through renderer packages or presets, while component packages only adapt their own ecosystem without nesting through another framework implementation.
|
|
36
|
+
|
|
37
|
+
| Preview pipeline | Category | Extensions | Capabilities | Loading |
|
|
38
|
+
| --- | --- | --- | --- | --- |
|
|
39
|
+
| Word OpenXML | office | `.docx`, `.docm`, `.dotx`, `.dotm` | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
|
|
40
|
+
| Word Binary | office | `.doc`, `.dot` | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
|
|
41
|
+
| PowerPoint | office | `.pptx`, `.pptm`, `.potx`, `.potm`, `.ppsx`, `.ppsm` | download, print, HTML export, zoom(provider), search | lazy async |
|
|
42
|
+
| Open Document | office | `.rtf`, `.odt`, `.odp` | download, print, HTML export, zoom(provider), search | lazy async |
|
|
43
|
+
| Spreadsheet | office | `.xlsx`, `.xltx`, `.xlsm`, `.xlsb`, `.xls`, `.xlt`, `.xltm`, `.csv`, `.ods`, `.fods`, `.numbers` | download, zoom(provider), search | lazy async |
|
|
44
|
+
| PDF | document | `.pdf` | download, print(adapter), HTML export(adapter), zoom(provider), search(provider) | lazy async |
|
|
45
|
+
| OFD | document | `.ofd` | download, print, HTML export, zoom(provider), search | lazy async |
|
|
46
|
+
| Typst | document | `.typ`, `.typst` | download, print(adapter), HTML export(adapter), zoom(provider), search | lazy async |
|
|
47
|
+
| 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` | download, search | lazy async |
|
|
48
|
+
| Email | email | `.eml`, `.msg`, `.mbox` | download, HTML export, search | lazy async |
|
|
49
|
+
| EDA | eda | `.olb`, `.dra`, `.gds`, `.oas`, `.oasis` | download, print, HTML export, search | lazy async |
|
|
50
|
+
| CAD | cad | `.dxf`, `.dwg`, `.dwf`, `.dwfx`, `.xps` | download, print, HTML export, zoom(provider) | lazy async |
|
|
51
|
+
| 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` | download, zoom(provider) | lazy async |
|
|
52
|
+
| Geospatial | geo | `.geojson`, `.kml`, `.gpx`, `.shp` | download, print, HTML export, zoom(provider), search | lazy async |
|
|
53
|
+
| Drawing | drawing | `.excalidraw`, `.drawio`, `.dio`, `.mermaid`, `.mmd`, `.plantuml`, `.puml` | download, print, HTML export, zoom(provider), search | lazy async |
|
|
54
|
+
| Mind Map | mindmap | `.xmind` | download, print, HTML export, zoom(provider), search | lazy async |
|
|
55
|
+
| EPUB | ebook | `.epub` | download, HTML export, search(provider) | lazy async |
|
|
56
|
+
| UMD | ebook | `.umd` | download, print, HTML export, zoom(provider), search | lazy async |
|
|
57
|
+
| Image | image | `.gif`, `.jpg`, `.jpeg`, `.bmp`, `.tiff`, `.tif`, `.png`, `.svg`, `.webp`, `.avif`, `.ico`, `.heic`, `.heif`, `.jxl` | download, print, HTML export, zoom(provider) | lazy async |
|
|
58
|
+
| Markdown | markdown | `.md`, `.markdown` | download, print, HTML export, search | lazy async |
|
|
59
|
+
| Code and Text | code | `.txt`, `.json`, `.js`, `.mjs`, `.cjs`, `.css`, `.java`, `.py`, `.html`, `.htm`, `.jsx`, `.ts`, `.tsx`, `.xml`, `.log`, `.vue`, `.yaml`, `.yml`, `.ini`, `.sh`, `.bash`, `.sql`, `.go`, `.rs`, `.php`, `.c`, `.cpp`, `.cc`, `.h`, `.hpp`, `.cs`, `.diff`, `.patch`, `.bundle`, `.bdl`, `.jsonc`, `.json5`, `.ipynb`, `.toml`, `.proto`, `.hcl`, `.tex`, `.gv`, `.http`, `.react`, `.rb`, `.swift`, `.kt` | download, print, HTML export, search | lazy async |
|
|
60
|
+
| Video | media | `.mp4`, `.webm`, `.m3u8` | download | lazy async |
|
|
61
|
+
| Audio | media | `.mp3`, `.mpeg`, `.wav`, `.ogg`, `.oga`, `.opus`, `.m4a`, `.aac`, `.flac`, `.weba`, `.midi`, `.mid` | download | lazy async |
|
|
62
|
+
| Data Asset | asset | `.ttf`, `.otf`, `.woff`, `.woff2`, `.psd`, `.ai`, `.eps`, `.sqlite`, `.wasm`, `.parquet`, `.avro`, `.webarchive` | download, HTML export, search | lazy async |
|
|
63
|
+
|
|
64
|
+
## Engineering-Grade On-Demand Renderer Assembly
|
|
65
|
+
|
|
66
|
+
One component, one line of code, fast integration; renderer assembly is what controls install size and first-screen bundle weight. 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.
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
npm i @file-viewer/react-full @file-viewer/preset-office
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
import officePreset from '@file-viewer/preset-office'
|
|
74
|
+
|
|
75
|
+
const options = {
|
|
76
|
+
preset: officePreset,
|
|
77
|
+
rendererMode: 'replace'
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
When a product combines Office documents with engineering drawings, keep the same `preset` field and pass an array:
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
import officePreset from '@file-viewer/preset-office'
|
|
85
|
+
import engineeringPreset from '@file-viewer/preset-engineering'
|
|
86
|
+
|
|
87
|
+
const options = {
|
|
88
|
+
preset: [officePreset, engineeringPreset],
|
|
89
|
+
rendererMode: 'replace'
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
For exact small cuts, install one renderer and pass it through `options.renderers`:
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
import { pdfRenderer } from '@file-viewer/renderer-pdf'
|
|
97
|
+
|
|
98
|
+
const options = {
|
|
99
|
+
renderers: [pdfRenderer],
|
|
100
|
+
rendererMode: 'replace'
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Vite projects can add the plugin. It auto-discovers installed presets, injects the virtual module, and copies matching Worker / WASM / font / vendor assets:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
npm i -D @file-viewer/vite-plugin
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
import { fileViewerRenderers } from '@file-viewer/vite-plugin'
|
|
112
|
+
|
|
113
|
+
export default {
|
|
114
|
+
plugins: [
|
|
115
|
+
fileViewerRenderers({
|
|
116
|
+
copyAssets: true
|
|
117
|
+
// No preset option required: the plugin discovers installed @file-viewer/preset-office.
|
|
118
|
+
})
|
|
119
|
+
]
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
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:
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
npm i @file-viewer/react-full @file-viewer/preset-all
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Use explicit plugin options only when you need customization:
|
|
130
|
+
|
|
131
|
+
```ts
|
|
132
|
+
fileViewerRenderers({
|
|
133
|
+
preset: 'auto', // keep installed preset auto-discovery while scanning source hints
|
|
134
|
+
scan: true, // detects fileViewerFormats, data-file-viewer-formats, and accept
|
|
135
|
+
formats: ['pdf'], // adds exact renderers outside the installed preset
|
|
136
|
+
copyAssets: true,
|
|
137
|
+
chunkStrategy: 'renderer'
|
|
138
|
+
})
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
For strict custom cuts or component-library tests, disable injection and pass the virtual module explicitly:
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
// vite.config.ts
|
|
145
|
+
fileViewerRenderers({ formats: ['pdf'], inject: false, copyAssets: true })
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
```ts
|
|
149
|
+
// Application viewer entry
|
|
150
|
+
import { configuredFileViewerRenderers } from 'virtual:file-viewer-renderers'
|
|
151
|
+
|
|
152
|
+
const options = {
|
|
153
|
+
renderers: configuredFileViewerRenderers,
|
|
154
|
+
rendererMode: 'replace'
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
- 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.
|
|
159
|
+
- `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.
|
|
160
|
+
- 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`.
|
|
161
|
+
- `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.
|
|
162
|
+
- `scan:true` detects `fileViewerFormats`, `data-file-viewer-formats`, and upload `accept` hints so development and production builds select matching renderers automatically.
|
|
163
|
+
- `copyAssets:true` copies PDF/CAD/Typst/Archive/Data workers, WASM, and vendor assets for offline and enterprise intranet deployment.
|
|
164
|
+
- `builtinRenderers` remains available for advanced baseline control or historical compatibility. Normal quick starts only need `preset` / `renderers` plus `rendererMode`.
|
|
165
|
+
- 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.
|
|
166
|
+
- `@file-viewer/preset-all` is the full one-step capability path for demos, admin tools, and enterprise all-format workbenches. Normal product surfaces should still prefer narrower presets.
|
|
167
|
+
|
|
168
|
+
## Shared Options And Events
|
|
169
|
+
|
|
170
|
+
Every ecosystem package uses the same `ViewerMountOptions` and `FileViewerOptions` semantics, mapped to framework-native props, events, refs, actions, or plugin APIs.
|
|
171
|
+
|
|
172
|
+
| Option | Description |
|
|
173
|
+
| --- | --- |
|
|
174
|
+
| `url` | Remote file URL from object storage, business APIs, or intranet file services. |
|
|
175
|
+
| `file` | `File`, `Blob`, or `ArrayBuffer` for uploads, local selection, or already-fetched binary data. |
|
|
176
|
+
| `buffer` | Direct `ArrayBuffer` input after custom download, authorization, or decryption. |
|
|
177
|
+
| `name` / `filename` | Display name and extension hint. Pass it explicitly when the URL has no useful extension. |
|
|
178
|
+
| `type` | Explicit extension or MIME hint that overrides automatic detection. |
|
|
179
|
+
| `size` | File size hint used in lifecycle context, loading states, and safety limits. |
|
|
180
|
+
| `options` | The shared `FileViewerOptions` surface. Every component package keeps the same semantics. |
|
|
181
|
+
| `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. |
|
|
182
|
+
|
|
183
|
+
## Actual Component Props
|
|
184
|
+
|
|
185
|
+
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.
|
|
186
|
+
|
|
187
|
+
| Component | Actual props / entry | Event channel | Customization entry |
|
|
188
|
+
| --- | --- | --- | --- |
|
|
189
|
+
| 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. |
|
|
190
|
+
| 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` | Template refs expose `FileViewerExpose`. For `Blob` / `ArrayBuffer`, prefer wrapping it as a named `File` so extension detection stays deterministic. |
|
|
191
|
+
| 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. |
|
|
192
|
+
| 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. |
|
|
193
|
+
| 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. |
|
|
194
|
+
| React Legacy `@file-viewer/react-legacy` | Same as the React package | `onEvent`, `onStateChange` | Targets React 16.8 / 17 with a legacy-friendly component export. |
|
|
195
|
+
| 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. |
|
|
196
|
+
| 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`. |
|
|
197
|
+
|
|
198
|
+
| Options Field | Description |
|
|
199
|
+
| --- | --- |
|
|
200
|
+
| `theme` | `light`, `dark`, or `system`. This takes precedence over browser `prefers-color-scheme`. |
|
|
201
|
+
| `watermark` | Text or image watermark with opacity, rotation, gap, size, font, and color controls. |
|
|
202
|
+
| `toolbar` | Controls download, print, HTML export, zoom, toolbar position, and operation-level preflight checks. |
|
|
203
|
+
| `search` | Document search, highlight class names, case sensitivity, whole-word matching, max matches, and debounce. |
|
|
204
|
+
| `ai` | Text collection, chunk size, and max text length for provenance, location, vectorization, and external AI workflows. |
|
|
205
|
+
| `archive` | Archive Worker/WASM URLs, timeout, cache, archive limits, and nested entry preview limits. |
|
|
206
|
+
| `pdf` | PDF.js worker, navigation pane, outline, thumbnails, rotation, streaming, range chunk size, and credentials. |
|
|
207
|
+
| `docx` / `spreadsheet` | DOCX is provided by @file-viewer/renderer-word and uses the self-maintained @file-viewer/docx engine with Worker parsing, continuous flow reading, and async rendering by default; visual pagination is opt-in. Spreadsheet is provided by @file-viewer/renderer-spreadsheet with fidelity-first main-thread parsing, opt-in Worker loading, and opt-in header drag column resizing. |
|
|
208
|
+
| `typst` / `data` / `cad` | Typst, SQLite, CAD/DWG/DXF/DWF WASM, worker, encoding, and rendering strategy options. |
|
|
209
|
+
| `hooks` / `beforeOperation` | Shared lifecycle hooks and operation preflight checks for audit, permission, telemetry, and safety controls. |
|
|
210
|
+
|
|
211
|
+
## Toolbar Customization
|
|
212
|
+
|
|
213
|
+
| Config | Description |
|
|
214
|
+
| --- | --- |
|
|
215
|
+
| `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. |
|
|
216
|
+
| `toolbar: true` | Uses the default built-in toolbar. Download, print, HTML export, and zoom buttons are still shown only when the active renderer supports them. |
|
|
217
|
+
| `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. |
|
|
218
|
+
| `position` | `auto`, `top`, or `bottom-right`. The default `auto` floats PDF actions at bottom right to avoid conflicting with the PDF page / outline toolbar. |
|
|
219
|
+
| `beforeOperation` | Toolbar-level preflight that runs after `options.beforeOperation`. Returning `false` or throwing cancels the operation. |
|
|
220
|
+
| `beforeDownload` / `beforePrint` / `beforeExportHtml` | Operation-specific preflight for download permission, print audit, export confirmation, and similar business rules. |
|
|
221
|
+
|
|
222
|
+
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.
|
|
223
|
+
|
|
224
|
+
| Ecosystem | Recommended pattern |
|
|
225
|
+
| --- | --- |
|
|
226
|
+
| 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. |
|
|
227
|
+
| 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`. |
|
|
228
|
+
| 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`. |
|
|
229
|
+
| 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`. |
|
|
230
|
+
| jQuery | Use `$("#viewer").fileViewer({ options:{ toolbar:false } })`; buttons can call `$("#viewer").fileViewer("zoomIn")` or read capability state through `getFileViewerController($("#viewer")).subscribe()`. |
|
|
231
|
+
| Svelte | Use `<FileViewer bind:this={viewer} options={{ toolbar:false }} />`; buttons call `viewer.zoomIn()` / `viewer.printRenderedHtml()`, with `on:viewerEvent` or `onStateChange` for state sync. |
|
|
232
|
+
|
|
233
|
+
## Lifecycle And Operation Events
|
|
234
|
+
|
|
235
|
+
| Event / hook | Description |
|
|
236
|
+
| --- | --- |
|
|
237
|
+
| `load-start` / `hooks.onLoadStart` | Fires when parsing or downloading starts. Context includes filename, type, source, version, URL, File, and size. |
|
|
238
|
+
| `load-complete` / `hooks.onLoadComplete` | Fires when the current document has rendered. Context includes duration, source data, and version. |
|
|
239
|
+
| `unload-start` / `hooks.onUnloadStart` | Fires before replace, reset, or component unmount so external state or resources can be saved. |
|
|
240
|
+
| `unload-complete` / `hooks.onUnloadComplete` | Fires after the previous document is released. The reason is `replace`, `reset`, or `component-unmount`. |
|
|
241
|
+
| `operation-before` / `operation-cancel` | Fires around download, print, HTML export, and zoom actions. Returning `false` from `beforeOperation` cancels the action. |
|
|
242
|
+
| `operation-availability-change` | Fires when download, print, HTML export, or zoom support changes for the active format. |
|
|
243
|
+
| `search-change` / `location-change` / `zoom-change` | Fires when search matches, document anchors, or zoom state changes so host UIs can stay in sync. |
|
|
244
|
+
|
|
245
|
+
## Public Operation API
|
|
246
|
+
|
|
247
|
+
| API | Description |
|
|
248
|
+
| --- | --- |
|
|
249
|
+
| `load` / `update` / `reload` / `destroy` | Imperatively load, update, reload, and destroy the viewer. |
|
|
250
|
+
| `downloadOriginalFile()` | Downloads the original file while respecting toolbar and `beforeOperation` checks. |
|
|
251
|
+
| `printRenderedHtml()` | Prints the complete rendered document using the best available per-format print adapter. |
|
|
252
|
+
| `exportRenderedHtml()` | Exports rendered HTML for archiving, audit, or offline review. |
|
|
253
|
+
| `zoomIn()` / `zoomOut()` / `resetZoom()` | Uses the active renderer zoom provider instead of outer CSS transforms that can break coordinates. |
|
|
254
|
+
| `searchDocument()` / `nextSearchResult()` / `previousSearchResult()` | Runs document-level search and navigates highlighted matches. |
|
|
255
|
+
| `collectDocumentAnchors()` / `scrollToAnchor()` / `scrollToLine()` | Collects pages, outline items, headings, or code-line anchors and scrolls to them. |
|
|
256
|
+
| `getDocumentTextChunks()` | Returns structured text chunks for search, AI provenance, vectorization, and external indexes. |
|
|
257
|
+
| `getOperationAvailability()` / `getZoomState()` / `getSearchState()` | Reads current capability, zoom, and search state for custom toolbars. |
|
|
258
|
+
|
|
259
|
+
## Workers, WASM, And Private Deployment
|
|
260
|
+
|
|
261
|
+
| Asset | Description |
|
|
262
|
+
| --- | --- |
|
|
263
|
+
| Shared viewer assets | The Pure Web package ships `file-viewer-copy-assets` to copy workers, WASM, vendor files, and examples into your static directory. |
|
|
264
|
+
| CAD / DWG / DXF / DWF | Configure `options.cad.wasmPath`, `workerUrl`, `dwfWasmUrl`, and `dxfEncoding` for self-hosted or intranet deployment. |
|
|
265
|
+
| PDF / DOCX / Excel | Configure `options.pdf.workerUrl`, `options.pdf.cMapUrl`, `options.pdf.wasmUrl`, `options.pdf.standardFontDataUrl`, `options.docx.workerUrl`, `options.docx.workerJsZipUrl`, and `options.spreadsheet.workerUrl`; DOCX Worker parsing is enabled by default, Excel Worker remains explicit opt-in, and header drag column resizing is controlled by `options.spreadsheet.resizableColumns`. |
|
|
266
|
+
| Typst / SQLite / Archive | Configure Typst compiler/renderer WASM, `data.sqlWasmUrl`, and `archive.workerUrl` / `archive.wasmUrl` as needed; Typst renders through local WASM only and never falls back to a public CDN. |
|
|
267
|
+
| Drawing | Draw.io uses the official diagrams.net offline viewer shipped with viewer assets by default; override `options.drawing.viewerScriptUrl` for custom paths, or set `preferOfficial:false` for the built-in SVG fallback. |
|
|
268
|
+
| Offline deployment | Runtime preview code does not depend on public CDN or third-party online assets; `file-viewer-copy-assets` copies PDF, CAD, Typst, SQLite, archive, Draw.io, DOCX worker/JSZip, and Office worker/vendor assets. |
|
|
269
|
+
| Deployment principle | Heavy workers, WASM files, and parser libraries stay lazy-loaded and are only requested when the active file type needs them. |
|
|
270
|
+
|
|
271
|
+
## Quality Gates
|
|
272
|
+
|
|
273
|
+
- Component packages only depend on `@file-viewer/core` and their own ecosystem dependencies. They do not nest through another framework component package.
|
|
274
|
+
- Format parsing, search, zoom, print, export, watermark, lifecycle, and beforeOperation semantics all come from the same core.
|
|
275
|
+
- Releases should pass type checks, component API verification, README generation checks, format-matrix verification, standalone repository export, and browser smoke tests.
|
|
276
|
+
|
|
277
|
+
See the official documentation for options, lifecycle hooks, beforeOperation, theme, watermark, search, zoom, print, and export APIs: https://doc.file-viewer.app/
|
|
278
|
+
|
|
279
|
+
Online demo: https://demo.file-viewer.app/. License: Apache-2.0. For second development or commercial use, keep clear Flyfish Viewer attribution; shared compatibility fixes are welcome in the matching component repository.
|
|
280
|
+
<!-- FILE_VIEWER_GENERATED:END -->
|
package/README.md
ADDED
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
# @file-viewer/react-full
|
|
2
|
+
|
|
3
|
+
完整格式能力的 React 集成包。构建后会由仓库脚本同步完整 README。
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm install @file-viewer/react-full
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
<!-- FILE_VIEWER_GENERATED:START -->
|
|
10
|
+
## 生态包矩阵
|
|
11
|
+
|
|
12
|
+
所有标准组件包都只共享 `@file-viewer/core` 这个总底座，不依赖其他框架组件实现。core 负责格式矩阵、资源解析、renderer 协议、事件、操作 API、搜索、缩放、打印和导出；PDF、Word、PPTX、CAD、Typst 等重型链路通过独立 renderer 或 preset 显式装配；各框架组件包自己维护本地 controller、组件生命周期、类型出口和生态交互。
|
|
13
|
+
|
|
14
|
+
| 框架 | 标准 npm 包 | 入口格式 | GitHub | Gitee | 兼容历史包 |
|
|
15
|
+
| --- | --- | --- | --- | --- | --- |
|
|
16
|
+
| Vanilla JS / Pure Web | `@file-viewer/web` | ESM, 类型声明, script 标签 IIFE, Worker/WASM viewer 资源, 复制静态资源 CLI | [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` |
|
|
17
|
+
| Vanilla JS / Pure Web Full | `@file-viewer/web-full` | ESM, 类型声明, script 标签 IIFE | [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) | 无 |
|
|
18
|
+
| 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` |
|
|
19
|
+
| 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) | 无 |
|
|
20
|
+
| 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` |
|
|
21
|
+
| 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) | 无 |
|
|
22
|
+
| 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) | 无 |
|
|
23
|
+
| 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) | 无 |
|
|
24
|
+
| 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` |
|
|
25
|
+
| 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) | 无 |
|
|
26
|
+
| 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) | 无 |
|
|
27
|
+
| 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) | 无 |
|
|
28
|
+
| 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) | 无 |
|
|
29
|
+
| 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) | 无 |
|
|
30
|
+
| 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) | 无 |
|
|
31
|
+
| 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) | 无 |
|
|
32
|
+
|
|
33
|
+
## 格式支持矩阵
|
|
34
|
+
|
|
35
|
+
共享格式矩阵当前覆盖 24 条预览链路、206 个扩展名。完整能力通过 renderer / preset 按需装配，组件层只做生态适配，不互相嵌套。
|
|
36
|
+
|
|
37
|
+
| 预览链路 | 分类 | 扩展名 | 能力 | 加载 |
|
|
38
|
+
| --- | --- | --- | --- | --- |
|
|
39
|
+
| Word OpenXML | office | `.docx`, `.docm`, `.dotx`, `.dotm` | 下载, 打印(适配器), HTML(适配器), 缩放(Provider), 搜索 | 按需异步 |
|
|
40
|
+
| Word Binary | office | `.doc`, `.dot` | 下载, 打印(适配器), HTML(适配器), 缩放(Provider), 搜索 | 按需异步 |
|
|
41
|
+
| PowerPoint | office | `.pptx`, `.pptm`, `.potx`, `.potm`, `.ppsx`, `.ppsm` | 下载, 打印, HTML, 缩放(Provider), 搜索 | 按需异步 |
|
|
42
|
+
| Open Document | office | `.rtf`, `.odt`, `.odp` | 下载, 打印, HTML, 缩放(Provider), 搜索 | 按需异步 |
|
|
43
|
+
| Spreadsheet | office | `.xlsx`, `.xltx`, `.xlsm`, `.xlsb`, `.xls`, `.xlt`, `.xltm`, `.csv`, `.ods`, `.fods`, `.numbers` | 下载, 缩放(Provider), 搜索 | 按需异步 |
|
|
44
|
+
| PDF | document | `.pdf` | 下载, 打印(适配器), HTML(适配器), 缩放(Provider), 搜索(Provider) | 按需异步 |
|
|
45
|
+
| OFD | document | `.ofd` | 下载, 打印, HTML, 缩放(Provider), 搜索 | 按需异步 |
|
|
46
|
+
| Typst | document | `.typ`, `.typst` | 下载, 打印(适配器), HTML(适配器), 缩放(Provider), 搜索 | 按需异步 |
|
|
47
|
+
| 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` | 下载, 搜索 | 按需异步 |
|
|
48
|
+
| Email | email | `.eml`, `.msg`, `.mbox` | 下载, HTML, 搜索 | 按需异步 |
|
|
49
|
+
| EDA | eda | `.olb`, `.dra`, `.gds`, `.oas`, `.oasis` | 下载, 打印, HTML, 搜索 | 按需异步 |
|
|
50
|
+
| CAD | cad | `.dxf`, `.dwg`, `.dwf`, `.dwfx`, `.xps` | 下载, 打印, HTML, 缩放(Provider) | 按需异步 |
|
|
51
|
+
| 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` | 下载, 缩放(Provider) | 按需异步 |
|
|
52
|
+
| Geospatial | geo | `.geojson`, `.kml`, `.gpx`, `.shp` | 下载, 打印, HTML, 缩放(Provider), 搜索 | 按需异步 |
|
|
53
|
+
| Drawing | drawing | `.excalidraw`, `.drawio`, `.dio`, `.mermaid`, `.mmd`, `.plantuml`, `.puml` | 下载, 打印, HTML, 缩放(Provider), 搜索 | 按需异步 |
|
|
54
|
+
| Mind Map | mindmap | `.xmind` | 下载, 打印, HTML, 缩放(Provider), 搜索 | 按需异步 |
|
|
55
|
+
| EPUB | ebook | `.epub` | 下载, HTML, 搜索(Provider) | 按需异步 |
|
|
56
|
+
| UMD | ebook | `.umd` | 下载, 打印, HTML, 缩放(Provider), 搜索 | 按需异步 |
|
|
57
|
+
| Image | image | `.gif`, `.jpg`, `.jpeg`, `.bmp`, `.tiff`, `.tif`, `.png`, `.svg`, `.webp`, `.avif`, `.ico`, `.heic`, `.heif`, `.jxl` | 下载, 打印, HTML, 缩放(Provider) | 按需异步 |
|
|
58
|
+
| Markdown | markdown | `.md`, `.markdown` | 下载, 打印, HTML, 搜索 | 按需异步 |
|
|
59
|
+
| Code and Text | code | `.txt`, `.json`, `.js`, `.mjs`, `.cjs`, `.css`, `.java`, `.py`, `.html`, `.htm`, `.jsx`, `.ts`, `.tsx`, `.xml`, `.log`, `.vue`, `.yaml`, `.yml`, `.ini`, `.sh`, `.bash`, `.sql`, `.go`, `.rs`, `.php`, `.c`, `.cpp`, `.cc`, `.h`, `.hpp`, `.cs`, `.diff`, `.patch`, `.bundle`, `.bdl`, `.jsonc`, `.json5`, `.ipynb`, `.toml`, `.proto`, `.hcl`, `.tex`, `.gv`, `.http`, `.react`, `.rb`, `.swift`, `.kt` | 下载, 打印, HTML, 搜索 | 按需异步 |
|
|
60
|
+
| Video | media | `.mp4`, `.webm`, `.m3u8` | 下载 | 按需异步 |
|
|
61
|
+
| Audio | media | `.mp3`, `.mpeg`, `.wav`, `.ogg`, `.oga`, `.opus`, `.m4a`, `.aac`, `.flac`, `.weba`, `.midi`, `.mid` | 下载 | 按需异步 |
|
|
62
|
+
| Data Asset | asset | `.ttf`, `.otf`, `.woff`, `.woff2`, `.psd`, `.ai`, `.eps`, `.sqlite`, `.wasm`, `.parquet`, `.avro`, `.webarchive` | 下载, HTML, 搜索 | 按需异步 |
|
|
63
|
+
|
|
64
|
+
## 工程级按需 renderer 装配
|
|
65
|
+
|
|
66
|
+
一个组件，一行代码，快速集成；真正影响安装体积和首屏包体的是 renderer 装配。推荐先安装当前生态组件包，再按产品形态选择 `@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 并复制离线资产。
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
npm i @file-viewer/react-full @file-viewer/preset-office
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
import officePreset from '@file-viewer/preset-office'
|
|
74
|
+
|
|
75
|
+
const options = {
|
|
76
|
+
preset: officePreset,
|
|
77
|
+
rendererMode: 'replace'
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
需要组合办公文档与工程图纸等能力时，继续使用同一个 `preset` 字段传数组即可：
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
import officePreset from '@file-viewer/preset-office'
|
|
85
|
+
import engineeringPreset from '@file-viewer/preset-engineering'
|
|
86
|
+
|
|
87
|
+
const options = {
|
|
88
|
+
preset: [officePreset, engineeringPreset],
|
|
89
|
+
rendererMode: 'replace'
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
如果只需要少数格式，也可以安装单 renderer 并传给 `options.renderers`：
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
import { pdfRenderer } from '@file-viewer/renderer-pdf'
|
|
97
|
+
|
|
98
|
+
const options = {
|
|
99
|
+
renderers: [pdfRenderer],
|
|
100
|
+
rendererMode: 'replace'
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Vite 项目可以再加插件，插件会免配置发现已安装 preset、注入 virtual module，并按命中格式复制 Worker / WASM / 字体 / vendor 资源：
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
npm i -D @file-viewer/vite-plugin
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
import { fileViewerRenderers } from '@file-viewer/vite-plugin'
|
|
112
|
+
|
|
113
|
+
export default {
|
|
114
|
+
plugins: [
|
|
115
|
+
fileViewerRenderers({
|
|
116
|
+
copyAssets: true
|
|
117
|
+
// 无需 preset 配置：插件会自动发现已安装的 @file-viewer/preset-office。
|
|
118
|
+
})
|
|
119
|
+
]
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
重度用户需要一次拥有官方 Demo 的完整能力时，直接把 preset 换成全量包；非 Vite 项目继续传 `options.preset`，Vite 配置也保持不变：
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
npm i @file-viewer/react-full @file-viewer/preset-all
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
需要自定义装配时，再显式配置插件：
|
|
130
|
+
|
|
131
|
+
```ts
|
|
132
|
+
fileViewerRenderers({
|
|
133
|
+
preset: 'auto', // 同时开启源码扫描时，仍自动发现已安装 preset
|
|
134
|
+
scan: true, // 识别 fileViewerFormats、data-file-viewer-formats、accept
|
|
135
|
+
formats: ['pdf'], // 在已安装 preset 之外额外补充精确 renderer
|
|
136
|
+
copyAssets: true,
|
|
137
|
+
chunkStrategy: 'renderer'
|
|
138
|
+
})
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
严格裁剪或组件库内部测试时，可以关闭自动注入并显式传入 virtual module：
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
// vite.config.ts
|
|
145
|
+
fileViewerRenderers({ formats: ['pdf'], inject: false, copyAssets: true })
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
```ts
|
|
149
|
+
// 业务组件入口
|
|
150
|
+
import { configuredFileViewerRenderers } from 'virtual:file-viewer-renderers'
|
|
151
|
+
|
|
152
|
+
const options = {
|
|
153
|
+
renderers: configuredFileViewerRenderers,
|
|
154
|
+
rendererMode: 'replace'
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
- Vue、React、Svelte、jQuery、Vanilla JS / Pure Web 都传同一份 `options`，只是在各自生态中映射为 props、hook、action、plugin 或 `mountViewer(...)` 参数。
|
|
159
|
+
- `preset-lite` 面向文本、Markdown、代码、图片和音视频；`preset-office` 面向 PDF / Word / Excel / PowerPoint / OFD；`preset-engineering` 面向 CAD / 3D / 绘图 / XMind / Geo / Typst / EDA / Data。
|
|
160
|
+
- 想要最小包体时，可以不用 preset，直接安装 `@file-viewer/renderer-pdf`、`@file-viewer/renderer-word` 等单个 renderer，并通过 `options.renderers` 手动注入。
|
|
161
|
+
- `fileViewerRenderers()` 或 `fileViewerRenderers({ copyAssets:true })` 会免配置自动发现已安装 preset；如果同时开启 `scan:true`，请使用 `preset:'auto'` 或 `autoPresets:true` 保留 preset 自动发现。
|
|
162
|
+
- `scan:true` 会识别 `fileViewerFormats`、`data-file-viewer-formats` 和上传控件 `accept`，调试与打包时自动选择 renderer。
|
|
163
|
+
- `copyAssets:true` 会复制 PDF/CAD/Typst/Archive/Data 等 worker、WASM 和 vendor 资源，满足离线和企业内网部署。
|
|
164
|
+
- `builtinRenderers` 仍可用于高级基线控制或历史兼容；普通快速接入只需要 `preset` / `renderers` 与 `rendererMode`。
|
|
165
|
+
- 如果打开的是支持矩阵内但未装配的格式，预览器会提示应安装的 preset / renderer；只有真正不在矩阵中的扩展名才提示不支持。
|
|
166
|
+
- `@file-viewer/preset-all` 是全量一键方案，适合 demo、后台运维工具和企业全格式附件中心；普通业务仍建议优先选择更窄的 preset。
|
|
167
|
+
|
|
168
|
+
## 统一参数与事件
|
|
169
|
+
|
|
170
|
+
所有生态组件都围绕同一套 `ViewerMountOptions` 与 `FileViewerOptions` 工作，只是映射到各自框架的 props、事件、ref、action 或插件 API。
|
|
171
|
+
|
|
172
|
+
| 参数 | 说明 |
|
|
173
|
+
| --- | --- |
|
|
174
|
+
| `url` | 远程文件地址，适合对象存储、业务接口或内网文件服务返回的文件链接。 |
|
|
175
|
+
| `file` | `File`、`Blob` 或 `ArrayBuffer`，适合上传、本地选择和业务接口已取回的二进制。 |
|
|
176
|
+
| `buffer` | 直接传入 `ArrayBuffer`，适合解密、鉴权或自定义下载后再预览。 |
|
|
177
|
+
| `name` / `filename` | 显示文件名并辅助推断扩展名；当 URL 不含扩展名时建议显式传入。 |
|
|
178
|
+
| `type` | 显式指定扩展名或 MIME 线索，覆盖自动识别结果。 |
|
|
179
|
+
| `size` | 文件大小提示，用于生命周期上下文、加载状态和安全限制展示。 |
|
|
180
|
+
| `options` | 完整 `FileViewerOptions`，所有框架包保持同一套参数语义。 |
|
|
181
|
+
| `onEvent` / `onStateChange` | Vanilla JS / Pure Web、React、Svelte 等命令式包装层的统一事件和状态订阅；Vue 组件会映射为原生 emit。 |
|
|
182
|
+
|
|
183
|
+
## 实际组件属性
|
|
184
|
+
|
|
185
|
+
下面列的是每个标准组件包当前真实暴露的属性、事件和控制入口。需要 `buffer`、`name`、`type`、`size` 这类命令式挂载参数时，优先选择 Vanilla JS / Pure Web、React、Svelte、jQuery 或 Vue2 组件；Vue3 声明式组件保持 `url` / `file` / `options` 的简洁入口，复杂二进制来源请包装成带文件名的 `File`。
|
|
186
|
+
|
|
187
|
+
| 组件 | 实际属性 / 入口 | 事件入口 | 定制入口 |
|
|
188
|
+
| --- | --- | --- | --- |
|
|
189
|
+
| 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。 |
|
|
190
|
+
| Vue 3 `@file-viewer/vue3` | `url`、`file`、`options` | `load-start`、`load-complete`、`unload-start`、`unload-complete`、`operation-before`、`operation-cancel`、`operation-availability-change`、`search-change`、`location-change`、`zoom-change` | 模板 `ref` 暴露 `FileViewerExpose`；适合声明式接入。`Blob` / `ArrayBuffer` 建议包装成带扩展名的 `File` 后传给 `file`。 |
|
|
191
|
+
| 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` 平滑升级。 |
|
|
192
|
+
| Vue 2.6 `@file-viewer/vue2.6` | 同 Vue 2.7 | `viewer-event` / `viewerEvent` | 独立 Vue 2.6 构建，不要求业务升级到 Vue 2.7。 |
|
|
193
|
+
| React `@file-viewer/react` | `ViewerMountOptions` + `div` 原生属性，如 `className`、`style`、`data-*`、`aria-*` | `onEvent`、`onStateChange` | `ref` 暴露 `FileViewerHandle`；`useFileViewer()` 会返回 `ref`、`props`、`state`、`handle`，便于自定义工具栏。 |
|
|
194
|
+
| React Legacy `@file-viewer/react-legacy` | 同 React 标准包 | `onEvent`、`onStateChange` | 面向 React 16.8 / 17；组件名和默认导出保持 legacy 生态友好。 |
|
|
195
|
+
| jQuery `@file-viewer/jquery` | `$(el).fileViewer(ViewerMountOptions & { replace?: boolean })` | `onEvent`、`onStateChange` 或 `getFileViewerController(el).subscribe()` | 插件方法支持 `zoomIn`、`printRenderedHtml`、`searchDocument` 等；`replace:false` 可在同一节点上原地更新。 |
|
|
196
|
+
| Svelte `@file-viewer/svelte` | `ViewerMountOptions` + `className`、`containerStyle` | `on:viewerEvent`、`onEvent`、`onStateChange` | `bind:this` 暴露 controller handle；也提供 `use:fileViewer` action，action 额外支持 `replace`。 |
|
|
197
|
+
|
|
198
|
+
| Options 字段 | 说明 |
|
|
199
|
+
| --- | --- |
|
|
200
|
+
| `theme` | `light`、`dark` 或 `system`，优先级高于浏览器 `prefers-color-scheme`。 |
|
|
201
|
+
| `watermark` | 开启文字或图片水印，可设置透明度、旋转、间距、尺寸、字体和颜色。 |
|
|
202
|
+
| `toolbar` | 控制下载、打印、HTML 导出、缩放和工具栏位置，并支持操作级前置校验。 |
|
|
203
|
+
| `search` | 配置文档搜索、高亮 class、大小写、整词匹配、最大命中数和 debounce。 |
|
|
204
|
+
| `ai` | 控制文本结构采集、分块大小和最大文本长度，为溯源、定位、向量化和外部 AI 流程提供基础。 |
|
|
205
|
+
| `archive` | 配置压缩包 Worker/WASM、超时、缓存、包体限制和压缩包内单文件预览大小。 |
|
|
206
|
+
| `pdf` | 配置 PDF.js Worker、导航栏、目录、缩略图、旋转、流式读取、Range chunk 和凭据。 |
|
|
207
|
+
| `docx` / `spreadsheet` | DOCX 由 @file-viewer/renderer-word 承接并使用自研 @file-viewer/docx，默认 Worker 解析、连续流式阅读和异步分批渲染，可按需显式开启视觉分页；表格由 @file-viewer/renderer-spreadsheet 承接，默认保真主线程渲染，Worker 和表头拖拽调列宽均可按需显式开启。 |
|
|
208
|
+
| `typst` / `data` / `cad` | 配置 Typst、SQLite、CAD/DWG/DXF/DWF 等 WASM、Worker、编码和渲染策略。 |
|
|
209
|
+
| `hooks` / `beforeOperation` | 统一生命周期 hooks 和操作前置校验，可用于审计、权限、埋点和安全控制。 |
|
|
210
|
+
|
|
211
|
+
## 工具栏定制
|
|
212
|
+
|
|
213
|
+
| 配置 | 说明 |
|
|
214
|
+
| --- | --- |
|
|
215
|
+
| `toolbar: false` | 隐藏内置工具栏，但不关闭下载、打印、导出、缩放等 controller API，适合完全自定义业务工具栏。 |
|
|
216
|
+
| `toolbar: true` | 使用默认内置工具栏，下载、打印、HTML 导出和缩放按钮都会按能力动态显隐。 |
|
|
217
|
+
| `download` / `print` / `exportHtml` / `zoom` | 表达业务是否允许展示对应按钮；最终仍会结合文件类型、渲染完成状态、导出适配器和缩放 provider 计算真实可用性。 |
|
|
218
|
+
| `position` | `auto`、`top`、`bottom-right`。默认 `auto`，PDF 自动悬浮右下角，减少和 PDF 自身页码 / 目录工具栏冲突。 |
|
|
219
|
+
| `beforeOperation` | 工具栏层统一前置校验，会在 `options.beforeOperation` 后执行。返回 `false` 或抛错都会取消本次操作。 |
|
|
220
|
+
| `beforeDownload` / `beforePrint` / `beforeExportHtml` | 单按钮前置校验；适合下载权限、打印审计、导出水印确认等细粒度业务规则。 |
|
|
221
|
+
|
|
222
|
+
完全自定义工具栏时，推荐关闭内置工具栏并使用组件 ref / controller 暴露的标准 API。不要在预览器外层用 CSS `transform: scale()` 做缩放；PDF、Excel、CAD、canvas 和文本层格式都应通过内部缩放 provider 保持坐标正确。
|
|
223
|
+
|
|
224
|
+
| 生态 | 推荐方式 |
|
|
225
|
+
| --- | --- |
|
|
226
|
+
| 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()` 同步状态。 |
|
|
227
|
+
| Vue 3 | 传 `:options="{ toolbar: false }"` 隐藏内置工具栏，通过模板 `ref` 调用 `downloadOriginalFile()`、`printRenderedHtml()`、`exportRenderedHtml()`、`zoomIn()`、`zoomOut()`、`resetZoom()`；用 `@operation-availability-change` 和 `@zoom-change` 同步按钮显隐与比例。 |
|
|
228
|
+
| Vue 2.7 / 2.6 | 同样设置 `toolbar:false`，通过 `$refs.viewer` 调用实例方法；监听 `@viewer-event`，在 `event.type === "operation-availability-change"` 或 `event.type === "zoom-change"` 时更新外部工具栏。 |
|
|
229
|
+
| React / React Legacy | 推荐 `useFileViewer({ options:{ toolbar:false } })`，把 `viewer.props` 传给组件，把按钮绑定到 `viewer.handle`，并读取 `viewer.state.availability` / `viewer.state.zoom` 控制禁用状态。 |
|
|
230
|
+
| jQuery | `$("#viewer").fileViewer({ options:{ toolbar:false } })`；按钮调用 `$("#viewer").fileViewer("zoomIn")` 或通过 `getFileViewerController($("#viewer")).subscribe()` 获取能力状态。 |
|
|
231
|
+
| Svelte | `<FileViewer bind:this={viewer} options={{ toolbar:false }} />`；按钮直接调用 `viewer.zoomIn()`、`viewer.printRenderedHtml()`，并用 `on:viewerEvent` / `onStateChange` 同步状态。 |
|
|
232
|
+
|
|
233
|
+
## 生命周期与操作事件
|
|
234
|
+
|
|
235
|
+
| 事件 / hook | 说明 |
|
|
236
|
+
| --- | --- |
|
|
237
|
+
| `load-start` / `hooks.onLoadStart` | 开始解析或下载文档时触发，包含文件名、类型、来源、版本、URL、File 和 size。 |
|
|
238
|
+
| `load-complete` / `hooks.onLoadComplete` | 当前文档完成渲染时触发，包含耗时、来源上下文和版本号。 |
|
|
239
|
+
| `unload-start` / `hooks.onUnloadStart` | 替换、重置或组件卸载前触发，可用于保存状态或释放外部资源。 |
|
|
240
|
+
| `unload-complete` / `hooks.onUnloadComplete` | 旧文档释放完成后触发，reason 会标识 `replace`、`reset` 或 `component-unmount`。 |
|
|
241
|
+
| `operation-before` / `operation-cancel` | 下载、打印、HTML 导出和缩放前后触发；`beforeOperation` 返回 `false` 可取消操作。 |
|
|
242
|
+
| `operation-availability-change` | 当前格式是否可下载、可打印、可导出 HTML、可缩放发生变化时触发。 |
|
|
243
|
+
| `search-change` / `location-change` / `zoom-change` | 搜索命中、定位锚点和缩放状态变化时触发，用于外层同步 UI。 |
|
|
244
|
+
|
|
245
|
+
## 公共操作 API
|
|
246
|
+
|
|
247
|
+
| API | 说明 |
|
|
248
|
+
| --- | --- |
|
|
249
|
+
| `load` / `update` / `reload` / `destroy` | 命令式控制文档加载、参数更新、重新加载和销毁。 |
|
|
250
|
+
| `downloadOriginalFile()` | 下载原始文件，遵循 toolbar 与 `beforeOperation` 权限校验。 |
|
|
251
|
+
| `printRenderedHtml()` | 打印当前完整渲染内容，优先使用各格式的高保真打印适配器。 |
|
|
252
|
+
| `exportRenderedHtml()` | 导出当前渲染后的 HTML，用于归档、审计和离线查看。 |
|
|
253
|
+
| `zoomIn()` / `zoomOut()` / `resetZoom()` | 调用当前格式自己的缩放 provider，避免外层 CSS 缩放导致坐标偏移。 |
|
|
254
|
+
| `searchDocument()` / `nextSearchResult()` / `previousSearchResult()` | 打开文档级搜索并在命中之间导航，保持高亮状态。 |
|
|
255
|
+
| `collectDocumentAnchors()` / `scrollToAnchor()` / `scrollToLine()` | 采集页面、目录、标题或代码行锚点，并执行定位跳转。 |
|
|
256
|
+
| `getDocumentTextChunks()` | 获取结构化文本块，便于搜索、AI 溯源、向量化和外部索引。 |
|
|
257
|
+
| `getOperationAvailability()` / `getZoomState()` / `getSearchState()` | 读取当前能力、缩放和搜索状态，便于自定义工具栏。 |
|
|
258
|
+
|
|
259
|
+
## Worker、WASM 与私有化部署
|
|
260
|
+
|
|
261
|
+
| 资源 | 说明 |
|
|
262
|
+
| --- | --- |
|
|
263
|
+
| 通用 viewer assets | Pure Web 包提供 `file-viewer-copy-assets`，可把 Worker、WASM、vendor 和示例资源复制到业务静态目录。 |
|
|
264
|
+
| CAD / DWG / DXF / DWF | 按需配置 `options.cad.wasmPath`、`workerUrl`、`dwfWasmUrl`、`dxfEncoding`，支持自托管和内网部署。 |
|
|
265
|
+
| PDF / DOCX / Excel | 按需配置 `options.pdf.workerUrl`、`options.pdf.cMapUrl`、`options.pdf.wasmUrl`、`options.pdf.standardFontDataUrl`、`options.docx.workerUrl`、`options.docx.workerJsZipUrl`、`options.spreadsheet.workerUrl`；DOCX 默认启用自研 Worker 解析，Excel Worker 需显式开启，列宽拖拽可通过 `options.spreadsheet.resizableColumns` 显式开启。 |
|
|
266
|
+
| Typst / SQLite / Archive | 按需配置 Typst compiler/renderer WASM、`data.sqlWasmUrl`、`archive.workerUrl` / `archive.wasmUrl`；Typst 仅使用本地 WASM 真实渲染，不访问公共 CDN。 |
|
|
267
|
+
| Drawing | Draw.io 默认使用随 viewer assets 分发的官方 diagrams.net 离线 viewer；路径特殊时可通过 `options.drawing.viewerScriptUrl` 覆盖，`preferOfficial:false` 才切到内置 SVG 兜底。 |
|
|
268
|
+
| 离线部署 | 运行时不依赖公共 CDN 或第三方在线资源；`file-viewer-copy-assets` 会复制 PDF、CAD、Typst、SQLite、压缩包、Draw.io、DOCX worker/JSZip 和 Office worker/vendor 资产。 |
|
|
269
|
+
| 部署原则 | 默认只在命中特定格式时异步加载对应依赖；没有命中的格式不会拉取重型 Worker、WASM 或解析库。 |
|
|
270
|
+
|
|
271
|
+
## 质量门禁
|
|
272
|
+
|
|
273
|
+
- 组件包只依赖 `@file-viewer/core` 和自身生态依赖，不嵌套引用其他框架组件包。
|
|
274
|
+
- 格式解析、搜索、缩放、打印、导出、水印、生命周期和 beforeOperation 语义全部来自同一个 core。
|
|
275
|
+
- 发布前需通过类型检查、组件 API 校验、README 生成校验、格式矩阵校验、独立仓库导出和浏览器 smoke。
|
|
276
|
+
|
|
277
|
+
完整参数、生命周期 hooks、beforeOperation、主题、水印、搜索、缩放、打印和导出说明见官方文档: https://doc.file-viewer.app/
|
|
278
|
+
|
|
279
|
+
在线 Demo: https://demo.file-viewer.app/ 。License: Apache-2.0。二开或商用请保留 Flyfish Viewer 来源说明；如果修复了通用兼容问题，也欢迎贡献回对应组件仓库。
|
|
280
|
+
<!-- FILE_VIEWER_GENERATED:END -->
|
package/dist/index.d.ts
ADDED
package/dist/index.js
ADDED
package/package.json
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@file-viewer/react-full",
|
|
3
|
+
"version": "2.1.3",
|
|
4
|
+
"private": false,
|
|
5
|
+
"type": "module",
|
|
6
|
+
"description": "Full React package for Flyfish File Viewer with the complete preset enabled by default.",
|
|
7
|
+
"keywords": [
|
|
8
|
+
"file-viewer",
|
|
9
|
+
"document-preview",
|
|
10
|
+
"react",
|
|
11
|
+
"full-preset",
|
|
12
|
+
"office-preview",
|
|
13
|
+
"cad-viewer",
|
|
14
|
+
"document-viewer",
|
|
15
|
+
"file-preview",
|
|
16
|
+
"self-hosted"
|
|
17
|
+
],
|
|
18
|
+
"publishConfig": {
|
|
19
|
+
"access": "public",
|
|
20
|
+
"registry": "https://registry.npmjs.org/"
|
|
21
|
+
},
|
|
22
|
+
"author": {
|
|
23
|
+
"name": "Wangyu",
|
|
24
|
+
"email": "wybaby168@gmail.com"
|
|
25
|
+
},
|
|
26
|
+
"repository": {
|
|
27
|
+
"type": "git",
|
|
28
|
+
"url": "git+https://github.com/flyfish-dev/file-viewer-react-full.git",
|
|
29
|
+
"directory": "packages/components/react-full"
|
|
30
|
+
},
|
|
31
|
+
"homepage": "https://doc.file-viewer.app/",
|
|
32
|
+
"bugs": {
|
|
33
|
+
"url": "https://github.com/flyfish-dev/file-viewer-react-full/issues"
|
|
34
|
+
},
|
|
35
|
+
"funding": {
|
|
36
|
+
"type": "individual",
|
|
37
|
+
"url": "https://dev.flyfish.group/shop"
|
|
38
|
+
},
|
|
39
|
+
"main": "./dist/index.js",
|
|
40
|
+
"module": "./dist/index.js",
|
|
41
|
+
"types": "./dist/index.d.ts",
|
|
42
|
+
"exports": {
|
|
43
|
+
".": {
|
|
44
|
+
"types": "./dist/index.d.ts",
|
|
45
|
+
"import": "./dist/index.js",
|
|
46
|
+
"default": "./dist/index.js"
|
|
47
|
+
},
|
|
48
|
+
"./package.json": "./package.json"
|
|
49
|
+
},
|
|
50
|
+
"files": [
|
|
51
|
+
"dist",
|
|
52
|
+
"README.md",
|
|
53
|
+
"README.en.md"
|
|
54
|
+
],
|
|
55
|
+
"peerDependencies": {
|
|
56
|
+
"react": ">=17 <20"
|
|
57
|
+
},
|
|
58
|
+
"dependencies": {
|
|
59
|
+
"@file-viewer/preset-all": "^2.1.3",
|
|
60
|
+
"@file-viewer/react": "^2.1.3"
|
|
61
|
+
},
|
|
62
|
+
"devDependencies": {
|
|
63
|
+
"@types/react": "^19.2.17",
|
|
64
|
+
"react": "^19.2.7",
|
|
65
|
+
"typescript": "^6.0.3"
|
|
66
|
+
},
|
|
67
|
+
"license": "Apache-2.0",
|
|
68
|
+
"scripts": {
|
|
69
|
+
"build": "tsc -b tsconfig.json",
|
|
70
|
+
"type-check": "tsc -b tsconfig.json"
|
|
71
|
+
}
|
|
72
|
+
}
|