@file-viewer/core 2.1.17 → 2.1.19

package/dist/rendering/handler.js

@@ -13,6 +13,48 @@ import { findFileViewerViewStateProvider } from '../features/document/dom/index.
 import { registerFileViewerGenericViewStateProvider } from '../features/document/viewState.js';
 export const FILE_VIEWER_RENDER_SESSION_DISPOSE_ERROR_MESSAGE = '预览内容卸载失败';
 export const DEFAULT_FILE_VIEWER_RENDER_TARGET_CLASS = 'file-render';
+const FILE_VIEWER_RENDER_HOST_CLASS = 'file-render-host';
+const FILE_VIEWER_SHADOW_RENDER_TARGET_CLASS = 'file-render-shadow-target';
+export const isFileViewerShadowRoot = (value) => {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    if (typeof ShadowRoot !== 'undefined' && value instanceof ShadowRoot) {
+        return true;
+    }
+    return value.nodeType === 11 &&
+        !!value.host;
+};
+const getElementRootNode = (element) => {
+    var _a;
+    return ((_a = element === null || element === void 0 ? void 0 : element.getRootNode) === null || _a === void 0 ? void 0 : _a.call(element)) || null;
+};
+export const getFileViewerShadowRootForNode = (node) => {
+    var _a;
+    if (!node) {
+        return null;
+    }
+    if (isFileViewerShadowRoot(node)) {
+        return node;
+    }
+    const root = (_a = node.getRootNode) === null || _a === void 0 ? void 0 : _a.call(node);
+    return isFileViewerShadowRoot(root) ? root : null;
+};
+export const normalizeFileViewerStyleIsolation = (isolation) => {
+    return isolation === 'shadow' || isolation === 'scoped' || isolation === 'none'
+        ? isolation
+        : 'auto';
+};
+export const resolveFileViewerStyleIsolation = (options, container) => {
+    const isolation = normalizeFileViewerStyleIsolation(options === null || options === void 0 ? void 0 : options.styleIsolation);
+    if (isolation === 'auto') {
+        return isFileViewerShadowRoot(getElementRootNode(container)) ? 'scoped' : 'none';
+    }
+    if (isolation === 'shadow' && isFileViewerShadowRoot(getElementRootNode(container))) {
+        return 'scoped';
+    }
+    return isolation;
+};
 const isPromiseLike = (value) => {
     return !!value &&
         (typeof value === 'object' || typeof value === 'function') &&
@@ -35,6 +77,76 @@ export const createFileViewerRenderTarget = (container, options = {}) => {
     container.appendChild(target);
     return target;
 };
+export const createFileViewerRenderSurface = (container, options = {}) => {
+    const styleIsolation = resolveFileViewerStyleIsolation({
+        styleIsolation: options.styleIsolation,
+    }, container);
+    const className = options.className || DEFAULT_FILE_VIEWER_RENDER_TARGET_CLASS;
+    if (styleIsolation === 'shadow' && typeof container.attachShadow === 'function') {
+        const host = container.ownerDocument.createElement('div');
+        host.className = `${FILE_VIEWER_RENDER_HOST_CLASS} ${className}`;
+        host.dataset.fileViewerStyleIsolation = 'shadow';
+        host.style.width = '100%';
+        host.style.minWidth = '0';
+        host.style.minHeight = '0';
+        const shadowRoot = host.attachShadow({ mode: 'open' });
+        const target = container.ownerDocument.createElement('div');
+        target.className = `${FILE_VIEWER_SHADOW_RENDER_TARGET_CLASS} ${className}`;
+        target.dataset.fileViewerStyleIsolation = 'shadow';
+        target.style.width = '100%';
+        target.style.minWidth = '0';
+        target.style.minHeight = '0';
+        shadowRoot.appendChild(target);
+        container.appendChild(host);
+        return {
+            host,
+            container: target,
+            shadowRoot,
+            styleIsolation,
+        };
+    }
+    const target = createFileViewerRenderTarget(container, { className });
+    target.dataset.fileViewerStyleIsolation = styleIsolation;
+    return {
+        host: target,
+        container: target,
+        styleIsolation,
+    };
+};
+const appendStyleElement = (target, css) => {
+    const documentRef = target.ownerDocument;
+    const style = documentRef.createElement('style');
+    style.textContent = css;
+    target.appendChild(style);
+    return style;
+};
+const canUseAdoptedStyleSheet = (root) => {
+    return 'adoptedStyleSheets' in root &&
+        typeof CSSStyleSheet !== 'undefined' &&
+        typeof CSSStyleSheet.prototype.replaceSync === 'function';
+};
+export const appendFileViewerStyle = (target, css, options = {}) => {
+    const shadowRoot = getFileViewerShadowRootForNode(target);
+    if (options.adoptedStyleSheet && shadowRoot && canUseAdoptedStyleSheet(shadowRoot)) {
+        const sheet = new CSSStyleSheet();
+        sheet.replaceSync(css);
+        shadowRoot.adoptedStyleSheets = [...shadowRoot.adoptedStyleSheets, sheet];
+        return {
+            sheet,
+            remove() {
+                shadowRoot.adoptedStyleSheets = shadowRoot.adoptedStyleSheets.filter(item => item !== sheet);
+            },
+        };
+    }
+    const styleTarget = isFileViewerShadowRoot(target) ? target : target;
+    const node = appendStyleElement(styleTarget, css);
+    return {
+        node,
+        remove() {
+            node.remove();
+        },
+    };
+};
 export const removeFileViewerRenderTarget = (container, target) => {
     if (target.parentNode !== container) {
         return false;
@@ -161,7 +273,7 @@ export const resetFileViewerRenderSurface = ({ surfaceState, readinessState, con
     clearFileViewerRenderSurface(container);
     return session;
 };
-export const runFileViewerRenderSurfaceClear = ({ reason = 'replace', surfaceState, readinessState, container, disposeOptions, onUnloadStart, onUnloadComplete, onClearActiveDocumentContext, onClearDocumentState, onStopZoomObserver, onClearZoomProvider, onStopViewStateObserver, onClearViewStateProvider, }) => {
+export const runFileViewerRenderSurfaceClear = ({ reason = 'replace', surfaceState, readinessState, container, disposeOptions, onUnloadStart, onUnloadComplete, onClearActiveDocumentContext, onClearDocumentState, onStopZoomObserver, onClearZoomProvider, onStopFitObserver, onStopViewStateObserver, onClearViewStateProvider, }) => {
     const unloadContext = onUnloadStart === null || onUnloadStart === void 0 ? void 0 : onUnloadStart(reason);
     let session;
     try {
@@ -177,6 +289,7 @@ export const runFileViewerRenderSurfaceClear = ({ reason = 'replace', surfaceSta
         onClearDocumentState === null || onClearDocumentState === void 0 ? void 0 : onClearDocumentState();
         onStopZoomObserver === null || onStopZoomObserver === void 0 ? void 0 : onStopZoomObserver();
         onClearZoomProvider === null || onClearZoomProvider === void 0 ? void 0 : onClearZoomProvider();
+        onStopFitObserver === null || onStopFitObserver === void 0 ? void 0 : onStopFitObserver();
         onStopViewStateObserver === null || onStopViewStateObserver === void 0 ? void 0 : onStopViewStateObserver();
         onClearViewStateProvider === null || onClearViewStateProvider === void 0 ? void 0 : onClearViewStateProvider();
     }
@@ -187,7 +300,7 @@ export const runFileViewerRenderSurfaceClear = ({ reason = 'replace', surfaceSta
         session,
     };
 };
-export const runFileViewerRenderSurfaceMount = async ({ buffer, file, version, sourceUrl, streamUrl, getContainer, surfaceState, readinessState, isCurrent, clearRenderedContent, render, waitForContainer, waitForPaint = waitForFileViewerNextPaint, disposeSession = disposeFileViewerRendererSession, onStartZoomObserver, onStartViewStateObserver, onRefreshDocumentIndex, onRefreshZoomProvider, onRefreshViewStateProvider, }) => {
+export const runFileViewerRenderSurfaceMount = async ({ buffer, file, version, sourceUrl, streamUrl, getContainer, surfaceState, readinessState, isCurrent, clearRenderedContent, render, waitForContainer, waitForPaint = waitForFileViewerNextPaint, disposeSession = disposeFileViewerRendererSession, onStartZoomObserver, onStartFitObserver, onStartViewStateObserver, onApplyInitialFit, onRefreshDocumentIndex, onRefreshZoomProvider, onRefreshViewStateProvider, }) => {
     if (!getContainer()) {
         await (waitForContainer === null || waitForContainer === void 0 ? void 0 : waitForContainer());
     }
@@ -198,6 +311,7 @@ export const runFileViewerRenderSurfaceMount = async ({ buffer, file, version, s
     clearRenderedContent('replace');
     const target = createFileViewerRenderTarget(container);
     onStartZoomObserver === null || onStartZoomObserver === void 0 ? void 0 : onStartZoomObserver();
+    onStartFitObserver === null || onStartFitObserver === void 0 ? void 0 : onStartFitObserver();
     onStartViewStateObserver === null || onStartViewStateObserver === void 0 ? void 0 : onStartViewStateObserver();
     await (waitForContainer === null || waitForContainer === void 0 ? void 0 : waitForContainer());
     await waitForPaint();
@@ -236,6 +350,11 @@ export const runFileViewerRenderSurfaceMount = async ({ buffer, file, version, s
         void (onRefreshDocumentIndex === null || onRefreshDocumentIndex === void 0 ? void 0 : onRefreshDocumentIndex());
         onRefreshZoomProvider === null || onRefreshZoomProvider === void 0 ? void 0 : onRefreshZoomProvider();
         onRefreshViewStateProvider === null || onRefreshViewStateProvider === void 0 ? void 0 : onRefreshViewStateProvider();
+        if (onApplyInitialFit) {
+            await onApplyInitialFit();
+            onRefreshZoomProvider === null || onRefreshZoomProvider === void 0 ? void 0 : onRefreshZoomProvider();
+            onRefreshViewStateProvider === null || onRefreshViewStateProvider === void 0 ? void 0 : onRefreshViewStateProvider();
+        }
         return session;
     }
     catch (error) {
@@ -243,7 +362,7 @@ export const runFileViewerRenderSurfaceMount = async ({ buffer, file, version, s
         throw error;
     }
 };
-export const createFileViewerRenderSurfaceActionHandlers = ({ getContainer, surfaceState, readinessState, isCurrent, render, waitForContainer, waitForPaint, disposeOptions, onUnloadStart, onUnloadComplete, onClearActiveDocumentContext, onClearDocumentState, onStartZoomObserver, onStopZoomObserver, onClearZoomProvider, onStartViewStateObserver, onStopViewStateObserver, onClearViewStateProvider, onRefreshDocumentIndex, onRefreshZoomProvider, onRefreshViewStateProvider, }) => {
+export const createFileViewerRenderSurfaceActionHandlers = ({ getContainer, surfaceState, readinessState, isCurrent, render, waitForContainer, waitForPaint, disposeOptions, onUnloadStart, onUnloadComplete, onClearActiveDocumentContext, onClearDocumentState, onStartZoomObserver, onStopZoomObserver, onClearZoomProvider, onStartFitObserver, onStopFitObserver, onStartViewStateObserver, onStopViewStateObserver, onClearViewStateProvider, onApplyInitialFit, onRefreshDocumentIndex, onRefreshZoomProvider, onRefreshViewStateProvider, }) => {
     const handleDisposeError = (error) => {
         if (disposeOptions === null || disposeOptions === void 0 ? void 0 : disposeOptions.onError) {
             disposeOptions.onError(error);
@@ -274,6 +393,7 @@ export const createFileViewerRenderSurfaceActionHandlers = ({ getContainer, surf
             onClearDocumentState,
             onStopZoomObserver,
             onClearZoomProvider,
+            onStopFitObserver,
             onStopViewStateObserver,
             onClearViewStateProvider,
         });
@@ -295,7 +415,9 @@ export const createFileViewerRenderSurfaceActionHandlers = ({ getContainer, surf
             waitForPaint,
             disposeSession: destroyRenderSession,
             onStartZoomObserver,
+            onStartFitObserver,
             onStartViewStateObserver,
+            onApplyInitialFit,
             onRefreshDocumentIndex,
             onRefreshZoomProvider,
             onRefreshViewStateProvider,
@@ -308,11 +430,12 @@ export const createFileViewerRenderSurfaceActionHandlers = ({ getContainer, surf
         mountRenderedContent,
     };
 };
-export const buildFileRenderContextFromLoadContext = ({ source, options, registerExportAdapter, renderContext, }) => ({
+export const buildFileRenderContextFromLoadContext = ({ source, surface, options, registerExportAdapter, renderContext, }) => ({
     filename: source.filename,
     url: source.url,
     streamUrl: source.url,
     options,
+    surface,
     registerExportAdapter,
     ...renderContext,
 });

package/dist/source/loading.d.ts

@@ -430,8 +430,10 @@ export interface RunFileViewerPreviewSourceChangeInput {
 export interface RunFileViewerPreviewComponentUnmountInput {
     reason?: FileViewerLifecycleContext['reason'];
     onCancelPreview?: (reason: FileViewerLifecycleContext['reason']) => void;
+    onClearRenderedContent?: (reason: FileViewerLifecycleContext['reason']) => void;
     onResetLoading?: () => void;
     onStopZoomObserver?: () => void;
+    onStopFitObserver?: () => void;
     onStopViewStateObserver?: () => void;
 }
 export interface FileViewerPreviewComponentUnmountState {
@@ -502,7 +504,7 @@ export declare const applyFileViewerPreviewRequestResetState: <Target extends Mu
 export declare const commitFileViewerPreviewRequestStartState: ({ reason, requestController, previewTarget, onClearRenderedContent, onClearError, }: CommitFileViewerPreviewRequestStartStateInput) => number;
 export declare const cancelFileViewerPreviewRequest: ({ reason, requestController, previewTarget, onClearRenderedContent, onClearError, }: CancelFileViewerPreviewRequestInput) => number;
 export declare const runFileViewerPreviewSourceChange: ({ onRefreshPreview, }?: RunFileViewerPreviewSourceChangeInput) => unknown;
-export declare const runFileViewerPreviewComponentUnmount: ({ reason, onCancelPreview, onResetLoading, onStopZoomObserver, onStopViewStateObserver, }?: RunFileViewerPreviewComponentUnmountInput) => FileViewerPreviewComponentUnmountState;
+export declare const runFileViewerPreviewComponentUnmount: ({ reason, onCancelPreview, onClearRenderedContent, onResetLoading, onStopZoomObserver, onStopFitObserver, onStopViewStateObserver, }?: RunFileViewerPreviewComponentUnmountInput) => FileViewerPreviewComponentUnmountState;
 export declare const applyFileViewerEmptyPreviewState: <Target extends MutableFileViewerPreviewState>(target: Target, state?: FileViewerEmptyPreviewState) => Target;
 export declare const commitFileViewerEmptyPreviewResetState: ({ previewTarget, state, reason, onClearRenderedContent, onResetLoading, }: CommitFileViewerEmptyPreviewResetStateInput) => MutableFileViewerPreviewState;
 export declare const runFileViewerPreviewRequest: <LocalResult = unknown, RemoteResult = unknown>({ file, url, reason, requestController, previewTarget, onPreviewLocalFile, onPreviewRemoteFile, onClearRenderedContent, onClearError, onResetLoading, }: RunFileViewerPreviewRequestInput<LocalResult, RemoteResult>) => Promise<FileViewerPreviewRequestRunState<LocalResult, RemoteResult>>;

package/dist/source/loading.js

@@ -17,7 +17,7 @@ export const resolveFileViewerPreviewLoadErrorMessage = ({ kind, error, formatEr
         : kind === 'stream'
             ? translateFileViewerMessage(i18n, 'error.stream')
             : translateFileViewerMessage(i18n, 'error.load');
-    return formatErrorMessage((_a = prefixes === null || prefixes === void 0 ? void 0 : prefixes[kind]) !== null && _a !== void 0 ? _a : fallbackPrefix, error);
+    return formatErrorMessage((_a = prefixes === null || prefixes === void 0 ? void 0 : prefixes[kind]) !== null && _a !== void 0 ? _a : fallbackPrefix, error, i18n);
 };
 export const resolveFileViewerMissingRemoteDataErrorMessage = ({ message, i18n, } = {}) => message || translateFileViewerMessage(i18n, 'error.remoteDownload');
 export const DEFAULT_FILE_VIEWER_PREVIEW_LOAD_ERROR_LOGGER = error => {
@@ -182,10 +182,14 @@ export const cancelFileViewerPreviewRequest = ({ reason = 'component-unmount', r
 export const runFileViewerPreviewSourceChange = ({ onRefreshPreview, } = {}) => {
     return onRefreshPreview === null || onRefreshPreview === void 0 ? void 0 : onRefreshPreview();
 };
-export const runFileViewerPreviewComponentUnmount = ({ reason = 'component-unmount', onCancelPreview, onResetLoading, onStopZoomObserver, onStopViewStateObserver, } = {}) => {
+export const runFileViewerPreviewComponentUnmount = ({ reason = 'component-unmount', onCancelPreview, onClearRenderedContent, onResetLoading, onStopZoomObserver, onStopFitObserver, onStopViewStateObserver, } = {}) => {
     onCancelPreview === null || onCancelPreview === void 0 ? void 0 : onCancelPreview(reason);
+    if (!onCancelPreview) {
+        onClearRenderedContent === null || onClearRenderedContent === void 0 ? void 0 : onClearRenderedContent(reason);
+    }
     onResetLoading === null || onResetLoading === void 0 ? void 0 : onResetLoading();
     onStopZoomObserver === null || onStopZoomObserver === void 0 ? void 0 : onStopZoomObserver();
+    onStopFitObserver === null || onStopFitObserver === void 0 ? void 0 : onStopFitObserver();
     onStopViewStateObserver === null || onStopViewStateObserver === void 0 ? void 0 : onStopViewStateObserver();
     return {
         reason,

package/dist/viewer/createViewer.js

@@ -8,11 +8,12 @@ import { createEmptyFileViewerSearchState, } from '../features/document/model.js
 import { createFileViewerDocumentFeatureControllerActionHandlers, } from '../features/document/events.js';
 import { createFileViewerZoomController } from '../features/document/zoom.js';
 import { createFileViewerViewStateController } from '../features/document/viewState.js';
+import { createFileViewerFitController, hasFileViewerExplicitInitialViewState, } from '../features/document/fit.js';
 import { DEFAULT_FILE_VIEWER_DOWNLOAD_FILENAME, DEFAULT_FILE_VIEWER_EXPORT_FILENAME, DEFAULT_FILE_VIEWER_PREVIEW_TITLE, createFileViewerOriginalSourceStateFromNormalizedSource, executeFileViewerDownloadOperation, executeFileViewerExportHtmlOperation, executeFileViewerPrintOperation, resolveFileViewerDisplayFilename, resolveFileViewerOperationFilename, } from './operations.js';
 import { applyFileViewerZoomAvailability, createUnsupportedAvailability, getRendererAvailability, } from '../registry/capabilities.js';
 import { buildFileViewerLifecycleContextFromNormalizedSource, buildFileViewerOperationContext, runFileViewerBeforeOperation, runFileViewerLifecycleHook, } from '../lifecycle/operations.js';
 import { collectFileViewerRendererPlugins, createRendererRegistry, getFileViewerAutoRendererPresetVersion, hasFileViewerRendererPresetName, installFileViewerRendererPlugins, listFileViewerAutoRendererPresets, resolveFileViewerRendererPresetInputs, } from '../registry/registry.js';
-import { createFileRenderHandlerLoader, applyFileViewerRenderSurfaceState, createFileViewerRenderSurfaceState, createFileViewerRenderTarget, removeFileViewerRenderTarget, } from '../rendering/handler.js';
+import { createFileRenderHandlerLoader, applyFileViewerRenderSurfaceState, createFileViewerRenderSurfaceState, createFileViewerRenderSurface, removeFileViewerRenderTarget, } from '../rendering/handler.js';
 import { createFileViewerCoreRendererRegistry } from '../renderers/index.js';
 import { createFileViewerRequestScope } from '../source/loading.js';
 import { normalizeSource } from '../source/index.js';
@@ -94,6 +95,7 @@ export const createViewer = (container, createOptions = {}) => {
     let installedAutoRendererVersion = -1;
     let currentSource = null;
     let currentRenderTarget = null;
+    let currentDocumentRoot = null;
     const renderSurfaceState = createFileViewerRenderSurfaceState();
     const requestScope = createFileViewerRequestScope();
     const documentTarget = {
@@ -190,12 +192,16 @@ export const createViewer = (container, createOptions = {}) => {
         }
     };
     const createRenderTarget = (fillHeight = true) => {
-        const target = createFileViewerRenderTarget(container);
+        const surface = createFileViewerRenderSurface(container, {
+            styleIsolation: options.styleIsolation,
+        });
+        const target = surface.host || surface.container;
         if (fillHeight) {
             target.style.height = '100%';
+            surface.container.style.height = '100%';
         }
         currentRenderTarget = target;
-        return target;
+        return surface;
     };
     const disposeStaleSession = async (session, target) => {
         var _a;
@@ -350,20 +356,41 @@ export const createViewer = (container, createOptions = {}) => {
         emitZoomChange(state);
         emitOperationAvailabilityChange();
     };
+    const emitFitChange = (result) => {
+        var _a;
+        (_a = createOptions.onEvent) === null || _a === void 0 ? void 0 : _a.call(createOptions, {
+            type: 'fit-change',
+            payload: result,
+        });
+    };
     const zoomController = createFileViewerZoomController({
-        root: () => container,
+        root: () => currentDocumentRoot || container,
         beforeZoom: runBeforeViewerOperation,
         onChange: state => emitZoomAndOperationAvailabilityChange(state),
     });
+    const fitController = createFileViewerFitController({
+        root: () => currentDocumentRoot || container,
+        getFit: () => options.fit,
+        onFit: result => {
+            zoomController.refreshProvider();
+            viewStateController.refreshProvider();
+            emitZoomAndOperationAvailabilityChange();
+            emitFitChange(result);
+        },
+    });
     const viewStateController = createFileViewerViewStateController({
-        root: () => container,
+        root: () => currentDocumentRoot || container,
         onChange: change => {
             var _a;
+            if ((change.source === 'user' || change.source === 'api') &&
+                change.action !== 'fit') {
+                fitController.markUserInteraction();
+            }
             (_a = createOptions.onEvent) === null || _a === void 0 ? void 0 : _a.call(createOptions, { type: 'view-state-change', payload: change });
         },
     });
     const documentActions = createFileViewerDocumentFeatureControllerActionHandlers({
-        root: () => container,
+        root: () => currentDocumentRoot || container,
         searchTarget: documentTarget,
         searchOptions: () => options.search,
         getAiOptions: () => options.ai,
@@ -378,6 +405,7 @@ export const createViewer = (container, createOptions = {}) => {
     });
     zoomController.observe();
     viewStateController.observe();
+    fitController.observe();
     const destroyCurrent = async (reason = 'replace') => {
         var _a;
         const session = renderSurfaceState.session;
@@ -394,6 +422,7 @@ export const createViewer = (container, createOptions = {}) => {
         await ((_a = session === null || session === void 0 ? void 0 : session.destroy) === null || _a === void 0 ? void 0 : _a.call(session));
         removeRenderTarget(target || undefined);
         currentSource = null;
+        currentDocumentRoot = null;
         applyFileViewerRenderSurfaceState(renderSurfaceState, {
             session: null,
             exportAdapter: null,
@@ -402,6 +431,7 @@ export const createViewer = (container, createOptions = {}) => {
         await documentActions.clearDocumentState();
         zoomController.clearProvider();
         viewStateController.clearProvider();
+        fitController.resetAutoFit();
         emitZoomAndOperationAvailabilityChange();
         if (source) {
             await emitLifecycle(options, createOptions.onEvent, 'unload-complete', source, version, startedAt, reason);
@@ -421,7 +451,10 @@ export const createViewer = (container, createOptions = {}) => {
             const renderer = registry.getByExtension(normalized.extension);
             const startedAt = Date.now();
             await emitLifecycle(options, createOptions.onEvent, 'load-start', normalized, version, startedAt);
-            const target = createRenderTarget((renderer === null || renderer === void 0 ? void 0 : renderer.id) !== 'office-presentation');
+            const surface = createRenderTarget((renderer === null || renderer === void 0 ? void 0 : renderer.id) !== 'office-presentation');
+            const target = surface.container;
+            const targetHost = surface.host || target;
+            currentDocumentRoot = target;
             if (!(renderer === null || renderer === void 0 ? void 0 : renderer.load)) {
                 renderMissingRendererState(target, normalized.extension, options);
                 applyFileViewerRenderSurfaceState(renderSurfaceState, { session: null });
@@ -434,7 +467,7 @@ export const createViewer = (container, createOptions = {}) => {
             try {
                 session = await renderer.load({
                     source: normalized,
-                    surface: { container: target },
+                    surface,
                     options,
                     signal: createOptions.signal,
                     registerExportAdapter: adapter => {
@@ -446,14 +479,14 @@ export const createViewer = (container, createOptions = {}) => {
             }
             catch (error) {
                 if (!requestScope.isCurrentRequest(version)) {
-                    removeRenderTarget(target);
+                    removeRenderTarget(targetHost);
                     return null;
                 }
-                removeRenderTarget(target);
+                removeRenderTarget(targetHost);
                 throw error;
             }
             if (!requestScope.isCurrentRequest(version)) {
-                await disposeStaleSession(session, target);
+                await disposeStaleSession(session, targetHost);
                 return null;
             }
             applyFileViewerRenderSurfaceState(renderSurfaceState, { session });
@@ -461,6 +494,11 @@ export const createViewer = (container, createOptions = {}) => {
             zoomController.refreshProvider();
             viewStateController.refreshProvider();
             await documentActions.refreshDocumentIndex({ notify: false });
+            await fitController.applyInitialFit({
+                skip: hasFileViewerExplicitInitialViewState(options.initialViewState),
+            });
+            zoomController.refreshProvider();
+            viewStateController.refreshProvider();
             emitZoomAndOperationAvailabilityChange();
             await emitLifecycle(options, createOptions.onEvent, 'load-complete', normalized, version, startedAt);
             return session;
@@ -471,14 +509,20 @@ export const createViewer = (container, createOptions = {}) => {
             documentActions.destroyDocumentFeatures();
             zoomController.destroy();
             viewStateController.destroy();
+            fitController.destroy();
             removeWatermarkOverlay();
         },
         updateOptions(nextOptions) {
+            const previousFit = options.fit;
             options = {
                 ...options,
                 ...nextOptions,
             };
             syncWatermarkOverlay();
+            if ('fit' in nextOptions && nextOptions.fit !== previousFit) {
+                fitController.resetAutoFit();
+                fitController.scheduleFit('resize');
+            }
         },
         getCapabilities(extension) {
             return getCapabilitiesForExtension(extension);
@@ -540,20 +584,30 @@ export const createViewer = (container, createOptions = {}) => {
             });
         },
         async zoomIn() {
+            fitController.markUserInteraction();
             const state = await zoomController.zoomIn();
             emitZoomAndOperationAvailabilityChange(state);
             return state;
         },
         async zoomOut() {
+            fitController.markUserInteraction();
             const state = await zoomController.zoomOut();
             emitZoomAndOperationAvailabilityChange(state);
             return state;
         },
         async resetZoom() {
+            fitController.markUserInteraction();
             const state = await zoomController.resetZoom();
             emitZoomAndOperationAvailabilityChange(state);
             return state;
         },
+        async fitToView(fit) {
+            const result = await fitController.fit(fit, { source: 'api', reason: 'api' });
+            zoomController.refreshProvider();
+            viewStateController.refreshProvider();
+            emitZoomAndOperationAvailabilityChange();
+            return result;
+        },
         getZoomState() {
             return zoomController.getState();
         },
@@ -561,6 +615,7 @@ export const createViewer = (container, createOptions = {}) => {
             return viewStateController.getState();
         },
         applyViewState(state, applyOptions) {
+            fitController.markUserInteraction();
             return viewStateController.applyState(state, applyOptions);
         },
         search(query) {

package/dist/viewer/operations.js

@@ -50,7 +50,7 @@ export const resolveFileViewerOperationFilename = ({ filename, source, fallback
 };
 export const resolveFileViewerOperationActionErrorMessage = ({ context, formatErrorMessage, prefixes, i18n, }) => {
     var _a;
-    return formatErrorMessage((_a = prefixes === null || prefixes === void 0 ? void 0 : prefixes[context.operation]) !== null && _a !== void 0 ? _a : translateFileViewerMessage(i18n, FILE_VIEWER_OPERATION_ACTION_ERROR_MESSAGE_KEYS[context.operation]), context.error);
+    return formatErrorMessage((_a = prefixes === null || prefixes === void 0 ? void 0 : prefixes[context.operation]) !== null && _a !== void 0 ? _a : translateFileViewerMessage(i18n, FILE_VIEWER_OPERATION_ACTION_ERROR_MESSAGE_KEYS[context.operation]), context.error, i18n);
 };
 export const hasFileViewerOriginalSource = (source) => {
     return !!source.buffer || !!source.file || !!source.url;

package/dist/viewer/state.d.ts

@@ -1,6 +1,6 @@
 import { type FileViewerI18nInput } from '../i18n/messages';
 import type { FileViewerRendererCategory, FileViewerStateDescriptor, FileViewerStateTheme } from '../contracts/types';
-export type FileViewerErrorMessageFormatter = (prefix: string, error: unknown) => string;
+export type FileViewerErrorMessageFormatter = (prefix: string, error: unknown, i18n?: FileViewerI18nInput) => string;
 export declare const FILE_VIEWER_PREVIEW_MESSAGES: Readonly<{
     downloading: "正在下载文件资源...";
     streamingPdf: "正在建立 PDF 流式预览...";
@@ -28,6 +28,6 @@ export declare const createFileViewerPreviewLoadingState: (extension?: string, m
 export declare const createFileViewerReadyState: (extension?: string, theme?: FileViewerStateTheme, i18n?: FileViewerI18nInput) => FileViewerStateDescriptor;
 export declare const createFileViewerEmptyState: (extension?: string, theme?: FileViewerStateTheme, i18n?: FileViewerI18nInput) => FileViewerStateDescriptor;
 export declare const createFileViewerUnsupportedState: (extension?: string, theme?: FileViewerStateTheme, i18n?: FileViewerI18nInput) => FileViewerStateDescriptor;
-export declare const normalizeFileViewerErrorMessage: (error: unknown) => string;
+export declare const normalizeFileViewerErrorMessage: (error: unknown, i18n?: FileViewerI18nInput) => string;
 export declare const formatFileViewerErrorMessage: FileViewerErrorMessageFormatter;
 export declare const createFileViewerErrorState: (extension?: string, error?: unknown, theme?: FileViewerStateTheme, i18n?: FileViewerI18nInput) => FileViewerStateDescriptor;

package/dist/viewer/state.js

@@ -197,20 +197,53 @@ export const createFileViewerUnsupportedState = (extension = '', theme = DEFAULT
         recoverable: true,
     });
 };
-export const normalizeFileViewerErrorMessage = (error) => {
+const FILE_VIEWER_KNOWN_ERROR_MESSAGE_KEYS = {
+    'Blob is not available in the current execution environment.': 'error.blobUnavailable',
+    'Unsupported file source input.': 'error.sourceUnsupported',
+    'Failed to read file as ArrayBuffer.': 'error.fileReadArrayBuffer',
+    'Failed to read file as data URL.': 'error.fileReadDataUrl',
+    'Failed to read file as text.': 'error.fileReadText',
+    'Unable to read image data URL.': 'error.imageDataUrlRead',
+    '文件不是有效的 DOCX/OOXML 压缩包，可能下载不完整或被服务端错误内容替换，请重新上传或检查文件源。': 'word.error.invalidDocx',
+    'ODF 文件缺少 content.xml': 'word.error.missingOdfContent',
+    'ODF 文件缺少 content.xml。': 'word.error.missingOdfContent',
+    'ODF XML 解析失败': 'word.error.odfXmlParseFailed',
+    'ODF XML 解析失败。': 'word.error.odfXmlParseFailed',
+    'OFD 文件中没有可渲染的文档': 'ofd.error.empty',
+    'OFD 文件解析失败': 'ofd.error.parseFailed',
+    'IndexedDB 不可用': 'archive.error.indexedDbUnavailable',
+    'Web Worker is not supported by this browser.': 'archive.error.workerUnsupported',
+};
+const resolveKnownFileViewerErrorMessage = (message, i18n) => {
+    const key = FILE_VIEWER_KNOWN_ERROR_MESSAGE_KEYS[message.trim()];
+    return key ? translateFileViewerMessage(i18n, key) : message;
+};
+export const normalizeFileViewerErrorMessage = (error, i18n) => {
     if (error instanceof Error) {
-        return error.message;
+        return resolveKnownFileViewerErrorMessage(error.message, i18n);
+    }
+    if (typeof error === 'string') {
+        return resolveKnownFileViewerErrorMessage(error, i18n);
+    }
+    if (error === undefined || error === null) {
+        return translateFileViewerMessage(i18n, 'error.unknown');
     }
     return String(error);
 };
-export const formatFileViewerErrorMessage = (prefix, error) => {
-    return `${prefix}：${normalizeFileViewerErrorMessage(error)}`;
+export const formatFileViewerErrorMessage = (prefix, error, i18n) => {
+    const detail = normalizeFileViewerErrorMessage(error, i18n);
+    if (!detail) {
+        return prefix;
+    }
+    return resolveFileViewerLocale(i18n) === 'zh-CN'
+        ? `${prefix}：${detail}`
+        : `${prefix}: ${detail}`;
 };
-export const createFileViewerErrorState = (extension = '', error = '未知错误', theme = DEFAULT_FILE_VIEWER_STATE_THEME, i18n) => createFileViewerStateDescriptor({
+export const createFileViewerErrorState = (extension = '', error = undefined, theme = DEFAULT_FILE_VIEWER_STATE_THEME, i18n) => createFileViewerStateDescriptor({
     state: 'error',
     extension,
     title: translateFileViewerMessage(i18n, 'state.error.title'),
-    message: normalizeFileViewerErrorMessage(error),
+    message: normalizeFileViewerErrorMessage(error, i18n),
     theme,
     recoverable: true,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@file-viewer/core",
-  "version": "2.1.17",
+  "version": "2.1.19",
   "private": false,
   "type": "module",
   "description": "Framework-neutral modular TypeScript core for Flyfish File Viewer renderer orchestration, lifecycle APIs, search, zoom, print, and export",