ice-render 1.0.4 → 1.0.5

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

@@ -0,0 +1,436 @@
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import { mat2d } from 'gl-matrix';
+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;
+    ctx: any;
+    evtBus: EventBus;
+    parentNode: any;
+    protected static instanceCounter: number;
+    protected __dirty: boolean;
+    private __localBoxScratch;
+    /** 本渲染通道的「本地 → 设备」CTM（主画布通道 = 视口·composed；离屏位图通道 = base·composed）。 */
+    private __activeCtm;
+    /** 本渲染通道的「世界 → 设备」矩阵（主画布通道 = 视口；离屏通道 = 缓存位图的 base 矩阵）。 */
+    private __activeWorldMatrix;
+    /** 可见性缓存（代际号 + 值）：见 `isEffectivelyVisible` 的说明。 */
+    private __visEpoch;
+    private __visValue;
+    /** 声明式渐变缓存：按描述对象引用判定，`refreshParams()` 里失效（setState 必然触发它）。 */
+    private __gradCache;
+    /**
+     * 「自身派生参数需要重算」标志（尺寸 / 点集 / 文本量测等，由 calcComponentParams 产出）。
+     *
+     * 与 `dirty` 的区别：
+     * - `dirty` 表示**需要重绘**。祖先变换变化时，后代的绝对矩阵变了 → 必须重绘；
+     * - `paramsDirty` 表示**自身派生参数需要重算**。它只取决于组件自身的 state，
+     *   与祖先变换无关。
+     *
+     * 拆分的目的：移动一个容器时，旧实现递归把所有后代置 `dirty`，而后代又以 `dirty`
+     * 判断是否重算派生参数 → 后代（尤其点集类图元）会白白重算 `calcDots()`。
+     * 现在后代只置 `dirty`（要重绘），派生参数仍为干净 → 跳过重量测。
+     *
+     * 统一由 `refreshParams()` 读取与清理，不要在别处手工维护。
+     */
+    protected __paramsDirty: boolean;
+    private __absScratchA;
+    private __absScratchB;
+    private __transScratch;
+    private __originScratch;
+    private __composeScratch;
+    private __viewportScratch;
+    /**
+     * @cfg
+     * {
+     *   id: 'ICE_XXXXXXX',                                      //UUID
+     *   left: 0,                                                //x 坐标相对于父组件的偏移量
+     *   top: 0,                                                 //y 坐标相对于父组件的偏移量
+     *   width: 0,                                               //原始宽度，没有经过变换
+     *   height: 0,                                              //原始高度，没有经过变换
+     *   style: {
+     *     fillStyle: 'red',
+     *     strokeStyle: 'blue',
+     *     lineWidth: 1,
+     *   },
+     *   fill:true,                                              //是否填充
+     *   stroke:true,                                            //是否描边
+     *   animations: {},                                         //动画
+     *   transform: {                                            //组件自身的变换参数，不包含父组件
+     *     translate: [0, 0],                                    //平移，像素
+     *     scale: [1, 1],                                        //X轴缩放倍数，Y轴缩放倍数
+     *     skew: [0, 0],                                         //X轴扭曲角度，Y轴扭曲角度
+     *     rotate: 0,                                            //旋转角度
+     *   },
+     *   linearMatrix: [],                            //线性变换矩阵，不含平移，按照 gl-matrix 的格式定义
+     *   composedMatrix: [],                          //复合变换矩阵，包含所有祖先节点的平移、原点移动、线性变换计算，composedMatrix 不会实时更新，如果需要获取当前最新的变换矩阵，需要调用 composeMatrix() 方法。按照 gl-matrix 的格式定义
+     *   origin:'localCenter',
+     *   localOrigin: [0,0],                          //相对于组件本地坐标系（组件内部的左上角为 [0,0] 点）计算的原点坐标
+     *   absoluteOrigin: [0,0],                       //相对于全局坐标系（canvas 的左上角 [0,0] 点）计算的原点坐标
+     *   zIndex: ICEComponent.instanceCounter++,      //类似于 CSS 中的 zIndex
+     *   display:true,                                //如果 display 为 false ， Renderer 不会调用其 render 方法，对象在内存中存在，但是不会被渲染出来。如果 display 为 false ，所有子组件也不会被渲染出来。
+     *   draggable:true,                              //是否可以拖动
+     *   transformable:true,                          //是否可以进行变换：scale/rotate/skew ，以及 resize ，但是不控制拖动
+     *   linkable:true,                               //组件是否可以用连接线连接起来，如果此状态为 true ，ICELinkSlotManager 在运行时会动态在组件上创建连接插槽 ICELinkSlot 的实例
+     *   interactive: true,                           //是否可以进行用户交互操作，如果此参数为 false ， draggable, transformable TODO:动画运行过程中不允许选中，不能进行交互？？？
+     *   showMinBoundingBox:true,                     //是否显示最小包围盒，开发时打开，主要用于 debug
+     *   showMaxBoundingBox:true,                     //是否显示最大包围盒，开发时打开，主要用于 debug
+     * }
+     * @param props
+     */
+    props: any;
+    /**
+     * 在 ICE 引擎中，所有对象都可以启用动画效果，所以对象的 state 随时可能发生变化。
+     * props 与 state 之间的关系与行为模式借鉴自 React 框架，概念模型完全一致。
+     * @see https://reactjs.org/docs/components-and-props.html
+     */
+    state: any;
+    private __presetName?;
+    private __userProps?;
+    constructor(props?: any);
+    /**
+     * 初始化 state：同样原型继承共享默认，只把用户传入的 own 字段深拷贝到实例，
+     * 运行时派生字段（矩阵/原点等）预分配 own 空值。
+     *
+     * 这样 state 与 props 是独立对象，任何「直接写 state」都不会污染 props 或共享默认；
+     * 同时省去「完整 cloneDeep(props)」里重复的默认嵌套对象（内存优化）。
+     */
+    private __initState;
+    /**
+     * 重新 resolve preset（主题热切换用）：把 preset 补丁按当前主题重新展开，
+     * 只更新 preset 涉及的字段（style + radius/stroke/fill 等），用户显式传的值优先。
+     */
+    __reapplyPreset(theme?: any): void;
+    /**
+     * @method initEvents 注册默认支持的事件
+     *
+     * - ICEComponent 是顶级类，这里注册的事件所有子类都会响应。
+     * - 子类可以提供自己特殊的实现，也可以把此方法覆盖成空函数。
+     *
+     * @see {ICEComponent.keyboardEvtHandler}
+     */
+    protected initEvents(): void;
+    protected mouseDownEvtHandler(evt?: any): void;
+    protected mouseMoveEvtHandler(evt: any): boolean;
+    protected mouseUpEvtHandler(evt?: any): void;
+    /**
+     * @method keyboardEvtHandler 默认键盘事件处理
+     *
+     * - ICE 中的所有组件默认都可以接收键盘事件，子类可以覆盖此方法提供自己的实现。
+     * - 子类如果不需要响应键盘事件，可以覆盖一个空实现，或者在构造完成之后删掉对键盘事件的监听。
+     *
+     * !注意，这里只支持标准写法，不再兼容历史的 charCode 和 keyCode 写法。
+     * !W3C 标准按键值定义 https://www.w3.org/TR/uievents-key/#key-attribute-value
+     * @param evt
+     * @returns
+     */
+    protected keyboardEvtHandler(evt: any): void;
+    /**
+     * !Important: 核心方法，FrameManager 会调度此方法进行实际的渲染操作。
+     * !Important: 这些方法调用有顺序
+     */
+    render(): void;
+    /**
+     * 把组件渲染到指定的目标上下文（离屏缓存用）。
+     *
+     * - baseMatrix：在组件自身 composedMatrix 之前再叠加的基准矩阵。离屏缓存用它把世界盒
+     *   平移到离屏画布左上角，即最终 CTM = baseMatrix · composedMatrix。
+     * - 渲染期间临时把 this.ctx 重定向到 targetCtx，结束后恢复，不改变组件状态。
+     */
+    renderTo(targetCtx: any, baseMatrix?: number[] | null): void;
+    /**
+     * 「最终可见」：自身与**所有祖先**的 `state.display` 都为真。
+     *
+     * `state.display = false` 的语义是「整棵子树都不渲染」（见上方 props 文档），但渲染队列
+     * 是把树拉平后逐个入队的，只判组件自身的话，把一个父容器设为 false 后它的子组件仍会被
+     * 画出来、也仍能被点中。
+     *
+     * 顶层组件（无 parentNode）走 O(1) 快路径 —— 绝大多数组件都是顶层，热路径上不付出遍历成本。
+     */
+    isEffectivelyVisible(): boolean;
+    /** 真正沿父链判定一次（只在代际变化时执行）。 */
+    private __computeEffectivelyVisible;
+    private __renderCore;
+    protected applyStyleToCtx(): void;
+    /**
+     * 应用单个样式属性到 ctx，支持简写：
+     * - shadow: 'sm' | 'md' | 'lg' 展开成 shadowColor/shadowBlur/shadowOffsetX/shadowOffsetY。
+     */
+    private __applyStyleProp;
+    /**
+     * 把声明式渐变描述解析成 `CanvasGradient`（带缓存）。
+     *
+     * 描述形状（坐标是**组件本地坐标**）：
+     * ```
+     * { type: 'linear', from: [0,0], to: [100,0], stops: [[0,'#fff'],[1,'#000']] }
+     * { type: 'radial', center: [50,50], radius: 50, innerRadius: 0, stops: [...] }
+     * { type: 'conic',  center: [50,50], startAngle: 0, stops: [...] }
+     * ```
+     * 它比手搓 `CanvasGradient` 多两个好处：**可序列化**（纯对象，存盘不丢）与**可用于主题 preset**。
+     */
+    private __resolveGradient;
+    /** 真正构造 CanvasGradient。缺少对应 ctx API 时返回 null（调用方会退回纯色）。 */
+    private __buildGradient;
+    /**
+     * @method calcComponentParams
+     * - 计算组件最原始的宽高和位置，此时没有经过任何变换，也没有移动坐标原点。
+     * - 在计算组件的原始尺寸时还没有确定原点坐标，所以只能基于组件本地坐标系的左上角 (0,0) 点进行计算。
+     * - 此方法不能依赖原点位置和 transform 矩阵。
+     * - 此方法会在 render() 中调用，所以不需要在构造函数中调用。
+     * - 此方法中不能使用 setState() ，如果需要修改状态，直接赋值，如：this.state.width = 100;
+     * - 子类可以覆盖此方法，实现自己的计算逻辑。
+     * @returns
+     */
+    protected calcComponentParams(): {
+        width: any;
+        height: any;
+    };
+    /**
+     * 组件**本地包围盒**（未变换、未减去原点），写入并返回 [x0, y0, x1, y1]。
+     *
+     * 默认约定：几何自本地 (0,0) 起、尺寸为 `state.width/height`。
+     * **子类若几何不遵守该约定必须覆盖本方法** —— 例如 `ICEPolyLine` 的本地原点固定为 (0,0)，
+     * 而点集可以含负坐标，此时 [0,0,w,h] 并非它的真实盒子。
+     *
+     * `getMinBoundingBox()` 与 `__paintWorldBox()` 都消费本方法，因此两者**必然一致**。
+     * 这两者以前各算各的：`__paintWorldBox()` 直接由 width/height 推导，而折线的 `width ≈ 0`
+     * （见 ICEPolyLine.calcComponentParams 的历史实现）→ 它上屏快照是个退化小盒 →
+     * dirty-rect 按快照盒挑选「需要重画的组件」时会漏掉折线，导致擦除区域内折线笔迹丢失。
+     *
+     * 注意：返回的是实例内复用缓冲，调用方应**立即读取**，不要持有。
+     */
+    protected __localBox(): number[];
+    /**
+     * 显式「测量」：刷新一次自身派生参数（尺寸 / 点集 / 文本量测）。
+     *
+     * 布局管理器（`ICELayoutManager`）排布时读的是 `child.state.width/height`，
+     * 而这些值在首次渲染之前是 0（文本甚至是 10 的哨兵值）—— 布局因此会算错。
+     * 由容器在布局前统一调一次本方法，布局就不必「等一帧才正确」。
+     */
+    measure(): void;
+    /**
+     * 派生参数刷新入口（**唯一**）：按需调用子类的 `calcComponentParams()`，并在算完后清除 `paramsDirty`。
+     *
+     * - 参数干净时直接返回，因此「只重绘、不改自身参数」的帧（例如祖先移动）不会重算点集/文本量测。
+     * - 需要强制重算时请先置 `paramsDirty = true`（`setState` 已自动做这件事）。
+     */
+    refreshParams(): void;
+    /**
+     * 计算本地原点坐标，相对于组件本地坐标系。
+     * 此方法依赖于 width/height ，需要先计算组件的尺寸，然后才能调用此方法。
+     * @returns
+     */
+    protected calcLocalOrigin(): any;
+    /**
+     * 根据原点位置描述计算原点坐标值。
+     * 移动坐标原点后，组件内部所有的坐标点数值、边界盒子的坐标，都会受到影响。
+     * 计算出的原点数值已经包含了所有父层的移位和变换。
+     * @method calcAbsoluteOrigin
+     */
+    calcAbsoluteOrigin(): any;
+    /**
+     * 计算线性变换矩阵，此矩阵不包含平移操作。
+     * 线性变换顺序：旋转->错切->缩放
+     * 由于矩阵变换有顺序，这里采用符合自然理解的顺序进行。
+     * @method calcLinearMatrix
+     * @returns
+     */
+    protected calcLinearMatrix(): any;
+    /**
+     * 复合所有祖先节点的线性变换矩阵，获得相对于全局 canvas 对象的变换矩阵。
+     * @returns
+     */
+    calcAbsoluteLinearMatrix(): any;
+    /**
+     * 仿射变换由2步完成：
+     * - ctx 平移到指定的原点。
+     * - ctx 进行线性变换。
+     *
+     * Canvas 绘图过程中的仿射变换动作与线性代数中的规则有差异：
+     * - Canvas 的 Y 坐标轴方向是向下的。
+     * - Canvas 在做仿射变换时，变换的是 ctx 本身，而不是组件对象，相当于画布本身是具有弹性的可变形对象。
+     *
+     * @method composeMatrix
+     * @returns
+     */
+    protected composeMatrix(): mat2d;
+    /**
+     * 把变换矩阵应用到 this.ctx 上
+     */
+    protected applyTransformToCtx(baseMatrix?: number[] | null, applyViewport?: boolean): void;
+    /**
+     * 复原「本渲染通道的完整 CTM」（`base·composed` 或 `viewport·composed`）。
+     *
+     * 子类在 `super.doRender()` 之后需要重新拿到完整变换 —— 链上的 `ICEComponent.doRender()` 会
+     * 把 CTM 换成「世界 → 设备」矩阵以绘制 debug 包围盒。
+     *
+     * **不要用 `applyTransformToCtx(null, true)` 代替**：那条路径无条件按主画布视口重算，
+     * 在离屏位图通道里会把内容画到完全错误的位置（丢掉位图原点的平移），
+     * 表现为「连线的箭头与标签在缓存位图里整块消失」——离屏缓存保真测试就是抓这个的。
+     */
+    protected applyActiveTransform(): void;
+    /**
+     * 把「世界 → 设备」矩阵应用到 ctx。
+     * debug 包围盒的坐标本身就是世界坐标，不能套「本地 → 世界」的 composed 矩阵。
+     */
+    protected applyWorldTransform(): void;
+    /**
+     * 所有子类都应该提供具体的实现。
+     * @method doRender
+     */
+    protected doRender(): void;
+    /** 判断两个边界盒是否在视觉上重合（用于避免重复绘制几乎相同的 min/max 框）。 */
+    private __areBoundingBoxesNearlyEqual;
+    /**
+     * 获取组件的最小包围盒，此盒子的变换矩阵与组件自身完全相同。
+     * 此方法需要在 render() 之后调用，组件没有渲染时无法计算最小包围盒。
+     * @returns
+     */
+    getMinBoundingBox(refresh?: boolean): ICEBoundingBox;
+    /**
+     * 获取组件的最大包围盒：
+     * - 盒子保持水平和竖直，不旋转、不错切。
+     * - 盒子的4边在全局坐标 X/Y 轴上的投影范围与组件完全一致。
+     * @returns
+     */
+    getMaxBoundingBox(refresh?: boolean): ICEBoundingBox;
+    /**
+     * @method setState 更新组件状态
+     *
+     * - setState 仅仅修改参数，不会立即导致重新渲染，需要等待 FrameManager 调度，最小延迟时间约为 1/60=16.67 ms 。
+     * - state 上的所有数据是随时可能发生变化的，而 props 构造参数是不可变的，这一特性与 React 框架保持一致。 @see https://reactjs.org/docs/components-and-props.html
+     * - state 上的所有参数默认都会被序列化。
+     *
+     * @param newState
+     */
+    setState(newState: any): void;
+    /**
+     * `setState` 的**前置**钩子：必须在 `merge(this.state, newState)` 之前调用（要对比新旧值）。
+     *
+     * 覆盖 `setState` 的子类**必须**成对调用前后置钩子 —— `ICEGroup.setState` 是独立实现
+     * （它自己 merge、且不调 `super.setState`），曾因此漏掉这两件事：
+     * 「隐藏一个分组」不会让后代的可见性缓存失效、「分组改尺寸」不会触发父容器重排。
+     *
+     * @returns 尺寸是否变化（决定 `__afterStateMerge` 是否需要请求重排）
+     */
+    protected __beforeStateMerge(newState: any): boolean;
+    /** `setState` 的**后置**钩子：尺寸变化时请求父容器重排（合并到下一帧，见 `ICEGroup.requestLayout`）。 */
+    protected __afterStateMerge(sizeChanged: boolean): void;
+    set dirty(flag: boolean);
+    get dirty(): boolean;
+    set paramsDirty(flag: boolean);
+    get paramsDirty(): boolean;
+    /**
+     * 相对于父组件的坐标系和原点。
+     * @param left
+     * @param top
+     * @param evt
+     */
+    setPosition(left: number, top: number, evt?: any): void;
+    /**
+     * 在全局空间(canvas)中移动指定的位移。
+     * 注意：此方法用于直接设置组件在全局空间中的位移，而不是相对于其它坐标系。
+     * @param tx
+     * @param ty
+     * @param evt
+     */
+    moveGlobalPosition(tx: number, ty: number, evt?: any): void;
+    /**
+     * 直接设置在全局空间 (canvas) 中的位置。
+     * 注意：此方法用于直接设置组件在全局空间中的位置，而不是相对于其它坐标系。
+     * @param left
+     * @param top
+     * @param evt
+     */
+    setGlobalPosition(left: number, top: number, evt?: any): void;
+    /**
+     * 在全局空间(canvas)中旋转指定的角度。
+     * 注意：此方法用于直接设置组件在全局空间中的旋转角，而不是相对于其它坐标系。
+     * @param rotateAngle
+     */
+    setGlobalRotate(rotateAngle: any): void;
+    /**
+     * 组件局部坐标系中的点转换成全局空间(canvas)中的点，包含移动原点的操作。
+     * @param localX
+     * @param localY
+     * @returns
+     */
+    localToGlobal(localX: number, localY: number): number[];
+    /**
+     * 全局空间(canvas)中的点转换成组件局部坐标系中的点，包含移动原点的操作。
+     * @param globalX
+     * @param globalY
+     * @returns
+     */
+    globalToLocal(globalX: number, globalY: number): number[];
+    /**
+     * @method getRotateAngle 获取组件的旋转角度。
+     * 根据变换矩阵计算组件在全局空间(canvas)中的旋转角度。
+     * @param refresh 如果为 true ，则重新计算变换矩阵，否则使用缓存的变换矩阵。
+     * @returns
+     */
+    getRotateAngle(refresh?: boolean): number;
+    /**
+     * @method getLocalLeftTop 得到组件在局部坐标系中的左上角坐标。
+     * @param refresh 如果为 true ，则重新计算变换矩阵，否则使用缓存的变换矩阵。
+     * @returns
+     */
+    getLocalLeftTop(refresh?: boolean): {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * @internal 渲染器专用：render 结束后的 ctx 泄漏属性归位（组件自包含，见顶部 LEAKY_CTX_PROPS）。
+     * 仅当本组件确实写过了某个泄漏属性时才归位，避免无谓的每帧属性写入。
+     */
+    __resetLeakyCtxState(): void;
+    private __leakyIndex;
+    /**
+     * @internal 渲染器专用：用「当前的 composedMatrix + __localBox() + localOrigin」计算世界轴对齐
+     * 包围盒 [minX, minY, maxX, maxY]，零分配（手动 4 角变换，不复用 vec2 以免每帧分配）。
+     * 前置条件：调用方已保证 composedMatrix 新鲜（render 之后 / composeMatrix 之后）。
+     */
+    __paintWorldBox(out?: any): number[];
+    containsPoint(x: number, y: number): boolean;
+    /**
+     * 判断本地坐标（以组件 origin 为原点的空间）的点是否位于图元内部。
+     * 默认用最小包围盒（AABB），子类可覆盖为精确形状判定。
+     * @param localX
+     * @param localY
+     */
+    protected containsLocalPoint(localX: number, localY: number): boolean;
+    /**
+     * @method destory
+     * 销毁组件
+     * - FIXME:立即停止组件上的所有动画效果
+     * - 需要清理绑定的事件
+     * - 带有子节点的组件需要先销毁子节点，然后再销毁自身。
+     * - 子类需要覆盖此方法，释放自己占有的资源。
+     */
+    /**
+     * `destory()` 的拼写修正别名。
+     * 历史 API 拼写为 `destory`（已对外发布，不能直接改名），这里提供正确拼写作为等价入口。
+     */
+    destroy(): void;
+    destory(): void;
+}
+export default ICEComponent;