@file-viewer/react 2.1.16 → 2.1.18

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 CHANGED
@@ -202,6 +202,7 @@ Every ecosystem package uses the same `ViewerMountOptions` and `FileViewerOption
202
202
  | `type` | Explicit extension or MIME hint that overrides automatic detection. |
203
203
  | `size` | File size hint used in lifecycle context, loading states, and safety limits. |
204
204
  | `options` | The shared `FileViewerOptions` surface. Every component package keeps the same semantics. |
205
+ | `options.styleIsolation` | `auto`, `shadow`, `scoped`, or `none`. Pure Web / IIFE / Custom Element entries default to strong isolation; framework packages keep compatibility by default and can opt renderer content into a ShadowRoot. |
205
206
  | `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. |
206
207
 
207
208
  ## Actual Component Props
@@ -222,6 +223,7 @@ The table below lists the real props, event channel, and customization entry for
222
223
  | Options Field | Description |
223
224
  | --- | --- |
224
225
  | `theme` | `light`, `dark`, or `system`. This takes precedence over browser `prefers-color-scheme`. |
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`. |
225
227
  | `watermark` | Text or image watermark with opacity, rotation, gap, size, font, and color controls. |
226
228
  | `toolbar` | Controls download, print, HTML export, zoom, toolbar position, and operation-level preflight checks. |
227
229
  | `search` | Document search, highlight class names, case sensitivity, whole-word matching, max matches, and debounce. |
@@ -232,6 +234,47 @@ The table below lists the real props, event channel, and customization entry for
232
234
  | `typst` / `data` / `cad` | Typst, SQLite, CAD/DWG/DXF/DWF WASM, worker, encoding, and rendering strategy options. |
233
235
  | `hooks` / `beforeOperation` | Shared lifecycle hooks and operation preflight checks for audit, permission, telemetry, and safety controls. |
234
236
 
237
+ ## Style Isolation And Theme Customization
238
+
239
+ For OA systems, low-code shells, micro-frontends, portals, and admin products, prefer the strong Shadow DOM isolation used by Pure Web / Web Component and full packages 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.
240
+
241
+ | Mode | Description |
242
+ | --- | --- |
243
+ | `auto` | Default. `@file-viewer/web`, `@file-viewer/web-full`, IIFE, and `<flyfish-file-viewer>` use Shadow DOM by default. Vue, React, Svelte, and jQuery keep light-DOM compatibility for existing projects while renderer content can still be isolated by core. |
244
+ | `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. |
245
+ | `scoped` | Does not create a ShadowRoot. Uses a stable root selector, `@layer file-viewer`, and local resets to constrain cascade impact while keeping controlled inheritance from the host. |
246
+ | `none` | Historical light-DOM behavior for projects that depend on deep class overrides, old theme CSS, or snapshot tests. |
247
+
248
+ 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.
249
+
250
+ ```css
251
+ flyfish-file-viewer {
252
+ --file-viewer-bg: #f7f9fc;
253
+ --file-viewer-text: #172033;
254
+ --file-viewer-toolbar-bg: rgba(255, 255, 255, 0.96);
255
+ --file-viewer-button-color: #154b83;
256
+ --file-viewer-button-radius: 6px;
257
+ }
258
+
259
+ flyfish-file-viewer::part(toolbar) {
260
+ border: 1px solid rgba(20, 60, 100, 0.14);
261
+ }
262
+
263
+ flyfish-file-viewer::part(button) {
264
+ font-weight: 600;
265
+ }
266
+ ```
267
+
268
+ Framework packages can opt into renderer isolation through the shared options object:
269
+
270
+ ```ts
271
+ const options = {
272
+ styleIsolation: 'shadow',
273
+ theme: 'light',
274
+ toolbar: { position: 'bottom-right' }
275
+ }
276
+ ```
277
+
235
278
  ## Toolbar Customization
236
279
 
237
280
  | Config | Description |
@@ -239,7 +282,7 @@ The table below lists the real props, event channel, and customization entry for
239
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. |
240
283
  | `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. |
241
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. |
242
- | `position` | `auto`, `top`, or `bottom-right`. The default `auto` floats PDF actions at bottom right to avoid conflicting with the PDF page / outline toolbar. |
285
+ | `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. |
243
286
  | `beforeOperation` | Toolbar-level preflight that runs after `options.beforeOperation`. Returning `false` or throwing cancels the operation. |
244
287
  | `beforeDownload` / `beforePrint` / `beforeExportHtml` | Operation-specific preflight for download permission, print audit, export confirmation, and similar business rules. |
245
288
 
package/README.md CHANGED
@@ -202,6 +202,7 @@ const options = {
202
202
  | `type` | 显式指定扩展名或 MIME 线索,覆盖自动识别结果。 |
203
203
  | `size` | 文件大小提示,用于生命周期上下文、加载状态和安全限制展示。 |
204
204
  | `options` | 完整 `FileViewerOptions`,所有框架包保持同一套参数语义。 |
205
+ | `options.styleIsolation` | `auto`、`shadow`、`scoped` 或 `none`。Pure Web / IIFE / Custom Element 默认强隔离;框架组件默认保持历史兼容,可按需让 renderer 内容进入独立 ShadowRoot。 |
205
206
  | `onEvent` / `onStateChange` | Vanilla JS / Pure Web、React、Svelte 等命令式包装层的统一事件和状态订阅;Vue 组件会映射为原生 emit。 |
206
207
 
207
208
  ## 实际组件属性
@@ -222,6 +223,7 @@ const options = {
222
223
  | Options 字段 | 说明 |
223
224
  | --- | --- |
224
225
  | `theme` | `light`、`dark` 或 `system`,优先级高于浏览器 `prefers-color-scheme`。 |
226
+ | `styleIsolation` | `auto`、`shadow`、`scoped` 或 `none`。`auto` 下 Web Component / full / IIFE 默认使用 Shadow DOM;Vue、React、Svelte、jQuery 默认保持 light DOM 兼容,但 renderer 内容可通过 `shadow` 获得独立渲染根。 |
225
227
  | `watermark` | 开启文字或图片水印,可设置透明度、旋转、间距、尺寸、字体和颜色。 |
226
228
  | `toolbar` | 控制下载、打印、HTML 导出、缩放和工具栏位置,并支持操作级前置校验。 |
227
229
  | `search` | 配置文档搜索、高亮 class、大小写、整词匹配、最大命中数和 debounce。 |
@@ -232,6 +234,47 @@ const options = {
232
234
  | `typst` / `data` / `cad` | 配置 Typst、SQLite、CAD/DWG/DXF/DWF 等 WASM、Worker、编码和渲染策略。 |
233
235
  | `hooks` / `beforeOperation` | 统一生命周期 hooks 和操作前置校验,可用于审计、权限、埋点和安全控制。 |
234
236
 
237
+ ## 样式隔离与主题定制
238
+
239
+ 推荐在 OA、低代码、微前端、门户和后台系统中优先使用 Pure Web / Web Component 或 full 包默认的 Shadow DOM 强隔离。宿主页面里的 `*`、`button`、`table`、`img`、`svg`、`canvas` 等全局样式不会直接侵入预览器工具栏和正文;预览器也不会把局部 reset 粗暴写到业务页面。
240
+
241
+ | 模式 | 说明 |
242
+ | --- | --- |
243
+ | `auto` | 默认值。`@file-viewer/web`、`@file-viewer/web-full`、IIFE 和 `<flyfish-file-viewer>` 默认走 Shadow DOM;Vue、React、Svelte、jQuery 为兼容旧项目保持 light DOM,但 renderer 内容可由 core 按需隔离。 |
244
+ | `shadow` | 显式创建 ShadowRoot 作为渲染面,适合宿主 CSS 不可控、微前端混挂、低代码平台和设计系统全局 reset 很强的页面。 |
245
+ | `scoped` | 不创建 ShadowRoot,使用稳定根选择器、`@layer file-viewer` 和局部 reset 约束样式权重,适合需要被外层 CSS 轻度继承但又不想污染页面的场景。 |
246
+ | `none` | 历史 light DOM 行为,保留给依赖深度 class 覆盖、旧主题 CSS 或自动化测试快照的项目。 |
247
+
248
+ 定制优先级建议是:先使用 `--file-viewer-*` CSS 变量覆盖颜色、字体、间距、圆角、工具栏和按钮;需要命中内部结构时再使用稳定 Shadow Parts。当前 Web shell 暴露 `host`、`shell`、`toolbar`、`toolbar-group`、`toolbar-status`、`button`、`input` 和 `content`,后续 renderer 扩展应继续使用 `state-panel`、`watermark` 这类稳定命名。不要依赖内部 class 名,它们只服务实现细节。
249
+
250
+ ```css
251
+ flyfish-file-viewer {
252
+ --file-viewer-bg: #f7f9fc;
253
+ --file-viewer-text: #172033;
254
+ --file-viewer-toolbar-bg: rgba(255, 255, 255, 0.96);
255
+ --file-viewer-button-color: #154b83;
256
+ --file-viewer-button-radius: 6px;
257
+ }
258
+
259
+ flyfish-file-viewer::part(toolbar) {
260
+ border: 1px solid rgba(20, 60, 100, 0.14);
261
+ }
262
+
263
+ flyfish-file-viewer::part(button) {
264
+ font-weight: 600;
265
+ }
266
+ ```
267
+
268
+ 框架组件的推荐写法是在 `options` 中显式声明隔离策略:
269
+
270
+ ```ts
271
+ const options = {
272
+ styleIsolation: 'shadow',
273
+ theme: 'light',
274
+ toolbar: { position: 'bottom-right' }
275
+ }
276
+ ```
277
+
235
278
  ## 工具栏定制
236
279
 
237
280
  | 配置 | 说明 |
@@ -239,7 +282,7 @@ const options = {
239
282
  | `toolbar: false` | 隐藏内置工具栏,但不关闭下载、打印、导出、缩放等 controller API,适合完全自定义业务工具栏。 |
240
283
  | `toolbar: true` | 使用默认内置工具栏,下载、打印、HTML 导出和缩放按钮都会按能力动态显隐。 |
241
284
  | `download` / `print` / `exportHtml` / `zoom` | 表达业务是否允许展示对应按钮;最终仍会结合文件类型、渲染完成状态、导出适配器和缩放 provider 计算真实可用性。 |
242
- | `position` | `auto`、`top`、`bottom-right`。默认 `auto`,PDF 自动悬浮右下角,减少和 PDF 自身页码 / 目录工具栏冲突。 |
285
+ | `position` | `auto`、`top`、`top-center`、`bottom-right`。默认 `auto`,PDF 自动悬浮右下角,其他格式保持顶部靠右;需要顶部水平居中时传 `top-center`。 |
243
286
  | `beforeOperation` | 工具栏层统一前置校验,会在 `options.beforeOperation` 后执行。返回 `false` 或抛错都会取消本次操作。 |
244
287
  | `beforeDownload` / `beforePrint` / `beforeExportHtml` | 单按钮前置校验;适合下载权限、打印审计、导出水印确认等细粒度业务规则。 |
245
288
 
@@ -1,4 +1,4 @@
1
- import { type FileViewerAiOptions, type FileViewerArchiveOptions, type FileViewerCadOptions, type FileViewerDocxOptions, type FileViewerDocumentAnchor, type FileViewerDocumentChunk, type FileViewerEvent, type FileViewerEventHandler, type FileViewerEventType, type FileViewerFileRef, type FileViewerInstance, type FileViewerLifecycleContext, type FileViewerOperationAvailability, type FileViewerOperationContext, type FileViewerOptions, type FileViewerPdfOptions, type FileViewerSpreadsheetOptions, type FileViewerPublicApi, type FileViewerSearchOptions, type FileViewerSearchState, type FileViewerThemeMode, type FileViewerToolbarOptions, type FileViewerToolbarPosition, type FileViewerTypstOptions, type FileViewerWatermarkOptions, type FileViewerZoomState, type RendererRegistry } from '@file-viewer/core';
1
+ import { type FileViewerAiOptions, type FileViewerArchiveOptions, type FileViewerCadOptions, type FileViewerDocxOptions, type FileViewerDocumentAnchor, type FileViewerDocumentChunk, type FileViewerEvent, type FileViewerEventHandler, type FileViewerEventType, type FileViewerFileRef, type FileViewerFitMode, type FileViewerFitOptions, type FileViewerFitResult, type FileViewerInstance, type FileViewerLifecycleContext, type FileViewerOperationAvailability, type FileViewerOperationContext, type FileViewerOptions, type FileViewerPdfOptions, type FileViewerSpreadsheetOptions, type FileViewerPublicApi, type FileViewerSearchOptions, type FileViewerSearchState, type FileViewerThemeMode, type FileViewerToolbarOptions, type FileViewerToolbarPosition, type FileViewerTypstOptions, type FileViewerWatermarkOptions, type FileViewerZoomState, type RendererRegistry } from '@file-viewer/core';
2
2
  export type FileRef = FileViewerFileRef;
3
3
  export type ViewerWatermarkOptions = FileViewerWatermarkOptions;
4
4
  export type ViewerToolbarPosition = FileViewerToolbarPosition;
@@ -11,6 +11,9 @@ export type ViewerTypstOptions = FileViewerTypstOptions;
11
11
  export type ViewerCadOptions = FileViewerCadOptions;
12
12
  export type ViewerSearchOptions = FileViewerSearchOptions;
13
13
  export type ViewerAiOptions = FileViewerAiOptions;
14
+ export type ViewerFitMode = FileViewerFitMode;
15
+ export type ViewerFitOptions = FileViewerFitOptions;
16
+ export type ViewerFitResult = FileViewerFitResult;
14
17
  export type ViewerThemeMode = FileViewerThemeMode;
15
18
  export type ViewerOptions = FileViewerOptions;
16
19
  export type ViewerEventType = FileViewerEventType;
@@ -75,6 +78,7 @@ export interface ViewerController {
75
78
  zoomIn(): Promise<FileViewerZoomState | null>;
76
79
  zoomOut(): Promise<FileViewerZoomState | null>;
77
80
  resetZoom(): Promise<FileViewerZoomState | null>;
81
+ fitToView(fit?: FileViewerFitMode | FileViewerFitOptions): Promise<FileViewerFitResult | null>;
78
82
  searchDocument(query: string): Promise<FileViewerSearchState | null>;
79
83
  clearDocumentSearch(): Promise<FileViewerSearchState | null>;
80
84
  nextSearchResult(): Promise<FileViewerSearchState | null>;
@@ -103,6 +107,7 @@ export interface ViewerControllerHandle {
103
107
  zoomIn(): Promise<FileViewerZoomState | null>;
104
108
  zoomOut(): Promise<FileViewerZoomState | null>;
105
109
  resetZoom(): Promise<FileViewerZoomState | null>;
110
+ fitToView(fit?: FileViewerFitMode | FileViewerFitOptions): Promise<FileViewerFitResult | null>;
106
111
  searchDocument(query: string): Promise<FileViewerSearchState | null>;
107
112
  clearDocumentSearch(): Promise<FileViewerSearchState | null>;
108
113
  nextSearchResult(): Promise<FileViewerSearchState | null>;
@@ -124,6 +124,10 @@ export const createViewerControllerHandle = (getController, dispose) => ({
124
124
  var _a, _b;
125
125
  return (_b = (_a = getController()) === null || _a === void 0 ? void 0 : _a.resetZoom()) !== null && _b !== void 0 ? _b : Promise.resolve(null);
126
126
  },
127
+ fitToView(fit) {
128
+ var _a, _b;
129
+ return (_b = (_a = getController()) === null || _a === void 0 ? void 0 : _a.fitToView(fit)) !== null && _b !== void 0 ? _b : Promise.resolve(null);
130
+ },
127
131
  searchDocument(query) {
128
132
  var _a, _b;
129
133
  return (_b = (_a = getController()) === null || _a === void 0 ? void 0 : _a.searchDocument(query)) !== null && _b !== void 0 ? _b : Promise.resolve(null);
@@ -282,6 +286,9 @@ export const mountViewer = (container, initialOptions = {}, coreOptions = {}) =>
282
286
  fetchFile: coreOptions.fetchFile,
283
287
  signal: controller === null || controller === void 0 ? void 0 : controller.signal,
284
288
  });
289
+ if (disposed || (controller === null || controller === void 0 ? void 0 : controller.signal.aborted) || abortController !== controller) {
290
+ return null;
291
+ }
285
292
  return await instance.load(resolvedSource);
286
293
  }
287
294
  catch (error) {
@@ -369,6 +376,9 @@ export const mountViewer = (container, initialOptions = {}, coreOptions = {}) =>
369
376
  resetZoom() {
370
377
  return callApi(instance, api => api.resetZoom(), null);
371
378
  },
379
+ fitToView(fit) {
380
+ return callApi(instance, api => api.fitToView(fit), null);
381
+ },
372
382
  searchDocument(query) {
373
383
  return callApi(instance, api => api.search(query), null);
374
384
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@file-viewer/react",
3
- "version": "2.1.16",
3
+ "version": "2.1.18",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Standard React component package for Flyfish File Viewer",
@@ -33,7 +33,7 @@
33
33
  },
34
34
  "funding": {
35
35
  "type": "individual",
36
- "url": "https://dev.flyfish.group/shop"
36
+ "url": "https://dev.flyfish.group/donate?source=npm"
37
37
  },
38
38
  "main": "./dist/index.js",
39
39
  "module": "./dist/index.js",
@@ -55,7 +55,7 @@
55
55
  "react": ">=17 <20"
56
56
  },
57
57
  "dependencies": {
58
- "@file-viewer/core": "^2.1.16"
58
+ "@file-viewer/core": "^2.1.18"
59
59
  },
60
60
  "devDependencies": {
61
61
  "@types/react": "^19.2.17",