vtkviewer-vue 0.1.0

package/lib/types/core/I18nManager.d.ts

@@ -0,0 +1,135 @@
+import { Ref, ComputedRef } from 'vue';
+/**
+ * i18n 翻译函数签名。
+ * 与 vue-i18n / i18next / react-intl 的 t() 签名兼容。
+ *
+ * @param key 翻译 key
+ * @returns 翻译后的字符串；未找到对应 key 时返回 key 自身
+ */
+export type I18nTranslateFunction = (key: string) => string;
+/** 语言选项（对应 UI 下拉菜单中的语言条目） */
+export interface LanguageOption {
+    id: string;
+    label: string;
+}
+export declare class I18nManager {
+    /** 当前语言（单一数据源） */
+    readonly currentLocale: Ref<string>;
+    /**
+     * 翻译状态变更版号。
+     * _externalT / _packs 不是响应式的，通过此 ref 让 computed 感知它们的变化。
+     * 每次 setExternalTranslator() 或 registerLocale() 时递增。
+     */
+    private _stateVersion;
+    /** 外部注入的翻译函数（null = 无外部注入，走内置包） */
+    private _externalT;
+    /** 语言包注册表（locale → { key → value }） */
+    private _packs;
+    /**
+     * 默认语言标识。
+     * 由 VtkViewer 根据 props.locale 设置；未传 props.locale 时为 'zh'。
+     * 用于 reset 操作恢复初始语言。
+     */
+    private _defaultLocale;
+    /** UI 语言选项列表（下拉菜单可用语言） */
+    private _languageOptions;
+    /** locale 变更回调列表 */
+    private _localeCallbacks;
+    /** 是否已销毁 */
+    private _disposed;
+    constructor();
+    /**
+     * 设置/清除外部翻译函数。
+     *
+     * - 传入函数：后续 translate() 优先调用此函数
+     * - 传入 null：清除外部函数，完全回退内置包
+     *
+     * 外部函数的约定：
+     * - 找到翻译 → 返回翻译后的字符串
+     * - 未找到   → 返回 key 自身（不要返回 '' 或 undefined）
+     */
+    setExternalTranslator(fn: I18nTranslateFunction | null): void;
+    /**
+     * 命令式翻译快照。
+     *
+     * 每次调用返回当前 locale 下的翻译结果。
+     * 适用场景：非 Vue 上下文（工具函数、throw Error、console、DOM 操作）。
+     *
+     * @param key 翻译 key
+     * @returns 翻译后的字符串
+     */
+    translate(key: string): string;
+    /**
+     * 响应式翻译 computed。
+     *
+     * 返回 ComputedRef，在 Vue 的 computed/render 函数中使用时
+     * 自动追踪 currentLocale 变化，locale 切换后自动重求值。
+     *
+     * 适用场景：Vue render 函数、computed 属性、模板绑定。
+     *
+     * @param key 翻译 key
+     * @returns ComputedRef<string>
+     */
+    t(key: string): ComputedRef<string>;
+    /**
+     * 切换语言，触发所有响应式依赖更新。
+     * 同时同步通知 onLocaleChanged 注册的回调。
+     */
+    setLocale(locale: string): void;
+    /**
+     * 设置默认语言（由 VtkViewer 根据 props.locale 调用）。
+     * 只记录默认值，不切换当前语言。
+     */
+    setDefaultLocale(locale: string): void;
+    /**
+     * 重置到默认语言。
+     * 由 LanguageSwitchPlugin 响应 ResetManager 或类似重置操作时调用。
+     */
+    resetLocale(): void;
+    /** 注册/覆盖语言包 */
+    registerLocale(locale: string, pack: Record<string, string>): void;
+    /** 获取已注册的语言包 locale 列表 */
+    getAvailableLocales(): string[];
+    /**
+     * 设置 UI 语言选项列表（下拉菜单中显示的语言条目）。
+     * 传入空数组或不传则重置为内置默认 zh/en。
+     */
+    setLanguageOptions(opts?: LanguageOption[]): void;
+    /** 获取 UI 语言选项列表 */
+    getLanguageOptions(): LanguageOption[];
+    /**
+     * 注册 locale 变更回调。
+     * 与 EventBus 不同，此回调不经过事件总线，
+     * 直接在 currentLocale ref 变化时同步触发。
+     *
+     * @returns 取消注册函数
+     */
+    onLocaleChanged(callback: (locale: string) => void): () => void;
+    /** 销毁实例，释放回调引用（测试/多实例场景） */
+    dispose(): void;
+    /**
+     * 翻译查找核心逻辑。
+     *
+     * 优先级链：
+     *   1. 外部注入的 t(key)      — 不返回 key 自身 → 使用
+     *   2. currentLocale 内置包    — key 存在          → 使用
+     *   3. 默认 locale (zh) 内置包 — key 存在          → 使用
+     *   4. key 自身               — fallback          → 返回 key
+     */
+    private _lookup;
+}
+/**
+ * 获取全局 I18nManager 单例。
+ *
+ * 默认场景（单一查看器实例）直接使用此函数。
+ * 多实例场景可通过 new I18nManager() 创建独立实例。
+ */
+export declare function getI18nManager(): I18nManager;
+/**
+ * 便捷：全局单例的直接引用。
+ *
+ * 模块加载时即创建，可在任何 .ts 文件中直接 import 使用：
+ *   import { i18n } from '../core/I18nManager'
+ *   const text = i18n.translate('vtkviewer.plugin.rotate.name')
+ */
+export declare const i18n: I18nManager;

package/lib/types/core/InteractionSubContext.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 交互子上下文
+ * 管理用户交互工具（旋转、缩放、平移等）
+ */
+/** 交互配置 */
+export interface InteractionConfig {
+    rotate?: boolean;
+    zoom?: boolean;
+    pan?: boolean;
+    keyboardControl?: boolean;
+    gesture?: boolean;
+}
+/** 操纵器类型 */
+export type ManipulatorType = 'rotate' | 'zoom' | 'pan' | 'gesture' | 'keyboard';
+/** 操纵器配置 */
+export interface ManipulatorConfig {
+    /** 鼠标按钮（0=左键, 1=中键, 2=右键, -1=滚轮） */
+    button?: number;
+    /** 是否启用拖拽 */
+    dragEnabled?: boolean;
+    /** 是否启用滚动 */
+    scrollEnabled?: boolean;
+    /** 键盘按键列表 */
+    keys?: string[];
+    /** 手势类型 */
+    gestureType?: 'pinch' | 'rotate' | 'pan';
+    /** 自定义配置 */
+    [key: string]: any;
+}
+/**
+ * 交互子上下文接口
+ * 提供交互工具的开关、状态查询和高级配置能力
+ */
+export interface InteractionSubContext {
+    /** 初始化 VTK.js 交互管线（在渲染窗口可用后调用） */
+    init(): void;
+    /** 获取所有工具的启用状态 */
+    getEnabledTools(): {
+        rotate: boolean;
+        zoom: boolean;
+        pan: boolean;
+    };
+    /** 查询指定工具是否启用 */
+    isEnabled(tool: string): boolean;
+    /** 切换工具启用状态 */
+    toggleTool(tool: string): void;
+    /** 设置工具启用状态 */
+    setToolEnabled(tool: string, enabled: boolean): void;
+    /** 批量更新交互配置 */
+    updateInteraction(config: InteractionConfig): void;
+    /** 键盘控制是否启用 */
+    isKeyboardControlEnabled(): boolean;
+    /** 切换键盘控制 */
+    toggleKeyboardControl(): void;
+    /** 手势是否启用 */
+    isGestureEnabled(): boolean;
+    /** 是否为触屏设备 */
+    isTouchDevice(): boolean;
+    /** 获取指定类型的操纵器实例 */
+    getManipulator(type: ManipulatorType): any | null;
+    /** 配置指定类型的操纵器参数 */
+    configureManipulator(type: ManipulatorType, config: ManipulatorConfig): void;
+    /** 重置操纵器到默认配置 */
+    resetManipulator(type: ManipulatorType): void;
+    /** 重置所有操纵器到默认配置 */
+    resetAllManipulators(): void;
+    /** 获取当前交互配置快照 */
+    getInteractionSnapshot(): InteractionConfig & {
+        manipulators: Record<ManipulatorType, ManipulatorConfig>;
+    };
+    /** 释放所有 VTK.js 交互资源 */
+    dispose(): void;
+}

package/lib/types/core/RenderSubContext.d.ts

@@ -0,0 +1,74 @@
+import { vtkRenderWindow } from '@kitware/vtk.js/Rendering/Core/RenderWindow';
+import { vtkRenderer } from '@kitware/vtk.js/Rendering/Core/Renderer';
+import { vtkCamera } from '@kitware/vtk.js/Rendering/Core/Camera';
+/** 相机预设 */
+export type CameraPreset = 'front' | 'back' | 'left' | 'right' | 'top' | 'bottom' | 'iso';
+/** 相机状态（含投影模式、视场角、平行缩放） */
+export interface CameraState {
+    position: [number, number, number];
+    focalPoint: [number, number, number];
+    viewUp: [number, number, number];
+    /** 是否为平行投影（正交投影） */
+    parallelProjection?: boolean;
+    /** 平行投影缩放比例 */
+    parallelScale?: number;
+    /** 透视投影视场角（度） */
+    viewAngle?: number;
+}
+/** 截图选项 */
+export interface ScreenshotOptions {
+    /** 截图格式 */
+    format?: 'png' | 'jpeg' | 'webp';
+    /** 图片质量 (0-1) */
+    quality?: number;
+    /** 自定义宽度（像素），优先级高于 multiplier */
+    width?: number;
+    /** 自定义高度（像素），优先级高于 multiplier */
+    height?: number;
+    /** 倍率（1x/2x/4x），基于当前视口尺寸计算 */
+    multiplier?: 1 | 2 | 4;
+    /** 是否透明背景 */
+    transparentBackground?: boolean;
+}
+/**
+ * 渲染子上下文接口
+ * 提供 VTK.js 渲染管线的访问能力
+ */
+export interface RenderSubContext {
+    /** 获取渲染窗口 */
+    getRenderWindow(): vtkRenderWindow | null;
+    /** 获取渲染器 */
+    getRenderer(): vtkRenderer | null;
+    /** 获取相机 */
+    getCamera(): vtkCamera | null;
+    /** 获取交互器（来自 GenericRenderWindow，用于 OrientationMarkerWidget 等需要交互器的组件） */
+    getInteractor(): any | null;
+    /** 获取容器元素 */
+    getContainer(): HTMLElement | null;
+    /** 渲染器是否就绪 */
+    isReady(): boolean;
+    /** WebGL上下文是否丢失 */
+    isContextLost(): boolean;
+    /** 触发渲染 */
+    render(): void;
+    /** 重置相机（仅适配场景范围，不改变视角方向） */
+    resetCamera(): void;
+    /** 重置到默认视图（重置相机位置+视角+裁剪范围，用于加载新模型或重置所有） */
+    resetToDefaultView(): void;
+    /** 保存当前相机状态作为初始状态（模型加载后调用） */
+    saveInitialCameraState(): void;
+    /** 清除保存的初始相机状态（场景清除时调用） */
+    clearInitialCameraState(): void;
+    /** 设置相机预设视角 */
+    setCameraView(preset: CameraPreset): void;
+    /** 保存相机状态 */
+    saveCameraState(): CameraState;
+    /** 恢复相机状态 */
+    restoreCameraState(state: CameraState): void;
+    /** 将渲染管线附加到DOM容器（创建Canvas并初始化WebGL） */
+    attachToContainer(container: HTMLElement): void;
+    /** 通知 VTK.js 容器尺寸已变化，触发 Canvas 重新测量并渲染 */
+    resize(): void;
+    /** 释放所有VTK.js资源（销毁渲染窗口、渲染器等） */
+    dispose(): void;
+}

package/lib/types/core/ResetManager.d.ts

@@ -0,0 +1,122 @@
+import { EventBus } from './EventBus';
+import { ResetScope, ResetRegistry } from './ResetRegistry';
+/** 重置级别 */
+export declare enum ResetLevel {
+    /** 软重置：仅重置插件内部状态，保留配置 */
+    SOFT = "soft",
+    /** 硬重置：重置所有状态，恢复默认配置 */
+    HARD = "hard",
+    /** 完全重置：重置状态并重新初始化 */
+    FULL = "full"
+}
+/** 重置上下文 */
+export interface ResetContext {
+    /** 重置级别 */
+    level: ResetLevel;
+    /** 触发重置的来源 */
+    source: string;
+    /** 重置时间戳 */
+    timestamp: number;
+    /** 额外参数 */
+    params?: Record<string, any>;
+}
+/** 重置结果 */
+export interface ResetResult {
+    /** 插件 ID */
+    pluginId: string;
+    /** 是否成功 */
+    success: boolean;
+    /** 耗时（毫秒） */
+    duration: number;
+    /** 错误信息 */
+    error?: Error;
+}
+/** 重置报告 */
+export interface ResetReport {
+    /** 总插件数 */
+    total: number;
+    /** 成功数 */
+    succeeded: number;
+    /** 失败数 */
+    failed: number;
+    /** 跳过数（未实现重置） */
+    skipped: number;
+    /** 总耗时（毫秒） */
+    totalDuration: number;
+    /** 各插件结果 */
+    results: ResetResult[];
+}
+/** 重置管理器配置 */
+export interface ResetManagerConfig {
+    /** 单个插件重置超时时间（毫秒） */
+    pluginTimeout: number;
+    /** 是否在单个插件失败时继续执行 */
+    continueOnError: boolean;
+    /** 是否记录详细日志 */
+    verbose: boolean;
+    /** 重置前延迟（毫秒），用于防抖 */
+    debounceMs: number;
+}
+/**
+ * 重置管理器
+ * 对外提供统一的重置 API，内部完全委托 ResetRegistry
+ */
+export declare class ResetManager {
+    private config;
+    private eventBus;
+    private resetRegistry;
+    private debounceTimer;
+    constructor(eventBus: EventBus, resetRegistry: ResetRegistry, config?: Partial<ResetManagerConfig>);
+    /**
+     * 执行全局重置
+     * 只执行 scope 包含 GLOBAL 的动作，INDEPENDENT 动作不受影响
+     */
+    resetAll(level?: ResetLevel, source?: string, params?: Record<string, any>): Promise<ResetReport>;
+    /**
+     * 精准触发指定插件的指定重置动作
+     * 与全局 resetAll 完全解耦
+     *
+     * @param pluginId 目标插件 ID
+     * @param actionName 动作名称（省略则使用默认动作）
+     * @param level 重置级别
+     * @param source 触发来源
+     *
+     * @example
+     * // 清除测量数据（不触发全局重置）
+     * resetManager.invoke('measurement', 'clear')
+     *
+     * // 使用插件默认动作
+     * resetManager.invoke('cuttingPlane')
+     */
+    invoke(pluginId: string, actionName?: string, level?: ResetLevel, source?: string): Promise<ResetResult>;
+    /**
+     * 按作用域批量触发重置
+     *
+     * @example
+     * // 清理所有"非全局"的插件状态（如切换模型时）
+     * resetManager.invokeByScope(ResetScope.INDEPENDENT)
+     */
+    invokeByScope(scope: ResetScope, level?: ResetLevel, source?: string): Promise<ResetResult[]>;
+    /**
+     * 获取指定插件的所有可用重置动作
+     * 用于 UI 展示"可重置"菜单
+     */
+    getAvailableActions(pluginId: string): Array<{
+        name: string;
+        description?: string;
+        scope: ResetScope;
+    }>;
+    /**
+     * 获取所有已注册重置动作的插件列表
+     */
+    getResettablePluginIds(): string[];
+    /**
+     * 执行重置（带防抖）
+     */
+    private debounceReset;
+    /**
+     * 执行实际重置逻辑
+     * 通过 ResetRegistry 执行所有全局作用域动作
+     */
+    private executeReset;
+}

package/lib/types/core/ResetRegistry.d.ts

@@ -0,0 +1,170 @@
+import { PluginRegistry, IViewerPlugin } from '../plugins';
+import { EventBus } from './EventBus';
+import { ResetLevel, ResetContext, ResetResult } from './ResetManager';
+/**
+ * 重置作用域
+ * 决定一个重置动作在哪些场景下被触发
+ */
+export declare enum ResetScope {
+    /**
+     * 全局作用域：参与 resetAll 流程
+     * 典型场景：相机重置、工具状态恢复默认
+     */
+    GLOBAL = "global",
+    /**
+     * 独立作用域：不参与 resetAll，只能被显式调用
+     * 典型场景：清除测量数据、重置动画状态、重置特定 UI 面板
+     */
+    INDEPENDENT = "independent",
+    /**
+     * 条件作用域：仅在条件满足时参与 resetAll
+     * 典型场景：仅当模型已加载时才重置切割平面、仅当标注存在时才清除标注
+     */
+    CONDITIONAL = "conditional"
+}
+/** 重置动作守卫条件 */
+export interface ResetGuard {
+    /**
+     * 条件判断函数
+     * 返回 true 表示允许执行重置，false 表示跳过
+     */
+    predicate: () => boolean;
+    /** 条件不满足时的跳过原因（用于日志） */
+    skipReason?: string;
+}
+/** 重置链配置 */
+export interface ResetChain {
+    /**
+     * 当前动作完成后触发的目标动作列表
+     * 格式: 'pluginId:actionName' 或 'pluginId'（触发该插件的 default action）
+     */
+    triggers: string[];
+    /** 是否仅在当前动作成功时才触发链 */
+    onlyOnSuccess?: boolean;
+}
+/**
+ * 单个重置动作定义
+ * 插件通过 registerResetActions() 注册一个或多个动作
+ */
+export interface ResetAction {
+    /** 动作名称（同一插件内唯一） */
+    name: string;
+    /** 重置作用域 */
+    scope: ResetScope;
+    /**
+     * 执行函数
+     * @param context 重置上下文
+     */
+    execute: (context: ResetContext) => void | Promise<void>;
+    /** 是否为该插件的默认重置动作（未指定 actionName 时调用） */
+    isDefault?: boolean;
+    /** 作用域为 CONDITIONAL 时的守卫条件 */
+    guard?: ResetGuard;
+    /** 重置链：完成后触发的后续动作 */
+    chain?: ResetChain;
+    /** 优先级（数值小的先执行，默认 200） */
+    priority?: number;
+    /** 人类可读描述（用于日志和调试） */
+    description?: string;
+}
+/**
+ * 增强的可重置插件接口
+ * 替代原 IResettable，支持多动作注册
+ */
+export interface IResettableActions {
+    /**
+     * 注册该插件的所有重置动作
+     * 返回动作数组，由 ResetRegistry 统一索引
+     */
+    registerResetActions(): ResetAction[];
+}
+/**
+ * 类型守卫：检查插件是否实现了 IResettableActions
+ */
+export declare function hasResetActions(plugin: IViewerPlugin): plugin is IViewerPlugin & IResettableActions;
+/** 注册到 ResetRegistry 的动作条目 */
+interface ResetActionEntry {
+    /** 所属插件 ID */
+    pluginId: string;
+    /** 动作定义 */
+    action: ResetAction;
+    /** 全局唯一键: 'pluginId:actionName' */
+    key: string;
+}
+/**
+ * 重置注册表
+ * 负责收集、索引、查询所有插件的重置动作
+ *
+ * 生命周期：
+ *   1. 插件初始化时调用 collectActions() 收集所有动作
+ *   2. ResetManager 通过此表按需查找和执行动作
+ *   3. 插件卸载时自动移除其动作
+ */
+export declare class ResetRegistry {
+    private actions;
+    private pluginActions;
+    private eventBus;
+    private pluginRegistry;
+    private collected;
+    constructor(eventBus: EventBus, pluginRegistry: PluginRegistry);
+    /**
+     * 从所有已初始化插件中收集重置动作
+     * 应在所有插件 initAll() 完成后调用
+     */
+    collectActions(): void;
+    /**
+     * 注册单个插件的重置动作
+     */
+    private registerPluginActions;
+    /**
+     * 获取指定插件的所有重置动作
+     */
+    getActions(pluginId: string): ResetAction[];
+    /**
+     * 获取指定插件的默认重置动作
+     */
+    getDefaultAction(pluginId: string): ResetAction | undefined;
+    /**
+     * 通过 'pluginId:actionName' 键获取动作
+     */
+    getActionByKey(key: string): ResetActionEntry | undefined;
+    /**
+     * 获取所有属于指定作用域的动作
+     */
+    getActionsByScope(scope: ResetScope): ResetActionEntry[];
+    /**
+     * 获取所有参与全局重置的动作
+     * 即 scope === GLOBAL，或 scope === CONDITIONAL 且守卫条件满足
+     */
+    getGlobalResetActions(): ResetActionEntry[];
+    /**
+     * 检查插件是否有注册的重置动作
+     */
+    hasActions(pluginId: string): boolean;
+    /**
+     * 获取所有已注册的插件 ID
+     */
+    getRegisteredPluginIds(): string[];
+    /**
+     * 执行指定插件的指定动作
+     * @param pluginId 插件 ID
+     * @param actionName 动作名称（省略则使用默认动作）
+     * @param level 重置级别
+     * @param source 触发来源
+     */
+    invoke(pluginId: string, actionName?: string, level?: ResetLevel, source?: string): Promise<ResetResult>;
+    /**
+     * 批量执行指定作用域的所有动作
+     */
+    invokeByScope(scope: ResetScope, level?: ResetLevel, source?: string): Promise<ResetResult[]>;
+    /**
+     * 执行单个重置动作（含条件守卫、链式触发）
+     */
+    private executeAction;
+    /**
+     * 执行重置链
+     * @param triggers 目标列表，格式 'pluginId:actionName' 或 'pluginId'
+     */
+    private executeChain;
+}
+export {};

package/lib/types/core/SceneSubContext.d.ts

@@ -0,0 +1,25 @@
+import { Ref } from 'vue';
+import { vtkActor } from '@kitware/vtk.js/Rendering/Core/Actor';
+import { vtkVolume } from '@kitware/vtk.js/Rendering/Core/Volume';
+/**
+ * 场景子上下文接口
+ * 提供场景对象的增删查能力
+ */
+export interface SceneSubContext {
+    /** 获取所有 Actor */
+    getActors(): vtkActor[];
+    /** 获取所有 Volume */
+    getVolumes(): vtkVolume[];
+    /** 是否处于体渲染模式 */
+    isVolumeRendering(): boolean;
+    /** 场景中是否有模型（Actor 或 Volume） */
+    hasModels(): boolean;
+    /** 响应式模型数量（Vue 可追踪） */
+    readonly modelCount: Ref<number>;
+    /** 添加 Actor 到场景 */
+    addActor(actor: vtkActor): void;
+    /** 添加 Volume 到场景 */
+    addVolume(volume: vtkVolume): void;
+    /** 清空场景 */
+    clearScene(): void;
+}