@tmagic/stage 1.2.13 → 1.2.14

package/dist/tmagic-stage.js

@@ -289,16 +289,25 @@ class TargetShadow {
 }
 
 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.create({
@@ -332,6 +341,10 @@ class DragResizeHelper {
   setMode(mode) {
     this.mode = mode;
   }
+  /**
+   * 改变大小事件开始
+   * @param e 包含了拖拽节点的dom，moveableHelper会直接修改拖拽节点
+   */
   onResizeStart(e) {
     this.moveableHelper.onResizeStart(e);
     this.frameSnapShot.top = this.target.offsetTop;
@@ -420,6 +433,9 @@ class DragResizeHelper {
     this.moveableHelper.onResizeGroupStart(e);
     this.setFramesSnapShot(events);
   }
+  /**
+   * 多选状态下通过拖拽边框改变大小，所有选中组件会一起改变大小
+   */
   onResizeGroup(e) {
     const { events } = e;
     events.forEach((ev) => {
@@ -493,6 +509,9 @@ class DragResizeHelper {
     }
     return { width, height, left, top };
   }
+  /**
+   * 多选状态设置多个节点的快照
+   */
   setFramesSnapShot(events) {
     if (this.framesSnapShot.length > 0)
       return;
@@ -509,6 +528,9 @@ class DragResizeHelper {
       });
     });
   }
+  /**
+   * 流式布局把目标节点复制一份进行拖拽，在拖拽结束前不影响页面原布局样式
+   */
   generateGhostEl(el) {
     if (this.ghostEl) {
       this.destroyGhostEl();
@@ -622,7 +644,7 @@ const MoveableActionsAble = (handler) => ({
           "button",
           {
             className: "moveable-button",
-            title: "\u9009\u4E2D\u7236\u7EC4\u4EF6",
+            title: "选中父组件",
             onClick: () => {
               handler(AbleActionEventType.SELECT_PARENT);
             }
@@ -651,7 +673,7 @@ const MoveableActionsAble = (handler) => ({
         ),
         React.createElement("button", {
           className: "moveable-button moveable-remove-button",
-          title: "\u5220\u9664",
+          title: "删除",
           onClick: () => {
             handler(AbleActionEventType.REMOVE);
           }
@@ -662,12 +684,19 @@ const MoveableActionsAble = (handler) => ({
 });
 
 class MoveableOptionsManager extends EventEmitter {
+  /** 布局方式：流式布局、绝对定位、固定定位 */
   mode = Mode.ABSOLUTE;
+  /** 画布容器 */
   container;
+  /** 水平参考线 */
   horizontalGuidelines = [];
+  /** 垂直参考线 */
   verticalGuidelines = [];
+  /** 对齐元素集合 */
   elementGuidelines = [];
+  /** 由外部调用方（编辑器）传入进来的moveable默认参数，可以为空，也可以是一个回调函数 */
   customizedOptions;
+  /** 获取整个画布的根元素（在StageCore的mount函数中挂载的container） */
   getRootContainer;
   constructor(config) {
     super();
@@ -675,6 +704,11 @@ class MoveableOptionsManager extends EventEmitter {
     this.container = config.container;
     this.getRootContainer = config.getRootContainer;
   }
+  /**
+   * 设置水平/垂直参考线
+   * @param type 参考线类型
+   * @param guidelines 参考线坐标数组
+   */
   setGuidelines(type, guidelines) {
     if (type === GuidesType.HORIZONTAL) {
       this.horizontalGuidelines = guidelines;
@@ -683,11 +717,19 @@ class MoveableOptionsManager extends EventEmitter {
     }
     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();
@@ -697,11 +739,21 @@ class MoveableOptionsManager extends EventEmitter {
       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 merge(defaultOptions, customizedOptions, runtimeOptions);
   }
+  /**
+   * 获取单选和多选的moveable公共参数
+   * @returns moveable公共参数
+   */
   getDefaultOptions(isMultiSelect) {
     const isSortable = this.mode === Mode.SORTABLE;
     const commonOptions = {
@@ -716,6 +768,7 @@ class MoveableOptionsManager extends EventEmitter {
       elementGuidelines: this.elementGuidelines,
       bounds: {
         top: 0,
+        // 设置0的话无法移动到left为0，所以只能设置为-1
         left: -1,
         right: this.container.clientWidth - 1,
         bottom: isSortable ? void 0 : this.container.clientHeight
@@ -724,6 +777,10 @@ class MoveableOptionsManager extends EventEmitter {
     const differenceOptions = isMultiSelect ? this.getMultiOptions() : this.getSingleOptions();
     return merge(commonOptions, differenceOptions);
   }
+  /**
+   * 获取单选下的差异化参数
+   * @returns {MoveableOptions} moveable options参数
+   */
   getSingleOptions() {
     const isAbsolute = this.mode === Mode.ABSOLUTE;
     const isFixed = this.mode === Mode.FIXED;
@@ -757,6 +814,10 @@ class MoveableOptionsManager extends EventEmitter {
       ables: [MoveableActionsAble(this.actionHandler.bind(this))]
     };
   }
+  /**
+   * 获取多选下的差异化参数
+   * @returns {MoveableOptions} moveable options参数
+   */
   getMultiOptions() {
     return {
       defaultGroupRotate: 0,
@@ -767,15 +828,27 @@ class MoveableOptionsManager extends EventEmitter {
       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) {
@@ -790,6 +863,12 @@ class MoveableOptionsManager extends EventEmitter {
     }
     return frame;
   }
+  /**
+   * 判断一个元素是否在元素列表里面
+   * @param ele 元素
+   * @param eleList 元素列表
+   * @returns 是否在元素列表里面
+   */
   isInElementList(ele, eleList) {
     for (const eleItem of eleList) {
       if (ele === eleItem)
@@ -800,8 +879,11 @@ class MoveableOptionsManager extends EventEmitter {
 }
 
 class StageDragResize extends MoveableOptionsManager {
+  /** 目标节点 */
   target;
+  /** Moveable拖拽类实例 */
   moveable;
+  /** 拖动状态 */
   dragStatus = StageDragStatus.END;
   dragResizeHelper;
   disabledDragStart;
@@ -824,6 +906,12 @@ class StageDragResize extends MoveableOptionsManager {
   getTarget() {
     return this.target;
   }
+  /**
+   * 将选中框渲染并覆盖到选中的组件Dom节点上方
+   * 当选中的节点不是absolute时，会创建一个新的节点出来作为拖拽目标
+   * @param el 选中组件的Dom节点元素
+   * @param event 鼠标事件
+   */
   select(el, event) {
     if (!this.moveable || el !== this.target) {
       this.initMoveable(el);
@@ -834,11 +922,14 @@ class StageDragResize extends MoveableOptionsManager {
       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;
@@ -852,6 +943,9 @@ class StageDragResize extends MoveableOptionsManager {
     this.moveable.target = null;
     this.moveable.updateTarget();
   }
+  /**
+   * 销毁实例
+   */
   destroy() {
     this.moveable?.destroy();
     this.dragResizeHelper.destroy();
@@ -886,7 +980,7 @@ class StageDragResize extends MoveableOptionsManager {
   }
   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;
@@ -904,11 +998,11 @@ class StageDragResize extends MoveableOptionsManager {
   }
   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) => {
@@ -946,7 +1040,7 @@ class StageDragResize extends MoveableOptionsManager {
   }
   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);
@@ -972,7 +1066,7 @@ class StageDragResize extends MoveableOptionsManager {
   }
   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);
@@ -998,7 +1092,7 @@ class StageDragResize extends MoveableOptionsManager {
   }
   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;
@@ -1051,6 +1145,10 @@ class StageHighlight extends EventEmitter$1 {
       idPrefix: HIGHLIGHT_EL_ID_PREFIX
     });
   }
+  /**
+   * 高亮鼠标悬停的组件
+   * @param el 选中组件的Dom节点元素
+   */
   highlight(el) {
     if (!el || el === this.target)
       return;
@@ -1063,6 +1161,9 @@ class StageHighlight extends EventEmitter$1 {
       zoom: 2
     });
   }
+  /**
+   * 清空高亮
+   */
   clearHighlight() {
     if (!this.moveable || !this.target)
       return;
@@ -1070,6 +1171,9 @@ class StageHighlight extends EventEmitter$1 {
     this.moveable.target = null;
     this.moveable.updateTarget();
   }
+  /**
+   * 销毁实例
+   */
   destroy() {
     this.moveable?.destroy();
     this.targetShadow.destroy();
@@ -1077,8 +1181,11 @@ class StageHighlight extends EventEmitter$1 {
 }
 
 class StageMultiDragResize extends MoveableOptionsManager {
+  /** 画布容器 */
   container;
+  /** 多选:目标节点组 */
   targetList = [];
+  /** Moveable多选拖拽类实例 */
   moveableForMulti;
   dragStatus = StageDragStatus.END;
   dragResizeHelper;
@@ -1103,6 +1210,10 @@ class StageMultiDragResize extends MoveableOptionsManager {
       }
     });
   }
+  /**
+   * 多选
+   * @param els
+   */
   multiSelect(els) {
     if (els.length === 0) {
       return;
@@ -1172,7 +1283,7 @@ class StageMultiDragResize extends MoveableOptionsManager {
     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, {
@@ -1183,6 +1294,9 @@ class StageMultiDragResize extends MoveableOptionsManager {
     });
     this.moveableForMulti.updateTarget();
   }
+  /**
+   * 清除多选状态
+   */
   clearSelectStatus() {
     if (!this.moveableForMulti)
       return;
@@ -1191,10 +1305,17 @@ class StageMultiDragResize extends MoveableOptionsManager {
     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;
@@ -1218,13 +1339,21 @@ class ActionManager extends EventEmitter {
   dr;
   multiDr;
   highlightLayer;
+  /** 单选、多选、高亮的容器（蒙层的content） */
   container;
+  /** 当前选中的节点 */
   selectedEl;
+  /** 多选选中的节点组 */
   selectedElList = [];
+  /** 当前高亮的节点 */
   highlightedEl;
+  /** 当前是否处于多选状态 */
   isMultiSelectStatus = false;
+  /** 当拖拽组件到容器上方进入可加入容器状态时，给容器添加的一个class名称 */
   containerHighlightClassName;
+  /** 当拖拽组件到容器上方时，需要悬停多久才能将组件加入容器 */
   containerHighlightDuration;
+  /** 将组件加入容器的操作方式 */
   containerHighlightType;
   isAltKeydown = false;
   getTargetElement;
@@ -1283,18 +1412,33 @@ class ActionManager extends EventEmitter {
     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;
   }
@@ -1307,6 +1451,11 @@ class ActionManager extends EventEmitter {
   getSelectedElList() {
     return this.selectedElList;
   }
+  /**
+   * 获取鼠标下方第一个可选中元素，如果元素层叠，返回到是最上层元素
+   * @param event 鼠标事件
+   * @returns 鼠标下方第一个可选中元素
+   */
   async getElementFromPoint(event) {
     const els = this.getElementsFromPoint(event);
     let stopped = false;
@@ -1319,6 +1468,13 @@ class ActionManager extends EventEmitter {
       }
     }
   }
+  /**
+   * 判断一个元素能否在当前场景被选中
+   * @param el 被判断的元素
+   * @param event 鼠标事件
+   * @param stop 通过该元素如果得知剩下的元素都不可被选中，通知调用方终止对剩下元素的判断
+   * @returns 能否选中
+   */
   async isElCanSelect(el, event, stop) {
     const canSelectByProp = await this.canSelect(el, event, stop);
     if (!canSelectByProp)
@@ -1328,6 +1484,9 @@ class ActionManager extends EventEmitter {
     }
     return true;
   }
+  /**
+   * 判断一个元素是否可以被多选，如果当前元素是page，则调stop函数告诉调用方不必继续判断其它元素了
+   */
   canMultiSelect(el, stop) {
     if (el.className.includes(PAGE_CLASS)) {
       stop();
@@ -1377,6 +1536,10 @@ class ActionManager extends EventEmitter {
     this.setHighlightEl(void 0);
     this.highlightLayer.clearHighlight();
   }
+  /**
+   * 用于在切换选择模式时清除上一次的状态
+   * @param selectType 需要清理的选择模式
+   */
   clearSelectStatus(selectType) {
     if (selectType === SelectStatus.MULTI_SELECT) {
       this.multiDr.clearSelectStatus();
@@ -1385,6 +1548,11 @@ class ActionManager extends EventEmitter {
       this.dr.clearSelectStatus();
     }
   }
+  /**
+   * 找到鼠标下方的容器，通过添加className对容器进行标记
+   * @param event 鼠标事件
+   * @param excludeElList 计算鼠标点所在容器时要排除的元素列表
+   */
   async addContainerHighlightClassName(event, excludeElList) {
     const doc = this.getRenderDocument();
     if (!doc)
@@ -1397,6 +1565,13 @@ class ActionManager extends EventEmitter {
       }
     }
   }
+  /**
+   * 鼠标拖拽着元素，在容器上方悬停，延迟一段时间后，对容器进行标记，如果悬停时间够长将标记成功，悬停时间短，调用方通过返回的timeoutId取消标记
+   * 标记的作用：1、高亮容器，给用户一个加入容器的交互感知；2、释放鼠标后，通过标记的标志找到要加入的容器
+   * @param event 鼠标事件
+   * @param excludeElList 计算鼠标所在容器时要排除的元素列表
+   * @returns timeoutId，调用方在鼠标移走时要取消该timeout，阻止标记
+   */
   delayedMarkContainer(event, excludeElList = []) {
     if (this.canAddToContainer()) {
       return globalThis.setTimeout(() => {
@@ -1428,6 +1603,11 @@ class ActionManager extends EventEmitter {
     }
     return options;
   }
+  /**
+   * 在执行多选逻辑前，先准备好多选选中元素
+   * @param el 新选中的元素
+   * @returns 多选选中的元素列表
+   */
   async beforeMultiSelect(event) {
     const el = await this.getElementFromPoint(event);
     if (!el)
@@ -1443,9 +1623,16 @@ class ActionManager extends EventEmitter {
       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()) {
@@ -1459,6 +1646,9 @@ class ActionManager extends EventEmitter {
     this.container.addEventListener("mouseleave", this.mouseLeaveHandler);
     this.container.addEventListener("wheel", this.mouseWheelHandler);
   }
+  /**
+   * 初始化键盘事件监听
+   */
   initKeyEvent() {
     const { isMac } = new Env();
     const ctrl = isMac ? "meta" : "ctrl";
@@ -1483,6 +1673,9 @@ class ActionManager extends EventEmitter {
       this.isAltKeydown = false;
     });
   }
+  /**
+   * 处理单选、多选抛出来的事件
+   */
   initActionEvent() {
     this.dr.on("update", (data) => {
       setTimeout(() => this.emit("update", data));
@@ -1508,6 +1701,9 @@ class ActionManager extends EventEmitter {
       this.emit("change-to-select", el);
     });
   }
+  /**
+   * 在down事件中集中cpu处理画布中选中操作渲染，在up事件中再通知外面的编辑器更新
+   */
   mouseDownHandler = async (event) => {
     this.clearHighlight();
     event.stopImmediatePropagation();
@@ -1542,6 +1738,9 @@ class ActionManager extends EventEmitter {
     }
     return false;
   }
+  /**
+   * 在up事件中负责对外通知选中事件，通知画布之外的编辑器更新
+   */
   mouseUpHandler = () => {
     getDocument().removeEventListener("mouseup", this.mouseUpHandler);
     this.container.addEventListener("mousemove", this.mouseMoveHandler);
@@ -1580,6 +1779,10 @@ class Rule extends EventEmitter {
     });
     this.containerResizeObserver.observe(this.container);
   }
+  /**
+   * 是否显示辅助线
+   * @param isShowGuides 是否显示
+   */
   showGuides(isShowGuides = true) {
     this.isShowGuides = isShowGuides;
     this.hGuides.setState({
@@ -1607,9 +1810,16 @@ class Rule extends EventEmitter {
       guides: vLines
     });
   }
+  /**
+   * 清空所有参考线
+   */
   clearGuides() {
     this.setGuides([[], []]);
   }
+  /**
+   * 是否显示标尺
+   * @param show 是否显示
+   */
   showRule(show = true) {
     if (show) {
       this.hGuides.destroy();
@@ -1739,6 +1949,11 @@ class StageMask extends Rule {
       this.content.style.height = `${this.height}px`;
     }
   }
+  /**
+   * 初始化视窗和蒙层监听，监听元素是否在视窗区域、监听mask蒙层所在的wrapper大小变化
+   * @description 初始化视窗和蒙层监听
+   * @param page 页面Dom节点
+   */
   observe(page) {
     if (!page)
       return;
@@ -1746,6 +1961,10 @@ class StageMask extends Rule {
     this.initObserverIntersection();
     this.initObserverWrapper();
   }
+  /**
+   * 处理页面大小变更，同步页面和mask大小
+   * @param entries ResizeObserverEntry，获取页面最新大小
+   */
   pageResize(entries) {
     const [entry] = entries;
     const { clientHeight, clientWidth } = entry.target;
@@ -1753,12 +1972,20 @@ class StageMask extends Rule {
     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) {
@@ -1772,6 +1999,9 @@ class StageMask extends Rule {
     this.scrollTop = this.pageScrollParent.scrollTop;
     this.scroll();
   }
+  /**
+   * 销毁实例
+   */
   destroy() {
     this.content?.remove();
     this.page = null;
@@ -1779,6 +2009,9 @@ class StageMask extends Rule {
     this.wrapperResizeObserver?.disconnect();
     super.destroy();
   }
+  /**
+   * 监听选中元素是否在画布可视区域内，如果目标元素不在可视区域内，通过滚动使该元素出现在可视区域
+   */
   initObserverIntersection() {
     this.pageScrollParent = getScrollParent(this.page) || null;
     this.intersectionObserver?.disconnect();
@@ -1801,6 +2034,9 @@ class StageMask extends Rule {
       );
     }
   }
+  /**
+   * 监听mask的容器大小变化
+   */
   initObserverWrapper() {
     this.wrapperResizeObserver?.disconnect();
     if (typeof ResizeObserver !== "undefined") {
@@ -1841,22 +2077,40 @@ class StageMask extends Rule {
     });
     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;
@@ -1869,7 +2123,7 @@ class StageMask extends Rule {
   }
   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;
@@ -1889,6 +2143,7 @@ class StageMask extends Rule {
 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$1 {
+  /** 组件的js、css执行的环境，直接渲染为当前window，iframe渲染则为iframe.contentWindow */
   contentWindow = null;
   runtime = null;
   iframe;
@@ -1942,9 +2197,13 @@ class StageRender extends EventEmitter$1 {
   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 (!isSameDomain(this.runtimeUrl) && this.runtimeUrl) {
       let html = await fetch(this.runtimeUrl).then((res) => res.text());
@@ -1970,6 +2229,11 @@ class StageRender extends EventEmitter$1 {
   getDocument() {
     return this.contentWindow?.document;
   }
+  /**
+   * 通过坐标获得坐标下所有HTML元素数组
+   * @param point 坐标
+   * @returns 坐标下方所有HTML元素数组，会包含父元素直至html，元素层叠时返回顺序是从上到下
+   */
   getElementsFromPoint(point) {
     let x = point.clientX;
     let y = point.clientY;
@@ -1986,11 +2250,14 @@ class StageRender extends EventEmitter$1 {
     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;
@@ -1998,6 +2265,10 @@ class StageRender extends EventEmitter$1 {
     this.iframe = void 0;
     this.removeAllListeners();
   }
+  /**
+   * 在runtime中对被选中的元素进行标记，部分组件有对选中态进行特殊显示的需求
+   * @param el 被选中的元素
+   */
   flagSelectedEl(el) {
     const doc = this.getDocument();
     if (doc) {
@@ -2060,6 +2331,10 @@ class StageCore extends EventEmitter$1 {
     this.initActionEvent();
     this.initMaskEvent();
   }
+  /**
+   * 单选选中元素
+   * @param idOrEl 选中的id或者元素
+   */
   async select(idOrEl, event) {
     const el = this.renderer.getTargetElement(idOrEl);
     if (el === this.actionManager.getSelectedEl())
@@ -2071,6 +2346,10 @@ class StageCore extends EventEmitter$1 {
       this.mask.observerIntersection(el);
     }
   }
+  /**
+   * 多选选中多个元素
+   * @param idOrElList 选中元素的id或元素列表
+   */
   async multiSelect(idOrElList) {
     const els = idOrElList.map((idOrEl) => this.renderer.getTargetElement(idOrEl));
     if (els.length === 0)
@@ -2084,9 +2363,17 @@ class StageCore extends EventEmitter$1 {
       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);
@@ -2099,15 +2386,27 @@ class StageCore extends EventEmitter$1 {
       }
     });
   }
+  /**
+   * 往画布增加一个组件
+   * @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;
@@ -2115,16 +2414,32 @@ class StageCore extends EventEmitter$1 {
     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();
@@ -2134,6 +2449,9 @@ class StageCore extends EventEmitter$1 {
     this.removeAllListeners();
     this.container = void 0;
   }
+  /**
+   * 监听页面大小变化
+   */
   observePageResize(page) {
     if (typeof ResizeObserver !== "undefined") {
       this.pageResizeObserver = new ResizeObserver((entries) => {
@@ -2177,12 +2495,18 @@ class StageCore extends EventEmitter$1 {
       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);
@@ -2194,6 +2518,9 @@ class StageCore extends EventEmitter$1 {
       this.emit("multi-select", selectedElList);
     });
   }
+  /**
+   * 初始化DragResize类通过ActionManager抛出来的事件监听
+   */
   initDrEvent() {
     this.actionManager.on("update", (data) => {
       this.emit("update", data);
@@ -2205,6 +2532,9 @@ class StageCore extends EventEmitter$1 {
       this.emit("remove", data);
     });
   }
+  /**
+   * 初始化MultiDragResize类通过ActionManager抛出来的事件监听
+   */
   initMulDrEvent() {
     this.actionManager.on("change-to-select", (el) => {
       this.select(el);
@@ -2213,6 +2543,9 @@ class StageCore extends EventEmitter$1 {
       this.emit("update", data);
     });
   }
+  /**
+   * 初始化Highlight类通过ActionManager抛出来的事件监听
+   */
   initHighlightEvent() {
     this.actionManager.on("highlight", async (highlightEl) => {
       this.emit("highlight", highlightEl);