@djvlc/runtime-host-react 1.1.2 → 1.1.4

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+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 react from 'react';
@@ -8,12 +9,31 @@ import react__default, { ReactNode } from 'react';
  * 将核心运行时封装为 React 友好的 API
  */
 
+/**
+ * 性能指标
+ */
+interface ReactRuntimeMetrics {
+    /** 初始化耗时 */
+    initTime: number;
+    /** 加载耗时 */
+    loadTime: number;
+    /** 渲染耗时 */
+    renderTime: number;
+    /** 总耗时 */
+    totalTime: number;
+    /** 初始化时间戳 */
+    initTimestamp: number | null;
+    /** 就绪时间戳 */
+    readyTimestamp: number | null;
+}
 /**
  * React 运行时选项
  */
 interface ReactRuntimeOptions extends Omit<RuntimeOptions, 'container'> {
     /** 容器元素引用 */
     containerRef?: React.RefObject<HTMLElement>;
+    /** 启用性能追踪 */
+    enableMetrics?: boolean;
 }
 /**
  * React 运行时返回值
@@ -31,6 +51,12 @@ interface ReactRuntimeReturn {
     error: RuntimeError | null;
     /** Host API */
     hostApi: HostAPI | null;
+    /** 是否就绪 */
+    isReady: boolean;
+    /** 是否有错误 */
+    hasError: boolean;
+    /** 性能指标 */
+    metrics: ReactRuntimeMetrics;
     /** 初始化 */
     init: () => Promise<void>;
     /** 加载页面 */
@@ -39,10 +65,18 @@ interface ReactRuntimeReturn {
     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>;
 }
 /**
  * 使用 React 运行时 Hook
@@ -118,21 +152,31 @@ interface DJVRendererProps {
     onError?: (error: RuntimeError) => void;
     /** 就绪回调 */
     onReady?: () => void;
+    /** 阶段变化回调 */
+    onPhaseChange?: (phase: string) => void;
     /** 加载中显示 */
     loadingComponent?: ReactNode;
     /** 错误显示 */
-    errorComponent?: ReactNode | ((error: RuntimeError) => ReactNode);
+    errorComponent?: ReactNode | ((error: RuntimeError, retry: () => void) => ReactNode);
+    /** 空状态显示 */
+    emptyComponent?: ReactNode;
     /** 子元素 */
     children?: ReactNode;
     /** 容器类名 */
     className?: string;
     /** 容器样式 */
     style?: react__default.CSSProperties;
+    /** 重试次数（默认 3） */
+    retryCount?: number;
+    /** 重试延迟（默认 1000ms） */
+    retryDelay?: number;
+    /** 超时时间（默认 30000ms） */
+    timeout?: number;
 }
 /**
  * DJV 渲染器组件
  */
-declare function DJVRenderer({ pageUid, apiBaseUrl, cdnBaseUrl, channel, userId, deviceId, authToken, previewToken, debug, enableSRI, onLoad, onError, onReady, loadingComponent, errorComponent, children, className, style, }: DJVRendererProps): JSX.Element;
+declare function DJVRenderer({ pageUid, apiBaseUrl, cdnBaseUrl, channel, userId, deviceId, authToken, previewToken, debug, enableSRI, onLoad, onError, onReady, onPhaseChange, loadingComponent, errorComponent, emptyComponent, children, className, style, retryCount, retryDelay, timeout, }: DJVRendererProps): JSX.Element;
 
 /**
  * DJV Provider 组件
@@ -149,17 +193,22 @@ interface DJVProviderProps {
     hostApi: HostAPI | null;
     /** 子元素 */
     children: ReactNode;
+    /** 容器类名 */
+    className?: string;
+    /** 是否显示调试信息 */
+    debug?: boolean;
+    /** 状态变更回调 */
+    onStateChange?: (state: RuntimeState) => void;
+    /** 阶段变更回调 */
+    onPhaseChange?: (phase: RuntimePhase) => void;
+    /** 错误回调 */
+    onError?: (error: RuntimeError) => void;
 }
 /**
  * DJV Provider 组件
  * 用于手动控制运行时时使用
  */
-declare function DJVProvider({ runtime, hostApi, children, }: DJVProviderProps): JSX.Element;
-
-/**
- * React Hooks
- * 运行时相关的 React Hooks
- */
+declare function DJVProvider({ runtime, hostApi, children, className, debug, onStateChange, onPhaseChange, onError, }: DJVProviderProps): JSX.Element;
 
 /**
  * 使用 DJV 运行时
@@ -171,6 +220,12 @@ declare function useDJVRuntime(): {
     phase: RuntimePhase;
     error: RuntimeError | null;
     page: PageResolveResult | null;
+    /** 是否已就绪 */
+    isReady: boolean;
+    /** 是否有错误 */
+    hasError: boolean;
+    /** 重新加载 */
+    reload: () => Promise<void>;
 };
 /**
  * 使用 Host API
@@ -187,35 +242,157 @@ 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: T | undefined;
     loading: boolean;
     error: Error | null;
     refetch: () => Promise<void>;
+    /** 上次刷新时间 */
+    lastUpdated: 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: boolean;
     result: T | undefined;
     error: Error | null;
+    /** 重置状态 */
+    reset: () => void;
+    /** 执行次数 */
+    executionCount: number;
 };
 /**
  * 使用数据请求
  */
 declare function useData<T = unknown, P = Record<string, unknown>>(queryId: string, params?: P, options?: {
+    /** 立即执行（默认 true） */
     immediate?: boolean;
+    /** 自动刷新间隔（毫秒） */
+    refreshInterval?: number;
+    /** 参数变化时重新请求 */
+    refreshOnParamsChange?: boolean;
+    /** 成功回调 */
+    onSuccess?: (data: T) => void;
+    /** 失败回调 */
+    onError?: (error: Error) => void;
 }): {
     data: T | undefined;
     loading: boolean;
     error: Error | null;
     refetch: (newParams?: P) => Promise<void>;
+    /** 是否已获取过数据 */
+    isFetched: boolean;
 };
 /**
  * 使用事件监听
  */
 declare function useRuntimeEvent<T = unknown>(eventType: string, handler: (data: T) => void): void;
+/**
+ * 使用页面信息
+ */
+declare function usePageInfo(): {
+    /** 页面 UID */
+    pageUid: string | undefined;
+    /** 页面版本 ID */
+    pageVersionId: string | undefined;
+    /** Schema 版本 */
+    schemaVersion: "1.0.0" | undefined;
+    /** 页面标题 */
+    title: string | undefined;
+    /** 页面配置 */
+    config: Record<string, unknown> | undefined;
+    /** 页面是否已加载 */
+    isLoaded: boolean;
+};
+/**
+ * 使用组件状态
+ */
+declare function useComponentState(componentId: string): {
+    /** 组件是否已加载 */
+    isLoaded: boolean;
+    /** 组件是否加载中 */
+    isLoading: boolean;
+    /** 组件是否加载失败 */
+    hasError: boolean;
+    /** 加载耗时 */
+    loadTime: number | undefined;
+    /** 组件信息 */
+    info: _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: RuntimePhase;
+    /** 是否已 mounted */
+    hasMounted: boolean;
+    /** 是否已 ready */
+    hasReady: boolean;
+};
+/**
+ * 使用条件执行
+ * 当条件满足时执行回调
+ */
+declare function useWhen(condition: boolean, callback: () => void | Promise<void>, options?: {
+    /** 是否只执行一次 */
+    once?: boolean;
+}): {
+    /** 是否已执行 */
+    executed: boolean;
+};
+/**
+ * 使用防抖动作
+ */
+declare function useDebouncedAction<T = unknown, P = Record<string, unknown>>(actionType: string, delay?: number): {
+    execute: (params?: P) => void;
+    loading: boolean;
+    result: T | undefined;
+    error: Error | null;
+    cancel: () => void;
+};
+/**
+ * 使用异步操作
+ */
+declare function useAsync<T>(asyncFn: () => Promise<T>, deps?: React.DependencyList, options?: {
+    /** 立即执行 */
+    immediate?: boolean;
+    /** 成功回调 */
+    onSuccess?: (data: T) => void;
+    /** 失败回调 */
+    onError?: (error: Error) => void;
+}): {
+    data: T | undefined;
+    loading: boolean;
+    error: Error | null;
+    execute: () => Promise<T | undefined>;
+};
+/**
+ * 使用前一个值
+ */
+declare function usePrevious<T>(value: T): T | undefined;
 
-export { DJVProvider, type DJVProviderProps, DJVRenderer, type DJVRendererProps, type ReactRuntimeOptions, type ReactRuntimeReturn, RuntimeContext, type RuntimeContextValue, RuntimeProvider, type RuntimeProviderProps, useAction, useDJVRuntime, useData, useHostApi, useQuery, useReactRuntime, useRuntimeContext, useRuntimeEvent, useRuntimeState, useRuntimeStateWritable };
+export { DJVProvider, type DJVProviderProps, DJVRenderer, type DJVRendererProps, type ReactRuntimeMetrics, type ReactRuntimeOptions, type ReactRuntimeReturn, RuntimeContext, type RuntimeContextValue, RuntimeProvider, type RuntimeProviderProps, useAction, useAsync, useComponentState, useDJVRuntime, useData, useDebouncedAction, useHostApi, useLifecycle, usePageInfo, usePrevious, useQuery, useReactRuntime, useRuntimeContext, useRuntimeEvent, useRuntimeState, useRuntimeStateWritable, useWhen };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+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 react from 'react';
@@ -8,12 +9,31 @@ import react__default, { ReactNode } from 'react';
  * 将核心运行时封装为 React 友好的 API
  */
 
+/**
+ * 性能指标
+ */
+interface ReactRuntimeMetrics {
+    /** 初始化耗时 */
+    initTime: number;
+    /** 加载耗时 */
+    loadTime: number;
+    /** 渲染耗时 */
+    renderTime: number;
+    /** 总耗时 */
+    totalTime: number;
+    /** 初始化时间戳 */
+    initTimestamp: number | null;
+    /** 就绪时间戳 */
+    readyTimestamp: number | null;
+}
 /**
  * React 运行时选项
  */
 interface ReactRuntimeOptions extends Omit<RuntimeOptions, 'container'> {
     /** 容器元素引用 */
     containerRef?: React.RefObject<HTMLElement>;
+    /** 启用性能追踪 */
+    enableMetrics?: boolean;
 }
 /**
  * React 运行时返回值
@@ -31,6 +51,12 @@ interface ReactRuntimeReturn {
     error: RuntimeError | null;
     /** Host API */
     hostApi: HostAPI | null;
+    /** 是否就绪 */
+    isReady: boolean;
+    /** 是否有错误 */
+    hasError: boolean;
+    /** 性能指标 */
+    metrics: ReactRuntimeMetrics;
     /** 初始化 */
     init: () => Promise<void>;
     /** 加载页面 */
@@ -39,10 +65,18 @@ interface ReactRuntimeReturn {
     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>;
 }
 /**
  * 使用 React 运行时 Hook
@@ -118,21 +152,31 @@ interface DJVRendererProps {
     onError?: (error: RuntimeError) => void;
     /** 就绪回调 */
     onReady?: () => void;
+    /** 阶段变化回调 */
+    onPhaseChange?: (phase: string) => void;
     /** 加载中显示 */
     loadingComponent?: ReactNode;
     /** 错误显示 */
-    errorComponent?: ReactNode | ((error: RuntimeError) => ReactNode);
+    errorComponent?: ReactNode | ((error: RuntimeError, retry: () => void) => ReactNode);
+    /** 空状态显示 */
+    emptyComponent?: ReactNode;
     /** 子元素 */
     children?: ReactNode;
     /** 容器类名 */
     className?: string;
     /** 容器样式 */
     style?: react__default.CSSProperties;
+    /** 重试次数（默认 3） */
+    retryCount?: number;
+    /** 重试延迟（默认 1000ms） */
+    retryDelay?: number;
+    /** 超时时间（默认 30000ms） */
+    timeout?: number;
 }
 /**
  * DJV 渲染器组件
  */
-declare function DJVRenderer({ pageUid, apiBaseUrl, cdnBaseUrl, channel, userId, deviceId, authToken, previewToken, debug, enableSRI, onLoad, onError, onReady, loadingComponent, errorComponent, children, className, style, }: DJVRendererProps): JSX.Element;
+declare function DJVRenderer({ pageUid, apiBaseUrl, cdnBaseUrl, channel, userId, deviceId, authToken, previewToken, debug, enableSRI, onLoad, onError, onReady, onPhaseChange, loadingComponent, errorComponent, emptyComponent, children, className, style, retryCount, retryDelay, timeout, }: DJVRendererProps): JSX.Element;
 
 /**
  * DJV Provider 组件
@@ -149,17 +193,22 @@ interface DJVProviderProps {
     hostApi: HostAPI | null;
     /** 子元素 */
     children: ReactNode;
+    /** 容器类名 */
+    className?: string;
+    /** 是否显示调试信息 */
+    debug?: boolean;
+    /** 状态变更回调 */
+    onStateChange?: (state: RuntimeState) => void;
+    /** 阶段变更回调 */
+    onPhaseChange?: (phase: RuntimePhase) => void;
+    /** 错误回调 */
+    onError?: (error: RuntimeError) => void;
 }
 /**
  * DJV Provider 组件
  * 用于手动控制运行时时使用
  */
-declare function DJVProvider({ runtime, hostApi, children, }: DJVProviderProps): JSX.Element;
-
-/**
- * React Hooks
- * 运行时相关的 React Hooks
- */
+declare function DJVProvider({ runtime, hostApi, children, className, debug, onStateChange, onPhaseChange, onError, }: DJVProviderProps): JSX.Element;
 
 /**
  * 使用 DJV 运行时
@@ -171,6 +220,12 @@ declare function useDJVRuntime(): {
     phase: RuntimePhase;
     error: RuntimeError | null;
     page: PageResolveResult | null;
+    /** 是否已就绪 */
+    isReady: boolean;
+    /** 是否有错误 */
+    hasError: boolean;
+    /** 重新加载 */
+    reload: () => Promise<void>;
 };
 /**
  * 使用 Host API
@@ -187,35 +242,157 @@ 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: T | undefined;
     loading: boolean;
     error: Error | null;
     refetch: () => Promise<void>;
+    /** 上次刷新时间 */
+    lastUpdated: 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: boolean;
     result: T | undefined;
     error: Error | null;
+    /** 重置状态 */
+    reset: () => void;
+    /** 执行次数 */
+    executionCount: number;
 };
 /**
  * 使用数据请求
  */
 declare function useData<T = unknown, P = Record<string, unknown>>(queryId: string, params?: P, options?: {
+    /** 立即执行（默认 true） */
     immediate?: boolean;
+    /** 自动刷新间隔（毫秒） */
+    refreshInterval?: number;
+    /** 参数变化时重新请求 */
+    refreshOnParamsChange?: boolean;
+    /** 成功回调 */
+    onSuccess?: (data: T) => void;
+    /** 失败回调 */
+    onError?: (error: Error) => void;
 }): {
     data: T | undefined;
     loading: boolean;
     error: Error | null;
     refetch: (newParams?: P) => Promise<void>;
+    /** 是否已获取过数据 */
+    isFetched: boolean;
 };
 /**
  * 使用事件监听
  */
 declare function useRuntimeEvent<T = unknown>(eventType: string, handler: (data: T) => void): void;
+/**
+ * 使用页面信息
+ */
+declare function usePageInfo(): {
+    /** 页面 UID */
+    pageUid: string | undefined;
+    /** 页面版本 ID */
+    pageVersionId: string | undefined;
+    /** Schema 版本 */
+    schemaVersion: "1.0.0" | undefined;
+    /** 页面标题 */
+    title: string | undefined;
+    /** 页面配置 */
+    config: Record<string, unknown> | undefined;
+    /** 页面是否已加载 */
+    isLoaded: boolean;
+};
+/**
+ * 使用组件状态
+ */
+declare function useComponentState(componentId: string): {
+    /** 组件是否已加载 */
+    isLoaded: boolean;
+    /** 组件是否加载中 */
+    isLoading: boolean;
+    /** 组件是否加载失败 */
+    hasError: boolean;
+    /** 加载耗时 */
+    loadTime: number | undefined;
+    /** 组件信息 */
+    info: _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: RuntimePhase;
+    /** 是否已 mounted */
+    hasMounted: boolean;
+    /** 是否已 ready */
+    hasReady: boolean;
+};
+/**
+ * 使用条件执行
+ * 当条件满足时执行回调
+ */
+declare function useWhen(condition: boolean, callback: () => void | Promise<void>, options?: {
+    /** 是否只执行一次 */
+    once?: boolean;
+}): {
+    /** 是否已执行 */
+    executed: boolean;
+};
+/**
+ * 使用防抖动作
+ */
+declare function useDebouncedAction<T = unknown, P = Record<string, unknown>>(actionType: string, delay?: number): {
+    execute: (params?: P) => void;
+    loading: boolean;
+    result: T | undefined;
+    error: Error | null;
+    cancel: () => void;
+};
+/**
+ * 使用异步操作
+ */
+declare function useAsync<T>(asyncFn: () => Promise<T>, deps?: React.DependencyList, options?: {
+    /** 立即执行 */
+    immediate?: boolean;
+    /** 成功回调 */
+    onSuccess?: (data: T) => void;
+    /** 失败回调 */
+    onError?: (error: Error) => void;
+}): {
+    data: T | undefined;
+    loading: boolean;
+    error: Error | null;
+    execute: () => Promise<T | undefined>;
+};
+/**
+ * 使用前一个值
+ */
+declare function usePrevious<T>(value: T): T | undefined;
 
-export { DJVProvider, type DJVProviderProps, DJVRenderer, type DJVRendererProps, type ReactRuntimeOptions, type ReactRuntimeReturn, RuntimeContext, type RuntimeContextValue, RuntimeProvider, type RuntimeProviderProps, useAction, useDJVRuntime, useData, useHostApi, useQuery, useReactRuntime, useRuntimeContext, useRuntimeEvent, useRuntimeState, useRuntimeStateWritable };
+export { DJVProvider, type DJVProviderProps, DJVRenderer, type DJVRendererProps, type ReactRuntimeMetrics, type ReactRuntimeOptions, type ReactRuntimeReturn, RuntimeContext, type RuntimeContextValue, RuntimeProvider, type RuntimeProviderProps, useAction, useAsync, useComponentState, useDJVRuntime, useData, useDebouncedAction, useHostApi, useLifecycle, usePageInfo, usePrevious, useQuery, useReactRuntime, useRuntimeContext, useRuntimeEvent, useRuntimeState, useRuntimeStateWritable, useWhen };