@cloudtower/eagle 4100.0.20 → 4100.0.22

package/docs/core/ImmersiveDialog/guide.md

@@ -81,6 +81,14 @@ const App = () => {
 
 > **注意**：ImmersiveDialog 的 `onOk` 签名是 `(e: React.MouseEvent) => void`，不会自动关闭弹窗。必须通过 `usePopModal()` 获取 `popModal` 函数手动关闭，这一点与 SmallDialog / MediumDialog 的 `(popModal: () => void) => void` 签名不同。
 
+## 初始化生命周期
+
+`initializeOnce` 默认为 `true`，首次初始化成功后忽略后续的 `initializing` 和 `initializingError`，保留正常标题、内容和 footer。成功前允许失败后多次重试；设置 `initializeOnce={false}` 可恢复完全受控行为。
+
+初始化记录按组件的挂载周期计算。仅切换 `visible`，包括底层 Modal 的 `destroyOnClose` 销毁内容，都不会重置 ImmersiveDialog 自身的记录。切换资源并需要重新初始化时，可通过 `key` 重新挂载。
+
+首次渲染没有加载和错误时也视为成功；延迟请求应在准备期间保持 `initializing=true`。更多调用约定见 [SmallDialog 初始化生命周期](../SmallDialog/guide.md#初始化生命周期)。
+
 ## 常见模式
 
 ### 模式一：三栏布局
@@ -272,7 +280,7 @@ ImmersiveDialog 的 `onOk` 签名是 `(e: React.MouseEvent) => void`，与 Small
   onOk={(popModal) => {
     popModal(); // 直接通过参数关闭
   }}
-/>
+/>;
 
 // ImmersiveDialog -- 需要 usePopModal() hook
 const MyDialog = () => {

package/docs/core/MediumDialog/guide.md

@@ -22,7 +22,12 @@ MediumDialog 是一个固定 720px 宽度的中型对话框组件，继承 Small
 
 ```tsx
 import React from "react";
-import { MediumDialog, Button, KitStoreProvider, ModalStack } from "@cloudtower/eagle";
+import {
+  MediumDialog,
+  Button,
+  KitStoreProvider,
+  ModalStack,
+} from "@cloudtower/eagle";
 import { usePushModal } from "@cloudtower/eagle";
 
 const App = () => {
@@ -243,16 +248,20 @@ const App = () => {
 };
 ```
 
+## 初始化生命周期
+
+MediumDialog 继承 SmallDialog 的 `initializeOnce`，默认为 `true`：成功前允许失败重试，首次成功后忽略后续的加载和初始化错误。需要反复展示骨架屏时，显式设置 `initializeOnce={false}`。完整约定见 [SmallDialog 初始化生命周期](../SmallDialog/guide.md#初始化生命周期)。
+
 ## 与 SmallDialog 的差异对比
 
-| 特性 | SmallDialog | MediumDialog |
-|------|-------------|--------------|
-| 默认宽度 | 492px | 720px |
-| 水平内边距 | 40px | 60px |
-| 标题排版 | `d2_bold_title` | `d1s_bold_title` |
-| 骨架屏默认行数 | 2 | 3 |
-| 全屏模式 | 不支持 | 支持（`isContentFull`） |
-| 适用场景 | 简单确认、信息提示 | 表单弹窗、内容较多的确认 |
+| 特性           | SmallDialog        | MediumDialog             |
+| -------------- | ------------------ | ------------------------ |
+| 默认宽度       | 492px              | 720px                    |
+| 水平内边距     | 40px               | 60px                     |
+| 标题排版       | `d2_bold_title`    | `d1s_bold_title`         |
+| 骨架屏默认行数 | 2                  | 3                        |
+| 全屏模式       | 不支持             | 支持（`isContentFull`）  |
+| 适用场景       | 简单确认、信息提示 | 表单弹窗、内容较多的确认 |
 
 ## 相关组件
 

package/docs/core/SmallDialog/guide.md

@@ -23,7 +23,12 @@ SmallDialog 是一个固定 492px 宽度的轻量级对话框组件，适用于
 
 ```tsx
 import React from "react";
-import { SmallDialog, Button, KitStoreProvider, ModalStack } from "@cloudtower/eagle";
+import {
+  SmallDialog,
+  Button,
+  KitStoreProvider,
+  ModalStack,
+} from "@cloudtower/eagle";
 import { usePushModal } from "@cloudtower/eagle";
 
 const App = () => {
@@ -57,6 +62,18 @@ const App = () => {
 };
 ```
 
+## 初始化生命周期
+
+`initializeOnce` 默认为 `true`。当 `initializing` 为 false 或未传入，且 `initializingError` 无值时，弹窗记录首次初始化成功。之后忽略这两个属性的变化，后台刷新不会再显示骨架屏或初始化错误页，也不会因此卸载内容中的表单。
+
+- 成功前，加载失败仍展示初始化错误；点击重试可以再次进入骨架屏，多次失败重试也一样。
+- 首次渲染就没有加载和错误时，也会记录成功，例如直接使用缓存数据的场景。
+- 延迟启动请求时，应在准备期间保持 `initializing=true`，避免尚未请求就被视为成功。
+- 记录按组件的一次挂载周期计算。卸载后重新打开会重置；同一实例切换资源时，可通过 `key` 重新挂载。
+- 设置 `initializeOnce={false}` 可恢复完全受控行为，允许反复进入加载和错误状态。已有调用方若依赖此行为，需要显式关闭该选项。
+
+该选项仅处理 `initializing` 和 `initializingError`，不会冻结其他 props。后台刷新时应继续传入正常标题和内容；刷新错误可以在内容区域或通过 `error` 展示。
+
 ## 常见模式
 
 ### 模式一：异步提交弹窗

package/docs/core/WizardDialog/guide.md

@@ -47,8 +47,7 @@ const CreateVmDialog: React.FC = () => {
         console.log("提交创建");
         popModal();
       }}
-    >
-    </WizardDialog>
+    ></WizardDialog>
   );
 };
 
@@ -107,8 +106,7 @@ const BasicWizardDialog: React.FC = () => {
         console.log("提交集群初始化");
         popModal();
       }}
-    >
-    </WizardDialog>
+    ></WizardDialog>
   );
 };
 
@@ -210,8 +208,7 @@ const ValidatedWizardDialog: React.FC = () => {
         console.log("提交创建", { vmName, network });
         popModal();
       }}
-    >
-    </WizardDialog>
+    ></WizardDialog>
   );
 };
 
@@ -279,8 +276,7 @@ const ControlledWizardDialog: React.FC = () => {
         console.log("确认部署");
         popModal();
       }}
-    >
-    </WizardDialog>
+    ></WizardDialog>
   );
 };
 
@@ -305,6 +301,7 @@ const App = () => {
 
 ## 关键说明
 
+- **首次初始化**：继承 ImmersiveDialog 的 `initializeOnce`，默认为 `true`。成功前允许失败重试，首次成功后忽略后续的加载和初始化错误，避免刷新时卸载步骤内容。设为 false 可恢复完全受控行为；仅切换 `visible` 不重置记录。完整约定见 [ImmersiveDialog 初始化生命周期](../ImmersiveDialog/guide.md#初始化生命周期)。
 - **按钮文案自动切换**：非最后一步时，确认按钮文案自动显示为 `nextText`（默认"下一步"）；最后一步时显示为 `okText`（默认"确认"）。
 - **onNextStep 校验机制**：`onNextStep` 返回值严格等于 `false`（`=== false`）时阻止导航到下一步。返回 `undefined`、`null`、`true` 或其他值均不会阻止。这是该组件最核心的交互模式。
 - **onOk 仅在最后一步触发**：非最后一步点击确认按钮时触发的是 `onNextStep`，不会触发 `onOk`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudtower/eagle",
-  "version": "4100.0.20",
+  "version": "4100.0.22",
   "main": "dist/cjs/index.js",
   "module": "./dist/esm/index.js",
   "types": "dist/src/index.d.ts",
@@ -30,8 +30,8 @@
     "sync:typography": "node tools/sync-figma-typography.js --write"
   },
   "dependencies": {
-    "@cloudtower/icons-react": "^4100.0.20",
-    "@cloudtower/parrot": "^4100.0.20",
+    "@cloudtower/icons-react": "^4100.0.22",
+    "@cloudtower/parrot": "^4100.0.22",
     "@cloudtower/rc-notification": "^4.6.1",
     "@linaria/core": "^4.2.2",
     "@linaria/react": "^4.3.0",