@cloudtower/eagle 490.0.5 → 490.0.7

package/dist/src/core/Cascader/cascader.type.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="react" />
 import type { CascaderProps as Antd5CascaderProps } from "antd5/lib/cascader";
-import { SearchInputProps } from "../SearchInput/searchInput.type";
+import { SearchInputProps } from "../SearchInput";
 export type { Antd5SizeType } from "../../utils/type";
 export type PresetCascaderRenderProps = {
     menus: Parameters<NonNullable<CascaderProps["dropdownRender"]>>[0];

package/dist/src/core/ImmersiveDialog/type.d.ts

@@ -1,43 +1,151 @@
 /// <reference types="react" />
 import { ButtonProps } from "../../core/Button";
 import { ModalProps as AntdModalProps } from "antd/lib/modal";
+/**
+ * 沉浸式全屏对话框，支持左中右三栏布局。适合复杂操作、大面积内容展示。通过 usePushModal 打开。
+ *
+ * 默认三栏布局宽度：左侧面板 192px、中间内容区 648px、右侧面板 192px，左右面板与内容区间距 60px。
+ * 设置 `isContentFull` 后左右面板隐藏，内容区占满整个对话框宽度。
+ *
+ * @example
+ * ```tsx
+ * // 带左右面板的全屏对话框（创建虚拟机场景）
+ * import { ImmersiveDialog } from "@cloudtower/eagle";
+ * import { usePushModal, usePopModal } from "@cloudtower/eagle";
+ *
+ * const pushModal = usePushModal();
+ *
+ * pushModal({
+ *   component: () => (
+ *     <ImmersiveDialog
+ *       title="创建虚拟机"
+ *       left={<VMConfigSteps current={step} />}
+ *       right={<VMResourceSummary cpu={cpu} memory={memory} />}
+ *       onOk={() => handleCreate()}
+ *     >
+ *       <VMConfigForm step={step} />
+ *     </ImmersiveDialog>
+ *   ),
+ *   props: { name: "CreateVmDialog" },
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 纯内容全屏对话框（isContentFull 模式）
+ * import { ImmersiveDialog } from "@cloudtower/eagle";
+ * import { usePushModal, usePopModal } from "@cloudtower/eagle";
+ *
+ * const popModal = usePopModal();
+ *
+ * <ImmersiveDialog
+ *   title="查看详情"
+ *   isContentFull
+ *   onOk={() => popModal()}
+ * >
+ *   <FullWidthContent />
+ * </ImmersiveDialog>
+ * ```
+ *
+ * 除下列自有属性外，还继承了 antd Modal 的全部属性（如 `onCancel`、`maskClosable`、`closable` 等），
+ * 这些属性会直接透传给底层 Modal 组件。
+ *
+ * @see WizardDialog — 基于 ImmersiveDialog 的向导变体，支持分步操作
+ * @see SmallDialog — 小型弹窗（492px），适用于简单确认或少量内容
+ * @see MediumDialog — 中型弹窗（720px），适用于中等复杂度的表单或内容
+ */
 export type ImmersiveDialogProps = React.PropsWithChildren<AntdModalProps & {
-    /** 自定义关闭图标 */
+    /** 自定义关闭图标，替换右上角默认的关闭按钮图标 */
     closeIcon?: React.ReactNode;
-    /** 是否显示取消按钮 */
+    /**
+     * 是否显示取消按钮
+     * @default true
+     */
     showCancel?: boolean;
-    /** 取消按钮的文本 */
+    /**
+     * 取消按钮的文本。
+     * 当 showOk 为 true 时默认为"取消"，否则默认为"关闭"。
+     */
     cancelText?: string;
-    /** 取消按钮的属性 */
+    /** 取消按钮的属性，透传至底层 Button 组件 */
     cancelButtonProps?: ButtonProps;
-    /** 是否显示确定按钮 */
+    /**
+     * 是否显示确定按钮
+     * @default true
+     */
     showOk?: boolean;
-    /** 确定按钮的文本 */
+    /**
+     * 确定按钮的文本。
+     * 当存在 initializingError 时默认为"重试"，否则默认为"确认"。
+     */
     okText?: string;
-    /** 确定按钮的属性 */
+    /** 确定按钮的属性，透传至底层 Button 组件 */
     okButtonProps?: ButtonProps;
-    /** 错误信息 */
+    /** 底部错误信息，显示在 footer 左侧区域，最多展示 3 行溢出后 tooltip 提示 */
     error?: React.ReactNode;
-    /** 是否隐藏 footer */
+    /**
+     * 是否隐藏 footer。隐藏后 footer 区域仍保留 40px 的空白间距。
+     * @default false
+     */
     hideFooter?: boolean;
-    /** 是否展示在 modal footer 的错误图标, 默认展示 */
+    /**
+     * 是否展示 footer 错误信息旁的错误图标
+     * @default true
+     */
     showFooterErrorIcon?: boolean;
-    /** 确定按钮的回调 */
+    /**
+     * 确定按钮的回调。
+     *
+     * 注意：签名为 `(e: React.MouseEvent) => void`，与 SmallDialog/MediumDialog 的
+     * `onOk?: (popModal: () => void) => void` 不同。此组件的 onOk 不会自动关闭弹窗，
+     * 需要通过 `usePopModal()` hook 获取 popModal 函数手动关闭。
+     */
     onOk?: (e: React.MouseEvent<HTMLElement, MouseEvent>) => void;
-    /** 是否内容占满 */
+    /**
+     * 是否内容占满整个对话框宽度。
+     * 开启后隐藏左右面板，内容区域占满对话框，左右各留 40px 的内边距。
+     * @default false
+     */
     isContentFull?: boolean;
-    /** 左侧自定义内容 */
+    /**
+     * 左侧面板的自定义内容。
+     * 三栏布局下固定宽度 192px，使用 fixed 定位，顶部距弹窗上边缘 140px。
+     * 当 isContentFull 为 true 或处于 initializing/initializingError 状态时不渲染。
+     */
     left?: React.ReactNode;
-    /** 左侧自定义内容类名 */
+    /**
+     * 左侧面板的自定义类名，用于覆盖左侧面板的默认样式。
+     * 面板默认宽度 192px，可通过此类名调整样式。
+     */
     leftClassName?: string;
-    /** 右侧自定义内容 */
+    /**
+     * 右侧面板的自定义内容。
+     * 三栏布局下固定宽度 192px，使用 fixed 定位，顶部距弹窗上边缘 140px。
+     * 当 isContentFull 为 true 或处于 initializing/initializingError 状态时不渲染。
+     */
     right?: React.ReactNode;
-    /** 右侧自定义内容类名 */
+    /**
+     * 右侧面板的自定义类名，用于覆盖右侧面板的默认样式。
+     * 面板默认宽度 192px，可通过此类名调整样式。
+     */
     rightClassName?: string;
-    /** 底部左侧的操作区域 */
+    /**
+     * 底部左侧的操作区域，通常放置"上一步"按钮或其他辅助操作。
+     * 渲染在 footer 左侧，与确定/取消按钮分居两端。
+     */
     footerLeftAction?: React.ReactNode;
-    /** 是否初始化中 */
+    /**
+     * 是否处于初始化加载中状态。
+     * 为 true 时标题区显示骨架屏，内容区显示 4 行骨架屏加载占位，footer 隐藏。
+     * 加载完成后设为 false 显示正常内容。
+     * @default false
+     */
     initializing?: boolean;
-    /** 初始化错误内容 */
+    /**
+     * 初始化错误的内容。设置后内容区显示错误提示（居中展示），
+     * 标题自动变为"加载失败"，确定按钮文本自动变为"重试"。
+     * 与 initializing 配合使用：先设 initializing=true 开始加载，
+     * 失败时设 initializing=false 并设置 initializingError。
+     */
     initializingError?: string | React.ReactNode;
 }>;

package/dist/src/core/MediumDialog/MediumDialog.type.d.ts

@@ -1,5 +1,53 @@
 import { SmallDialogProps } from "../SmallDialog/SmallDialog.type";
+/**
+ * 720px 宽度的中型对话框，适合表单和较多内容的场景。
+ *
+ * @description
+ * MediumDialog 继承 SmallDialog 的全部功能，在此基础上提供更大的显示区域（720px 宽度、
+ * 60px 水平内边距）和更突出的标题排版（d1s_bold_title）。通过 `usePushModal` 打开弹窗，
+ * 在 `onOk` / `onCancel` 回调中调用 `popModal` 参数来关闭弹窗。
+ *
+ * @example
+ * ```tsx
+ * import { MediumDialog, Button, KitStoreProvider, ModalStack } from "@cloudtower/eagle";
+ * import { usePushModal } from "@cloudtower/eagle/KitStoreProvider";
+ *
+ * const EditVmButton: React.FC = () => {
+ *   const pushModal = usePushModal();
+ *
+ *   return (
+ *     <Button onClick={() => pushModal({
+ *       component: () => (
+ *         <MediumDialog
+ *           title="编辑虚拟机"
+ *           onOk={(popModal) => {
+ *             saveVmConfig().then(() => popModal());
+ *           }}
+ *           onCancel={(popModal) => popModal()}
+ *         >
+ *           <VmConfigForm />
+ *         </MediumDialog>
+ *       ),
+ *       props: { name: "EditVmDialog" },
+ *     })}>
+ *       编辑虚拟机
+ *     </Button>
+ *   );
+ * };
+ * ```
+ *
+ * @see SmallDialog — 更小的对话框（492px 宽度）
+ * @see ImmersiveDialog — 全屏沉浸式对话框
+ */
 export interface MediumDialogProps extends SmallDialogProps {
-    /** 内容是否尽可能占满视窗，用于适配中型弹窗的非常规尺寸 */
+    /**
+     * 内容是否尽可能占满视窗，用于适配中型弹窗的非常规尺寸。
+     *
+     * @description
+     * 开启后弹窗尺寸变为 `width: calc(100vw - 160px)`、`height: calc(100vh - 80px)`，
+     * 内容区域自动 flex 填充剩余高度，适用于需要大面积展示内容（如表格、拓扑图）的场景。
+     *
+     * @default false
+     */
     isContentFull?: boolean;
 }

package/dist/src/core/SearchInput/SearchInput.d.ts

@@ -0,0 +1,2 @@
+import type { SearchInputComponentType } from "./SearchInput.type";
+export declare const SearchInput: SearchInputComponentType;

package/dist/src/core/SearchInput/SearchInput.hook.d.ts

@@ -0,0 +1,9 @@
+import { type DebouncedFunc } from "lodash";
+import React from "react";
+import type { SearchInputProps } from "./SearchInput.type";
+export declare const searchInputRecentSearchLocalStorageKey = "search-input-recent-search";
+export declare const useRecentSearch: (recentSearchLocalStorageKey: SearchInputProps["recentSearchLocalStorageKey"], maxRecentCount: number, setValue: React.Dispatch<React.SetStateAction<string>>, onChange: SearchInputProps["onChange"]) => {
+    recentSearchKeys: string[];
+    setRecentSearchKeysDebounceRef: React.MutableRefObject<DebouncedFunc<(val: string) => void> | undefined>;
+    antd5DropdownMenu: import("antd5").MenuProps | undefined;
+};

package/dist/src/core/SearchInput/SearchInput.style.d.ts

@@ -0,0 +1,5 @@
+export declare const SearchInputStyles: import("@linaria/core").LinariaClassName;
+export declare const CountTextStyles: import("@linaria/core").LinariaClassName;
+export declare const IconContainerStyles: import("@linaria/core").LinariaClassName;
+export declare const DisabledIconStyles: import("@linaria/core").LinariaClassName;
+export declare const SearchInputDropdownStyles: import("@linaria/core").LinariaClassName;

package/dist/src/core/SearchInput/SearchInput.type.d.ts

@@ -0,0 +1,150 @@
+/// <reference types="react" />
+import { InputProps } from "antd/lib/input";
+import { SrcType } from "../BaseIcon";
+/**
+ * @description 搜索输入框组件，基于 Input 封装，提供防抖搜索、结果导航（上一个/下一个）和最近搜索历史功能。
+ * 支持受控和非受控两种模式，适用于表格内搜索、页面全局搜索等场景。
+ *
+ * @example
+ * 基础搜索（带防抖）：
+ * ```tsx
+ * import React, { useState } from "react";
+ * import { SearchInput } from "@cloudtower/eagle";
+ *
+ * const App = () => {
+ *   const [keyword, setKeyword] = useState("");
+ *   return (
+ *     <SearchInput
+ *       debounceWait={300}
+ *       onChange={(value) => setKeyword(value)}
+ *     />
+ *   );
+ * };
+ * ```
+ *
+ * @example
+ * 带结果导航（显示匹配数和上下翻页）：
+ * ```tsx
+ * import React from "react";
+ * import { SearchInput } from "@cloudtower/eagle";
+ *
+ * const App = () => (
+ *   <SearchInput
+ *     total={10}
+ *     onChange={(value) => console.log("搜索:", value)}
+ *     onSearchNext={(value, current) => console.log("下一个:", current)}
+ *     onSearchPrev={(value, current) => console.log("上一个:", current)}
+ *   />
+ * );
+ * ```
+ *
+ * @example
+ * 启用最近搜索历史：
+ * ```tsx
+ * import React from "react";
+ * import { SearchInput } from "@cloudtower/eagle";
+ *
+ * const App = () => (
+ *   <SearchInput
+ *     enableRecentSearch
+ *     recentSearchLocalStorageKey="vm-search"
+ *     maxRecentCount={5}
+ *     onChange={(value) => console.log(value)}
+ *   />
+ * );
+ * ```
+ *
+ * @see Input 基础输入框
+ * @see Cascader 级联选择器（内置了 SearchInput 作为搜索区域）
+ */
+export type SearchInputProps = Omit<InputProps, "value" | "onChange"> & {
+    /**
+     * 输入框的值，用于受控模式。
+     * 配置 value 时，需把 debounceWait 设置为 0，否则输入时会有卡顿的问题
+     */
+    value?: InputProps["value"];
+    /**
+     * 防抖延迟时间，单位为毫秒。输入停止后延迟指定时间再触发 onChange
+     * @default 300
+     */
+    debounceWait?: number;
+    /**
+     * 搜索结果的总数。设置后，当同时提供 onSearchNext 和 onSearchPrev 时，
+     * 输入框后缀区域将显示 "current/total" 计数器和上下翻页按钮
+     */
+    total?: number;
+    /**
+     * 当前选中的结果索引（从 1 开始），可用于外部控制当前位置。
+     * 如果不提供，组件将内部管理此状态
+     */
+    current?: number;
+    /**
+     * 点击"下一个"按钮或按下 Enter 键时的回调。
+     * 需同时提供 onSearchPrev 才会显示导航按钮
+     * @param value - 当前搜索关键词
+     * @param current - 导航后的结果索引
+     */
+    onSearchNext?: (value: string, current: number) => void;
+    /**
+     * 点击"上一个"按钮时的回调。
+     * 需同时提供 onSearchNext 才会显示导航按钮
+     * @param value - 当前搜索关键词
+     * @param current - 导航后的结果索引
+     */
+    onSearchPrev?: (value: string, current: number) => void;
+    /**
+     * 输入内容改变时的回调函数（经过防抖处理后触发）
+     * @param value - 当前输入的搜索关键词
+     */
+    onChange: (value: string) => void;
+    /**
+     * 自定义搜索图标（输入框前缀），替换默认的放大镜图标
+     */
+    searchIcon?: SrcType;
+    /**
+     * 自定义"上一个"按钮的默认态图标
+     */
+    prefixIcon?: SrcType;
+    /**
+     * 自定义"上一个"按钮的 hover 态图标
+     */
+    prefixHoverIcon?: SrcType;
+    /**
+     * 自定义"下一个"按钮的默认态图标
+     */
+    nextIcon?: SrcType;
+    /**
+     * 自定义"下一个"按钮的 hover 态图标
+     */
+    nextHoverIcon?: SrcType;
+    /**
+     * 自定义清空按钮的默认态图标
+     */
+    clearIcon?: SrcType;
+    /**
+     * 自定义清空按钮的 hover 态图标
+     */
+    clearHoverIcon?: SrcType;
+    /**
+     * 搜索框宽度
+     * @default 276
+     */
+    width?: number | string;
+    /**
+     * 是否开启最近搜索功能。开启后，聚焦空输入框时会显示最近搜索记录的下拉菜单。
+     * 搜索记录通过 localStorage 持久化存储
+     * @default false
+     */
+    enableRecentSearch?: boolean;
+    /**
+     * 最近搜索记录在 localStorage 中的存储键名。
+     * 开启 enableRecentSearch 时必须提供，不同业务场景应使用不同的 key 以隔离数据
+     */
+    recentSearchLocalStorageKey?: string;
+    /**
+     * 最近搜索记录的最大展示条数
+     * @default 5
+     */
+    maxRecentCount?: number;
+};
+export type SearchInputComponentType = React.FC<SearchInputProps>;

package/dist/src/core/SearchInput/__test__/SearchInput.hook.test.d.ts

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

package/dist/src/core/SearchInput/index.d.ts

@@ -1,4 +1,2 @@
-import { SearchInputComponentType } from "./searchInput.type";
-declare const SearchInput: SearchInputComponentType;
-export default SearchInput;
-export * from "./searchInput.type";
+export * from "./SearchInput";
+export * from "./SearchInput.type";

package/dist/src/core/SmallDialog/SmallDialog.type.d.ts

@@ -1,49 +1,178 @@
 import { ButtonProps } from "../../core/Button";
 import React from "react";
+/**
+ * @description 小尺寸弹窗组件，固定宽度 492px，适用于确认操作、简短表单、信息提示等场景。
+ * 通过 `usePushModal` 打开弹窗，在 `onOk`/`onCancel` 回调中调用 `popModal()` 关闭弹窗。
+ * 弹窗基于 Redux 模态栈管理（KitStoreProvider），支持多层弹窗嵌套。
+ *
+ * @example 基础确认弹窗
+ * ```tsx
+ * import { SmallDialog } from "@cloudtower/eagle";
+ * import { usePushModal } from "@cloudtower/eagle/lib/core/KitStoreProvider";
+ *
+ * const MyComponent = () => {
+ *   const pushModal = usePushModal();
+ *
+ *   const openDialog = () => {
+ *     pushModal(
+ *       <SmallDialog
+ *         title="确认操作"
+ *         onOk={(popModal) => {
+ *           // 执行确认逻辑
+ *           popModal();
+ *         }}
+ *         onCancel={(popModal) => {
+ *           popModal();
+ *         }}
+ *       >
+ *         确定要执行此操作吗？
+ *       </SmallDialog>
+ *     );
+ *   };
+ *
+ *   return <Button onClick={openDialog}>打开弹窗</Button>;
+ * };
+ * ```
+ *
+ * @example 异步提交弹窗（含 confirmLoading）
+ * ```tsx
+ * const [loading, setLoading] = useState(false);
+ *
+ * pushModal(
+ *   <SmallDialog
+ *     title="删除确认"
+ *     confirmLoading={loading}
+ *     onOk={async (popModal) => {
+ *       setLoading(true);
+ *       try {
+ *         await deleteResource();
+ *         popModal();
+ *       } catch (e) {
+ *         // 处理错误，弹窗保持打开
+ *       } finally {
+ *         setLoading(false);
+ *       }
+ *     }}
+ *     onCancel={(popModal) => popModal()}
+ *   >
+ *     删除后数据将无法恢复，是否继续？
+ *   </SmallDialog>
+ * );
+ * ```
+ *
+ * @see MediumDialog 中等尺寸弹窗（720px），适用于复杂表单
+ * @see ImmersiveDialog 沉浸式全屏弹窗，适用于复杂表单和详情编辑
+ * @see WizardDialog 向导式弹窗，适用于分步操作
+ * @see DeleteDialog 删除确认弹窗，基于 SmallDialog 的业务封装，位于 coreX/Dialogs/
+ * @see RejectDialog 操作拒绝反馈弹窗，基于 SmallDialog 的业务封装，位于 coreX/Dialogs/
+ */
 export interface SmallDialogProps {
-    /** 弹窗宽度 */
+    /**
+     * 弹窗宽度
+     * @default 492
+     */
     width?: number | string;
-    /** 弹窗标题 */
+    /** 弹窗标题，支持 ReactNode 自定义渲染 */
     title: React.ReactNode;
-    /** 自定义标题 */
+    /**
+     * 自定义标题渲染组件，替换默认的标题渲染逻辑。
+     * 默认标题使用 `Typo.Display.d2_bold_title` 样式。
+     */
     TitleRender?: React.FC<{
         title?: React.ReactNode;
     }>;
-    /** 取消按钮文案 */
+    /** 取消按钮文案，默认根据 `showOk` 决定：showOk=true 时为"取消"，showOk=false 时为"关闭" */
     cancelText?: string;
-    /** 确认按钮文案 */
+    /** 确认按钮文案，默认为"确认"；当 `initializingError` 有值时默认为"重试" */
     okText?: string;
-    /** 是否显示确认按钮 */
+    /**
+     * 是否显示确认按钮。设为 false 时仅显示取消按钮，
+     * 且取消按钮样式从 `quiet` 变为 `ordinary`，文案默认从"取消"变为"关闭"。
+     * @default true
+     */
     showOk?: boolean;
-    /** 点击确认按钮回调 */
+    /**
+     * 点击确认按钮的回调。
+     * @param popModal - 关闭当前弹窗的函数，调用后将弹窗从模态栈中移除。
+     * 在异步操作中，可先执行业务逻辑，成功后再调用 popModal() 关闭弹窗；
+     * 若未提供 onOk，点击确认按钮将直接调用 popModal() 关闭弹窗。
+     *
+     * @example
+     * ```tsx
+     * onOk={async (popModal) => {
+     *   await submitData();
+     *   popModal();
+     * }}
+     * ```
+     */
     onOk?: (popModal: () => void) => void;
-    /** 点击取消按钮或关闭弹窗回调 */
+    /**
+     * 点击取消按钮、右上角关闭按钮或遮罩层时的回调。
+     * @param popModal - 关闭当前弹窗的函数，调用后将弹窗从模态栈中移除。
+     * 若未提供 onCancel，上述关闭操作将直接调用 popModal() 关闭弹窗。
+     *
+     * @example
+     * ```tsx
+     * onCancel={(popModal) => {
+     *   // 可在关闭前执行清理逻辑
+     *   popModal();
+     * }}
+     * ```
+     */
     onCancel?: (popModal: () => void) => void;
-    /** 是否可点击遮罩层关闭 */
+    /**
+     * 是否可点击遮罩层关闭弹窗，点击遮罩层会触发 onCancel 回调
+     * @default true
+     */
     maskClosable?: boolean;
-    /** 是否显示右上角关闭按钮 */
+    /**
+     * 是否显示右上角关闭按钮，点击关闭按钮会触发 onCancel 回调
+     * @default true
+     */
     closable?: boolean;
-    /** 自定义类名 */
+    /** 自定义弹窗容器类名 */
     className?: string;
-    /** 自定义footer类名 */
+    /** 自定义 footer 区域类名 */
     footerClassName?: string;
-    /** 确认按钮属性，优先使用 okText */
+    /** 确认按钮的额外属性，会透传给 Button 组件。若同时设置了 okText，okText 优先 */
     okButtonProps?: ButtonProps;
-    /** 取消按钮属性，优先使用 cancelText */
+    /** 取消按钮的额外属性，会透传给 Button 组件。若同时设置了 cancelText，cancelText 优先 */
     cancelButtonProps?: ButtonProps;
+    /** 弹窗主体内容，当 `initializing` 为 true 时显示骨架屏，当 `initializingError` 有值时显示错误状态 */
     children?: React.ReactNode;
-    /** 展示在 modal footer 的错误文案 */
+    /** 展示在 footer 区域的错误文案，支持 ReactNode。最多显示 3 行，超出后 tooltip 展示完整内容 */
     error?: React.ReactNode;
-    /** 是否隐藏 footer */
+    /**
+     * 是否隐藏 footer 区域（包括确认/取消按钮和错误信息）
+     * @default false
+     */
     hideFooter?: boolean;
-    /** 是否展示在 modal footer 的错误图标, 默认展示 */
+    /**
+     * 是否在 footer 错误文案前展示错误图标
+     * @default true
+     */
     showFooterErrorIcon?: boolean;
-    /** 确认按钮加载状态 */
+    /**
+     * 确认按钮加载状态，为 true 时确认按钮显示 loading 动画且不可重复点击
+     * @default false
+     */
     confirmLoading?: boolean;
-    /** 是否初始化中 */
+    /**
+     * 是否处于初始化加载中状态。为 true 时，标题显示骨架屏、
+     * 内容区域显示骨架屏（行数由 `initializingSkeletonRows` 控制）、footer 隐藏。
+     * 初始化完成后设为 false，若加载失败可设置 `initializingError` 展示错误状态。
+     */
     initializing?: boolean;
-    /** 初始化错误内容 */
+    /**
+     * 初始化错误内容。有值时弹窗进入错误状态：标题变为"加载失败"，
+     * 内容区域显示错误详情，确认按钮文案变为"重试"。
+     * 与 `initializing` 配合使用：先设 initializing=true 加载，
+     * 失败时设 initializing=false 且 initializingError="错误信息"。
+     */
     initializingError?: string | React.ReactNode;
-    /** 初始化骨架屏行数 */
+    /**
+     * 初始化骨架屏行数，仅在 `initializing` 为 true 时生效
+     * @default 2
+     */
     initializingSkeletonRows?: number;
 }