@vlian/framework 1.0.0

package/dist/core/error/ErrorBoundary.cjs

@@ -0,0 +1,331 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get ErrorBoundary () {
+        return ErrorBoundary;
+    },
+    get useErrorHandler () {
+        return useErrorHandler;
+    },
+    get withErrorBoundary () {
+        return withErrorBoundary;
+    }
+});
+const _jsxruntime = require("react/jsx-runtime");
+const _react = /*#__PURE__*/ _interop_require_wildcard(require("react"));
+const _reacterrorboundary = require("react-error-boundary");
+const _antd = require("antd");
+const _utils = require("../../utils");
+const _errors = require("../../utils/errors");
+const _initialization = require("../initialization");
+function _getRequireWildcardCache(nodeInterop) {
+    if (typeof WeakMap !== "function") return null;
+    var cacheBabelInterop = new WeakMap();
+    var cacheNodeInterop = new WeakMap();
+    return (_getRequireWildcardCache = function(nodeInterop) {
+        return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
+    })(nodeInterop);
+}
+function _interop_require_wildcard(obj, nodeInterop) {
+    if (!nodeInterop && obj && obj.__esModule) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
+        return {
+            default: obj
+        };
+    }
+    var cache = _getRequireWildcardCache(nodeInterop);
+    if (cache && cache.has(obj)) {
+        return cache.get(obj);
+    }
+    var newObj = {
+        __proto__: null
+    };
+    var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
+    for(var key in obj){
+        if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
+            var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
+            if (desc && (desc.get || desc.set)) {
+                Object.defineProperty(newObj, key, desc);
+            } else {
+                newObj[key] = obj[key];
+            }
+        }
+    }
+    newObj.default = obj;
+    if (cache) {
+        cache.set(obj, newObj);
+    }
+    return newObj;
+}
+function ErrorBoundary({ children, fallback, onError, showInConsole = true, resetKeys, onReset, onResetKeysChange }) {
+    // 使用 ref 存储重试计数，在多次错误之间保持状态
+    const retryCountRef = (0, _react.useRef)(0);
+    // 处理错误，将标准 Error 转换为 FrameworkError
+    const handleError = (error, errorInfo)=>{
+        const normalizedError = _errors.errorUtils.normalizeError(error);
+        // 将 react-error-boundary 的 errorInfo 转换为 React 的 ErrorInfo 格式
+        const reactErrorInfo = {
+            componentStack: errorInfo.componentStack || ''
+        };
+        // 记录错误
+        _utils.logger.error('错误边界捕获到错误:', {
+            error: normalizedError.toJSON(),
+            errorInfo: {
+                componentStack: reactErrorInfo.componentStack
+            }
+        });
+        // 调用错误回调
+        if (onError) {
+            onError(normalizedError, reactErrorInfo);
+        }
+        // 在控制台显示错误
+        if (showInConsole) {
+            console.error('错误边界捕获到错误:', normalizedError);
+            console.error('错误信息:', reactErrorInfo);
+        }
+    };
+    // 处理重置
+    const handleReset = ()=>{
+        // 清除初始化错误状态
+        _initialization.initializationErrorState.clearError();
+        // 调用用户提供的重置回调
+        if (onReset) {
+            onReset();
+        }
+    };
+    // 默认 fallback UI（使用 antd 组件）
+    // 使用内部组件来管理重试计数状态，使用 React.memo 优化性能
+    const DefaultFallbackComponent = /*#__PURE__*/ _react.default.memo(({ error, resetErrorBoundary })=>{
+        const normalizedError = _errors.errorUtils.normalizeError(error);
+        const [retryCount, setRetryCount] = (0, _react.useState)(retryCountRef.current);
+        const [showDetails, setShowDetails] = (0, _react.useState)(false);
+        // 同步 ref 的值到 state，确保组件重新创建时能读取到最新的重试计数
+        (0, _react.useEffect)(()=>{
+            setRetryCount(retryCountRef.current);
+        }, []);
+        const handleRetry = (0, _react.useCallback)(()=>{
+            // 增加重试计数
+            const newCount = retryCount + 1;
+            retryCountRef.current = newCount;
+            setRetryCount(newCount);
+            // 执行重置
+            handleReset();
+            resetErrorBoundary();
+        }, [
+            retryCount,
+            resetErrorBoundary
+        ]);
+        const handleReload = (0, _react.useCallback)(()=>{
+            // 刷新页面
+            window.location.reload();
+        }, []);
+        // 构建用户友好的错误提示
+        const userFriendlyMessage = (0, _react.useMemo)(()=>{
+            // 根据错误类型提供不同的提示
+            if (normalizedError.code === 'NETWORK_ERROR') {
+                return '网络连接失败，请检查您的网络设置后重试';
+            }
+            if (normalizedError.code === 'TIMEOUT_ERROR') {
+                return '请求超时，请稍后重试';
+            }
+            if (normalizedError.code === 'VALIDATION_ERROR') {
+                return '数据验证失败，请检查输入内容';
+            }
+            // 默认提示
+            return '应用运行时发生了错误，请稍后重试';
+        }, [
+            normalizedError.code
+        ]);
+        // 构建按钮数组
+        const extraButtons = (0, _react.useMemo)(()=>{
+            const buttons = [
+                /*#__PURE__*/ (0, _jsxruntime.jsx)(_antd.Button, {
+                    type: "primary",
+                    onClick: handleRetry,
+                    "aria-label": "重试加载应用",
+                    children: "重试"
+                }, "retry"),
+                /*#__PURE__*/ (0, _jsxruntime.jsx)(_antd.Button, {
+                    onClick: ()=>setShowDetails(!showDetails),
+                    "aria-label": showDetails ? '隐藏错误详情' : '显示错误详情',
+                    children: showDetails ? '隐藏详情' : '查看详情'
+                }, "details")
+            ];
+            // 如果重试次数 >= 1，添加刷新页面按钮（提前显示）
+            if (retryCount >= 1) {
+                buttons.push(/*#__PURE__*/ (0, _jsxruntime.jsx)(_antd.Button, {
+                    onClick: handleReload,
+                    "aria-label": "刷新页面",
+                    children: "刷新页面"
+                }, "reload"));
+            }
+            return buttons;
+        }, [
+            retryCount,
+            handleRetry,
+            handleReload,
+            showDetails
+        ]);
+        return /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
+            role: "alert",
+            "aria-live": "assertive",
+            "aria-atomic": "true",
+            style: {
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
+                justifyContent: 'center',
+                minHeight: '100vh',
+                padding: '24px'
+            },
+            children: [
+                /*#__PURE__*/ (0, _jsxruntime.jsx)(_antd.Result, {
+                    status: "error",
+                    title: "出错了",
+                    subTitle: userFriendlyMessage,
+                    extra: extraButtons
+                }),
+                showDetails && /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
+                    style: {
+                        marginTop: 24,
+                        padding: 16,
+                        backgroundColor: '#f5f5f5',
+                        borderRadius: 4,
+                        maxWidth: 800,
+                        width: '100%',
+                        maxHeight: 400,
+                        overflow: 'auto'
+                    },
+                    children: [
+                        /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
+                            style: {
+                                marginBottom: 8,
+                                fontWeight: 'bold'
+                            },
+                            children: "错误详情："
+                        }),
+                        /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
+                            style: {
+                                fontFamily: 'monospace',
+                                fontSize: 12
+                            },
+                            children: [
+                                /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
+                                    children: [
+                                        /*#__PURE__*/ (0, _jsxruntime.jsx)("strong", {
+                                            children: "错误类型："
+                                        }),
+                                        normalizedError.name
+                                    ]
+                                }),
+                                /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
+                                    children: [
+                                        /*#__PURE__*/ (0, _jsxruntime.jsx)("strong", {
+                                            children: "错误代码："
+                                        }),
+                                        normalizedError.code
+                                    ]
+                                }),
+                                /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
+                                    children: [
+                                        /*#__PURE__*/ (0, _jsxruntime.jsx)("strong", {
+                                            children: "错误信息："
+                                        }),
+                                        normalizedError.message
+                                    ]
+                                }),
+                                normalizedError.stack && /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
+                                    style: {
+                                        marginTop: 8
+                                    },
+                                    children: [
+                                        /*#__PURE__*/ (0, _jsxruntime.jsx)("strong", {
+                                            children: "堆栈信息："
+                                        }),
+                                        /*#__PURE__*/ (0, _jsxruntime.jsx)("pre", {
+                                            style: {
+                                                whiteSpace: 'pre-wrap',
+                                                wordBreak: 'break-word'
+                                            },
+                                            children: normalizedError.stack
+                                        })
+                                    ]
+                                })
+                            ]
+                        })
+                    ]
+                })
+            ]
+        });
+    });
+    DefaultFallbackComponent.displayName = 'DefaultFallbackComponent';
+    const defaultFallback = ({ error, resetErrorBoundary })=>{
+        return /*#__PURE__*/ (0, _jsxruntime.jsx)(DefaultFallbackComponent, {
+            error: error,
+            resetErrorBoundary: resetErrorBoundary
+        });
+    };
+    // 如果提供了自定义 fallback，使用自定义的
+    const fallbackRender = fallback ? ({ error, resetErrorBoundary })=>{
+        const normalizedError = _errors.errorUtils.normalizeError(error);
+        return fallback(normalizedError, ()=>{
+            handleReset();
+            resetErrorBoundary();
+        });
+    } : defaultFallback;
+    // 处理重置时清除重试计数
+    const handleResetWithCount = ()=>{
+        retryCountRef.current = 0;
+        handleReset();
+    };
+    // 处理 resetKeys 变化时清除重试计数
+    const handleResetKeysChange = (prevKeys, nextKeys)=>{
+        retryCountRef.current = 0;
+        if (onResetKeysChange) {
+            onResetKeysChange(prevKeys, nextKeys);
+        }
+    };
+    // 构建 react-error-boundary 的 props
+    const errorBoundaryProps = {
+        fallbackRender,
+        onError: handleError,
+        onReset: handleResetWithCount,
+        resetKeys,
+        onResetKeysChange: handleResetKeysChange
+    };
+    return /*#__PURE__*/ (0, _jsxruntime.jsx)(_reacterrorboundary.ErrorBoundary, {
+        ...errorBoundaryProps,
+        children: children
+    });
+}
+function withErrorBoundary(Component, errorBoundaryProps) {
+    const WrappedComponent = (props)=>{
+        return /*#__PURE__*/ (0, _jsxruntime.jsx)(ErrorBoundary, {
+            ...errorBoundaryProps,
+            children: /*#__PURE__*/ (0, _jsxruntime.jsx)(Component, {
+                ...props
+            })
+        });
+    };
+    WrappedComponent.displayName = `withErrorBoundary(${Component.displayName || Component.name || 'Component'})`;
+    return WrappedComponent;
+}
+function useErrorHandler() {
+    return (error)=>{
+        // 将错误设置到初始化错误状态
+        // InitializationErrorThrower 组件会检测到错误并抛出，让 ErrorBoundary 捕获
+        _initialization.initializationErrorState.setError(error);
+    };
+}
+
+//# sourceMappingURL=ErrorBoundary.js.map

package/dist/core/error/ErrorBoundary.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/core/error/ErrorBoundary.tsx"],"sourcesContent":["import React, { type ReactNode, type ErrorInfo, useState, useRef, useEffect, useCallback, useMemo } from 'react';\nimport { ErrorBoundary as ReactErrorBoundary } from 'react-error-boundary';\nimport { Result, Button } from 'antd';\nimport { logger } from '../../utils';\nimport { errorUtils } from '../../utils/errors';\nimport type { FrameworkError } from '../../utils/errors';\nimport { initializationErrorState } from '../initialization';\n\n/**\n * 错误边界组件属性\n */\nexport interface ErrorBoundaryProps {\n  /**\n   * 子组件\n   */\n  children: ReactNode;\n  /**\n   * 错误回退 UI（函数形式）\n   * \n   * 如果不提供，将使用默认的错误 UI（基于 antd 的 Result 组件，居中显示）。\n   * 如果提供，将使用自定义的错误 UI。\n   * \n   * @param error - 标准化后的框架错误对象\n   * @param resetError - 重置错误边界的函数，调用后可以尝试重新渲染子组件\n   * @returns 错误 UI 的 React 节点\n   * \n   * @example\n   * ```tsx\n   * <ErrorBoundary\n   *   fallback={(error, reset) => (\n   *     <Result\n   *       status=\"error\"\n   *       title=\"自定义错误标题\"\n   *       subTitle={error.message}\n   *       extra={<Button onClick={reset}>重试</Button>}\n   *     />\n   *   )}\n   * >\n   *   <App />\n   * </ErrorBoundary>\n   * ```\n   */\n  fallback?: (error: FrameworkError, resetError: () => void) => ReactNode;\n  /**\n   * 错误回调\n   */\n  onError?: (error: FrameworkError, errorInfo: ErrorInfo) => void;\n  /**\n   * 是否在控制台显示错误\n   */\n  showInConsole?: boolean;\n  /**\n   * 重置键数组，当这些值变化时自动重置错误边界\n   */\n  resetKeys?: Array<string | number>;\n  /**\n   * 重置错误时的回调\n   */\n  onReset?: () => void;\n  /**\n   * 重置键变化时的回调\n   */\n  onResetKeysChange?: (prevKeys: Array<string | number> | undefined, nextKeys: Array<string | number> | undefined) => void;\n}\n\n/**\n * 错误边界组件\n * \n * 基于 react-error-boundary 实现，集成了框架的错误处理系统\n * 用于捕获 React 组件树中的错误，防止整个应用崩溃\n * \n * 默认使用 antd 的 Result 组件显示错误 UI，居中显示，美观易用。\n * 可以通过 fallback 属性自定义错误 UI。\n * \n * @example\n * ```tsx\n * // 使用默认错误 UI（推荐）\n * <ErrorBoundary>\n *   <App />\n * </ErrorBoundary>\n * \n * // 自定义错误 UI\n * <ErrorBoundary\n *   fallback={(error, reset) => (\n *     <div>\n *       <h1>出错了</h1>\n *       <p>{error.message}</p>\n *       <button onClick={reset}>重试</button>\n *     </div>\n *   )}\n * >\n *   <App />\n * </ErrorBoundary>\n * ```\n */\nexport function ErrorBoundary({\n  children,\n  fallback,\n  onError,\n  showInConsole = true,\n  resetKeys,\n  onReset,\n  onResetKeysChange,\n}: ErrorBoundaryProps): ReactNode {\n  // 使用 ref 存储重试计数，在多次错误之间保持状态\n  const retryCountRef = useRef<number>(0);\n\n  // 处理错误，将标准 Error 转换为 FrameworkError\n  const handleError = (error: Error, errorInfo: { componentStack?: string | null }): void => {\n    const normalizedError = errorUtils.normalizeError(error);\n\n    // 将 react-error-boundary 的 errorInfo 转换为 React 的 ErrorInfo 格式\n    const reactErrorInfo: ErrorInfo = {\n      componentStack: errorInfo.componentStack || '',\n    };\n\n    // 记录错误\n    logger.error('错误边界捕获到错误:', {\n      error: normalizedError.toJSON(),\n      errorInfo: {\n        componentStack: reactErrorInfo.componentStack,\n      },\n    });\n\n    // 调用错误回调\n    if (onError) {\n      onError(normalizedError, reactErrorInfo);\n    }\n\n    // 在控制台显示错误\n    if (showInConsole) {\n      console.error('错误边界捕获到错误:', normalizedError);\n      console.error('错误信息:', reactErrorInfo);\n    }\n  };\n\n  // 处理重置\n  const handleReset = (): void => {\n    // 清除初始化错误状态\n    initializationErrorState.clearError();\n    // 调用用户提供的重置回调\n    if (onReset) {\n      onReset();\n    }\n  };\n\n  // 默认 fallback UI（使用 antd 组件）\n  // 使用内部组件来管理重试计数状态，使用 React.memo 优化性能\n  const DefaultFallbackComponent = React.memo(({ error, resetErrorBoundary }: { error: Error; resetErrorBoundary: () => void }): ReactNode => {\n    const normalizedError = errorUtils.normalizeError(error);\n    const [retryCount, setRetryCount] = useState<number>(retryCountRef.current);\n    const [showDetails, setShowDetails] = useState(false);\n\n    // 同步 ref 的值到 state，确保组件重新创建时能读取到最新的重试计数\n    useEffect(() => {\n      setRetryCount(retryCountRef.current);\n    }, []);\n\n    const handleRetry = useCallback((): void => {\n      // 增加重试计数\n      const newCount = retryCount + 1;\n      retryCountRef.current = newCount;\n      setRetryCount(newCount);\n      \n      // 执行重置\n      handleReset();\n      resetErrorBoundary();\n    }, [retryCount, resetErrorBoundary]);\n\n    const handleReload = useCallback((): void => {\n      // 刷新页面\n      window.location.reload();\n    }, []);\n\n    // 构建用户友好的错误提示\n    const userFriendlyMessage = useMemo(() => {\n      // 根据错误类型提供不同的提示\n      if (normalizedError.code === 'NETWORK_ERROR') {\n        return '网络连接失败，请检查您的网络设置后重试';\n      }\n      if (normalizedError.code === 'TIMEOUT_ERROR') {\n        return '请求超时，请稍后重试';\n      }\n      if (normalizedError.code === 'VALIDATION_ERROR') {\n        return '数据验证失败，请检查输入内容';\n      }\n      // 默认提示\n      return '应用运行时发生了错误，请稍后重试';\n    }, [normalizedError.code]);\n\n    // 构建按钮数组\n    const extraButtons = useMemo(() => {\n      const buttons = [\n        <Button\n          type=\"primary\"\n          key=\"retry\"\n          onClick={handleRetry}\n          aria-label=\"重试加载应用\"\n        >\n          重试\n        </Button>,\n        <Button\n          key=\"details\"\n          onClick={() => setShowDetails(!showDetails)}\n          aria-label={showDetails ? '隐藏错误详情' : '显示错误详情'}\n        >\n          {showDetails ? '隐藏详情' : '查看详情'}\n        </Button>,\n      ];\n\n      // 如果重试次数 >= 1，添加刷新页面按钮（提前显示）\n      if (retryCount >= 1) {\n        buttons.push(\n          <Button\n            key=\"reload\"\n            onClick={handleReload}\n            aria-label=\"刷新页面\"\n          >\n            刷新页面\n          </Button>\n        );\n      }\n\n      return buttons;\n    }, [retryCount, handleRetry, handleReload, showDetails]);\n\n    return (\n      <div\n        role=\"alert\"\n        aria-live=\"assertive\"\n        aria-atomic=\"true\"\n        style={{\n          display: 'flex',\n          flexDirection: 'column',\n          alignItems: 'center',\n          justifyContent: 'center',\n          minHeight: '100vh',\n          padding: '24px',\n        }}\n      >\n        <Result\n          status=\"error\"\n          title=\"出错了\"\n          subTitle={userFriendlyMessage}\n          extra={extraButtons}\n        />\n        {showDetails && (\n          <div\n            style={{\n              marginTop: 24,\n              padding: 16,\n              backgroundColor: '#f5f5f5',\n              borderRadius: 4,\n              maxWidth: 800,\n              width: '100%',\n              maxHeight: 400,\n              overflow: 'auto',\n            }}\n          >\n            <div style={{ marginBottom: 8, fontWeight: 'bold' }}>错误详情：</div>\n            <div style={{ fontFamily: 'monospace', fontSize: 12 }}>\n              <div><strong>错误类型：</strong>{normalizedError.name}</div>\n              <div><strong>错误代码：</strong>{normalizedError.code}</div>\n              <div><strong>错误信息：</strong>{normalizedError.message}</div>\n              {normalizedError.stack && (\n                <div style={{ marginTop: 8 }}>\n                  <strong>堆栈信息：</strong>\n                  <pre style={{ whiteSpace: 'pre-wrap', wordBreak: 'break-word' }}>\n                    {normalizedError.stack}\n                  </pre>\n                </div>\n              )}\n            </div>\n          </div>\n        )}\n      </div>\n    );\n  });\n  \n  DefaultFallbackComponent.displayName = 'DefaultFallbackComponent';\n\n  const defaultFallback = ({ error, resetErrorBoundary }: { error: Error; resetErrorBoundary: () => void }): ReactNode => {\n    return <DefaultFallbackComponent error={error} resetErrorBoundary={resetErrorBoundary} />;\n  };\n\n  // 如果提供了自定义 fallback，使用自定义的\n  const fallbackRender = fallback\n    ? ({ error, resetErrorBoundary }: { error: Error; resetErrorBoundary: () => void }): ReactNode => {\n        const normalizedError = errorUtils.normalizeError(error);\n        return fallback(normalizedError, () => {\n          handleReset();\n          resetErrorBoundary();\n        });\n      }\n    : defaultFallback;\n\n  // 处理重置时清除重试计数\n  const handleResetWithCount = (): void => {\n    retryCountRef.current = 0;\n    handleReset();\n  };\n\n  // 处理 resetKeys 变化时清除重试计数\n  const handleResetKeysChange = (\n    prevKeys: Array<string | number> | undefined,\n    nextKeys: Array<string | number> | undefined\n  ): void => {\n    retryCountRef.current = 0;\n    if (onResetKeysChange) {\n      onResetKeysChange(prevKeys, nextKeys);\n    }\n  };\n\n  // 构建 react-error-boundary 的 props\n  const errorBoundaryProps = {\n    fallbackRender,\n    onError: handleError,\n    onReset: handleResetWithCount,\n    resetKeys,\n    onResetKeysChange: handleResetKeysChange,\n  } as any;\n\n  return (\n    <ReactErrorBoundary {...errorBoundaryProps}>\n      {children}\n    </ReactErrorBoundary>\n  );\n}\n\n/**\n * 带错误边界的 HOC\n */\nexport function withErrorBoundary<P extends object>(\n  Component: React.ComponentType<P>,\n  errorBoundaryProps?: Omit<ErrorBoundaryProps, 'children'>\n): React.ComponentType<P> {\n  const WrappedComponent = (props: P) => {\n    return (\n      <ErrorBoundary {...errorBoundaryProps}>\n        <Component {...props} />\n      </ErrorBoundary>\n    );\n  };\n\n  WrappedComponent.displayName = `withErrorBoundary(${Component.displayName || Component.name || 'Component'})`;\n\n  return WrappedComponent;\n}\n\n/**\n * 使用错误处理器的 Hook\n * \n * 用于在函数组件中处理异步错误\n * \n * 注意：这个 Hook 需要配合 ErrorBoundary 使用。当调用返回的错误处理函数时，\n * 错误会被设置到初始化错误状态，然后通过 InitializationErrorThrower 组件抛出。\n * \n * @example\n * ```tsx\n * import { useErrorHandler } from '@vlian/framework';\n * \n * function MyComponent() {\n *   const handleError = useErrorHandler();\n *   \n *   useEffect(() => {\n *     async function fetchData() {\n *       try {\n *         await someAsyncOperation();\n *       } catch (error) {\n *         handleError(error);\n *       }\n *     }\n *     fetchData();\n *   }, [handleError]);\n * }\n * ```\n */\nexport function useErrorHandler(): (error: unknown) => void {\n  return (error: unknown) => {\n    // 将错误设置到初始化错误状态\n    // InitializationErrorThrower 组件会检测到错误并抛出，让 ErrorBoundary 捕获\n    initializationErrorState.setError(error);\n  };\n}\n"],"names":["ErrorBoundary","useErrorHandler","withErrorBoundary","children","fallback","onError","showInConsole","resetKeys","onReset","onResetKeysChange","retryCountRef","useRef","handleError","error","errorInfo","normalizedError","errorUtils","normalizeError","reactErrorInfo","componentStack","logger","toJSON","console","handleReset","initializationErrorState","clearError","DefaultFallbackComponent","React","memo","resetErrorBoundary","retryCount","setRetryCount","useState","current","showDetails","setShowDetails","useEffect","handleRetry","useCallback","newCount","handleReload","window","location","reload","userFriendlyMessage","useMemo","code","extraButtons","buttons","Button","type","onClick","aria-label","push","div","role","aria-live","aria-atomic","style","display","flexDirection","alignItems","justifyContent","minHeight","padding","Result","status","title","subTitle","extra","marginTop","backgroundColor","borderRadius","maxWidth","width","maxHeight","overflow","marginBottom","fontWeight","fontFamily","fontSize","strong","name","message","stack","pre","whiteSpace","wordBreak","displayName","defaultFallback","fallbackRender","handleResetWithCount","handleResetKeysChange","prevKeys","nextKeys","errorBoundaryProps","ReactErrorBoundary","Component","WrappedComponent","props","setError"],"mappings":"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"}

package/dist/core/error/ErrorBoundary.d.ts

@@ -0,0 +1,123 @@
+import React, { type ReactNode, type ErrorInfo } from 'react';
+import type { FrameworkError } from '../../utils/errors';
+/**
+ * 错误边界组件属性
+ */
+export interface ErrorBoundaryProps {
+    /**
+     * 子组件
+     */
+    children: ReactNode;
+    /**
+     * 错误回退 UI（函数形式）
+     *
+     * 如果不提供，将使用默认的错误 UI（基于 antd 的 Result 组件，居中显示）。
+     * 如果提供，将使用自定义的错误 UI。
+     *
+     * @param error - 标准化后的框架错误对象
+     * @param resetError - 重置错误边界的函数，调用后可以尝试重新渲染子组件
+     * @returns 错误 UI 的 React 节点
+     *
+     * @example
+     * ```tsx
+     * <ErrorBoundary
+     *   fallback={(error, reset) => (
+     *     <Result
+     *       status="error"
+     *       title="自定义错误标题"
+     *       subTitle={error.message}
+     *       extra={<Button onClick={reset}>重试</Button>}
+     *     />
+     *   )}
+     * >
+     *   <App />
+     * </ErrorBoundary>
+     * ```
+     */
+    fallback?: (error: FrameworkError, resetError: () => void) => ReactNode;
+    /**
+     * 错误回调
+     */
+    onError?: (error: FrameworkError, errorInfo: ErrorInfo) => void;
+    /**
+     * 是否在控制台显示错误
+     */
+    showInConsole?: boolean;
+    /**
+     * 重置键数组，当这些值变化时自动重置错误边界
+     */
+    resetKeys?: Array<string | number>;
+    /**
+     * 重置错误时的回调
+     */
+    onReset?: () => void;
+    /**
+     * 重置键变化时的回调
+     */
+    onResetKeysChange?: (prevKeys: Array<string | number> | undefined, nextKeys: Array<string | number> | undefined) => void;
+}
+/**
+ * 错误边界组件
+ *
+ * 基于 react-error-boundary 实现，集成了框架的错误处理系统
+ * 用于捕获 React 组件树中的错误，防止整个应用崩溃
+ *
+ * 默认使用 antd 的 Result 组件显示错误 UI，居中显示，美观易用。
+ * 可以通过 fallback 属性自定义错误 UI。
+ *
+ * @example
+ * ```tsx
+ * // 使用默认错误 UI（推荐）
+ * <ErrorBoundary>
+ *   <App />
+ * </ErrorBoundary>
+ *
+ * // 自定义错误 UI
+ * <ErrorBoundary
+ *   fallback={(error, reset) => (
+ *     <div>
+ *       <h1>出错了</h1>
+ *       <p>{error.message}</p>
+ *       <button onClick={reset}>重试</button>
+ *     </div>
+ *   )}
+ * >
+ *   <App />
+ * </ErrorBoundary>
+ * ```
+ */
+export declare function ErrorBoundary({ children, fallback, onError, showInConsole, resetKeys, onReset, onResetKeysChange, }: ErrorBoundaryProps): ReactNode;
+/**
+ * 带错误边界的 HOC
+ */
+export declare function withErrorBoundary<P extends object>(Component: React.ComponentType<P>, errorBoundaryProps?: Omit<ErrorBoundaryProps, 'children'>): React.ComponentType<P>;
+/**
+ * 使用错误处理器的 Hook
+ *
+ * 用于在函数组件中处理异步错误
+ *
+ * 注意：这个 Hook 需要配合 ErrorBoundary 使用。当调用返回的错误处理函数时，
+ * 错误会被设置到初始化错误状态，然后通过 InitializationErrorThrower 组件抛出。
+ *
+ * @example
+ * ```tsx
+ * import { useErrorHandler } from '@vlian/framework';
+ *
+ * function MyComponent() {
+ *   const handleError = useErrorHandler();
+ *
+ *   useEffect(() => {
+ *     async function fetchData() {
+ *       try {
+ *         await someAsyncOperation();
+ *       } catch (error) {
+ *         handleError(error);
+ *       }
+ *     }
+ *     fetchData();
+ *   }, [handleError]);
+ * }
+ * ```
+ */
+export declare function useErrorHandler(): (error: unknown) => void;
+//# sourceMappingURL=ErrorBoundary.d.ts.map

package/dist/core/error/ErrorBoundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorBoundary.d.ts","sourceRoot":"","sources":["../../../src/core/error/ErrorBoundary.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAqD,MAAM,OAAO,CAAC;AAKjH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGzD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,IAAI,KAAK,SAAS,CAAC;IACxE;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC;IAChE;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IACnC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;OAEG;IACH,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,KAAK,IAAI,CAAC;CAC1H;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,aAAa,CAAC,EAC5B,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,aAAoB,EACpB,SAAS,EACT,OAAO,EACP,iBAAiB,GAClB,EAAE,kBAAkB,GAAG,SAAS,CAgOhC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAChD,SAAS,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EACjC,kBAAkB,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,GACxD,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAYxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAM1D"}