@tmagic/stage 1.2.13 → 1.2.14

package/dist/tmagic-stage.umd.cjs

@@ -4,14 +4,6 @@
   (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.TMagicStage = {}, global.EventEmitter, global.KeyController, global.lodashEs, global.core, global.utils, global.MoveableHelper, global.Moveable, global.Guides));
 })(this, (function (exports, EventEmitter, KeyController, lodashEs, core, utils, MoveableHelper, Moveable, Guides) { 'use strict';
 
-  const _interopDefaultLegacy = e => e && typeof e === 'object' && 'default' in e ? e : { default: e };
-
-  const EventEmitter__default = /*#__PURE__*/_interopDefaultLegacy(EventEmitter);
-  const KeyController__default = /*#__PURE__*/_interopDefaultLegacy(KeyController);
-  const MoveableHelper__default = /*#__PURE__*/_interopDefaultLegacy(MoveableHelper);
-  const Moveable__default = /*#__PURE__*/_interopDefaultLegacy(Moveable);
-  const Guides__default = /*#__PURE__*/_interopDefaultLegacy(Guides);
-
   const GHOST_EL_ID_PREFIX = "ghost_el_";
   const DRAG_EL_ID_PREFIX = "drag_el_";
   const HIGHLIGHT_EL_ID_PREFIX = "highlight_el_";
@@ -294,19 +286,28 @@
   }
 
   class DragResizeHelper {
+    /** 目标节点在蒙层上的占位节点，用于跟鼠标交互，避免鼠标事件直接作用到目标节点 */
     targetShadow;
+    /** 要操作的原始目标节点 */
     target;
+    /** 多选:目标节点组 */
     targetList = [];
+    /** 响应拖拽的状态事件，修改绝对定位布局下targetShadow的dom。
+     * MoveableHelper里面的方法是成员属性，如果DragResizeHelper用继承的方式将无法通过super去调这些方法 */
     moveableHelper;
+    /** 流式布局下，目标节点的镜像节点 */
     ghostEl;
+    /** 用于记录节点被改变前的位置 */
     frameSnapShot = {
       left: 0,
       top: 0
     };
+    /** 多选模式下的多个节点 */
     framesSnapShot = [];
+    /** 布局方式：流式布局、绝对定位、固定定位 */
     mode = Mode.ABSOLUTE;
     constructor(config) {
-      this.moveableHelper = MoveableHelper__default.default.create({
+      this.moveableHelper = MoveableHelper.create({
         useBeforeRender: true,
         useRender: false,
         createAuto: true
@@ -337,6 +338,10 @@
     setMode(mode) {
       this.mode = mode;
     }
+    /**
+     * 改变大小事件开始
+     * @param e 包含了拖拽节点的dom，moveableHelper会直接修改拖拽节点
+     */
     onResizeStart(e) {
       this.moveableHelper.onResizeStart(e);
       this.frameSnapShot.top = this.target.offsetTop;
@@ -425,6 +430,9 @@
       this.moveableHelper.onResizeGroupStart(e);
       this.setFramesSnapShot(events);
     }
+    /**
+     * 多选状态下通过拖拽边框改变大小，所有选中组件会一起改变大小
+     */
     onResizeGroup(e) {
       const { events } = e;
       events.forEach((ev) => {
@@ -498,6 +506,9 @@
       }
       return { width, height, left, top };
     }
+    /**
+     * 多选状态设置多个节点的快照
+     */
     setFramesSnapShot(events) {
       if (this.framesSnapShot.length > 0)
         return;
@@ -514,6 +525,9 @@
         });
       });
     }
+    /**
+     * 流式布局把目标节点复制一份进行拖拽，在拖拽结束前不影响页面原布局样式
+     */
     generateGhostEl(el) {
       if (this.ghostEl) {
         this.destroyGhostEl();
@@ -627,7 +641,7 @@
             "button",
             {
               className: "moveable-button",
-              title: "\u9009\u4E2D\u7236\u7EC4\u4EF6",
+              title: "选中父组件",
               onClick: () => {
                 handler(AbleActionEventType.SELECT_PARENT);
               }
@@ -656,7 +670,7 @@
           ),
           React.createElement("button", {
             className: "moveable-button moveable-remove-button",
-            title: "\u5220\u9664",
+            title: "删除",
             onClick: () => {
               handler(AbleActionEventType.REMOVE);
             }
@@ -666,13 +680,20 @@
     }
   });
 
-  class MoveableOptionsManager extends EventEmitter__default.default {
+  class MoveableOptionsManager extends EventEmitter {
+    /** 布局方式：流式布局、绝对定位、固定定位 */
     mode = Mode.ABSOLUTE;
+    /** 画布容器 */
     container;
+    /** 水平参考线 */
     horizontalGuidelines = [];
+    /** 垂直参考线 */
     verticalGuidelines = [];
+    /** 对齐元素集合 */
     elementGuidelines = [];
+    /** 由外部调用方（编辑器）传入进来的moveable默认参数，可以为空，也可以是一个回调函数 */
     customizedOptions;
+    /** 获取整个画布的根元素（在StageCore的mount函数中挂载的container） */
     getRootContainer;
     constructor(config) {
       super();
@@ -680,6 +701,11 @@
       this.container = config.container;
       this.getRootContainer = config.getRootContainer;
     }
+    /**
+     * 设置水平/垂直参考线
+     * @param type 参考线类型
+     * @param guidelines 参考线坐标数组
+     */
     setGuidelines(type, guidelines) {
       if (type === GuidesType.HORIZONTAL) {
         this.horizontalGuidelines = guidelines;
@@ -688,11 +714,19 @@
       }
       this.emit("update-moveable");
     }
+    /**
+     * 清除横向和纵向的参考线
+     */
     clearGuides() {
       this.horizontalGuidelines = [];
       this.verticalGuidelines = [];
       this.emit("update-moveable");
     }
+    /**
+     * 设置有哪些元素要辅助对齐
+     * @param selectedElList 选中的元素列表，需要排除在对齐元素之外
+     * @param allElList 全部元素列表
+     */
     setElementGuidelines(selectedElList, allElList) {
       this.elementGuidelines.forEach((node) => {
         node.remove();
@@ -702,11 +736,21 @@
         this.container.append(this.createGuidelineElements(selectedElList, allElList));
       }
     }
+    /**
+     * 获取moveable参数
+     * @param isMultiSelect 是否多选模式
+     * @param runtimeOptions 调用时实时传进来的的moveable参数
+     * @returns moveable所需参数
+     */
     getOptions(isMultiSelect, runtimeOptions = {}) {
       const defaultOptions = this.getDefaultOptions(isMultiSelect);
       const customizedOptions = this.getCustomizeOptions();
       return lodashEs.merge(defaultOptions, customizedOptions, runtimeOptions);
     }
+    /**
+     * 获取单选和多选的moveable公共参数
+     * @returns moveable公共参数
+     */
     getDefaultOptions(isMultiSelect) {
       const isSortable = this.mode === Mode.SORTABLE;
       const commonOptions = {
@@ -721,6 +765,7 @@
         elementGuidelines: this.elementGuidelines,
         bounds: {
           top: 0,
+          // 设置0的话无法移动到left为0，所以只能设置为-1
           left: -1,
           right: this.container.clientWidth - 1,
           bottom: isSortable ? void 0 : this.container.clientHeight
@@ -729,6 +774,10 @@
       const differenceOptions = isMultiSelect ? this.getMultiOptions() : this.getSingleOptions();
       return lodashEs.merge(commonOptions, differenceOptions);
     }
+    /**
+     * 获取单选下的差异化参数
+     * @returns {MoveableOptions} moveable options参数
+     */
     getSingleOptions() {
       const isAbsolute = this.mode === Mode.ABSOLUTE;
       const isFixed = this.mode === Mode.FIXED;
@@ -762,6 +811,10 @@
         ables: [MoveableActionsAble(this.actionHandler.bind(this))]
       };
     }
+    /**
+     * 获取多选下的差异化参数
+     * @returns {MoveableOptions} moveable options参数
+     */
     getMultiOptions() {
       return {
         defaultGroupRotate: 0,
@@ -772,15 +825,27 @@
         padding: { left: 0, top: 0, right: 0, bottom: 0 }
       };
     }
+    /**
+     * 获取业务方自定义的moveable参数
+     */
     getCustomizeOptions() {
       if (typeof this.customizedOptions === "function") {
         return this.customizedOptions();
       }
       return this.customizedOptions;
     }
+    /**
+     * 这是给selectParentAbles的回调函数，用于触发选中父元素事件
+     */
     actionHandler(type) {
       this.emit(type);
     }
+    /**
+     * 为需要辅助对齐的元素创建div
+     * @param selectedElList 选中的元素列表，需要排除在对齐元素之外
+     * @param allElList 全部元素列表
+     * @returns frame 辅助对齐元素集合的页面片
+     */
     createGuidelineElements(selectedElList, allElList) {
       const frame = globalThis.document.createDocumentFragment();
       for (const node of allElList) {
@@ -795,6 +860,12 @@
       }
       return frame;
     }
+    /**
+     * 判断一个元素是否在元素列表里面
+     * @param ele 元素
+     * @param eleList 元素列表
+     * @returns 是否在元素列表里面
+     */
     isInElementList(ele, eleList) {
       for (const eleItem of eleList) {
         if (ele === eleItem)
@@ -805,8 +876,11 @@
   }
 
   class StageDragResize extends MoveableOptionsManager {
+    /** 目标节点 */
     target;
+    /** Moveable拖拽类实例 */
     moveable;
+    /** 拖动状态 */
     dragStatus = StageDragStatus.END;
     dragResizeHelper;
     disabledDragStart;
@@ -829,6 +903,12 @@
     getTarget() {
       return this.target;
     }
+    /**
+     * 将选中框渲染并覆盖到选中的组件Dom节点上方
+     * 当选中的节点不是absolute时，会创建一个新的节点出来作为拖拽目标
+     * @param el 选中组件的Dom节点元素
+     * @param event 鼠标事件
+     */
     select(el, event) {
       if (!this.moveable || el !== this.target) {
         this.initMoveable(el);
@@ -839,11 +919,14 @@
         this.moveable?.dragStart(event);
       }
     }
+    /**
+     * 初始化选中框并渲染出来
+     */
     updateMoveable(el = this.target) {
       if (!this.moveable)
         return;
       if (!el)
-        throw new Error("\u672A\u9009\u4E2D\u4EFB\u4F55\u8282\u70B9");
+        throw new Error("未选中任何节点");
       const options = this.init(el);
       Object.entries(options).forEach(([key, value]) => {
         this.moveable[key] = value;
@@ -857,6 +940,9 @@
       this.moveable.target = null;
       this.moveable.updateTarget();
     }
+    /**
+     * 销毁实例
+     */
     destroy() {
       this.moveable?.destroy();
       this.dragResizeHelper.destroy();
@@ -881,7 +967,7 @@
       const options = this.init(el);
       this.dragResizeHelper.clear();
       this.moveable?.destroy();
-      this.moveable = new Moveable__default.default(this.container, {
+      this.moveable = new Moveable(this.container, {
         ...options
       });
       this.bindResizeEvent();
@@ -891,7 +977,7 @@
     }
     bindResizeEvent() {
       if (!this.moveable)
-        throw new Error("moveable \u672A\u521D\u59CB\u5316");
+        throw new Error("moveable 未初始化");
       this.moveable.on("resizeStart", (e) => {
         if (!this.target)
           return;
@@ -909,11 +995,11 @@
     }
     bindDragEvent() {
       if (!this.moveable)
-        throw new Error("moveable \u672A\u521D\u59CB\u5316");
+        throw new Error("moveable 未初始化");
       let timeout;
       this.moveable.on("dragStart", (e) => {
         if (!this.target)
-          throw new Error("\u672A\u9009\u4E2D\u7EC4\u4EF6");
+          throw new Error("未选中组件");
         this.dragStatus = StageDragStatus.START;
         this.dragResizeHelper.onDragStart(e);
       }).on("drag", (e) => {
@@ -951,7 +1037,7 @@
     }
     bindRotateEvent() {
       if (!this.moveable)
-        throw new Error("moveable \u672A\u521D\u59CB\u5316");
+        throw new Error("moveable 未初始化");
       this.moveable.on("rotateStart", (e) => {
         this.dragStatus = StageDragStatus.START;
         this.dragResizeHelper.onRotateStart(e);
@@ -977,7 +1063,7 @@
     }
     bindScaleEvent() {
       if (!this.moveable)
-        throw new Error("moveable \u672A\u521D\u59CB\u5316");
+        throw new Error("moveable 未初始化");
       this.moveable.on("scaleStart", (e) => {
         this.dragStatus = StageDragStatus.START;
         this.dragResizeHelper.onScaleStart(e);
@@ -1003,7 +1089,7 @@
     }
     sort() {
       if (!this.target || !this.dragResizeHelper.getGhostEl())
-        throw new Error("\u672A\u77E5\u9519\u8BEF");
+        throw new Error("未知错误");
       const { top } = this.dragResizeHelper.getGhostEl().getBoundingClientRect();
       const { top: oriTop } = this.target.getBoundingClientRect();
       const deltaTop = top - oriTop;
@@ -1056,18 +1142,25 @@
         idPrefix: HIGHLIGHT_EL_ID_PREFIX
       });
     }
+    /**
+     * 高亮鼠标悬停的组件
+     * @param el 选中组件的Dom节点元素
+     */
     highlight(el) {
       if (!el || el === this.target)
         return;
       this.target = el;
       this.moveable?.destroy();
-      this.moveable = new Moveable__default.default(this.container, {
+      this.moveable = new Moveable(this.container, {
         target: this.targetShadow.update(el),
         origin: false,
         rootContainer: this.getRootContainer(),
         zoom: 2
       });
     }
+    /**
+     * 清空高亮
+     */
     clearHighlight() {
       if (!this.moveable || !this.target)
         return;
@@ -1075,6 +1168,9 @@
       this.moveable.target = null;
       this.moveable.updateTarget();
     }
+    /**
+     * 销毁实例
+     */
     destroy() {
       this.moveable?.destroy();
       this.targetShadow.destroy();
@@ -1082,8 +1178,11 @@
   }
 
   class StageMultiDragResize extends MoveableOptionsManager {
+    /** 画布容器 */
     container;
+    /** 多选:目标节点组 */
     targetList = [];
+    /** Moveable多选拖拽类实例 */
     moveableForMulti;
     dragStatus = StageDragStatus.END;
     dragResizeHelper;
@@ -1108,6 +1207,10 @@
         }
       });
     }
+    /**
+     * 多选
+     * @param els
+     */
     multiSelect(els) {
       if (els.length === 0) {
         return;
@@ -1119,7 +1222,7 @@
       this.setElementGuidelines(this.targetList, elementGuidelines);
       this.moveableForMulti?.destroy();
       this.dragResizeHelper.clear();
-      this.moveableForMulti = new Moveable__default.default(
+      this.moveableForMulti = new Moveable(
         this.container,
         this.getOptions(true, {
           target: this.dragResizeHelper.getShadowEls()
@@ -1177,7 +1280,7 @@
       if (!this.moveableForMulti)
         return;
       if (!eleList)
-        throw new Error("\u672A\u9009\u4E2D\u4EFB\u4F55\u8282\u70B9");
+        throw new Error("未选中任何节点");
       this.targetList = eleList;
       this.dragResizeHelper.setTargetList(eleList);
       const options = this.getOptions(true, {
@@ -1188,6 +1291,9 @@
       });
       this.moveableForMulti.updateTarget();
     }
+    /**
+     * 清除多选状态
+     */
     clearSelectStatus() {
       if (!this.moveableForMulti)
         return;
@@ -1196,10 +1302,17 @@
       this.moveableForMulti.updateTarget();
       this.targetList = [];
     }
+    /**
+     * 销毁实例
+     */
     destroy() {
       this.moveableForMulti?.destroy();
       this.dragResizeHelper.destroy();
     }
+    /**
+     * 拖拽完成后将更新的位置信息暴露给上层业务方，业务方可以接收事件进行保存
+     * @param isResize 是否进行大小缩放
+     */
     update(isResize = false, parentEl = null) {
       if (this.targetList.length === 0)
         return;
@@ -1219,17 +1332,25 @@
 
   const throttleTime = 100;
   const defaultContainerHighlightDuration = 800;
-  class ActionManager extends EventEmitter__default.default {
+  class ActionManager extends EventEmitter {
     dr;
     multiDr;
     highlightLayer;
+    /** 单选、多选、高亮的容器（蒙层的content） */
     container;
+    /** 当前选中的节点 */
     selectedEl;
+    /** 多选选中的节点组 */
     selectedElList = [];
+    /** 当前高亮的节点 */
     highlightedEl;
+    /** 当前是否处于多选状态 */
     isMultiSelectStatus = false;
+    /** 当拖拽组件到容器上方进入可加入容器状态时，给容器添加的一个class名称 */
     containerHighlightClassName;
+    /** 当拖拽组件到容器上方时，需要悬停多久才能将组件加入容器 */
     containerHighlightDuration;
+    /** 将组件加入容器的操作方式 */
     containerHighlightType;
     isAltKeydown = false;
     getTargetElement;
@@ -1288,18 +1409,33 @@
       this.initKeyEvent();
       this.initActionEvent();
     }
+    /**
+     * 设置水平/垂直参考线
+     * @param type 参考线类型
+     * @param guidelines 参考线坐标数组
+     */
     setGuidelines(type, guidelines) {
       this.dr.setGuidelines(type, guidelines);
       this.multiDr.setGuidelines(type, guidelines);
     }
+    /**
+     * 清空所有参考线
+     */
     clearGuides() {
       this.dr.clearGuides();
       this.multiDr.clearGuides();
     }
+    /**
+     * 更新moveable，外部主要调用场景是元素配置变更、页面大小变更
+     * @param el 变更的元素
+     */
     updateMoveable(el) {
       this.dr.updateMoveable(el);
       this.multiDr.updateMoveable();
     }
+    /**
+     * 判断是否单选选中的元素
+     */
     isSelectedEl(el) {
       return el.id === this.selectedEl?.id;
     }
@@ -1312,6 +1448,11 @@
     getSelectedElList() {
       return this.selectedElList;
     }
+    /**
+     * 获取鼠标下方第一个可选中元素，如果元素层叠，返回到是最上层元素
+     * @param event 鼠标事件
+     * @returns 鼠标下方第一个可选中元素
+     */
     async getElementFromPoint(event) {
       const els = this.getElementsFromPoint(event);
       let stopped = false;
@@ -1324,6 +1465,13 @@
         }
       }
     }
+    /**
+     * 判断一个元素能否在当前场景被选中
+     * @param el 被判断的元素
+     * @param event 鼠标事件
+     * @param stop 通过该元素如果得知剩下的元素都不可被选中，通知调用方终止对剩下元素的判断
+     * @returns 能否选中
+     */
     async isElCanSelect(el, event, stop) {
       const canSelectByProp = await this.canSelect(el, event, stop);
       if (!canSelectByProp)
@@ -1333,6 +1481,9 @@
       }
       return true;
     }
+    /**
+     * 判断一个元素是否可以被多选，如果当前元素是page，则调stop函数告诉调用方不必继续判断其它元素了
+     */
     canMultiSelect(el, stop) {
       if (el.className.includes(PAGE_CLASS)) {
         stop();
@@ -1382,6 +1533,10 @@
       this.setHighlightEl(void 0);
       this.highlightLayer.clearHighlight();
     }
+    /**
+     * 用于在切换选择模式时清除上一次的状态
+     * @param selectType 需要清理的选择模式
+     */
     clearSelectStatus(selectType) {
       if (selectType === SelectStatus.MULTI_SELECT) {
         this.multiDr.clearSelectStatus();
@@ -1390,6 +1545,11 @@
         this.dr.clearSelectStatus();
       }
     }
+    /**
+     * 找到鼠标下方的容器，通过添加className对容器进行标记
+     * @param event 鼠标事件
+     * @param excludeElList 计算鼠标点所在容器时要排除的元素列表
+     */
     async addContainerHighlightClassName(event, excludeElList) {
       const doc = this.getRenderDocument();
       if (!doc)
@@ -1402,6 +1562,13 @@
         }
       }
     }
+    /**
+     * 鼠标拖拽着元素，在容器上方悬停，延迟一段时间后，对容器进行标记，如果悬停时间够长将标记成功，悬停时间短，调用方通过返回的timeoutId取消标记
+     * 标记的作用：1、高亮容器，给用户一个加入容器的交互感知；2、释放鼠标后，通过标记的标志找到要加入的容器
+     * @param event 鼠标事件
+     * @param excludeElList 计算鼠标所在容器时要排除的元素列表
+     * @returns timeoutId，调用方在鼠标移走时要取消该timeout，阻止标记
+     */
     delayedMarkContainer(event, excludeElList = []) {
       if (this.canAddToContainer()) {
         return globalThis.setTimeout(() => {
@@ -1433,6 +1600,11 @@
       }
       return options;
     }
+    /**
+     * 在执行多选逻辑前，先准备好多选选中元素
+     * @param el 新选中的元素
+     * @returns 多选选中的元素列表
+     */
     async beforeMultiSelect(event) {
       const el = await this.getElementFromPoint(event);
       if (!el)
@@ -1448,9 +1620,16 @@
         this.selectedElList.push(el);
       }
     }
+    /**
+     * 当前状态下能否将组件加入容器，默认是鼠标悬停一段时间加入，alt模式则是按住alt+鼠标悬停一段时间加入
+     */
     canAddToContainer() {
       return this.containerHighlightType === ContainerHighlightType.DEFAULT || this.containerHighlightType === ContainerHighlightType.ALT && this.isAltKeydown;
     }
+    /**
+     * 结束对container的标记状态
+     * @returns 标记的容器元素，没有标记的容器时返回null
+     */
     markContainerEnd() {
       const doc = this.getRenderDocument();
       if (doc && this.canAddToContainer()) {
@@ -1464,30 +1643,36 @@
       this.container.addEventListener("mouseleave", this.mouseLeaveHandler);
       this.container.addEventListener("wheel", this.mouseWheelHandler);
     }
+    /**
+     * 初始化键盘事件监听
+     */
     initKeyEvent() {
       const { isMac } = new core.Env();
       const ctrl = isMac ? "meta" : "ctrl";
-      KeyController__default.default.global.keydown(ctrl, (e) => {
+      KeyController.global.keydown(ctrl, (e) => {
         e.inputEvent.preventDefault();
         this.isMultiSelectStatus = true;
       });
-      KeyController__default.default.global.on("blur", () => {
+      KeyController.global.on("blur", () => {
         this.isMultiSelectStatus = false;
       });
-      KeyController__default.default.global.keyup(ctrl, (e) => {
+      KeyController.global.keyup(ctrl, (e) => {
         e.inputEvent.preventDefault();
         this.isMultiSelectStatus = false;
       });
-      KeyController__default.default.global.keydown("alt", (e) => {
+      KeyController.global.keydown("alt", (e) => {
         e.inputEvent.preventDefault();
         this.isAltKeydown = true;
       });
-      KeyController__default.default.global.keyup("alt", (e) => {
+      KeyController.global.keyup("alt", (e) => {
         e.inputEvent.preventDefault();
         this.markContainerEnd();
         this.isAltKeydown = false;
       });
     }
+    /**
+     * 处理单选、多选抛出来的事件
+     */
     initActionEvent() {
       this.dr.on("update", (data) => {
         setTimeout(() => this.emit("update", data));
@@ -1513,6 +1698,9 @@
         this.emit("change-to-select", el);
       });
     }
+    /**
+     * 在down事件中集中cpu处理画布中选中操作渲染，在up事件中再通知外面的编辑器更新
+     */
     mouseDownHandler = async (event) => {
       this.clearHighlight();
       event.stopImmediatePropagation();
@@ -1547,6 +1735,9 @@
       }
       return false;
     }
+    /**
+     * 在up事件中负责对外通知选中事件，通知画布之外的编辑器更新
+     */
     mouseUpHandler = () => {
       utils.getDocument().removeEventListener("mouseup", this.mouseUpHandler);
       this.container.addEventListener("mousemove", this.mouseMoveHandler);
@@ -1564,7 +1755,7 @@
     };
   }
 
-  class Rule extends EventEmitter__default.default {
+  class Rule extends EventEmitter {
     hGuides;
     vGuides;
     horizontalGuidelines = [];
@@ -1585,6 +1776,10 @@
       });
       this.containerResizeObserver.observe(this.container);
     }
+    /**
+     * 是否显示辅助线
+     * @param isShowGuides 是否显示
+     */
     showGuides(isShowGuides = true) {
       this.isShowGuides = isShowGuides;
       this.hGuides.setState({
@@ -1612,9 +1807,16 @@
         guides: vLines
       });
     }
+    /**
+     * 清空所有参考线
+     */
     clearGuides() {
       this.setGuides([[], []]);
     }
+    /**
+     * 是否显示标尺
+     * @param show 是否显示
+     */
     showRule(show = true) {
       if (show) {
         this.hGuides.destroy();
@@ -1654,7 +1856,7 @@
       width: type === GuidesType.HORIZONTAL ? "100%" : "30px",
       height: type === GuidesType.HORIZONTAL ? "30px" : "100%"
     });
-    createGuides = (type, defaultGuides = []) => new Guides__default.default(this.container, {
+    createGuides = (type, defaultGuides = []) => new Guides(this.container, {
       type,
       defaultGuides,
       displayDragPos: true,
@@ -1744,6 +1946,11 @@
         this.content.style.height = `${this.height}px`;
       }
     }
+    /**
+     * 初始化视窗和蒙层监听，监听元素是否在视窗区域、监听mask蒙层所在的wrapper大小变化
+     * @description 初始化视窗和蒙层监听
+     * @param page 页面Dom节点
+     */
     observe(page) {
       if (!page)
         return;
@@ -1751,6 +1958,10 @@
       this.initObserverIntersection();
       this.initObserverWrapper();
     }
+    /**
+     * 处理页面大小变更，同步页面和mask大小
+     * @param entries ResizeObserverEntry，获取页面最新大小
+     */
     pageResize(entries) {
       const [entry] = entries;
       const { clientHeight, clientWidth } = entry.target;
@@ -1758,12 +1969,20 @@
       this.setWidth(clientWidth);
       this.scroll();
     }
+    /**
+     * 监听一个组件是否在画布可视区域内
+     * @param el 被选中的组件，可能是左侧目录树中选中的
+     */
     observerIntersection(el) {
       this.intersectionObserver?.observe(el);
     }
+    /**
+     * 挂载Dom节点
+     * @param el 将蒙层挂载到该Dom节点上
+     */
     mount(el) {
       if (!this.content)
-        throw new Error("content \u4E0D\u5B58\u5728");
+        throw new Error("content 不存在");
       el.appendChild(this.wrapper);
     }
     setLayout(el) {
@@ -1777,6 +1996,9 @@
       this.scrollTop = this.pageScrollParent.scrollTop;
       this.scroll();
     }
+    /**
+     * 销毁实例
+     */
     destroy() {
       this.content?.remove();
       this.page = null;
@@ -1784,6 +2006,9 @@
       this.wrapperResizeObserver?.disconnect();
       super.destroy();
     }
+    /**
+     * 监听选中元素是否在画布可视区域内，如果目标元素不在可视区域内，通过滚动使该元素出现在可视区域
+     */
     initObserverIntersection() {
       this.pageScrollParent = getScrollParent(this.page) || null;
       this.intersectionObserver?.disconnect();
@@ -1806,6 +2031,9 @@
         );
       }
     }
+    /**
+     * 监听mask的容器大小变化
+     */
     initObserverWrapper() {
       this.wrapperResizeObserver?.disconnect();
       if (typeof ResizeObserver !== "undefined") {
@@ -1846,22 +2074,40 @@
       });
       this.content.dispatchEvent(event);
     }
+    /**
+     * 设置蒙层高度
+     * @param height 高度
+     */
     setHeight(height) {
       this.height = height;
       this.setMaxScrollTop();
       this.content.style.height = `${height}px`;
     }
+    /**
+     * 设置蒙层宽度
+     * @param width 宽度
+     */
     setWidth(width) {
       this.width = width;
       this.setMaxScrollLeft();
       this.content.style.width = `${width}px`;
     }
+    /**
+     * 计算并设置最大滚动宽度
+     */
     setMaxScrollLeft() {
       this.maxScrollLeft = Math.max(this.width - this.wrapperWidth, 0);
     }
+    /**
+     * 计算并设置最大滚动高度
+     */
     setMaxScrollTop() {
       this.maxScrollTop = Math.max(this.height - this.wrapperHeight, 0);
     }
+    /**
+     * 修复滚动距离
+     * 由于滚动容器变化等因素，会导致当前滚动的距离不正确
+     */
     fixScrollValue() {
       if (this.scrollTop < 0)
         this.scrollTop = 0;
@@ -1874,7 +2120,7 @@
     }
     mouseWheelHandler = (event) => {
       if (!this.page)
-        throw new Error("page \u672A\u521D\u59CB\u5316");
+        throw new Error("page 未初始化");
       const { deltaY, deltaX } = event;
       if (this.page.clientHeight < this.wrapperHeight && deltaY)
         return;
@@ -1894,6 +2140,7 @@
   const style = ".tmagic-stage-container-highlight::after {\n  content: '';\n  position: absolute;\n  width: 100%;\n  height: 100%;\n  top: 0;\n  left: 0;\n  background-color: #000;\n  opacity: .1;\n  pointer-events: none;\n}\n\n.magic-ui-container.magic-layout-relative {\n  min-height: 50px;\n}\n";
 
   class StageRender extends EventEmitter.EventEmitter {
+    /** 组件的js、css执行的环境，直接渲染为当前window，iframe渲染则为iframe.contentWindow */
     contentWindow = null;
     runtime = null;
     iframe;
@@ -1947,9 +2194,13 @@
     setZoom(zoom = DEFAULT_ZOOM) {
       this.zoom = zoom;
     }
+    /**
+     * 挂载Dom节点
+     * @param el 将页面挂载到该Dom节点上
+     */
     async mount(el) {
       if (!this.iframe) {
-        throw Error("mount \u5931\u8D25");
+        throw Error("mount 失败");
       }
       if (!utils.isSameDomain(this.runtimeUrl) && this.runtimeUrl) {
         let html = await fetch(this.runtimeUrl).then((res) => res.text());
@@ -1975,6 +2226,11 @@
     getDocument() {
       return this.contentWindow?.document;
     }
+    /**
+     * 通过坐标获得坐标下所有HTML元素数组
+     * @param point 坐标
+     * @returns 坐标下方所有HTML元素数组，会包含父元素直至html，元素层叠时返回顺序是从上到下
+     */
     getElementsFromPoint(point) {
       let x = point.clientX;
       let y = point.clientY;
@@ -1991,11 +2247,14 @@
       if (typeof idOrEl === "string" || typeof idOrEl === "number") {
         const el = this.getDocument()?.getElementById(`${idOrEl}`);
         if (!el)
-          throw new Error(`\u4E0D\u5B58\u5728ID\u4E3A${idOrEl}\u7684\u5143\u7D20`);
+          throw new Error(`不存在ID为${idOrEl}的元素`);
         return el;
       }
       return idOrEl;
     }
+    /**
+     * 销毁实例
+     */
     destroy() {
       this.iframe?.removeEventListener("load", this.loadHandler);
       this.contentWindow = null;
@@ -2003,6 +2262,10 @@
       this.iframe = void 0;
       this.removeAllListeners();
     }
+    /**
+     * 在runtime中对被选中的元素进行标记，部分组件有对选中态进行特殊显示的需求
+     * @param el 被选中的元素
+     */
     flagSelectedEl(el) {
       const doc = this.getDocument();
       if (doc) {
@@ -2065,6 +2328,10 @@
       this.initActionEvent();
       this.initMaskEvent();
     }
+    /**
+     * 单选选中元素
+     * @param idOrEl 选中的id或者元素
+     */
     async select(idOrEl, event) {
       const el = this.renderer.getTargetElement(idOrEl);
       if (el === this.actionManager.getSelectedEl())
@@ -2076,6 +2343,10 @@
         this.mask.observerIntersection(el);
       }
     }
+    /**
+     * 多选选中多个元素
+     * @param idOrElList 选中元素的id或元素列表
+     */
     async multiSelect(idOrElList) {
       const els = idOrElList.map((idOrEl) => this.renderer.getTargetElement(idOrEl));
       if (els.length === 0)
@@ -2089,9 +2360,17 @@
         this.mask.observerIntersection(lastEl);
       }
     }
+    /**
+     * 高亮选中元素
+     * @param el 要高亮的元素
+     */
     highlight(idOrEl) {
       this.actionManager.highlight(idOrEl);
     }
+    /**
+     * 更新组件
+     * @param data 更新组件的数据
+     */
     async update(data) {
       const { config } = data;
       await this.renderer.update(data);
@@ -2104,15 +2383,27 @@
         }
       });
     }
+    /**
+     * 往画布增加一个组件
+     * @param data 组件信息数据
+     */
     async add(data) {
       return await this.renderer.add(data);
     }
+    /**
+     * 从画布删除一个组件
+     * @param data 组件信息数据
+     */
     async remove(data) {
       return await this.renderer.remove(data);
     }
     setZoom(zoom = DEFAULT_ZOOM) {
       this.renderer.setZoom(zoom);
     }
+    /**
+     * 挂载Dom节点
+     * @param el 将stage挂载到该Dom节点上
+     */
     async mount(el) {
       this.container = el;
       const { mask, renderer } = this;
@@ -2120,16 +2411,32 @@
       mask.mount(el);
       this.emit("mounted");
     }
+    /**
+     * 清空所有参考线
+     */
     clearGuides() {
       this.mask.clearGuides();
       this.actionManager.clearGuides();
     }
+    /**
+     * @deprecated 废弃接口，建议用delayedMarkContainer代替
+     */
     getAddContainerHighlightClassNameTimeout(event, excludeElList = []) {
       return this.delayedMarkContainer(event, excludeElList);
     }
+    /**
+     * 鼠标拖拽着元素，在容器上方悬停，延迟一段时间后，对容器进行标记，如果悬停时间够长将标记成功，悬停时间短，调用方通过返回的timeoutId取消标记
+     * 标记的作用：1、高亮容器，给用户一个加入容器的交互感知；2、释放鼠标后，通过标记的标志找到要加入的容器
+     * @param event 鼠标事件
+     * @param excludeElList 计算鼠标所在容器时要排除的元素列表
+     * @returns timeoutId，调用方在鼠标移走时要取消该timeout，阻止标记
+     */
     delayedMarkContainer(event, excludeElList = []) {
       return this.actionManager.delayedMarkContainer(event, excludeElList);
     }
+    /**
+     * 销毁实例
+     */
     destroy() {
       const { mask, renderer, actionManager, pageResizeObserver } = this;
       renderer.destroy();
@@ -2139,6 +2446,9 @@
       this.removeAllListeners();
       this.container = void 0;
     }
+    /**
+     * 监听页面大小变化
+     */
     observePageResize(page) {
       if (typeof ResizeObserver !== "undefined") {
         this.pageResizeObserver = new ResizeObserver((entries) => {
@@ -2182,12 +2492,18 @@
         this.emit("change-guides", data);
       });
     }
+    /**
+     * 初始化操作相关事件监听
+     */
     initActionEvent() {
       this.initActionManagerEvent();
       this.initDrEvent();
       this.initMulDrEvent();
       this.initHighlightEvent();
     }
+    /**
+     * 初始化ActionManager类本身抛出来的事件监听
+     */
     initActionManagerEvent() {
       this.actionManager.on("before-select", (idOrEl, event) => {
         this.select(idOrEl, event);
@@ -2199,6 +2515,9 @@
         this.emit("multi-select", selectedElList);
       });
     }
+    /**
+     * 初始化DragResize类通过ActionManager抛出来的事件监听
+     */
     initDrEvent() {
       this.actionManager.on("update", (data) => {
         this.emit("update", data);
@@ -2210,6 +2529,9 @@
         this.emit("remove", data);
       });
     }
+    /**
+     * 初始化MultiDragResize类通过ActionManager抛出来的事件监听
+     */
     initMulDrEvent() {
       this.actionManager.on("change-to-select", (el) => {
         this.select(el);
@@ -2218,6 +2540,9 @@
         this.emit("update", data);
       });
     }
+    /**
+     * 初始化Highlight类通过ActionManager抛出来的事件监听
+     */
     initHighlightEvent() {
       this.actionManager.on("highlight", async (highlightEl) => {
         this.emit("highlight", highlightEl);