ice-render 1.0.4 → 1.0.6

package/dist/types/FrameManager.d.mts

@@ -0,0 +1,26 @@
+/**
+ * @singleton
+ * @class FrameManager 帧频控制器
+ *
+ * - 全局单例，请勿创建多个实例。
+ * - 在同一个 window/global 中，只有一个 FrameManager ，也就是说 FrameManager 是跨 ICE 实例共享的。
+ * - FrameManager 只负责把 window/global 上的 requestAnimationFrame 回调函数转换成 ICE_EVENT_NAME_CONSTS.ICE_FRAME_EVENT 事件，然后在所有事件总线上进行触发。
+ * - FrameManager 只触发事件，不进行渲染，渲染操作由对应的 Render 完成。
+ * - FrameManager 与 EventBus 之间是一对多的关系，一个 FrameManager 上可以注册多个事件总线，因为同一个页面上可能会存在多幅画面。
+ *
+ * @see ICE
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare const FrameManager: {
+    evtBuses: any[];
+    stopped: boolean;
+    frameCallback: () => void;
+    start: () => void;
+    stop: () => void;
+    /**
+     * @method registerEvtBus  注册事件总线
+     */
+    registerEvtBus: (evtBus: any) => void;
+    delEvtBus: (evtBus: any) => void;
+};
+export default FrameManager;

package/dist/types/FrameManager.d.ts

@@ -1,26 +1,26 @@
-/**
- * @singleton
- * @class FrameManager 帧频控制器
- *
- * - 全局单例，请勿创建多个实例。
- * - 在同一个 window/global 中，只有一个 FrameManager ，也就是说 FrameManager 是跨 ICE 实例共享的。
- * - FrameManager 只负责把 window/global 上的 requestAnimationFrame 回调函数转换成 ICE_EVENT_NAME_CONSTS.ICE_FRAME_EVENT 事件，然后在所有事件总线上进行触发。
- * - FrameManager 只触发事件，不进行渲染，渲染操作由对应的 Render 完成。
- * - FrameManager 与 EventBus 之间是一对多的关系，一个 FrameManager 上可以注册多个事件总线，因为同一个页面上可能会存在多幅画面。
- *
- * @see ICE
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-declare const FrameManager: {
-    evtBuses: any[];
-    stopped: boolean;
-    frameCallback: () => void;
-    start: () => void;
-    stop: () => void;
-    /**
-     * @method registerEvtBus  注册事件总线
-     */
-    regitserEvtBus: (evtBus: any) => void;
-    delEvtBus: (evtBus: any) => void;
-};
-export default FrameManager;
+/**
+ * @singleton
+ * @class FrameManager 帧频控制器
+ *
+ * - 全局单例，请勿创建多个实例。
+ * - 在同一个 window/global 中，只有一个 FrameManager ，也就是说 FrameManager 是跨 ICE 实例共享的。
+ * - FrameManager 只负责把 window/global 上的 requestAnimationFrame 回调函数转换成 ICE_EVENT_NAME_CONSTS.ICE_FRAME_EVENT 事件，然后在所有事件总线上进行触发。
+ * - FrameManager 只触发事件，不进行渲染，渲染操作由对应的 Render 完成。
+ * - FrameManager 与 EventBus 之间是一对多的关系，一个 FrameManager 上可以注册多个事件总线，因为同一个页面上可能会存在多幅画面。
+ *
+ * @see ICE
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare const FrameManager: {
+    evtBuses: any[];
+    stopped: boolean;
+    frameCallback: () => void;
+    start: () => void;
+    stop: () => void;
+    /**
+     * @method registerEvtBus  注册事件总线
+     */
+    registerEvtBus: (evtBus: any) => void;
+    delEvtBus: (evtBus: any) => void;
+};
+export default FrameManager;

package/dist/types/ICE.d.mts

@@ -0,0 +1,369 @@
+import AnimationManager from './animation/AnimationManager.mjs';
+import ICEControlPanelManager from './control-panel/ICEControlPanelManager.mjs';
+import AlignmentGuideManager from './control-panel/AlignmentGuideManager.mjs';
+import DOMEventDispatcher from './event/DOMEventDispatcher.mjs';
+import EventBus from './event/EventBus.mjs';
+import ICEComponent from './graphic/ICEComponent.mjs';
+import ICELinkSlotManager from './graphic/link/ICELinkSlotManager.mjs';
+import Deserializer from './persistence/Deserializer.mjs';
+import Serializer from './persistence/Serializer.mjs';
+import PluginHost, { ICEPlugin } from './plugin/PluginHost.mjs';
+import { ICEAccessibleNode, ICEAccessibilityOptions } from './a11y/accessibility.mjs';
+import ImageCache from './util/ImageCache.mjs';
+import { ICETheme, ICESemanticTheme } from './theme/ICETheme.mjs';
+/**
+ * @class ICE
+ *
+ * - ICE 是整个引擎的主入口类。
+ * - 同一个 canvas 标签上只能初始化一个 ICE 实例。
+ * - 同一个页面上可以存在多幅图。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICE {
+    childNodes: any[];
+    toolNodes: any[];
+    private __childSet;
+    private __toolSet;
+    evtBus: EventBus;
+    root: any;
+    canvasEl: any;
+    ctx: any;
+    canvasWidth: number;
+    canvasHeight: number;
+    canvasBoundingClientRect: any;
+    /** 视口变换（视图缩放/平移）：屏幕 = 世界 * scale + translate。默认单位视口，不影响既有行为。 */
+    viewport: {
+        scale: number;
+        tx: number;
+        ty: number;
+    };
+    /**
+     * 设备像素比。默认 1（不改变既有行为）。
+     *
+     * 传 >1 时（`ICE.init(el, { dpr: 2 })`）：引擎把 canvas 的 backing store 放大到 cssSize*dpr，
+     * 渲染变换乘以 dpr，从而在高分屏上不发虚。**交互侧（命中/拖拽/吸附）仍用 CSS 像素语义**，
+     * 因为鼠标/触摸坐标本身就是 CSS 像素，所以 screenToWorld 不参与 dpr。
+     */
+    dpr: number;
+    /** 渲染用视口缓存（= dpr · viewport），避免每组件每帧分配对象。 */
+    private __renderVp;
+    /**
+     * canvas 内容盒（绘制区）相对视口的偏移与尺寸。
+     *
+     * `getBoundingClientRect()` 返回的是 **border-box**，而 canvas 的绘制区是**内容盒**：
+     * 画布带 border / padding 时，若直接用 rect.left/top 换算鼠标坐标会整体偏移（差一个边框宽），
+     * backing store 尺寸也会被边框撑大。这里在刷新 rect 时一并读取 computedStyle 补偿。
+     */
+    private __contentBox;
+    selectionList: Array<any>;
+    /** 插件宿主：组件 / 渲染 / 交互工具三层注册点，见 `src/plugin/PluginHost.ts`。 */
+    plugins: PluginHost;
+    /**
+     * 当前实例持有的主题（**实例级**，互不污染）。
+     *
+     * 初始值取模块级默认主题；`setTheme()` 只改本实例。
+     * 组件构造时若用了 `preset`，会在加入本实例时按这里的主题重新解析一次
+     * （见 `addChild` / `addTool` 中的 `__reapplyPreset`）。
+     */
+    theme: ICETheme;
+    typeMapping: {};
+    /** 构造函数 → 类型名 的反查表（序列化用）。惰性构建，registerType/init 后失效重建。 */
+    private __typeIdMapping;
+    renderer: any;
+    animationManager: AnimationManager;
+    eventDispatcher: DOMEventDispatcher;
+    controlPanelManager: ICEControlPanelManager;
+    alignmentGuide: AlignmentGuideManager;
+    linkSlotManager: ICELinkSlotManager;
+    serializer: Serializer;
+    deserializer: Deserializer;
+    imageCache: ImageCache;
+    private __dirty;
+    constructor();
+    /** 是否已经完成初始化（用于 init 幂等 / destroy 配对） */
+    private __initialized;
+    /**
+     * 从 init 入参解析出 canvas 元素。
+     * 支持：HTMLCanvasElement、CanvasRenderingContext2D；解析不出则返回 null。
+     */
+    private __resolveCanvasEl;
+    /**
+     * @param ctx DOM id、HTMLCanvasElement 或 CanvasRenderingContext2D
+     * @param options 渲染配置。renderMode: 'dirty-rect'(默认) | 'full'
+     *
+     * 幂等：同一个 ICE 实例重复 init 到同一个 canvas 时直接返回自身。
+     * React StrictMode 下 effect 会被执行两次，幂等可以避免重复挂载 Manager / 重复绑定全局事件。
+     * 若要换一个 canvas，请先调用 destroy()。
+     */
+    init(ctx: any, options?: {
+        renderMode?: 'full' | 'dirty-rect';
+        dpr?: number;
+    }): this;
+    /**
+     * @method destroy 销毁当前实例
+     *
+     * 与 init() 配对：停止所有 Manager、解绑 canvas 上的原生事件、注销全局事件总线（FrameManager / DOMEventInterceptor 都是全局单例，必须显式注销）。
+     * 销毁之后可以再次 init（例如 React 组件重新挂载），不会累积监听或帧循环。
+     */
+    destroy(): void;
+    /**
+     * @method addChild
+     * 添加交互工具组件。
+     * 工具组件不触发事件，不产生动画效果。
+     * @param {ICEComponent} tool
+     */
+    addTool(tool: ICEComponent): void;
+    /**
+     * @methos removeTool
+     * 删除交互工具组件。
+     * 工具组件不触发事件，不产生动画效果。
+     * @param tool
+     */
+    removeTool(tool: ICEComponent): void;
+    /**
+     *
+     * 调用 ICE.addChild() 方法，会直接把对象画在 canvas 上。
+     * 如果需要在容器中画组件，参见 @see ICEGroup.addChild() 方法
+     *
+     * @param component
+     */
+    addChild(component: any, markDirty?: boolean): void;
+    addChildren(arr: Array<ICEComponent>): void;
+    removeChild(component: ICEComponent, markDirty?: boolean): void;
+    removeChildren(arr: Array<ICEComponent>): void;
+    clearAll(): void;
+    /**
+     * 按 id 查找组件。
+     *
+     * 查找范围：**先查顶层 `childNodes`**（同 id 时顶层优先，保持既有优先级），再深度优先递归整棵
+     * 子树。「连线连接嵌套子组件」依赖本方法（`ICEPolyLine.syncConnections` → 本方法）。
+     *
+     * **工具层 `toolNodes` 不参与查找**：工具是 UI 覆盖层（变换/连线手柄等），不应成为连线端点。
+     *
+     * 历史：早期只搜第一层，嵌套场景连线会静默失效；中途曾尝试放开递归但被回退 ——
+     * 当时表现为 `dirty-rect-pixel` 富场景 step1 约 900 px 差异，看起来像「连线端点推导与局部重绘
+     * 冲突」，实际根因是**折线的包围盒是退化的**（`state.width ≈ 0`），导致 dirty-rect 按快照盒
+     * 挑选重画对象时漏掉折线（擦除区域内的折线笔迹丢失）。该根因已修（见 `ICEComponent.__localBox`
+     * 与 `ICEPolyLine.calcComponentParams`），因此递归可以放开。
+     */
+    findComponent(id: string): any;
+    /** 深度优先查找子树（不含工具层）。 */
+    private __findComponentInTree;
+    set dirty(flag: boolean);
+    get dirty(): boolean;
+    /**
+     * @method registerType 注册组件类型
+     *
+     * - 需要在反序列化之前调用，否则无法反序列化。
+     * - ICE 内置的类型已经自动注册，不需要手动注册。
+     *
+     * @param className
+     * @param Clazz
+     */
+    registerType(className: string, Clazz: new (...args: any[]) => any): void;
+    /**
+     * 由构造函数反查稳定的类型名（序列化用）。
+     *
+     * - 已注册的类型：返回注册名（与类的 JS 名解耦，压缩改名不影响已存数据）
+     * - 未注册：返回 undefined，调用方回退到 `constructor.name`（保持既有行为）
+     * - 同一个构造函数注册了多个名字时，**先注册的优先**（内置类型因此不会被别名顶掉）
+     */
+    getTypeId(Clazz: new (...args: any[]) => any): string | undefined;
+    /**
+     * 注册插件（幂等：同名插件重复调用直接返回，不重复 setup）。
+     *
+     * 插件可提供三层扩展点：`components`（自定义图元类型）、`render`（每帧绘制回调）、
+     * `tools`（按选中组件匹配的交互工具）。详见 `src/plugin/PluginHost.ts`。
+     *
+     * @returns 是否本次真的注册（同名已存在时为 false）
+     */
+    use(plugin: ICEPlugin): boolean;
+    /**
+     * 注销插件：撤销其渲染回调与交互工具，并调用 `teardown`。
+     * 注意：`components` 里注册的类型**保留**（反序列化可能仍依赖，且撤销会让已存数据失效）。
+     */
+    unuse(name: string): boolean;
+    /** 已注册插件名（只读快照）。 */
+    getPlugins(): string[];
+    /**
+     * 更新选中集合的**统一入口**：写 `selectionList` 并同步插件工具。
+     * 约定：目前插件工具按「首个选中组件」匹配（引擎当前也仅支持单选）。
+     *
+     * @returns 是否有「排他」插件工具命中 —— 调用方据此禁用内置变换/连线面板
+     */
+    setSelection(components: Array<any> | any | null): boolean;
+    /**
+     * 无障碍：取「可访问节点快照」，供应用层渲染隐藏 DOM 镜像（screen reader / 键盘导航）。
+     *
+     * 引擎**不**自建 DOM 镜像层 —— 镜像的 DOM 结构、ARIA 属性、文案与焦点环高度依赖具体产品语义。
+     * 引擎负责给出：id / 角色建议 / 可读名称 / **屏幕坐标盒（CSS 像素）** / 层级 / tab 顺序 / 选中态；
+     * 应用层据此渲染 `<div role="img" aria-label=... style="position:absolute; ...">` 之类的镜像元素，
+     * 并用 `setFocusedComponent()` 把 DOM 焦点映射回组件。
+     *
+     * 不含未上屏（无有效变换矩阵）的组件，也不会修改任何组件 state。
+     */
+    getAccessibilityTree(options?: ICEAccessibilityOptions): ICEAccessibleNode[];
+    /**
+     * 设置键盘事件的焦点组件（无障碍 / 键盘导航原语）。
+     *
+     * 未设置时维持既有行为：键盘事件派发给「上次点击命中的组件」。
+     * 传入 id 字符串或组件实例；传 null / undefined 清除焦点。
+     */
+    setFocusedComponent(component: any | string | null): this;
+    /** 当前键盘焦点组件（未设置时为 null）。 */
+    getFocusedComponent(): any;
+    /**
+     * @method getType 获取组件构造函数
+     * @param className
+     * @returns
+     */
+    getType(className: string): any;
+    /**
+     * 加载自定义字体（平台适配）：浏览器走 FontFace API，小程序走 wx.loadFont。
+     * 加载后，在 ICEText 的 style.fontFamily 里引用该字体名即可。
+     * @param family 字体族名（如 'MyFont'）
+     * @param source 字体源（浏览器为 url/二进制，小程序为本地文件路径）
+     */
+    loadFont(family: string, source: string): Promise<any>;
+    /**
+     * 切换主题（string 按名切换 / object 浅合并 semantic），预设样式（preset）会自动跟随主题变量。
+     * 热切换：已渲染的组件里用了 preset 的会重新 resolve（用户显式传的样式优先）。
+     */
+    setTheme(theme: string | Partial<ICESemanticTheme>): this;
+    /**
+     * 设置视口（视图缩放 + 平移）。
+     *
+     * 屏幕坐标 = 世界坐标 * scale + translate。这是「视图缩放」，不改变任何组件的 state，
+     * 只影响渲染结果与命中检测的坐标换算。视口变化会让渲染器回退一次全量重绘并重建快照。
+     */
+    setViewport(scale: number, tx?: number, ty?: number): this;
+    /** 屏幕坐标（canvas 像素）→ 世界坐标（受视口逆变换）。 */
+    screenToWorld(sx: number, sy: number): [number, number];
+    /** 世界坐标 → 屏幕坐标（canvas 像素）。 */
+    worldToScreen(wx: number, wy: number): [number, number];
+    /**
+     * 刷新 canvas 的 getBoundingClientRect 缓存并返回。
+     *
+     * 输入事件用它把屏幕坐标换算成 canvas 内坐标；页面滚动 / 布局变化后必须刷新，
+     * 否则命中检测会整体偏移（旧实现只在 init 时取一次，滚动后即失效）。
+     * 高频的移动类事件复用缓存，见 DOMEventDispatcher.__resolveCanvasRect。
+     */
+    /**
+     * 渲染用视口 = dpr · viewport（仅「往画布上画」这一侧需要乘 dpr）。
+     * dpr === 1 时**直接返回 viewport 本身**：零分配、且与既有行为逐字节一致。
+     */
+    getRenderViewport(): {
+        scale: number;
+        tx: number;
+        ty: number;
+    };
+    /**
+     * 把 canvas 的 backing store 放大到 cssSize * dpr，并把 CSS 尺寸固定为逻辑尺寸。
+     * 只有传了 dpr>1 才会调用。
+     */
+    private __applyDevicePixelRatio;
+    updateCanvasBoundingRect(): any;
+    /**
+     * 读取 canvas 内容盒：把 border-box 的 rect 补偿成「绘制区」的偏移与尺寸。
+     * 无 getComputedStyle 的运行时（如小程序）补偿为 0，退回 rect 原值。
+     */
+    private __readContentBox;
+    /**
+     * 供输入派发器做坐标换算的矩形：**内容盒左上角**。
+     * 这样 `clientX - left` 就落在绘制区坐标里，与旧实现（offsetX）语义一致，不受 border/padding 影响。
+     */
+    getInputRect(): any;
+    /**
+     * 以屏幕点为锚点缩放视口（滚轮缩放 / 双指缩放可用的引擎原语）。
+     *
+     * 保持锚点下的世界坐标在缩放前后落在同一屏幕位置：先取锚点对应的世界坐标，
+     * 换算新 scale 后反解 translate。只改视口状态，**不修改任何组件的 state**
+     * （与 setViewport 同一约束）。
+     *
+     * 用法（应用层接滚轮，一行即可）：
+     * ```js
+     * ice.evtBus.on('wheel', (e) => {
+     *   ice.zoomAt(e.offsetX, e.offsetY, e.deltaY < 0 ? 1.1 : 1 / 1.1);
+     * });
+     * ```
+     *
+     * @param screenX 锚点屏幕 x（canvas 像素，通常是鼠标 / 触摸位置）
+     * @param screenY 锚点屏幕 y
+     * @param factor  缩放倍数，>1 放大、<1 缩小；非正数或非有限值直接忽略
+     * @param minScale 最小 scale（默认 0.05）
+     * @param maxScale 最大 scale（默认 20）
+     */
+    zoomAt(screenX: number, screenY: number, factor: number, minScale?: number, maxScale?: number): this;
+    /**
+     * 命中检测：屏幕坐标（canvas 像素）→ 命中的最上层可交互组件；无命中返回 null。
+     * 供应用层做「空白处拖拽平移 / 点击命中」等视口交互。
+     */
+    hitTest(sx: number, sy: number): any;
+    /**
+     * 注册命名主题（运行时注入，如多品牌 / 多租户 / 暗色主题）。
+     */
+    registerTheme(name: string, theme: ICETheme): this;
+    /**
+     * 获取当前主题对象（{ base, semantic }）。返回的是**本实例**的主题。
+     */
+    getTheme(): ICETheme;
+    /**
+     * 遍历组件树，对每个用了 preset 的组件重新 resolve preset（主题热切换）。
+     */
+    private __reapplyPresets;
+    /**
+     * 创建线性渐变对象，供组件 style.fillStyle/strokeStyle 使用。
+     * 用法：const g = ice.createLinearGradient(0,0,100,0); g.addColorStop(0,'red'); g.addColorStop(1,'blue');
+     *       new ICERect({ style: { fillStyle: g } })
+     */
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number): any;
+    /**
+     * 创建径向（圆形）渐变对象。
+     */
+    createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): any;
+    /**
+     * 创建锥形渐变（较新 API，Chrome 99+），不支持的环境返回 null。
+     */
+    createConicGradient(startAngle: number, x: number, y: number): any;
+    /**
+     * 创建图案填充（用图片平铺），供 style.fillStyle/strokeStyle 使用。
+     * @param image 图片源（HTMLImageElement/canvas 等）
+     * @param repetition 'repeat'|'repeat-x'|'repeat-y'|'no-repeat'
+     */
+    createPattern(image: any, repetition: string): any;
+    /**
+     * 读取画布指定区域的像素数据（取色、滤镜、橡皮擦等）。
+     */
+    getImageData(x: number, y: number, w: number, h: number): any;
+    /**
+     * 写入像素数据到画布。
+     */
+    putImageData(imageData: any, x: number, y: number): void;
+    createImageData(w: number, h: number): any;
+    /**
+     * 把画布导出为 dataURL（默认 PNG）。type 如 'image/png'/'image/jpeg'，quality 0~1（jpeg）。
+     */
+    toDataURL(type?: string, quality?: number): string;
+    /**
+     * 把画布导出为 Blob（回调接收）。
+     */
+    toBlob(callback: (blob: Blob | null) => void, type?: string, quality?: number): void;
+    /**
+     * 把对象序列化成 JSON 字符串：
+     * - 容器型组件需要负责子节点的序列化操作
+     * - 如果组件不需要序列化，需要返回 null
+     * @returns Object
+     */
+    toJSONString(): string;
+    /**
+     * 把对象序列化成 JSON 对象：
+     * - 容器型组件需要负责子节点的序列化操作
+     * - 如果组件不需要序列化，需要返回 null
+     * @returns Object
+     */
+    toJSONObject(): object;
+    fromJSONObject(jsonObject: any): void;
+    fromJSONString(jsonStr: string): void;
+}
+export default ICE;