ice-render 1.3.0 → 1.4.1

package/dist/types/graphic/ICEComponent.d.mts

@@ -10,14 +10,6 @@ import EventBus from '../event/EventBus.mjs';
 import ICEEventTarget from '../event/ICEEventTarget.mjs';
 import ICEBoundingBox from '../geometry/ICEBoundingBox.mjs';
 import ICE from '../ICE.mjs';
-/**
- * @class ICEComponent
- *
- * 最顶级的抽象类，Canvas 内部所有可见的组件都是它的子类。
- *
- * @abstract
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
 declare abstract class ICEComponent extends ICEEventTarget {
     ice: ICE;
     root: any;
@@ -337,6 +329,18 @@ declare abstract class ICEComponent extends ICEEventTarget {
     protected doRender(): void;
     /** 判断两个边界盒是否在视觉上重合（用于避免重复绘制几乎相同的 min/max 框）。 */
     private __areBoundingBoxesNearlyEqual;
+    /**
+     * 内部子组件是否为「由自身 state 派生」的。
+     *
+     * 复合组件（构造时按 state 建立内部子组件的组件，如「卡片 = 底框 + 标题」）应当返回 true：
+     * 这些子组件在反序列化时会被构造函数重建，序列化它们只会造成**重复挂载**
+     * （先由构造函数建一份、再由 Deserializer 挂一份）、并且子组件的自动 zIndex 每次都会变，
+     * 让同一份数据的两次序列化结果不稳定。返回 true 后，Serializer / Deserializer 都会跳过
+     * 该组件的 childNodes —— 只持久化它自己的 state（真相源），子组件视为派生结果。
+     *
+     * 默认为 false（普通容器/叶子组件的子节点是「真数据」，必须序列化）。
+     */
+    hasDerivedChildren(): boolean;
     /**
      * 获取组件的最小包围盒，此盒子的变换矩阵与组件自身完全相同。
      * 此方法需要在 render() 之后调用，组件没有渲染时无法计算最小包围盒。

package/dist/types/graphic/ICEComponent.d.ts

@@ -10,14 +10,6 @@ import EventBus from '../event/EventBus';
 import ICEEventTarget from '../event/ICEEventTarget';
 import ICEBoundingBox from '../geometry/ICEBoundingBox';
 import ICE from '../ICE';
-/**
- * @class ICEComponent
- *
- * 最顶级的抽象类，Canvas 内部所有可见的组件都是它的子类。
- *
- * @abstract
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
 declare abstract class ICEComponent extends ICEEventTarget {
     ice: ICE;
     root: any;
@@ -337,6 +329,18 @@ declare abstract class ICEComponent extends ICEEventTarget {
     protected doRender(): void;
     /** 判断两个边界盒是否在视觉上重合（用于避免重复绘制几乎相同的 min/max 框）。 */
     private __areBoundingBoxesNearlyEqual;
+    /**
+     * 内部子组件是否为「由自身 state 派生」的。
+     *
+     * 复合组件（构造时按 state 建立内部子组件的组件，如「卡片 = 底框 + 标题」）应当返回 true：
+     * 这些子组件在反序列化时会被构造函数重建，序列化它们只会造成**重复挂载**
+     * （先由构造函数建一份、再由 Deserializer 挂一份）、并且子组件的自动 zIndex 每次都会变，
+     * 让同一份数据的两次序列化结果不稳定。返回 true 后，Serializer / Deserializer 都会跳过
+     * 该组件的 childNodes —— 只持久化它自己的 state（真相源），子组件视为派生结果。
+     *
+     * 默认为 false（普通容器/叶子组件的子节点是「真数据」，必须序列化）。
+     */
+    hasDerivedChildren(): boolean;
     /**
      * 获取组件的最小包围盒，此盒子的变换矩阵与组件自身完全相同。
      * 此方法需要在 render() 之后调用，组件没有渲染时无法计算最小包围盒。

package/dist/types/graphic/container/ICEGroup.d.mts

@@ -79,6 +79,16 @@ declare class ICEGroup extends ICERect {
      */
     addChild(child: ICEComponent, markDirty?: boolean): void;
     addChildren(arr: Array<ICEComponent>): void;
+    /**
+     * 把某个组件迁移到本容器下（**不销毁**它）。
+     *
+     * 为什么需要单独的 API：`removeChild()` 末尾会调用 `child.destory()`（清事件、清子节点），
+     * 所以「先 removeChild 再 addChild」式的重父级会把组件连同内部子树一起毁掉
+     * （BPMN 池/泳道里嵌节点时就踩到这个坑：标题、角标全没了）。
+     * 本方法只从旧父级的 childNodes / 去重集合里摘除，再挂到本容器，组件本体与子树保持完好。
+     * **坐标不换算**：调用方若要保持世界位置，请自行换算 left/top。
+     */
+    adoptChild(child: ICEComponent, markDirty?: boolean): void;
     removeChild(child: ICEComponent, markDirty?: boolean): void;
     removeChildren(arr: Array<ICEComponent>): void;
     /**

package/dist/types/graphic/container/ICEGroup.d.ts

@@ -79,6 +79,16 @@ declare class ICEGroup extends ICERect {
      */
     addChild(child: ICEComponent, markDirty?: boolean): void;
     addChildren(arr: Array<ICEComponent>): void;
+    /**
+     * 把某个组件迁移到本容器下（**不销毁**它）。
+     *
+     * 为什么需要单独的 API：`removeChild()` 末尾会调用 `child.destory()`（清事件、清子节点），
+     * 所以「先 removeChild 再 addChild」式的重父级会把组件连同内部子树一起毁掉
+     * （BPMN 池/泳道里嵌节点时就踩到这个坑：标题、角标全没了）。
+     * 本方法只从旧父级的 childNodes / 去重集合里摘除，再挂到本容器，组件本体与子树保持完好。
+     * **坐标不换算**：调用方若要保持世界位置，请自行换算 left/top。
+     */
+    adoptChild(child: ICEComponent, markDirty?: boolean): void;
     removeChild(child: ICEComponent, markDirty?: boolean): void;
     removeChildren(arr: Array<ICEComponent>): void;
     /**

package/dist/types/index.d.mts

@@ -51,5 +51,7 @@ export { default as ICE } from './ICE.mjs';
 export { default as CanvasRenderer } from './renderer/CanvasRenderer.mjs';
 export { default as PluginHost } from './plugin/PluginHost.mjs';
 export type { ICEPlugin, ICEPluginTool, ICERenderHook, ICERenderFrame } from './plugin/PluginHost.mjs';
+export { default as Serializer, SERIALIZATION_VERSION } from './persistence/Serializer.mjs';
+export { default as Deserializer, SERIALIZATION_MIGRATIONS } from './persistence/Deserializer.mjs';
 export { buildAccessibilityTree } from './a11y/accessibility.mjs';
 export type { ICEAccessibleNode, ICEAccessibleRole, ICEAccessibilityOptions } from './a11y/accessibility.mjs';

package/dist/types/index.d.ts

@@ -51,5 +51,7 @@ export { default as ICE } from './ICE';
 export { default as CanvasRenderer } from './renderer/CanvasRenderer';
 export { default as PluginHost } from './plugin/PluginHost';
 export type { ICEPlugin, ICEPluginTool, ICERenderHook, ICERenderFrame } from './plugin/PluginHost';
+export { default as Serializer, SERIALIZATION_VERSION } from './persistence/Serializer';
+export { default as Deserializer, SERIALIZATION_MIGRATIONS } from './persistence/Deserializer';
 export { buildAccessibilityTree } from './a11y/accessibility';
 export type { ICEAccessibleNode, ICEAccessibleRole, ICEAccessibilityOptions } from './a11y/accessibility';

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "大漠穷秋",
   "name": "ice-render",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "A canvas engine for interactive graphics.",
   "repository": {
     "type": "git",