@flyfish-group/file-viewer-react 1.0.20 → 1.0.21

package/README.md

@@ -3,10 +3,10 @@
 React 文件预览组件。只提供私有化部署路线: 依赖的 `@flyfish-group/file-viewer-web` 会随包携带 Vue 基线 viewer 产物；使用 `npm install` 或已允许 pnpm 安装脚本后，会复制到宿主项目 `public/file-viewer`。React 组件默认加载 `/file-viewer/index.html`，不依赖任何外部服务。
 
 ```bash
-npm install @flyfish-group/file-viewer-react@1.0.20
+npm install @flyfish-group/file-viewer-react@1.0.21
 ```
 
-pnpm 10 默认会拦截依赖包的 `postinstall`。如果安装后提示 `Ignored build scripts: @flyfish-group/file-viewer-web`，请执行 `pnpm approve-builds` 允许该包，或运行 `pnpm exec file-viewer-copy-assets ./public/file-viewer`。
+pnpm 10 默认会拦截依赖包的 `postinstall`。如果安装后提示 `Ignored build scripts: @flyfish-group/file-viewer-web`，请执行 `pnpm approve-builds` 允许该包，或运行 `pnpm exec file-viewer-copy-assets ./public/file-viewer`。复制脚本会先清空目标目录再复制，避免 `index.html` 和 `assets/*` hash 不同版本导致动态 import 404。
 
 ```tsx
 import FileViewer from '@flyfish-group/file-viewer-react'
@@ -45,4 +45,6 @@ export function Preview() {
 <FileViewer viewerUrl="/vendor/file-viewer/index.html" url={url} />
 ```
 
+React 组件内部复用 `mountViewerFrame` 的地址协议，会默认追加 `__flyfish_viewer_version` 来绕开旧 iframe 入口页缓存；静态服务已经保证 HTML 不缓存时，可传 `cacheKey={false}` 关闭。
+
 `options` 会透传给 Vue 基线预览器，可配置下载/打印/导出 HTML 操作栏、文字或图片水印，以及压缩包预览的 `libarchive.js` Worker、IndexedDB 缓存和体积上限。打印按钮会按当前格式和渲染链路动态显隐；Word / PDF 打印和导出会生成完整页面，不依赖当前 iframe 视口或已渲染 canvas。生命周期、操作能力变化和内置操作事件会通过 `onViewerEvent` 回传给宿主，适合记录加载耗时、审计下载/打印尝试和同步外部状态。

package/dist/index.d.ts

@@ -37,6 +37,10 @@ export interface FileViewerProps extends Omit<IframeHTMLAttributes<HTMLIFrameEle
      * 预留给 Vue 基线页面的查询参数。
      */
     params?: ViewerFrameOptions['params'];
+    /**
+     * iframe 入口页的缓存标识。默认使用 web 包版本；传 false 可关闭。
+     */
+    cacheKey?: ViewerFrameOptions['cacheKey'];
     /**
      * 透传给 Vue 基线预览器的运行时选项，例如水印、工具栏和压缩包缓存限制。
      */

package/dist/index.js

@@ -8,7 +8,7 @@ const defaultStyle = {
     display: 'block'
 };
 export const FileViewer = forwardRef((props, forwardedRef) => {
-    const { viewerUrl, url, file, name, from, targetOrigin, params, options, onViewerEvent, onLoad, style, title = 'Flyfish Viewer 文件预览', ...iframeProps } = props;
+    const { viewerUrl, url, file, name, from, targetOrigin, params, cacheKey, options, onViewerEvent, onLoad, style, title = 'Flyfish Viewer 文件预览', ...iframeProps } = props;
     const iframeRef = useRef(null);
     const [frameReady, setFrameReady] = useState(false);
     const frameOptions = useMemo(() => ({
@@ -19,12 +19,45 @@ export const FileViewer = forwardRef((props, forwardedRef) => {
         from,
         targetOrigin,
         params,
+        cacheKey,
         options
-    }), [viewerUrl, url, file, name, from, targetOrigin, params, options]);
+    }), [viewerUrl, url, file, name, from, targetOrigin, params, cacheKey, options]);
     const src = useMemo(() => buildViewerSrc(frameOptions), [frameOptions]);
+    const retryTimerRef = useRef(undefined);
+    const retryCountRef = useRef(0);
+    const lifecycleAcknowledgedRef = useRef(false);
     const postFile = useCallback(() => {
         return postFileToViewer(iframeRef.current, frameOptions);
     }, [frameOptions]);
+    const clearFilePostRetry = useCallback(() => {
+        if (retryTimerRef.current) {
+            window.clearTimeout(retryTimerRef.current);
+            retryTimerRef.current = undefined;
+        }
+    }, []);
+    const scheduleFilePost = useCallback(() => {
+        clearFilePostRetry();
+        retryCountRef.current = 0;
+        lifecycleAcknowledgedRef.current = false;
+        if (!frameOptions.file) {
+            return;
+        }
+        const post = () => {
+            if (lifecycleAcknowledgedRef.current) {
+                clearFilePostRetry();
+                return;
+            }
+            postFile();
+            retryCountRef.current += 1;
+            if (retryCountRef.current < 8) {
+                retryTimerRef.current = window.setTimeout(post, 120);
+            }
+            else {
+                retryTimerRef.current = undefined;
+            }
+        };
+        post();
+    }, [clearFilePostRetry, frameOptions.file, postFile]);
     const reload = useCallback(() => {
         if (iframeRef.current) {
             iframeRef.current.src = src;
@@ -38,13 +71,15 @@ export const FileViewer = forwardRef((props, forwardedRef) => {
         reload
     }), [postFile, reload]);
     useEffect(() => {
+        clearFilePostRetry();
+        lifecycleAcknowledgedRef.current = false;
         setFrameReady(false);
-    }, [src]);
+    }, [clearFilePostRetry, src]);
     useEffect(() => {
         if (frameReady) {
-            postFile();
+            scheduleFilePost();
         }
-    }, [frameReady, postFile]);
+    }, [frameReady, scheduleFilePost]);
     useEffect(() => {
         const handleMessage = (event) => {
             var _a, _b, _c;
@@ -55,11 +90,18 @@ export const FileViewer = forwardRef((props, forwardedRef) => {
                 ((_c = event.data) === null || _c === void 0 ? void 0 : _c.type) !== 'flyfish-viewer:operation') {
                 return;
             }
+            if (event.data.type === 'flyfish-viewer:lifecycle') {
+                lifecycleAcknowledgedRef.current = true;
+                clearFilePostRetry();
+            }
             onViewerEvent === null || onViewerEvent === void 0 ? void 0 : onViewerEvent(event.data, event);
         };
         window.addEventListener('message', handleMessage);
         return () => window.removeEventListener('message', handleMessage);
-    }, [onViewerEvent]);
+    }, [clearFilePostRetry, onViewerEvent]);
+    useEffect(() => {
+        return () => clearFilePostRetry();
+    }, [clearFilePostRetry]);
     const handleLoad = useCallback((event) => {
         setFrameReady(true);
         onLoad === null || onLoad === void 0 ? void 0 : onLoad(event);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flyfish-group/file-viewer-react",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "private": false,
   "type": "module",
   "description": "Private-deploy React component for Flyfish Viewer",
@@ -47,7 +47,7 @@
     "react": ">=17 <20"
   },
   "dependencies": {
-    "@flyfish-group/file-viewer-web": "^1.0.20"
+    "@flyfish-group/file-viewer-web": "^1.0.21"
   },
   "devDependencies": {
     "@types/react": "^19.2.14",