@file-viewer/react 2.1.24 → 2.1.26
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 +7 -4
- package/README.md +7 -4
- package/package.json +2 -2
package/README.en.md
CHANGED
|
@@ -212,7 +212,7 @@ The table below lists the real props, event channel, and customization entry for
|
|
|
212
212
|
| Component | Actual props / entry | Event channel | Customization entry |
|
|
213
213
|
| --- | --- | --- | --- |
|
|
214
214
|
| 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. |
|
|
215
|
-
| 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` | Template refs expose `FileViewerExpose`. For `Blob` / `ArrayBuffer`, prefer wrapping it as a named `File` so extension detection stays deterministic. |
|
|
215
|
+
| 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. |
|
|
216
216
|
| 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. |
|
|
217
217
|
| 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. |
|
|
218
218
|
| 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. |
|
|
@@ -225,7 +225,7 @@ The table below lists the real props, event channel, and customization entry for
|
|
|
225
225
|
| `theme` | `light`, `dark`, or `system`. This takes precedence over browser `prefers-color-scheme`. |
|
|
226
226
|
| `styleIsolation` | `auto`, `shadow`, `scoped`, or `none`. With `auto`, Web Component / full / IIFE entries use Shadow DOM by default; Vue, React, Svelte, and jQuery keep light-DOM compatibility unless renderer content is explicitly isolated with `shadow`. |
|
|
227
227
|
| `watermark` | Text or image watermark with opacity, rotation, gap, size, font, and color controls. |
|
|
228
|
-
| `toolbar` | Controls download, print, HTML export, zoom, toolbar position, and operation-level preflight checks. |
|
|
228
|
+
| `toolbar` | Controls the theme toggle, download, print, HTML export, zoom, item order, toolbar position, and operation-level preflight checks. |
|
|
229
229
|
| `search` | Document search, highlight class names, case sensitivity, whole-word matching, max matches, and debounce. |
|
|
230
230
|
| `ai` | Text collection, chunk size, and max text length for provenance, location, vectorization, and external AI workflows. |
|
|
231
231
|
| `archive` | Archive Worker/WASM URLs, timeout, cache, archive limits, nested entry preview limits, and legacy GBK/GB18030 ZIP filename decoding. |
|
|
@@ -280,8 +280,10 @@ const options = {
|
|
|
280
280
|
| Config | Description |
|
|
281
281
|
| --- | --- |
|
|
282
282
|
| `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. |
|
|
283
|
-
| `toolbar: true` | Uses the default built-in toolbar.
|
|
283
|
+
| `toolbar: true` | Uses the default built-in toolbar. The theme toggle is visible by default; download, print, HTML export, and zoom remain capability-aware. |
|
|
284
284
|
| `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. |
|
|
285
|
+
| `theme` | Controls the light/dark toggle and defaults to `true`. A change emits `theme-change`; set it to `false` to hide the button. |
|
|
286
|
+
| `order` | Orders built-in groups with `search`, `zoom`, `download`, `print`, `exportHtml`, and `theme`. Omitted items keep their default relative order. |
|
|
285
287
|
| `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. |
|
|
286
288
|
| `beforeOperation` | Toolbar-level preflight that runs after `options.beforeOperation`. Returning `false` or throwing cancels the operation. |
|
|
287
289
|
| `beforeDownload` / `beforePrint` / `beforeExportHtml` | Operation-specific preflight for download permission, print audit, export confirmation, and similar business rules. |
|
|
@@ -311,6 +313,7 @@ View-state sync is designed for projection systems, remote-control displays, sid
|
|
|
311
313
|
| `unload-complete` / `hooks.onUnloadComplete` | Fires after the previous document is released. The reason is `replace`, `reset`, or `component-unmount`. |
|
|
312
314
|
| `operation-before` / `operation-cancel` | Fires around download, print, HTML export, and zoom actions. Returning `false` from `beforeOperation` cancels the action. |
|
|
313
315
|
| `operation-availability-change` | Fires when download, print, HTML export, or zoom support changes for the active format. |
|
|
316
|
+
| `theme-change` | Fires when the built-in control selects light or dark mode. The payload is `light` or `dark`. |
|
|
314
317
|
| `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. |
|
|
315
318
|
|
|
316
319
|
## Public Operation API
|
|
@@ -334,7 +337,7 @@ View-state sync is designed for projection systems, remote-control displays, sid
|
|
|
334
337
|
| --- | --- |
|
|
335
338
|
| Shared viewer assets | The Pure Web package ships `file-viewer-copy-assets` to copy workers, WASM, vendor files, and examples into your static directory. |
|
|
336
339
|
| CAD / DWG / DXF / DWF | Configure `options.cad.wasmPath`, `workerUrl`, `dwfWasmUrl`, and `dxfEncoding` for self-hosted or intranet deployment. |
|
|
337
|
-
| PDF / DOCX / Excel / PPTX | Configure `options.pdf.workerUrl`, `options.pdf.cMapUrl`, `options.pdf.wasmUrl`, `options.pdf.standardFontDataUrl`, `options.docx.workerUrl`, `options.docx.workerJsZipUrl`, `options.spreadsheet.workerUrl`, and `options.presentation.workerUrl` / `options.presentation.workerType`; PDF probes the real static worker first and lazy-loads the packaged handler when unavailable; DOCX chooses worker or main-thread parsing automatically, Electron `file://` and other unsafe local protocols fall back without user configuration; Excel defaults to `worker: auto`, enabling Worker automatically for files at or above `workerAutoThreshold`, and header drag column resizing is controlled by `options.spreadsheet.resizableColumns`; PPTX creates a module Worker on demand and can pin the worker URL/type for strict CSP, legacy WebViews, or self-hosted CDNs. |
|
|
340
|
+
| PDF / DOCX / Excel / PPTX | Configure `options.pdf.workerUrl`, `options.pdf.cMapUrl`, `options.pdf.wasmUrl`, `options.pdf.standardFontDataUrl`, `options.pdf.cjkFontFallbackPath`, `options.pdf.identityFontRepair`, `options.docx.workerUrl`, `options.docx.workerJsZipUrl`, `options.spreadsheet.workerUrl`, and `options.presentation.workerUrl` / `options.presentation.workerType`; PDF probes the real static worker first and lazy-loads the packaged handler when unavailable, unembedded CJK fonts fall back to self-hosted Noto Sans SC shards loaded per page, and malformed Identity CJK fonts without ToUnicode are repaired in memory after corrupted text is detected; DOCX chooses worker or main-thread parsing automatically, Electron `file://` and other unsafe local protocols fall back without user configuration; Excel defaults to `worker: auto`, enabling Worker automatically for files at or above `workerAutoThreshold`, and header drag column resizing is controlled by `options.spreadsheet.resizableColumns`; PPTX creates a module Worker on demand and can pin the worker URL/type for strict CSP, legacy WebViews, or self-hosted CDNs. |
|
|
338
341
|
| 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; Archive decodes legacy GBK/GB18030 ZIP entry names, while RAR, 7z, and encrypted archives still require the libarchive Worker/WASM assets. |
|
|
339
342
|
| 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. |
|
|
340
343
|
| 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, PPTX worker, and Office worker/vendor assets. Vue full packages default to `/file-viewer/` as the asset root; call `setDefaultFullAssetBaseUrl()` first when your static prefix differs. |
|
package/README.md
CHANGED
|
@@ -212,7 +212,7 @@ const options = {
|
|
|
212
212
|
| 组件 | 实际属性 / 入口 | 事件入口 | 定制入口 |
|
|
213
213
|
| --- | --- | --- | --- |
|
|
214
214
|
| 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。 |
|
|
215
|
-
| 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` | 模板 `ref` 暴露 `FileViewerExpose`;适合声明式接入。`Blob` / `ArrayBuffer` 建议包装成带扩展名的 `File` 后传给 `file`。 |
|
|
215
|
+
| Vue 3 `@file-viewer/vue3` | `url`、`file`、`options` | `load-start`、`load-complete`、`unload-start`、`unload-complete`、`operation-before`、`operation-cancel`、`operation-availability-change`、`search-change`、`location-change`、`zoom-change`、`view-state-change`、`theme-change` | 模板 `ref` 暴露 `FileViewerExpose`;适合声明式接入。`Blob` / `ArrayBuffer` 建议包装成带扩展名的 `File` 后传给 `file`。 |
|
|
216
216
|
| 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` 平滑升级。 |
|
|
217
217
|
| Vue 2.6 `@file-viewer/vue2.6` | 同 Vue 2.7 | `viewer-event` / `viewerEvent` | 独立 Vue 2.6 构建,不要求业务升级到 Vue 2.7。 |
|
|
218
218
|
| React `@file-viewer/react` | `ViewerMountOptions` + `div` 原生属性,如 `className`、`style`、`data-*`、`aria-*` | `onEvent`、`onStateChange` | `ref` 暴露 `FileViewerHandle`;`useFileViewer()` 会返回 `ref`、`props`、`state`、`handle`,便于自定义工具栏。 |
|
|
@@ -225,7 +225,7 @@ const options = {
|
|
|
225
225
|
| `theme` | `light`、`dark` 或 `system`,优先级高于浏览器 `prefers-color-scheme`。 |
|
|
226
226
|
| `styleIsolation` | `auto`、`shadow`、`scoped` 或 `none`。`auto` 下 Web Component / full / IIFE 默认使用 Shadow DOM;Vue、React、Svelte、jQuery 默认保持 light DOM 兼容,但 renderer 内容可通过 `shadow` 获得独立渲染根。 |
|
|
227
227
|
| `watermark` | 开启文字或图片水印,可设置透明度、旋转、间距、尺寸、字体和颜色。 |
|
|
228
|
-
| `toolbar` |
|
|
228
|
+
| `toolbar` | 控制主题切换、下载、打印、HTML 导出、缩放、按钮顺序和工具栏位置,并支持操作级前置校验。 |
|
|
229
229
|
| `search` | 配置文档搜索、高亮 class、大小写、整词匹配、最大命中数和 debounce。 |
|
|
230
230
|
| `ai` | 控制文本结构采集、分块大小和最大文本长度,为溯源、定位、向量化和外部 AI 流程提供基础。 |
|
|
231
231
|
| `archive` | 配置压缩包 Worker/WASM、超时、缓存、包体限制和压缩包内单文件预览大小;旧 ZIP 中文文件名会自动按 GBK/GB18030 兼容解码。 |
|
|
@@ -280,8 +280,10 @@ const options = {
|
|
|
280
280
|
| 配置 | 说明 |
|
|
281
281
|
| --- | --- |
|
|
282
282
|
| `toolbar: false` | 隐藏内置工具栏,但不关闭下载、打印、导出、缩放等 controller API,适合完全自定义业务工具栏。 |
|
|
283
|
-
| `toolbar: true` |
|
|
283
|
+
| `toolbar: true` | 使用默认内置工具栏;主题切换默认显示,下载、打印、HTML 导出和缩放按钮按能力动态显隐。 |
|
|
284
284
|
| `download` / `print` / `exportHtml` / `zoom` | 表达业务是否允许展示对应按钮;最终仍会结合文件类型、渲染完成状态、导出适配器和缩放 provider 计算真实可用性。 |
|
|
285
|
+
| `theme` | 控制浅色/深色切换按钮,默认 `true`;切换后触发 `theme-change`,传 `false` 可隐藏。 |
|
|
286
|
+
| `order` | 设置内置分组顺序,可使用 `search`、`zoom`、`download`、`print`、`exportHtml`、`theme`;遗漏项保持默认相对顺序。 |
|
|
285
287
|
| `position` | `auto`、`top`、`top-center`、`bottom-right`。默认 `auto`,PDF 自动悬浮右下角,其他格式保持顶部靠右;需要顶部水平居中时传 `top-center`。 |
|
|
286
288
|
| `beforeOperation` | 工具栏层统一前置校验,会在 `options.beforeOperation` 后执行。返回 `false` 或抛错都会取消本次操作。 |
|
|
287
289
|
| `beforeDownload` / `beforePrint` / `beforeExportHtml` | 单按钮前置校验;适合下载权限、打印审计、导出水印确认等细粒度业务规则。 |
|
|
@@ -311,6 +313,7 @@ const options = {
|
|
|
311
313
|
| `unload-complete` / `hooks.onUnloadComplete` | 旧文档释放完成后触发,reason 会标识 `replace`、`reset` 或 `component-unmount`。 |
|
|
312
314
|
| `operation-before` / `operation-cancel` | 下载、打印、HTML 导出和缩放前后触发;`beforeOperation` 返回 `false` 可取消操作。 |
|
|
313
315
|
| `operation-availability-change` | 当前格式是否可下载、可打印、可导出 HTML、可缩放发生变化时触发。 |
|
|
316
|
+
| `theme-change` | 用户通过内置按钮切换浅色或深色模式时触发,payload 为 `light` 或 `dark`。 |
|
|
314
317
|
| `search-change` / `location-change` / `zoom-change` / `view-state-change` | 搜索命中、定位锚点、缩放状态和完整视图快照变化时触发,用于外层同步 UI、投屏或恢复阅读进度。 |
|
|
315
318
|
|
|
316
319
|
## 公共操作 API
|
|
@@ -334,7 +337,7 @@ const options = {
|
|
|
334
337
|
| --- | --- |
|
|
335
338
|
| 通用 viewer assets | Pure Web 包提供 `file-viewer-copy-assets`,可把 Worker、WASM、vendor 和示例资源复制到业务静态目录。 |
|
|
336
339
|
| CAD / DWG / DXF / DWF | 按需配置 `options.cad.wasmPath`、`workerUrl`、`dwfWasmUrl`、`dxfEncoding`,支持自托管和内网部署。 |
|
|
337
|
-
| PDF / DOCX / Excel / PPTX | 按需配置 `options.pdf.workerUrl`、`options.pdf.cMapUrl`、`options.pdf.wasmUrl`、`options.pdf.standardFontDataUrl`、`options.docx.workerUrl`、`options.docx.workerJsZipUrl`、`options.spreadsheet.workerUrl`、`options.presentation.workerUrl` / `options.presentation.workerType`;PDF 默认探测真实静态 Worker,不可用时懒加载包内 handler
|
|
340
|
+
| PDF / DOCX / Excel / PPTX | 按需配置 `options.pdf.workerUrl`、`options.pdf.cMapUrl`、`options.pdf.wasmUrl`、`options.pdf.standardFontDataUrl`、`options.pdf.cjkFontFallbackPath`、`options.pdf.identityFontRepair`、`options.docx.workerUrl`、`options.docx.workerJsZipUrl`、`options.spreadsheet.workerUrl`、`options.presentation.workerUrl` / `options.presentation.workerType`;PDF 默认探测真实静态 Worker,不可用时懒加载包内 handler 兜底,未嵌入的中文字体默认按页加载本地 Noto Sans SC 分片回退,缺失 ToUnicode 的异常 Identity CJK 字体会在检测到乱码后尝试内存修复;DOCX 默认自动选择 Worker 或主线程解析,Electron `file://` 等本地不安全协议会自动回退;Excel 默认 `worker: auto`,大文件达到 `workerAutoThreshold` 自动启用 Worker,列宽拖拽可通过 `options.spreadsheet.resizableColumns` 显式开启;PPTX 默认按需创建模块 Worker,严格 CSP、旧 WebView 或自托管 CDN 场景可固定 Worker 地址。 |
|
|
338
341
|
| Typst / SQLite / Archive | 按需配置 Typst compiler/renderer WASM、`data.sqlWasmUrl`、`archive.workerUrl` / `archive.wasmUrl`;Typst 仅使用本地 WASM 真实渲染,不访问公共 CDN;Archive 兼容 GBK/GB18030 旧 ZIP 中文文件名,RAR、7z 和加密压缩包仍需要 libarchive Worker/WASM。 |
|
|
339
342
|
| Drawing | Draw.io 默认使用随 viewer assets 分发的官方 diagrams.net 离线 viewer;路径特殊时可通过 `options.drawing.viewerScriptUrl` 覆盖,`preferOfficial:false` 才切到内置 SVG 兜底。 |
|
|
340
343
|
| 离线部署 | 运行时不依赖公共 CDN 或第三方在线资源;`file-viewer-copy-assets` 会复制 PDF、CAD、Typst、SQLite、压缩包、Draw.io、DOCX worker/JSZip、PPTX worker 和 Office worker/vendor 资产。Vue full 包默认使用 `/file-viewer/` 作为资源根,路径不同可先调用 `setDefaultFullAssetBaseUrl()`。 |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@file-viewer/react",
|
|
3
|
-
"version": "2.1.
|
|
3
|
+
"version": "2.1.26",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "Standard React component package for Flyfish File Viewer",
|
|
@@ -55,7 +55,7 @@
|
|
|
55
55
|
"react": ">=17 <20"
|
|
56
56
|
},
|
|
57
57
|
"dependencies": {
|
|
58
|
-
"@file-viewer/core": "2.1.
|
|
58
|
+
"@file-viewer/core": "2.1.26"
|
|
59
59
|
},
|
|
60
60
|
"devDependencies": {
|
|
61
61
|
"@types/react": "^19.2.17",
|