@djvlc/runtime-host-vue 1.0.1 → 1.0.3

package/dist/index.d.cts

@@ -1,21 +1,39 @@
 import * as vue from 'vue';
-import { Ref, ShallowRef, PropType, InjectionKey, Plugin } from 'vue';
+import { Ref, ShallowRef, ComputedRef, PropType, VNode, InjectionKey, Plugin } from 'vue';
 import * as _djvlc_runtime_core from '@djvlc/runtime-core';
 import { RuntimeOptions, DjvlcRuntime, RuntimePhase, PageResolveResult, RuntimeError, HostAPI, RuntimeState } from '@djvlc/runtime-core';
 export { HostAPI, PageResolveResult, RuntimeError, RuntimeOptions, RuntimePhase, RuntimeState } from '@djvlc/runtime-core';
-import * as _djvlc_contracts_types from '@djvlc/contracts-types';
 
 /**
  * Vue 运行时封装
  * 将核心运行时封装为 Vue 友好的 API
  */
 
+/**
+ * 性能指标
+ */
+interface VueRuntimeMetrics {
+    /** 初始化耗时 */
+    initTime: number;
+    /** 加载耗时 */
+    loadTime: number;
+    /** 渲染耗时 */
+    renderTime: number;
+    /** 总耗时 */
+    totalTime: number;
+    /** 初始化时间戳 */
+    initTimestamp: number | null;
+    /** 就绪时间戳 */
+    readyTimestamp: number | null;
+}
 /**
  * Vue 运行时选项
  */
 interface VueRuntimeOptions extends Omit<RuntimeOptions, 'container'> {
     /** 容器元素引用 */
     containerRef?: Ref<HTMLElement | null>;
+    /** 启用性能追踪 */
+    enableMetrics?: boolean;
 }
 /**
  * Vue 运行时返回值
@@ -33,6 +51,12 @@ interface VueRuntimeReturn {
     error: ShallowRef<RuntimeError | null>;
     /** Host API */
     hostApi: ShallowRef<HostAPI | null>;
+    /** 是否就绪 */
+    isReady: ComputedRef<boolean>;
+    /** 是否有错误 */
+    hasError: ComputedRef<boolean>;
+    /** 性能指标 */
+    metrics: ShallowRef<VueRuntimeMetrics>;
     /** 初始化 */
     init: () => Promise<void>;
     /** 加载页面 */
@@ -41,10 +65,18 @@ interface VueRuntimeReturn {
     render: () => Promise<void>;
     /** 销毁 */
     destroy: () => void;
+    /** 重新加载 */
+    reload: () => Promise<void>;
     /** 设置变量 */
     setVariable: (key: string, value: unknown) => void;
+    /** 批量设置变量 */
+    setVariables: (variables: Record<string, unknown>) => void;
+    /** 获取变量 */
+    getVariable: <T = unknown>(key: string) => T | undefined;
     /** 刷新数据 */
     refreshData: (queryId: string) => Promise<void>;
+    /** 执行动作 */
+    executeAction: <T = unknown>(actionType: string, params?: Record<string, unknown>) => Promise<T | undefined>;
 }
 /**
  * 创建 Vue 运行时
@@ -75,6 +107,12 @@ interface DJVRendererProps {
     debug?: boolean;
     /** 是否启用 SRI */
     enableSRI?: boolean;
+    /** 重试次数（默认 3） */
+    retryCount?: number;
+    /** 重试延迟（默认 1000ms） */
+    retryDelay?: number;
+    /** 超时时间（默认 30000ms） */
+    timeout?: number;
 }
 /**
  * DJV 渲染器组件
@@ -108,9 +146,21 @@ declare const DJVRenderer: vue.DefineComponent<vue.ExtractPropTypes<{
         type: BooleanConstructor;
         default: boolean;
     };
-}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    retryCount: {
+        type: NumberConstructor;
+        default: number;
+    };
+    retryDelay: {
+        type: NumberConstructor;
+        default: number;
+    };
+    timeout: {
+        type: NumberConstructor;
+        default: number;
+    };
+}>, () => VNode<vue.RendererNode, vue.RendererElement, {
     [key: string]: any;
-}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, ("ready" | "error" | "load")[], "ready" | "error" | "load", vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, ("ready" | "error" | "load" | "phase-change")[], "ready" | "error" | "load" | "phase-change", vue.PublicProps, Readonly<vue.ExtractPropTypes<{
     pageUid: {
         type: StringConstructor;
         required: true;
@@ -139,14 +189,30 @@ declare const DJVRenderer: vue.DefineComponent<vue.ExtractPropTypes<{
         type: BooleanConstructor;
         default: boolean;
     };
+    retryCount: {
+        type: NumberConstructor;
+        default: number;
+    };
+    retryDelay: {
+        type: NumberConstructor;
+        default: number;
+    };
+    timeout: {
+        type: NumberConstructor;
+        default: number;
+    };
 }>> & Readonly<{
     onError?: ((...args: any[]) => any) | undefined;
-    onReady?: ((...args: any[]) => any) | undefined;
     onLoad?: ((...args: any[]) => any) | undefined;
+    onReady?: ((...args: any[]) => any) | undefined;
+    "onPhase-change"?: ((...args: any[]) => any) | undefined;
 }>, {
     channel: "preview" | "prod" | "gray";
     debug: boolean;
     enableSRI: boolean;
+    retryCount: number;
+    retryDelay: number;
+    timeout: number;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 
 /**
@@ -157,6 +223,10 @@ interface DJVProviderProps {
     runtime: DjvlcRuntime | null;
     /** Host API */
     hostApi: HostAPI | null;
+    /** 容器类名 */
+    class?: string;
+    /** 是否显示调试信息 */
+    debug?: boolean;
 }
 /**
  * DJV Provider 组件
@@ -171,9 +241,17 @@ declare const DJVProvider: vue.DefineComponent<vue.ExtractPropTypes<{
         type: PropType<HostAPI | null>;
         default: null;
     };
+    class: {
+        type: StringConstructor;
+        default: string;
+    };
+    debug: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
 }>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
     [key: string]: any;
-}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, ("error" | "phase-change" | "state-change")[], "error" | "phase-change" | "state-change", vue.PublicProps, Readonly<vue.ExtractPropTypes<{
     runtime: {
         type: PropType<DjvlcRuntime | null>;
         default: null;
@@ -182,7 +260,21 @@ declare const DJVProvider: vue.DefineComponent<vue.ExtractPropTypes<{
         type: PropType<HostAPI | null>;
         default: null;
     };
-}>> & Readonly<{}>, {
+    class: {
+        type: StringConstructor;
+        default: string;
+    };
+    debug: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{
+    onError?: ((...args: any[]) => any) | undefined;
+    "onPhase-change"?: ((...args: any[]) => any) | undefined;
+    "onState-change"?: ((...args: any[]) => any) | undefined;
+}>, {
+    debug: boolean;
+    class: string;
     runtime: DjvlcRuntime | null;
     hostApi: HostAPI | null;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
@@ -215,8 +307,11 @@ declare function useDJVRuntime(): {
     state: vue.ComputedRef<RuntimeState>;
     loading: vue.ComputedRef<boolean>;
     phase: vue.ComputedRef<_djvlc_runtime_core.RuntimePhase>;
-    error: vue.ComputedRef<_djvlc_contracts_types.RuntimeError | null>;
-    page: vue.ComputedRef<_djvlc_contracts_types.PageResolveResult | null>;
+    error: vue.ComputedRef<_djvlc_runtime_core.RuntimeError | null>;
+    page: vue.ComputedRef<_djvlc_runtime_core.PageResolveResult | null>;
+    isReady: vue.ComputedRef<boolean>;
+    hasError: vue.ComputedRef<boolean>;
+    reload: () => Promise<void>;
 };
 /**
  * 使用 Host API
@@ -233,55 +328,189 @@ declare function useRuntimeStateWritable<T = unknown>(key: string, defaultValue?
 /**
  * 使用查询结果
  */
-declare function useQuery<T = unknown>(queryId: string): {
+declare function useQuery<T = unknown>(queryId: string, options?: {
+    /** 自动刷新间隔（毫秒） */
+    refreshInterval?: number;
+    /** 挂载时自动刷新 */
+    refreshOnMount?: boolean;
+    /** 窗口获得焦点时刷新 */
+    refreshOnFocus?: boolean;
+}): {
     data: Ref<T | undefined>;
     loading: Ref<boolean>;
     error: Ref<Error | null>;
     refetch: () => Promise<void>;
+    lastUpdated: Ref<number | null>;
 };
 /**
  * 使用动作
  */
-declare function useAction<T = unknown, P = Record<string, unknown>>(actionType: string): {
+declare function useAction<T = unknown, P = Record<string, unknown>>(actionType: string, options?: {
+    /** 执行成功回调 */
+    onSuccess?: (data: T) => void;
+    /** 执行失败回调 */
+    onError?: (error: Error) => void;
+    /** 重试次数 */
+    retryCount?: number;
+    /** 重试延迟（毫秒） */
+    retryDelay?: number;
+}): {
     execute: (params?: P) => Promise<T | undefined>;
     loading: Ref<boolean>;
     result: Ref<T | undefined>;
     error: Ref<Error | null>;
+    reset: () => void;
+    executionCount: Ref<number>;
 };
 /**
  * 使用数据请求
  */
-declare function useData<T = unknown, P = Record<string, unknown>>(queryId: string, params?: P, options?: {
+declare function useData<T = unknown, P = Record<string, unknown>>(queryId: string, params?: Ref<P> | P, options?: {
+    /** 立即执行（默认 true） */
     immediate?: boolean;
+    /** 自动刷新间隔（毫秒） */
+    refreshInterval?: number;
+    /** 参数变化时重新请求（默认 true） */
+    refreshOnParamsChange?: boolean;
+    /** 成功回调 */
+    onSuccess?: (data: T) => void;
+    /** 失败回调 */
+    onError?: (error: Error) => void;
 }): {
     data: Ref<T | undefined>;
     loading: Ref<boolean>;
     error: Ref<Error | null>;
     refetch: (newParams?: P) => Promise<void>;
+    isFetched: Ref<boolean>;
 };
 /**
  * 使用事件监听
  */
 declare function useRuntimeEvent<T = unknown>(eventType: string, handler: (data: T) => void): void;
+/**
+ * 使用页面信息
+ */
+declare function usePageInfo(): {
+    /** 页面 UID */
+    pageUid: vue.ComputedRef<string | undefined>;
+    /** 页面版本 ID */
+    pageVersionId: vue.ComputedRef<string | undefined>;
+    /** Schema 版本 */
+    schemaVersion: vue.ComputedRef<"1.0.0" | undefined>;
+    /** 页面标题 */
+    title: vue.ComputedRef<string | undefined>;
+    /** 页面配置 */
+    config: vue.ComputedRef<Record<string, unknown> | undefined>;
+    /** 页面是否已加载 */
+    isLoaded: vue.ComputedRef<boolean>;
+};
+/**
+ * 使用组件状态
+ */
+declare function useComponentState(componentId: string): {
+    /** 组件是否已加载 */
+    isLoaded: vue.ComputedRef<boolean>;
+    /** 组件是否加载中 */
+    isLoading: vue.ComputedRef<boolean>;
+    /** 组件是否加载失败 */
+    hasError: vue.ComputedRef<boolean>;
+    /** 加载耗时 */
+    loadTime: vue.ComputedRef<number | undefined>;
+    /** 组件信息 */
+    info: vue.ComputedRef<_djvlc_runtime_core.ComponentLoadResult | undefined>;
+};
+/**
+ * 使用生命周期钩子
+ */
+declare function useLifecycle(options?: {
+    onMounted?: () => void | Promise<void>;
+    onReady?: () => void | Promise<void>;
+    onError?: (error: unknown) => void;
+    onPhaseChange?: (phase: string) => void;
+}): {
+    /** 当前阶段 */
+    phase: vue.ComputedRef<_djvlc_runtime_core.RuntimePhase>;
+    /** 是否已 mounted */
+    hasMounted: Readonly<Ref<boolean, boolean>>;
+    /** 是否已 ready */
+    hasReady: Readonly<Ref<boolean, boolean>>;
+};
+/**
+ * 使用条件执行
+ * 当条件满足时执行回调
+ */
+declare function useWhen(condition: () => boolean, callback: () => void | Promise<void>, options?: {
+    /** 是否只执行一次 */
+    once?: boolean;
+    /** 是否立即检查 */
+    immediate?: boolean;
+}): {
+    /** 是否已执行 */
+    executed: Readonly<Ref<boolean, boolean>>;
+    /** 手动停止监听 */
+    stop: vue.WatchHandle;
+};
+/**
+ * 使用防抖动作
+ */
+declare function useDebouncedAction<T = unknown, P = Record<string, unknown>>(actionType: string, delay?: number): {
+    execute: (params?: P) => void;
+    loading: Ref<boolean>;
+    result: Ref<T | undefined>;
+    error: Ref<Error | null>;
+    cancel: () => void;
+};
+/**
+ * 使用全局配置
+ */
+declare function useGlobalConfig(): Record<string, unknown>;
 
 /**
  * Vue 插件
- * 全局注册 DJVLC 组件
+ * 全局注册 DJVLC 组件和指令
  */
 
+/**
+ * 全局配置 Key
+ */
+declare const DJVLC_CONFIG_KEY = "djvlc-config";
+/**
+ * 全局配置类型
+ */
+interface DJVGlobalConfig {
+    /** API 基础 URL */
+    apiBaseUrl?: string;
+    /** CDN 基础 URL */
+    cdnBaseUrl?: string;
+    /** 渠道 */
+    channel?: 'preview' | 'prod' | 'gray';
+    /** 调试模式 */
+    debug?: boolean;
+    /** 启用 SRI */
+    enableSRI?: boolean;
+    /** 启用性能追踪 */
+    enableMetrics?: boolean;
+    /** 重试次数 */
+    retryCount?: number;
+    /** 重试延迟 */
+    retryDelay?: number;
+    /** 超时时间 */
+    timeout?: number;
+}
 /**
  * 插件选项
  */
-interface DJVPluginOptions {
-    /** 全局配置 */
-    defaultApiBaseUrl?: string;
-    defaultCdnBaseUrl?: string;
+interface DJVPluginOptions extends DJVGlobalConfig {
     /** 是否注册全局组件 */
     registerComponents?: boolean;
+    /** 是否注册全局指令 */
+    registerDirectives?: boolean;
+    /** 组件前缀 */
+    componentPrefix?: string;
 }
 /**
  * DJVLC Vue 插件
  */
 declare const DJVPlugin: Plugin;
 
-export { DJVPlugin, type DJVPluginOptions, DJVProvider, type DJVProviderProps, DJVRenderer, type DJVRendererProps, RuntimeContextKey, type RuntimeContextValue, type VueRuntimeOptions, type VueRuntimeReturn, createVueRuntime, injectRuntime, provideRuntime, useAction, useDJVRuntime, useData, useHostApi, useQuery, useRuntimeEvent, useRuntimeState, useRuntimeStateWritable };
+export { type DJVGlobalConfig, DJVLC_CONFIG_KEY, DJVPlugin, type DJVPluginOptions, DJVProvider, type DJVProviderProps, DJVRenderer, type DJVRendererProps, RuntimeContextKey, type RuntimeContextValue, type VueRuntimeMetrics, type VueRuntimeOptions, type VueRuntimeReturn, createVueRuntime, injectRuntime, provideRuntime, useAction, useComponentState, useDJVRuntime, useData, useDebouncedAction, useGlobalConfig, useHostApi, useLifecycle, usePageInfo, useQuery, useRuntimeEvent, useRuntimeState, useRuntimeStateWritable, useWhen };