vtkviewer-vue 0.1.0

package/lib/types/plugins/types/index.d.ts

@@ -0,0 +1,250 @@
+import { Component } from 'vue';
+import { ViewerContext } from '../../core/ViewerContext';
+/** 插件类型 */
+export declare const PluginType: {
+    readonly FORMAT: "format";
+    readonly TOOLBAR: "toolbar";
+    readonly UI: "ui";
+    readonly SERVICE: "service";
+};
+export type PluginType = (typeof PluginType)[keyof typeof PluginType];
+/** 插件元数据 */
+export interface PluginMetadata {
+    id: string;
+    name: string;
+    type: PluginType;
+    description?: string;
+    version?: string;
+    icon?: Component;
+}
+/** 插件配置 */
+export interface PluginConfig {
+    enabled?: boolean;
+    [key: string]: any;
+}
+/**
+ * 统一插件接口（所有插件基类）
+ */
+export interface IViewerPlugin<TConfig extends PluginConfig = PluginConfig> {
+    readonly metadata: PluginMetadata;
+    readonly dependencies?: string[];
+    readonly initOrder?: number;
+    readonly defaultConfig?: TConfig;
+    init(ctx: ViewerContext, config?: TConfig): void | Promise<void>;
+    dispose(): void;
+    onConfigChange?(config: TConfig): void;
+    /** 获取插件配置中 hideWhenNoModel 的值 */
+    getHideWhenNoModel?(): boolean;
+}
+/** 格式解析结果 */
+export interface FormatParseResult {
+    /** 渲染对象（Actor/Volume） */
+    actors?: any[];
+    volumes?: any[];
+    /** 原始数据（如点云、网格） */
+    data?: any;
+    /** 元数据 */
+    metadata?: Record<string, any>;
+    /** 是否为体渲染 */
+    isVolume?: boolean;
+}
+/**
+ * 格式处理器插件
+ * 负责文件解析、数据转换、场景构建
+ */
+export interface IFormatPlugin<T extends PluginConfig = PluginConfig> extends IViewerPlugin<T> {
+    readonly metadata: PluginMetadata & {
+        type: 'format';
+    };
+    /** 支持的格式列表 */
+    readonly formats: string[];
+    /** 优先级（数值越大越优先） */
+    readonly priority: number;
+    /** 是否能处理该格式 */
+    canHandle(format: string, buffer?: ArrayBuffer): boolean;
+    /** 解析文件 */
+    parse(arrayBuffer: ArrayBuffer, format: string, options?: Record<string, any>): Promise<FormatParseResult>;
+    /** 获取文件元数据（可选） */
+    getMetadata?(arrayBuffer: ArrayBuffer, format: string): Promise<Record<string, any>>;
+}
+/** 工具栏插件分组 */
+export type ToolbarPluginGroup = string;
+/**
+ * 工具栏图标配置
+ * 支持单图标、双状态图标、多状态图标
+ */
+export interface ToolbarIconConfig {
+    /** 默认图标（当无状态特定图标时使用） */
+    default: Component;
+    /** 激活状态图标（可选，用于开关类插件） */
+    active?: Component;
+    /** 非激活状态图标（可选，用于开关类插件） */
+    inactive?: Component;
+    /** 多状态图标（用于多状态插件，如坐标轴切换） */
+    states?: Record<string, Component>;
+}
+/**
+ * 图标配置类型
+ * 支持单组件或带状态的图标配置
+ */
+export type PluginIcon = Component | ToolbarIconConfig;
+/**
+ * 输入映射类型
+ * 支持键盘、鼠标、手势三种输入方式
+ */
+export type InputMappingType = 'keyboard' | 'mouse' | 'gesture';
+/**
+ * 输入映射
+ * 定义一个具体的输入绑定
+ */
+export interface InputMapping {
+    /** 映射类型，默认 'keyboard' */
+    type?: InputMappingType;
+    /** 键盘按键（type='keyboard' 或省略 type 时使用） */
+    key?: string;
+    /** 键盘修饰键 */
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    meta?: boolean;
+    /** 鼠标按钮（type='mouse' 时使用，0=左键, 1=中键, 2=右键） */
+    button?: number;
+    /** 鼠标事件（type='mouse' 时使用） */
+    event?: 'click' | 'dblclick' | 'mousedown' | 'mouseup';
+    /** 手势类型（type='gesture' 时使用） */
+    gesture?: 'pinch' | 'rotate' | 'swipe' | 'pan';
+    /** 手势方向（type='gesture' 时使用） */
+    direction?: 'up' | 'down' | 'left' | 'right';
+}
+/**
+ * 键盘快捷键配置项（仅支持键盘按键）
+ * 用于工具栏插件的快捷键配置
+ */
+export interface KeyboardShortcutConfigItem {
+    /** 动作标识 */
+    action: string;
+    /** 动作描述 */
+    description?: string;
+    /** 按键（单个按键或组合键，如 'f' 或 'Ctrl+S'） */
+    key: string | string[];
+}
+/**
+ * 快捷键配置类型
+ * 支持多种简写形式，最终统一解析为 KeyboardShortcutConfigItem[]
+ *
+ * 使用规则：
+ * - string / string[]：仅当插件只有一种 action 时使用，等价于 { action: metadata.id, key: ... }
+ * - KeyboardShortcutConfigItem / KeyboardShortcutConfigItem[]：多 action 或需要自定义描述时使用
+ */
+export type ShortcutConfig = string | string[] | KeyboardShortcutConfigItem | KeyboardShortcutConfigItem[];
+export interface KeyboardShortcutAction {
+    /** 快捷键名称，对应 KeyboardShortcutConfigItem 的 action */
+    name?: string;
+    key: string;
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    action: () => void;
+    description?: string;
+}
+/**
+ * 工具栏插件基础配置
+ * 所有工具栏插件的 config 都应继承此接口
+ */
+export interface ToolbarPluginConfig extends PluginConfig {
+    /** 图标配置 */
+    icon?: PluginIcon;
+    /** 开关类插件的默认激活状态，true=默认开启，false/undefined=默认关闭 */
+    defaultActive?: boolean;
+    /** 没有模型时是否隐藏 */
+    hideWhenNoModel?: boolean;
+    /** 分组标识（可选），通过注册时配置传入，如 `[PluginClass, { group: 'core' }]` */
+    group?: ToolbarPluginGroup;
+    /** 快捷键配置（支持多种简写形式，统一解析为 KeyboardShortcutConfigItem[]） */
+    shortcut?: ShortcutConfig;
+    /** 在信息显示区的显示排序，越小越靠前 */
+    infoPanelPriority?: number;
+    /** 在工具栏拓展功能区域的显示排序越小越靠前 */
+    toolbarExtensionPriority?: number;
+}
+/**
+ * 工具栏插件
+ */
+export interface IToolbarPlugin extends IViewerPlugin {
+    readonly metadata: PluginMetadata & {
+        type: 'toolbar';
+    };
+    readonly order: number;
+    readonly icon?: PluginIcon;
+    getIcon?(state?: string): Component | undefined;
+    /** 获取分组标识（从 config.group 读取） */
+    getGroup?(): ToolbarPluginGroup | undefined;
+    render(): Component;
+    isVisible(ctx: ViewerContext): boolean;
+    /** 获取快捷键配置列表（统一解析后的标准格式） */
+    getShortcutConfig?(): KeyboardShortcutConfigItem[];
+    getKeyboardShortcutActions?(): KeyboardShortcutAction[];
+    /**
+     * 渲染扩展区内容（可选）
+     * 当插件功能激活时，扩展区内容将显示在工具栏下方
+     */
+    renderExtension?(): Component;
+    /**
+     * 扩展区是否激活（可选）
+     * 返回 true 时显示扩展区内容
+     */
+    isExtensionActive?(): boolean;
+}
+/** UI插件子类型 */
+export type UIPluginType = 'overlay' | 'panel' | 'notification' | 'portal';
+/** UI插件位置 */
+export type UIPluginPosition = 'top' | 'bottom' | 'left' | 'right' | 'center';
+/**
+ * UI插件
+ */
+export interface IUIPlugin extends IViewerPlugin {
+    readonly metadata: PluginMetadata & {
+        type: 'ui';
+    };
+    readonly uiType: UIPluginType;
+    readonly order: number;
+    render(): Component;
+    isVisible(ctx: ViewerContext): boolean;
+    getPosition?(): UIPluginPosition;
+    activate?(): void;
+    deactivate?(): void;
+    /** 获取 Teleport 目标（仅 uiType='portal' 时生效） */
+    getPortalTarget?(): string | Element | null;
+    /** 获取 Teleport 额外属性（仅 uiType='portal' 时生效） */
+    getPortalProps?(): Record<string, any>;
+}
+/**
+ * 服务插件（无UI）
+ */
+export interface IServicePlugin extends IViewerPlugin {
+    readonly metadata: PluginMetadata & {
+        type: 'service';
+    };
+}
+/** 通用插件标识类型 */
+export type PluginIdentifier<T extends PluginConfig = PluginConfig> = string | (new (...args: any[]) => IViewerPlugin<T>);
+/** 格式插件标识类型（仅类引用） */
+export type FormatPluginIdentifier<T extends PluginConfig = PluginConfig> = new (...args: any[]) => IFormatPlugin<T>;
+/** 通用插件配置项 */
+export type PluginItem<T extends PluginConfig = PluginConfig> = PluginIdentifier<T> | [PluginIdentifier<T>, T?];
+/** 格式插件配置项 */
+export type FormatPluginItem<T extends PluginConfig = PluginConfig> = FormatPluginIdentifier<T> | [FormatPluginIdentifier<T>, T?];
+/**
+ * 分类插件配置
+ * 按插件类型分组配置，支持按分类独立配置和覆盖
+ */
+export interface PluginsConfig {
+    /** 格式插件 */
+    format?: FormatPluginItem[];
+    /** 工具栏插件 */
+    toolbar?: PluginItem[];
+    /** UI 插件 */
+    ui?: PluginItem[];
+    /** 服务插件 */
+    service?: PluginItem[];
+}

package/lib/types/plugins/ui/ErrorPlugin.d.ts

@@ -0,0 +1,30 @@
+import { IUIPlugin, PluginConfig } from '../types';
+import { PluginBase } from '../PluginBase';
+import { DefineComponent, VNode, RendererNode, RendererElement, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+/** 错误提示插件配置 */
+export interface ErrorPluginConfig extends PluginConfig {
+    /** 是否显示重试按钮 */
+    showRetry?: boolean;
+    /** 遮罩层背景色（覆盖 CSS 变量 --iimm-vtk-error-overlay-bg），默认继承主题 */
+    overlayBackground?: string;
+}
+/**
+ * 错误提示插件
+ * 显示错误信息和恢复操作
+ */
+export declare class ErrorPlugin extends PluginBase<ErrorPluginConfig> implements IUIPlugin {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "ui";
+        description: string;
+    };
+    readonly uiType: "overlay";
+    readonly order = 1;
+    readonly defaultConfig: ErrorPluginConfig;
+    render(): DefineComponent<{}, () => VNode<RendererNode, RendererElement, {
+        [key: string]: any;
+    }> | null, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+    isVisible(): boolean;
+    getPosition(): 'bottom';
+}

package/lib/types/plugins/ui/FilenameInfoPlugin.d.ts

@@ -0,0 +1,40 @@
+import { IUIPlugin, PluginConfig } from '../types';
+import { PluginBase } from '../PluginBase';
+import { DefineComponent, VNode, RendererNode, RendererElement, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+/** 文件名信息插件配置 */
+export interface FilenameInfoPluginConfig extends PluginConfig {
+    /** 无模型时是否隐藏，默认 true */
+    hideWhenNoModel?: boolean;
+}
+/**
+ * 文件名信息展示插件
+ * 在视口底部以半透明状态栏形式显示当前加载模型的文件名
+ */
+export declare class FilenameInfoPlugin extends PluginBase<FilenameInfoPluginConfig> implements IUIPlugin {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "ui";
+        description: string;
+    };
+    readonly uiType: "overlay";
+    readonly order = 2;
+    readonly defaultConfig: FilenameInfoPluginConfig;
+    /** 当前显示的文件名文本 */
+    private displayName;
+    /** 当前显示的文件名类型提示 */
+    private sourceType;
+    protected onInit(): void;
+    /**
+     * 根据输入解析显示名称。
+     *
+     * @param raw 场景加载事件中的 filename 字段
+     * @returns 处理后的显示名称，无效时返回空字符串
+     */
+    private resolveDisplayName;
+    render(): DefineComponent<{}, () => VNode<RendererNode, RendererElement, {
+        [key: string]: any;
+    }> | null, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+    isVisible(): boolean;
+    getPosition(): 'bottom';
+}

package/lib/types/plugins/ui/LoadingPlugin.d.ts

@@ -0,0 +1,28 @@
+import { IUIPlugin, PluginConfig } from '../types';
+import { PluginBase } from '../PluginBase';
+import { DefineComponent, VNode, RendererNode, RendererElement, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+/** 加载进度插件配置 */
+export interface LoadingPluginConfig extends PluginConfig {
+    /** 是否显示进度条 */
+    showProgress?: boolean;
+}
+/**
+ * 加载进度插件
+ * 显示文件加载进度（现代化玻璃态卡片 + 环形进度条）
+ */
+export declare class LoadingPlugin extends PluginBase<LoadingPluginConfig> implements IUIPlugin {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "ui";
+        description: string;
+    };
+    readonly uiType: "overlay";
+    readonly order = 0;
+    readonly defaultConfig: LoadingPluginConfig;
+    render(): DefineComponent<{}, () => VNode<RendererNode, RendererElement, {
+        [key: string]: any;
+    }> | null, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+    isVisible(): boolean;
+    getPosition(): 'center';
+}

package/lib/types/plugins/ui/SceneTreePlugin.d.ts

@@ -0,0 +1,60 @@
+import { Component } from 'vue';
+import { IResettableActions, ResetAction } from '../../core';
+import { IUIPlugin, PluginConfig, UIPluginPosition } from '../types';
+import { PluginBase } from '../PluginBase';
+/** 场景树插件配置 */
+export interface SceneTreePluginConfig extends PluginConfig {
+    /** 面板宽度（px），默认 280 */
+    panelWidth?: number;
+    /** 是否在无模型时隐藏，默认 true */
+    hideWhenNoModel?: boolean;
+    /** 面板位置，默认 'left' */
+    position?: 'left' | 'right';
+}
+export declare class SceneTreePlugin extends PluginBase<SceneTreePluginConfig> implements IUIPlugin, IResettableActions {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "ui";
+        description: string;
+    };
+    readonly uiType: "panel";
+    readonly order = 10;
+    readonly defaultConfig: SceneTreePluginConfig;
+    /** 场景树条目列表 */
+    private items;
+    /** 面板是否展开 */
+    private isExpanded;
+    /** 颜色拾取中条目的 ID（打开颜色选择器的条目） */
+    private pickingColorId;
+    /**
+     * 初始状态快照
+     * 每次场景加载时记录所有 actor/volume 的初始 visible/opacity/color，
+     * resetAll 时恢复到此状态
+     */
+    private initialStates;
+    protected onInit(): void;
+    /**
+     * 保存当前场景对象的状态作为初始状态快照
+     * 用于 resetAll 时恢复
+     */
+    private saveInitialStates;
+    /**
+     * 刷新场景树条目
+     * 扫描场景中的 Actor 和 Volume，同步到树列表
+     */
+    private refreshSceneItems;
+    protected onDispose(): void;
+    /** 切换面板展开/收起 */
+    private togglePanel;
+    /** 切换条目显隐 */
+    private toggleVisibility;
+    /** 设置条目透明度 */
+    private setOpacity;
+    /** 设置 Actor 颜色 */
+    private setColor;
+    registerResetActions(): ResetAction[];
+    isVisible(): boolean;
+    getPosition(): UIPluginPosition;
+    render(): Component;
+}

package/lib/types/plugins/ui/WebGLContextLostPlugin.d.ts

@@ -0,0 +1,33 @@
+import { IUIPlugin, PluginConfig } from '../types';
+import { PluginBase } from '../PluginBase';
+import { DefineComponent, VNode, RendererNode, RendererElement, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+/** WebGL上下文丢失插件配置 */
+export interface WebGLContextLostPluginConfig extends PluginConfig {
+    /** 最大重试次数 */
+    maxRetries?: number;
+}
+/**
+ * WebGL上下文丢失插件
+ * 显示WebGL上下文丢失提示和恢复操作
+ */
+export declare class WebGLContextLostPlugin extends PluginBase<WebGLContextLostPluginConfig> implements IUIPlugin {
+    readonly metadata: {
+        id: string;
+        name: string;
+        type: "ui";
+        description: string;
+    };
+    readonly uiType: "overlay";
+    readonly order = 2;
+    readonly defaultConfig: WebGLContextLostPluginConfig;
+    private isContextLost;
+    private retryCount;
+    protected onInit(): void;
+    private onContextLost;
+    private onContextRestored;
+    render(): DefineComponent<{}, () => VNode<RendererNode, RendererElement, {
+        [key: string]: any;
+    }> | null, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+    isVisible(): boolean;
+    getPosition(): 'center';
+}

package/lib/types/plugins/ui/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * UI插件导出
+ */
+export * from './LoadingPlugin';
+export * from './ErrorPlugin';
+export * from './WebGLContextLostPlugin';
+export * from './FilenameInfoPlugin';
+export * from './SceneTreePlugin';

package/lib/types/polyfills.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/types/index.d.ts

@@ -0,0 +1,187 @@
+import { Ref } from 'vue';
+import { I18nTranslateFunction, LanguageOption, ThemeConfig, ViewerContext } from '../core';
+import { PluginsConfig } from '../plugins';
+/** 工具栏组件Props */
+export interface PluginToolbarProps {
+    /** 查看器上下文 */
+    ctx: ViewerContext;
+    /** 自定义类名 */
+    class?: string | string[];
+    /** i18n 版本号（locale 变更时递增，用于清空 renderCache） */
+    localeVersion?: number | Ref<number>;
+}
+/** 工具栏扩展区Props */
+export interface ToolbarExtensionProps {
+    /** 查看器上下文 */
+    ctx: ViewerContext;
+    /** 自定义类名 */
+    class?: string | string[];
+    /** 背景色 */
+    background?: string;
+    /** 圆角（px），默认 8 */
+    borderRadius?: number;
+    /** 内边距（px），默认 4 8 */
+    padding?: string;
+    /** 分隔线颜色 */
+    separatorColor?: string;
+    /** 按钮间距（px），默认 2 */
+    gap?: number;
+}
+/** 工具栏信息区Props */
+export interface ToolbarInfoPanelProps {
+    /** 查看器上下文 */
+    ctx: ViewerContext;
+    /** 自定义类名 */
+    class?: string | string[];
+    /** 背景色 */
+    background?: string;
+    /** 圆角（px），默认 8 */
+    borderRadius?: number;
+    /** 内边距（px），默认 4 8 */
+    padding?: string;
+    /** 字体大小，默认 12px */
+    fontSize?: number;
+    /** 最大高度（px），超出后滚动，默认 120 */
+    maxHeight?: number;
+}
+/** 工具栏配置 */
+export interface ToolbarConfig {
+    /** 图标尺寸（px），默认 20 */
+    iconSize?: number;
+    /** 按钮尺寸（px），默认 32 */
+    buttonSize?: number;
+    /** 背景色，默认 rgba(167, 165, 165, 0.6) */
+    background?: string;
+    /** 圆角（px），默认 8 */
+    borderRadius?: number;
+    /** 内边距（px），默认 8 */
+    padding?: number;
+    /** 按钮间距（px），默认 2 */
+    gap?: number;
+    /** 按钮背景色，默认 rgba(255, 255, 255, 0.06) */
+    buttonBackground?: string;
+    /** 按钮圆角（px），默认 6 */
+    buttonBorderRadius?: number;
+    /** 分隔线颜色，默认 rgba(255, 255, 255, 0.2) */
+    separatorColor?: string;
+}
+/** UI插件配置 */
+export interface UIConfig {
+    /** 没有模型时是否隐藏UI插件，默认 false */
+    hideWhenNoModel?: boolean;
+}
+/** 信息面板配置 */
+export interface InfoPanelConfig {
+    /** 是否显示信息面板，默认 true */
+    show?: boolean;
+    /** 背景色 */
+    background?: string;
+    /** 圆角（px），默认 8 */
+    borderRadius?: number;
+    /** 内边距，默认 '4px 8px' */
+    padding?: string;
+    /** 字体大小（px），默认 12 */
+    fontSize?: number;
+    /** 最大高度（px），默认 120 */
+    maxHeight?: number;
+}
+/** 数据源类型 */
+export type VtkViewerSource = File | string | ArrayBuffer | ReadableStream;
+/** VtkViewer组件属性 */
+export interface VtkViewerProps {
+    /** 默认背景色（响应式，支持外部动态修改）
+     * @default '#e6e6e6'
+     */
+    background?: string;
+    /** 自定义类名 */
+    class?: string | string[];
+    /** 工具栏配置，false 则隐藏工具栏 */
+    toolbar?: ToolbarConfig | boolean;
+    /** 传递到 PluginToolbar 的自定义 CSS class */
+    toolbarClass?: string | string[];
+    /** 信息面板配置，false 则隐藏信息面板 */
+    infoPanel?: InfoPanelConfig | boolean;
+    /** 传递到 ToolbarInfoPanel 的自定义 CSS class */
+    toolbarInfoPanelClass?: string | string[];
+    /** 传递到 ToolbarExtension 的自定义 CSS class */
+    toolbarExtensionClass?: string | string[];
+    /** UI插件配置 */
+    ui?: UIConfig;
+    /**
+     * 插件配置（高优先级）
+     * 采用分类配置格式，按插件类型分组：
+     *   - format:  格式插件
+     *   - toolbar: 工具栏插件
+     *   - ui:      UI 插件
+     *   - service: 服务插件
+     *
+     * 当 ctx 由外部传入时，同分类配置将覆盖 useViewer 中的默认配置。
+     * 当 ctx 由内部创建时，作为 useViewer 的 plugins 参数。
+     */
+    plugins?: PluginsConfig;
+    /**
+     * 数据源（File/URL/ArrayBuffer/ReadableStream），组件内部自动加载
+     * 设置后外部无需手动调用 loadFile 等操作
+     */
+    source?: VtkViewerSource | null;
+    /**
+     * 数据源格式（可选，但建议提供）
+     * 当 source 为 File 或 URL 时，可以从文件扩展名自动检测
+     * 当 source 为 ArrayBuffer 或 ReadableStream 时，建议提供此参数
+     * 如果不提供，内部会尝试使用魔数（magic number）进行格式探测
+     */
+    sourceFormat?: string;
+    /** 数据源文件名（当 source 为 ArrayBuffer 或 ReadableStream 时可选，用于格式检测） */
+    sourceFilename?: string;
+    /** 主题ID（如 'dark', 'light', 'ocean', 'forest', 'sunset'）
+     * @default 'light'
+    */
+    theme?: string;
+    /** 自定义主题配置（格式与内置主题一致，同名覆盖内置主题） */
+    customThemes?: Record<string, ThemeConfig>;
+    /**
+     * 国际化翻译函数（外部注入）。
+     * 不传时所有字符串原样使用 key 作为 fallback。
+     * key 格式：`vtkviewer.模块.子键`（如 `vtkviewer.toolbar.rotate.title`）
+     */
+    t?: I18nTranslateFunction | null;
+    /**
+     * 当前语言标识（如 'zh', 'en'）。
+     * 变更时触发 renderCache 清理和组件重渲染。
+     * @default 'zh'
+     */
+    locale?: string;
+    /**
+     * 可用语言列表。
+     * 传递给 LanguageSwitchPlugin，未传时默认 [{ id:'zh', label:'中文' }, { id:'en', label:'English' }]。
+     */
+    languages?: LanguageOption[];
+    /**
+     * 外部解码器路径配置。
+     * 键为解码器标识，值为 JS 文件路径（本地 public/ 路径或 CDN URL）。
+     * 支持的标识：
+     *   - draco: Draco 解码器，对应 draco_decoder.js
+     *   - ifc:   IFC 解码器（预留），对应 web-ifc.js
+     * 未配置时插件会尝试动态 import 对应的 npm 包。
+     */
+    decoders?: Record<string, string>;
+    /**
+     * 是否启用调试日志输出。
+     * 开启后会在控制台输出插件初始化、过程追踪等调试信息。
+     * 生产环境建议保持关闭。
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * 是否启用手势控制（触摸/捏合/旋转等触屏交互）。
+     * 设置为 false 时，即使硬件支持触屏，手势交互也不会启用。
+     * @default true。
+     */
+    enableGesture?: boolean;
+    /**
+     * 是否启用键盘控制（相机 WASD 导航和所有插件快捷键）。
+     * 设置为 false 时，所有键盘快捷键失效且不在 tooltip 中显示。
+     * @default true。
+     */
+    enableKeyboard?: boolean;
+}