@tmagic/stage 1.8.0-beta.2 → 1.8.0-beta.21

package/dist/tmagic-stage.umd.cjs

@@ -107,7 +107,8 @@
 	//#endregion
 	//#region node_modules/.pnpm/lodash-es@4.17.21/node_modules/lodash-es/_baseGetTag.js
 	/** `Object#toString` result references. */
-	var nullTag = "[object Null]", undefinedTag = "[object Undefined]";
+	var nullTag = "[object Null]";
+	var undefinedTag = "[object Undefined]";
 	/** Built-in value references. */
 	var symToStringTag = Symbol$1 ? Symbol$1.toStringTag : void 0;
 	/**
@@ -333,7 +334,10 @@
 	//#endregion
 	//#region node_modules/.pnpm/lodash-es@4.17.21/node_modules/lodash-es/isFunction.js
 	/** `Object#toString` result references. */
-	var asyncTag = "[object AsyncFunction]", funcTag$1 = "[object Function]", genTag = "[object GeneratorFunction]", proxyTag = "[object Proxy]";
+	var asyncTag = "[object AsyncFunction]";
+	var funcTag$1 = "[object Function]";
+	var genTag = "[object GeneratorFunction]";
+	var proxyTag = "[object Proxy]";
 	/**
 	* Checks if `value` is classified as a `Function` object.
 	*
@@ -409,7 +413,8 @@
 	/** Used to detect host constructors (Safari). */
 	var reIsHostCtor = /^\[object .+?Constructor\]$/;
 	/** Used for built-in method references. */
-	var funcProto$1 = Function.prototype, objectProto$3 = Object.prototype;
+	var funcProto$1 = Function.prototype;
+	var objectProto$3 = Object.prototype;
 	/** Used to resolve the decompiled source of functions. */
 	var funcToString$1 = funcProto$1.toString;
 	/** Used to check objects for own properties. */
@@ -518,7 +523,8 @@
 	//#endregion
 	//#region node_modules/.pnpm/lodash-es@4.17.21/node_modules/lodash-es/_shortOut.js
 	/** Used to detect hot functions by number of calls within a span of milliseconds. */
-	var HOT_COUNT = 800, HOT_SPAN = 16;
+	var HOT_COUNT = 800;
+	var HOT_SPAN = 16;
 	var nativeNow = Date.now;
 	/**
 	* Creates a function that'll short out and invoke `identity` instead
@@ -978,8 +984,30 @@
 	//#endregion
 	//#region node_modules/.pnpm/lodash-es@4.17.21/node_modules/lodash-es/_baseIsTypedArray.js
 	/** `Object#toString` result references. */
-	var argsTag = "[object Arguments]", arrayTag = "[object Array]", boolTag = "[object Boolean]", dateTag = "[object Date]", errorTag = "[object Error]", funcTag = "[object Function]", mapTag = "[object Map]", numberTag = "[object Number]", objectTag$1 = "[object Object]", regexpTag = "[object RegExp]", setTag = "[object Set]", stringTag = "[object String]", weakMapTag = "[object WeakMap]";
-	var arrayBufferTag = "[object ArrayBuffer]", dataViewTag = "[object DataView]", float32Tag = "[object Float32Array]", float64Tag = "[object Float64Array]", int8Tag = "[object Int8Array]", int16Tag = "[object Int16Array]", int32Tag = "[object Int32Array]", uint8Tag = "[object Uint8Array]", uint8ClampedTag = "[object Uint8ClampedArray]", uint16Tag = "[object Uint16Array]", uint32Tag = "[object Uint32Array]";
+	var argsTag = "[object Arguments]";
+	var arrayTag = "[object Array]";
+	var boolTag = "[object Boolean]";
+	var dateTag = "[object Date]";
+	var errorTag = "[object Error]";
+	var funcTag = "[object Function]";
+	var mapTag = "[object Map]";
+	var numberTag = "[object Number]";
+	var objectTag$1 = "[object Object]";
+	var regexpTag = "[object RegExp]";
+	var setTag = "[object Set]";
+	var stringTag = "[object String]";
+	var weakMapTag = "[object WeakMap]";
+	var arrayBufferTag = "[object ArrayBuffer]";
+	var dataViewTag = "[object DataView]";
+	var float32Tag = "[object Float32Array]";
+	var float64Tag = "[object Float64Array]";
+	var int8Tag = "[object Int8Array]";
+	var int16Tag = "[object Int16Array]";
+	var int32Tag = "[object Int32Array]";
+	var uint8Tag = "[object Uint8Array]";
+	var uint8ClampedTag = "[object Uint8ClampedArray]";
+	var uint16Tag = "[object Uint16Array]";
+	var uint32Tag = "[object Uint32Array]";
 	/** Used to identify `toStringTag` values of typed arrays. */
 	var typedArrayTags = {};
 	typedArrayTags[float32Tag] = typedArrayTags[float64Tag] = typedArrayTags[int8Tag] = typedArrayTags[int16Tag] = typedArrayTags[int32Tag] = typedArrayTags[uint8Tag] = typedArrayTags[uint8ClampedTag] = typedArrayTags[uint16Tag] = typedArrayTags[uint32Tag] = true;
@@ -1513,7 +1541,8 @@
 	/** `Object#toString` result references. */
 	var objectTag = "[object Object]";
 	/** Used for built-in method references. */
-	var funcProto = Function.prototype, objectProto = Object.prototype;
+	var funcProto = Function.prototype;
+	var objectProto = Object.prototype;
 	/** Used to resolve the decompiled source of functions. */
 	var funcToString = funcProto.toString;
 	/** Used to check objects for own properties. */
@@ -1666,7 +1695,8 @@
 	/** Detect free variable `module`. */
 	var freeModule = freeExports && typeof module == "object" && module && !module.nodeType && module;
 	/** Built-in value references. */
-	var Buffer$1 = freeModule && freeModule.exports === freeExports ? root.Buffer : void 0, allocUnsafe = Buffer$1 ? Buffer$1.allocUnsafe : void 0;
+	var Buffer$1 = freeModule && freeModule.exports === freeExports ? root.Buffer : void 0;
+	var allocUnsafe = Buffer$1 ? Buffer$1.allocUnsafe : void 0;
 	/**
 	* Creates a clone of  `buffer`.
 	*
@@ -1783,7 +1813,8 @@
 	//#region node_modules/.pnpm/lodash-es@4.17.21/node_modules/lodash-es/debounce.js
 	/** Error message constants. */
 	var FUNC_ERROR_TEXT$1 = "Expected a function";
-	var nativeMax = Math.max, nativeMin = Math.min;
+	var nativeMax = Math.max;
+	var nativeMin = Math.min;
 	/**
 	* Creates a debounced function that delays invoking `func` until after `wait`
 	* milliseconds have elapsed since the last time the debounced function was
@@ -2175,6 +2206,8 @@
 	var DRAG_EL_ID_PREFIX = "drag_el_";
 	/** 高亮时需要在蒙层中创建一个占位节点，该节点的id前缀 */
 	var HIGHLIGHT_EL_ID_PREFIX = "highlight_el_";
+	/** 闪烁提示时需要在蒙层中创建一个占位节点，该节点的id前缀 */
+	var FLASH_EL_ID_PREFIX = "flash_el_";
 	var CONTAINER_HIGHLIGHT_CLASS_NAME = "tmagic-stage-container-highlight";
 	var PAGE_CLASS = "magic-ui-page";
 	/** 默认放到缩小倍数 */
@@ -2349,6 +2382,33 @@
 		}
 		return null;
 	};
+	/**
+	* 将元素滚动到指定滚动容器的可视区域内（仅垂直方向，滚动最小距离）
+	* @description 与原生 scrollIntoView 不同，只滚动指定的容器自身，不会连带滚动外层祖先滚动容器，
+	* 避免编辑器画布外层容器（如 stage 外层使用 transform 模拟滚动的容器）被浏览器自动滚动导致整个画布位移
+	* @param el 目标元素
+	* @param container 滚动容器
+	*/
+	var scrollElementIntoView = (el, container) => {
+		const { ownerDocument } = container;
+		const win = ownerDocument?.defaultView;
+		if (!ownerDocument || !win) return;
+		const elRect = el.getBoundingClientRect();
+		let viewTop = 0;
+		let viewHeight = 0;
+		if (container === ownerDocument.documentElement || container === ownerDocument.body) {
+			viewTop = 0;
+			viewHeight = win.innerHeight;
+		} else {
+			viewTop = container.getBoundingClientRect().top + container.clientTop;
+			viewHeight = container.clientHeight;
+		}
+		const viewBottom = viewTop + viewHeight;
+		let delta = 0;
+		if (elRect.top < viewTop) delta = elRect.top - viewTop;
+		else if (elRect.bottom > viewBottom) delta = Math.min(elRect.bottom - viewBottom, elRect.top - viewTop);
+		if (delta !== 0) container.scrollTop += delta;
+	};
 	var removeSelectedClassName = (doc) => {
 		const oldEl = doc.querySelector(`.${SELECTED_CLASS}`);
 		if (oldEl) {
@@ -2786,7 +2846,7 @@
 	};
 	//#endregion
 	//#region packages/stage/src/moveable-able.css?raw
-	var moveable_able_default = ".moveable-button {\n  width: 20px;\n  height: 20px;\n  background: #4af;\n  border-radius: 4px;\n  appearance: none;\n  border: 0;\n  color: white;\n  font-size: 12px;\n  font-weight: bold;\n  margin-left: 2px;\n  position: relative;\n  cursor: pointer;\n}\n.moveable-remove-button:before, .moveable-remove-button:after {\n  content: \"\";\n  position: absolute;\n  left: 50%;\n  top: 50%;\n  transform: translate(-50%, -50%) rotate(45deg);\n  width: 14px;\n  height: 2px;\n  background: #fff;\n  border-radius: 1px;\n  cursor: pointer;\n}\n.moveable-remove-button:after {\n  transform: translate(-50%, -50%) rotate(-45deg);\n}\n\n.moveable-select-parent-arrow-top-icon {\n  transform: rotateZ(-45deg);\n  width: 4px;\n  height: 4px;\n  border-color: #fff;\n  border-width: 2px 2px 0 0;\n  border-style: solid;\n  position: absolute;\n  left: 4px;\n  top: 4px;\n}\n\n.moveable-select-parent-arrow-body-icon {\n  width: 7px;\n  height: 11px;\n  border-color: #fff;\n  border-width: 0 0 2px 2px;\n  border-style: solid;\n}\n\n.moveable-drag-area-button {\n  cursor: move;\n}\n\n.moveable-drag-area-button .moveable-select-parent-arrow-top-icon {\n  width: 2px;\n  height: 2px;\n}\n\n.moveable-drag-area-button .moveable-select-parent-arrow-top-icon-top {\n  transform: rotateZ(-45deg) translateX(-50%);\n  left: 50%;\n  top: 3px;\n  transform-origin: left;\n}\n\n.moveable-drag-area-button .moveable-select-parent-arrow-top-icon-bottom {\n  transform: rotateZ(135deg) translateX(-50%);\n  transform-origin: left;\n  left: 50%;\n  top: auto;\n  bottom: 3px;\n}\n\n.moveable-drag-area-button .moveable-select-parent-arrow-top-icon-right {\n  transform: rotateZ(45deg)  translateY(-50%);\n  transform-origin: top;\n  right: 3px;\n  left: auto;\n  top: 50%;\n}\n\n.moveable-drag-area-button .moveable-select-parent-arrow-top-icon-left {\n  transform: rotateZ(235deg) translateY(-50%);\n  transform-origin: top;\n  left: 3px;\n  top: 50%;\n}\n\n.moveable-drag-area-button .moveable-select-parent-arrow-body-icon-horizontal {\n  width: 2px;\n  height: 11px;\n  background-color: #fff;\n  position: absolute;\n  transform: translateX(-50%);\n  left: 50%;\n  top: 4px;\n}\n\n.moveable-drag-area-button .moveable-select-parent-arrow-body-icon-vertical {\n  width: 11px;\n  height: 2px;\n  background-color: #fff;\n  position: absolute;\n  transform: translateY(-50%);\n  left: 4px;\n  top: 50%;;\n}\n\n.moveable-rerender-button img {\n  position: absolute;\n  left: 2px;\n  top: 2px;\n}\n";
+	var moveable_able_default = ".moveable-button {\n  width: 20px;\n  height: 20px;\n  background: var(--el-color-primary,#4af);\n  border-radius: 4px;\n  appearance: none;\n  border: 0;\n  color: white;\n  font-size: 12px;\n  font-weight: bold;\n  margin-left: 2px;\n  position: relative;\n  cursor: pointer;\n}\n.moveable-remove-button:before, .moveable-remove-button:after {\n  content: \"\";\n  position: absolute;\n  left: 50%;\n  top: 50%;\n  transform: translate(-50%, -50%) rotate(45deg);\n  width: 14px;\n  height: 2px;\n  background: #fff;\n  border-radius: 1px;\n  cursor: pointer;\n}\n.moveable-remove-button:after {\n  transform: translate(-50%, -50%) rotate(-45deg);\n}\n\n.moveable-select-parent-arrow-top-icon {\n  transform: rotateZ(-45deg);\n  width: 4px;\n  height: 4px;\n  border-color: #fff;\n  border-width: 2px 2px 0 0;\n  border-style: solid;\n  position: absolute;\n  left: 4px;\n  top: 4px;\n}\n\n.moveable-select-parent-arrow-body-icon {\n  width: 7px;\n  height: 11px;\n  border-color: #fff;\n  border-width: 0 0 2px 2px;\n  border-style: solid;\n}\n\n.moveable-drag-area-button {\n  cursor: move;\n}\n\n.moveable-drag-area-button .moveable-select-parent-arrow-top-icon {\n  width: 2px;\n  height: 2px;\n}\n\n.moveable-drag-area-button .moveable-select-parent-arrow-top-icon-top {\n  transform: rotateZ(-45deg) translateX(-50%);\n  left: 50%;\n  top: 3px;\n  transform-origin: left;\n}\n\n.moveable-drag-area-button .moveable-select-parent-arrow-top-icon-bottom {\n  transform: rotateZ(135deg) translateX(-50%);\n  transform-origin: left;\n  left: 50%;\n  top: auto;\n  bottom: 3px;\n}\n\n.moveable-drag-area-button .moveable-select-parent-arrow-top-icon-right {\n  transform: rotateZ(45deg)  translateY(-50%);\n  transform-origin: top;\n  right: 3px;\n  left: auto;\n  top: 50%;\n}\n\n.moveable-drag-area-button .moveable-select-parent-arrow-top-icon-left {\n  transform: rotateZ(235deg) translateY(-50%);\n  transform-origin: top;\n  left: 3px;\n  top: 50%;\n}\n\n.moveable-drag-area-button .moveable-select-parent-arrow-body-icon-horizontal {\n  width: 2px;\n  height: 11px;\n  background-color: #fff;\n  position: absolute;\n  transform: translateX(-50%);\n  left: 50%;\n  top: 4px;\n}\n\n.moveable-drag-area-button .moveable-select-parent-arrow-body-icon-vertical {\n  width: 11px;\n  height: 2px;\n  background-color: #fff;\n  position: absolute;\n  transform: translateY(-50%);\n  left: 4px;\n  top: 50%;;\n}\n\n.moveable-rerender-button img {\n  position: absolute;\n  left: 2px;\n  top: 2px;\n}\n";
 	//#endregion
 	//#region packages/stage/src/MoveableActionsAble.ts
 	var MoveableActionsAble_default = (handler, customizedButton = []) => ({
@@ -3507,6 +3567,8 @@
 		containerHighlightDuration;
 		/** 将组件加入容器的操作方式 */
 		containerHighlightType;
+		/** 是否仅在新增组件时才启用将组件加入容器 */
+		containerHighlightAddOnly = false;
 		isAltKeydown = false;
 		getTargetElement;
 		getElementsFromPoint;
@@ -3540,6 +3602,7 @@
 			this.containerHighlightClassName = config.containerHighlightClassName || "tmagic-stage-container-highlight";
 			this.containerHighlightDuration = config.containerHighlightDuration || defaultContainerHighlightDuration;
 			this.containerHighlightType = config.containerHighlightType;
+			this.containerHighlightAddOnly = config.containerHighlightAddOnly ?? false;
 			this.disabledMultiSelect = config.disabledMultiSelect ?? false;
 			this.alwaysMultiSelect = config.alwaysMultiSelect ?? false;
 			this.getTargetElement = config.getTargetElement;
@@ -3771,10 +3834,11 @@
 		* 标记的作用：1、高亮容器，给用户一个加入容器的交互感知；2、释放鼠标后，通过标记的标志找到要加入的容器
 		* @param event 鼠标事件
 		* @param excludeElList 计算鼠标所在容器时要排除的元素列表
+		* @param isAdd 当前操作是否为新增组件（从组件列表拖入），开启 containerHighlightAddOnly 时只有新增才会标记
 		* @returns timeoutId，调用方在鼠标移走时要取消该timeout，阻止标记
 		*/
-		delayedMarkContainer(event, excludeElList = []) {
-			if (this.canAddToContainer()) return globalThis.setTimeout(() => {
+		delayedMarkContainer(event, excludeElList = [], isAdd = false) {
+			if (this.canAddToContainer(isAdd)) return globalThis.setTimeout(() => {
 				this.addContainerHighlightClassName(event, excludeElList);
 			}, this.containerHighlightDuration);
 		}
@@ -3893,9 +3957,12 @@
 			} else this.selectedElList.push(el);
 		}
 		/**
-		* 当前状态下能否将组件加入容器，默认是鼠标悬停一段时间加入，alt模式则是按住alt+鼠标悬停一段时间加入
+		* 当前状态下能否将组件加入容器，默认是鼠标悬停一段时间加入，alt模式则是按住alt+鼠标悬停一段时间加入；
+		* 开启containerHighlightAddOnly时，画布中拖动已有组件不能加入容器
+		* @param isAdd 当前操作是否为新增组件
 		*/
-		canAddToContainer() {
+		canAddToContainer(isAdd = false) {
+			if (this.containerHighlightAddOnly && !isAdd) return false;
 			return this.containerHighlightType === ContainerHighlightType.DEFAULT || this.containerHighlightType === ContainerHighlightType.ALT && this.isAltKeydown;
 		}
 		/**
@@ -3904,8 +3971,9 @@
 		*/
 		markContainerEnd() {
 			const doc = this.getRenderDocument();
-			if (doc && this.canAddToContainer()) return (0, _tmagic_core.removeClassNameByClassName)(doc, this.containerHighlightClassName);
-			return null;
+			if (!doc) return null;
+			const markedContainer = (0, _tmagic_core.removeClassNameByClassName)(doc, this.containerHighlightClassName);
+			return this.canAddToContainer() ? markedContainer : null;
 		}
 		initMouseEvent() {
 			this.container.addEventListener("mousedown", this.mouseDownHandler);
@@ -3993,6 +4061,104 @@
 		};
 	};
 	//#endregion
+	//#region packages/stage/src/StageFlashHighlight.ts
+	/** 闪烁提示节点的 class name */
+	var FLASH_TIP_CLASS_NAME = "tmagic-stage-flash-tip";
+	/** 闪烁动画名称 */
+	var FLASH_ANIMATION_NAME = "tmagic-stage-flash";
+	/** 闪烁动画时长（ms） */
+	var FLASH_DURATION = 1500;
+	/**
+	* 选中区域闪烁提示
+	* @description 当组件不是通过点击画布选中（如从图层树、面包屑等外部选中）时，在画布上对选中区域做一次高亮闪烁，
+	* 帮助用户快速定位组件在画布中的位置。
+	*/
+	var StageFlashHighlight = class {
+		/** 复用 TargetShadow 负责节点的定位校准（updateDragEl、fixed、滚动偏移等） */
+		targetShadow;
+		timer;
+		styleEl;
+		constructor(config) {
+			this.targetShadow = new TargetShadow({
+				container: config.container,
+				updateDragEl: config.updateDragEl,
+				zIndex: ZIndex.SELECTED_EL,
+				idPrefix: FLASH_EL_ID_PREFIX
+			});
+		}
+		/**
+		* 在目标元素所在区域做一次高亮闪烁
+		* @param el 选中组件的Dom节点元素
+		*/
+		flash(el) {
+			if (!el) return;
+			this.injectStyle();
+			this.clear();
+			const flashEl = this.targetShadow.update(el);
+			flashEl.classList.add(FLASH_TIP_CLASS_NAME);
+			flashEl.style.boxSizing = "border-box";
+			flashEl.style.pointerEvents = "none";
+			flashEl.style.border = "";
+			this.timer = globalThis.setTimeout(() => {
+				this.clear();
+			}, FLASH_DURATION);
+		}
+		/**
+		* 清除闪烁节点
+		*/
+		clear() {
+			if (this.timer) {
+				globalThis.clearTimeout(this.timer);
+				this.timer = void 0;
+			}
+			this.targetShadow.destroyEl();
+		}
+		/**
+		* 销毁实例
+		*/
+		destroy() {
+			this.clear();
+			this.targetShadow.destroy();
+			this.styleEl?.remove();
+			this.styleEl = void 0;
+		}
+		/**
+		* 注入闪烁动画样式（仅注入一次）
+		*/
+		injectStyle() {
+			if (this.styleEl) return;
+			this.styleEl = (0, _tmagic_core.injectStyle)((0, _tmagic_core.getDocument)(), `
+      @keyframes ${FLASH_ANIMATION_NAME} {
+        0% {
+          opacity: 0;
+          background-color: rgba(146, 84, 222, 0);
+        }
+        20% {
+          opacity: 1;
+          background-color: rgba(146, 84, 222, 0.7);
+        }
+        45% {
+          opacity: 0.6;
+          background-color: rgba(146, 84, 222, 0.4);
+        }
+        70% {
+          opacity: 1;
+          background-color: rgba(146, 84, 222, 0.7);
+        }
+        100% {
+          opacity: 0;
+          background-color: rgba(146, 84, 222, 0);
+        }
+      }
+      .${FLASH_TIP_CLASS_NAME} {
+        border: 2px solid #9254de;
+        border-radius: 2px;
+        animation: ${FLASH_ANIMATION_NAME} ${FLASH_DURATION}ms cubic-bezier(0.4, 0, 0.2, 1) both;
+      }
+      `);
+		}
+	};
+	//#endregion
 	//#region packages/stage/src/Rule.ts
 	var guidesClass = "tmagic-stage-guides";
 	var Rule = class extends events.default {
@@ -4244,8 +4410,8 @@
 				this.scrollIntoView(scrollParent);
 				return;
 			}
-			el.scrollIntoView();
 			if (!this.pageScrollParent) return;
+			scrollElementIntoView(el, this.pageScrollParent);
 			this.scrollLeft = this.pageScrollParent.scrollLeft;
 			this.scrollTop = this.pageScrollParent.scrollTop;
 			this.scroll();
@@ -4586,13 +4752,17 @@
 		renderer = null;
 		mask = null;
 		actionManager = null;
+		flashHighlight = null;
 		pageResizeObserver = null;
 		autoScrollIntoView;
 		customizedRender;
+		/** 非点击画布选中组件时，是否对选中区域做高亮闪烁提示，默认开启 */
+		disabledFlashTip;
 		constructor(config) {
 			super();
 			this.autoScrollIntoView = config.autoScrollIntoView;
 			this.customizedRender = config.render;
+			this.disabledFlashTip = config.disabledFlashTip ?? false;
 			this.renderer = new StageRender({
 				runtimeUrl: config.runtimeUrl,
 				zoom: config.zoom,
@@ -4607,6 +4777,10 @@
 				disabledRule: config.disabledRule
 			});
 			this.actionManager = new ActionManager(this.getActionManagerConfig(config));
+			this.flashHighlight = new StageFlashHighlight({
+				container: this.mask.content,
+				updateDragEl: config.updateDragEl
+			});
 			this.initRenderEvent();
 			this.initActionEvent();
 			this.initMaskEvent();
@@ -4615,7 +4789,7 @@
 		* 单选选中元素
 		* @param id 选中的id
 		*/
-		async select(id, event) {
+		async select(id, event, options = {}) {
 			if (!this.renderer) return;
 			let el = this.renderer.getTargetElement(id) || null;
 			if (!el) el = await new Promise((resolve) => {
@@ -4646,6 +4820,8 @@
 			if (el) this.mask?.setLayout(el);
 			this.actionManager?.select(el, event);
 			if (el && (this.autoScrollIntoView || el.dataset.autoScrollIntoView)) this.mask?.observerIntersection(el);
+			const isPage = el === this.mask?.page || el?.className.includes("magic-ui-page");
+			if (el && !event && options.flash !== false && !this.disabledFlashTip && !isPage) this.flashHighlight?.flash(el);
 		}
 		/**
 		* 多选选中多个元素
@@ -4733,10 +4909,11 @@
 		* 标记的作用：1、高亮容器，给用户一个加入容器的交互感知；2、释放鼠标后，通过标记的标志找到要加入的容器
 		* @param event 鼠标事件
 		* @param excludeElList 计算鼠标所在容器时要排除的元素列表
+		* @param isAdd 当前操作是否为新增组件（从组件列表拖入），开启 containerHighlightAddOnly 时只有新增才会标记
 		* @returns timeoutId，调用方在鼠标移走时要取消该timeout，阻止标记
 		*/
-		delayedMarkContainer(event, excludeElList = []) {
-			return this.actionManager?.delayedMarkContainer(event, excludeElList);
+		delayedMarkContainer(event, excludeElList = [], isAdd = false) {
+			return this.actionManager?.delayedMarkContainer(event, excludeElList, isAdd);
 		}
 		getMoveableOption(key) {
 			return this.actionManager?.getMoveableOption(key);
@@ -4771,16 +4948,18 @@
 		* 销毁实例
 		*/
 		destroy() {
-			const { mask, renderer, actionManager, pageResizeObserver } = this;
+			const { mask, renderer, actionManager, flashHighlight, pageResizeObserver } = this;
 			renderer?.destroy();
 			mask?.destroy();
 			actionManager?.destroy();
+			flashHighlight?.destroy();
 			pageResizeObserver?.disconnect();
 			this.removeAllListeners();
 			this.container = void 0;
 			this.renderer = null;
 			this.mask = null;
 			this.actionManager = null;
+			this.flashHighlight = null;
 			this.pageResizeObserver = null;
 		}
 		on(eventName, listener) {
@@ -4807,6 +4986,7 @@
 				containerHighlightClassName: config.containerHighlightClassName,
 				containerHighlightDuration: config.containerHighlightDuration,
 				containerHighlightType: config.containerHighlightType,
+				containerHighlightAddOnly: config.containerHighlightAddOnly,
 				moveableOptions: config.moveableOptions,
 				container: this.mask.content,
 				disabledDragStart: config.disabledDragStart,
@@ -4925,6 +5105,7 @@
 	exports.ContainerHighlightType = ContainerHighlightType;
 	exports.DEFAULT_ZOOM = DEFAULT_ZOOM;
 	exports.DRAG_EL_ID_PREFIX = DRAG_EL_ID_PREFIX;
+	exports.FLASH_EL_ID_PREFIX = FLASH_EL_ID_PREFIX;
 	exports.GHOST_EL_ID_PREFIX = GHOST_EL_ID_PREFIX;
 	exports.GuidesType = GuidesType;
 	exports.HIGHLIGHT_EL_ID_PREFIX = HIGHLIGHT_EL_ID_PREFIX;
@@ -4957,6 +5138,7 @@
 	exports.isRelative = isRelative;
 	exports.isStatic = isStatic;
 	exports.removeSelectedClassName = removeSelectedClassName;
+	exports.scrollElementIntoView = scrollElementIntoView;
 	exports.up = up;
 	Object.keys(moveable).forEach(function(k) {
 		if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.0-beta.2",
+  "version": "1.8.0-beta.21",
   "name": "@tmagic/stage",
   "type": "module",
   "sideEffects": false,
@@ -44,7 +44,7 @@
   },
   "peerDependencies": {
     "typescript": "^6.0.3",
-    "@tmagic/core": "1.8.0-beta.2"
+    "@tmagic/core": "1.8.0-beta.21"
   },
   "peerDependenciesMeta": {
     "typescript": {

package/src/ActionManager.ts

@@ -84,6 +84,8 @@ export default class ActionManager extends EventEmitter {
   private containerHighlightDuration: number;
   /** 将组件加入容器的操作方式 */
   private containerHighlightType?: ContainerHighlightType;
+  /** 是否仅在新增组件时才启用将组件加入容器 */
+  private containerHighlightAddOnly = false;
   private isAltKeydown = false;
   private getTargetElement: GetTargetElement;
   private getElementsFromPoint: GetElementsFromPoint;
@@ -124,6 +126,7 @@ export default class ActionManager extends EventEmitter {
     this.containerHighlightClassName = config.containerHighlightClassName || CONTAINER_HIGHLIGHT_CLASS_NAME;
     this.containerHighlightDuration = config.containerHighlightDuration || defaultContainerHighlightDuration;
     this.containerHighlightType = config.containerHighlightType;
+    this.containerHighlightAddOnly = config.containerHighlightAddOnly ?? false;
     this.disabledMultiSelect = config.disabledMultiSelect ?? false;
     this.alwaysMultiSelect = config.alwaysMultiSelect ?? false;
     this.getTargetElement = config.getTargetElement;
@@ -428,10 +431,15 @@ export default class ActionManager extends EventEmitter {
    * 标记的作用：1、高亮容器，给用户一个加入容器的交互感知；2、释放鼠标后，通过标记的标志找到要加入的容器
    * @param event 鼠标事件
    * @param excludeElList 计算鼠标所在容器时要排除的元素列表
+   * @param isAdd 当前操作是否为新增组件（从组件列表拖入），开启 containerHighlightAddOnly 时只有新增才会标记
    * @returns timeoutId，调用方在鼠标移走时要取消该timeout，阻止标记
    */
-  public delayedMarkContainer(event: MouseEvent, excludeElList: Element[] = []): NodeJS.Timeout | undefined {
-    if (this.canAddToContainer()) {
+  public delayedMarkContainer(
+    event: MouseEvent,
+    excludeElList: Element[] = [],
+    isAdd = false,
+  ): NodeJS.Timeout | undefined {
+    if (this.canAddToContainer(isAdd)) {
       return globalThis.setTimeout(() => {
         this.addContainerHighlightClassName(event, excludeElList);
       }, this.containerHighlightDuration);
@@ -609,9 +617,13 @@ export default class ActionManager extends EventEmitter {
   }
 
   /**
-   * 当前状态下能否将组件加入容器，默认是鼠标悬停一段时间加入，alt模式则是按住alt+鼠标悬停一段时间加入
+   * 当前状态下能否将组件加入容器，默认是鼠标悬停一段时间加入，alt模式则是按住alt+鼠标悬停一段时间加入；
+   * 开启containerHighlightAddOnly时，画布中拖动已有组件不能加入容器
+   * @param isAdd 当前操作是否为新增组件
    */
-  private canAddToContainer(): boolean {
+  private canAddToContainer(isAdd = false): boolean {
+    if (this.containerHighlightAddOnly && !isAdd) return false;
+
     return (
       this.containerHighlightType === ContainerHighlightType.DEFAULT ||
       (this.containerHighlightType === ContainerHighlightType.ALT && this.isAltKeydown)
@@ -624,10 +636,10 @@ export default class ActionManager extends EventEmitter {
    */
   private markContainerEnd(): HTMLElement | null {
     const doc = this.getRenderDocument();
-    if (doc && this.canAddToContainer()) {
-      return removeClassNameByClassName(doc, this.containerHighlightClassName);
-    }
-    return null;
+    if (!doc) return null;
+
+    const markedContainer = removeClassNameByClassName(doc, this.containerHighlightClassName);
+    return this.canAddToContainer() ? markedContainer : null;
   }
 
   private initMouseEvent(): void {

package/src/StageCore.ts

@@ -25,7 +25,8 @@ import type { Id } from '@tmagic/core';
 import { getIdFromEl } from '@tmagic/core';
 
 import ActionManager from './ActionManager';
-import { DEFAULT_ZOOM } from './const';
+import { DEFAULT_ZOOM, PAGE_CLASS } from './const';
+import StageFlashHighlight from './StageFlashHighlight';
 import StageMask from './StageMask';
 import StageRender from './StageRender';
 import type {
@@ -51,16 +52,20 @@ export default class StageCore extends EventEmitter {
   public renderer: StageRender | null = null;
   public mask: StageMask | null = null;
   public actionManager: ActionManager | null = null;
+  public flashHighlight: StageFlashHighlight | null = null;
 
   private pageResizeObserver: ResizeObserver | null = null;
   private autoScrollIntoView: boolean | undefined;
   private customizedRender?: CustomizeRender;
+  /** 非点击画布选中组件时，是否对选中区域做高亮闪烁提示，默认开启 */
+  private disabledFlashTip: boolean;
 
   constructor(config: StageCoreConfig) {
     super();
 
     this.autoScrollIntoView = config.autoScrollIntoView;
     this.customizedRender = config.render;
+    this.disabledFlashTip = config.disabledFlashTip ?? false;
 
     this.renderer = new StageRender({
       runtimeUrl: config.runtimeUrl,
@@ -78,6 +83,10 @@ export default class StageCore extends EventEmitter {
       disabledRule: config.disabledRule,
     });
     this.actionManager = new ActionManager(this.getActionManagerConfig(config));
+    this.flashHighlight = new StageFlashHighlight({
+      container: this.mask.content,
+      updateDragEl: config.updateDragEl,
+    });
 
     this.initRenderEvent();
     this.initActionEvent();
@@ -88,7 +97,7 @@ export default class StageCore extends EventEmitter {
    * 单选选中元素
    * @param id 选中的id
    */
-  public async select(id: Id, event?: MouseEvent): Promise<void> {
+  public async select(id: Id, event?: MouseEvent, options: { flash?: boolean } = {}): Promise<void> {
     if (!this.renderer) {
       return;
     }
@@ -133,6 +142,13 @@ export default class StageCore extends EventEmitter {
     if (el && (this.autoScrollIntoView || el.dataset.autoScrollIntoView)) {
       this.mask?.observerIntersection(el);
     }
+
+    // 非点击画布选中（如从图层树、面包屑等外部选中，此时没有鼠标事件）时，对选中区域做一次高亮闪烁，帮助用户定位组件
+    // 选中页面(mask.page 或带有 magic-ui-page class 的节点)时不做闪烁提示
+    const isPage = el === this.mask?.page || el?.className.includes(PAGE_CLASS);
+    if (el && !event && options.flash !== false && !this.disabledFlashTip && !isPage) {
+      this.flashHighlight?.flash(el);
+    }
   }
 
   /**
@@ -247,10 +263,15 @@ export default class StageCore extends EventEmitter {
    * 标记的作用：1、高亮容器，给用户一个加入容器的交互感知；2、释放鼠标后，通过标记的标志找到要加入的容器
    * @param event 鼠标事件
    * @param excludeElList 计算鼠标所在容器时要排除的元素列表
+   * @param isAdd 当前操作是否为新增组件（从组件列表拖入），开启 containerHighlightAddOnly 时只有新增才会标记
    * @returns timeoutId，调用方在鼠标移走时要取消该timeout，阻止标记
    */
-  public delayedMarkContainer(event: MouseEvent, excludeElList: Element[] = []): NodeJS.Timeout | undefined {
-    return this.actionManager?.delayedMarkContainer(event, excludeElList);
+  public delayedMarkContainer(
+    event: MouseEvent,
+    excludeElList: Element[] = [],
+    isAdd = false,
+  ): NodeJS.Timeout | undefined {
+    return this.actionManager?.delayedMarkContainer(event, excludeElList, isAdd);
   }
 
   public getMoveableOption<K extends keyof MoveableOptions>(key: K): MoveableOptions[K] | undefined {
@@ -300,11 +321,12 @@ export default class StageCore extends EventEmitter {
    * 销毁实例
    */
   public destroy(): void {
-    const { mask, renderer, actionManager, pageResizeObserver } = this;
+    const { mask, renderer, actionManager, flashHighlight, pageResizeObserver } = this;
 
     renderer?.destroy();
     mask?.destroy();
     actionManager?.destroy();
+    flashHighlight?.destroy();
     pageResizeObserver?.disconnect();
 
     this.removeAllListeners();
@@ -313,6 +335,7 @@ export default class StageCore extends EventEmitter {
     this.renderer = null;
     this.mask = null;
     this.actionManager = null;
+    this.flashHighlight = null;
     this.pageResizeObserver = null;
   }
 
@@ -350,6 +373,7 @@ export default class StageCore extends EventEmitter {
       containerHighlightClassName: config.containerHighlightClassName,
       containerHighlightDuration: config.containerHighlightDuration,
       containerHighlightType: config.containerHighlightType,
+      containerHighlightAddOnly: config.containerHighlightAddOnly,
       moveableOptions: config.moveableOptions,
       container: this.mask!.content,
       disabledDragStart: config.disabledDragStart,