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

package/dist/es/StageCore.js

@@ -1,5 +1,6 @@
 import "./const.js";
 import ActionManager from "./ActionManager.js";
+import StageFlashHighlight from "./StageFlashHighlight.js";
 import StageMask from "./StageMask.js";
 import StageRender from "./StageRender.js";
 import { EventEmitter } from "events";
@@ -13,13 +14,17 @@ var StageCore = class extends EventEmitter {
 	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,
@@ -34,6 +39,7 @@ var StageCore = class extends EventEmitter {
 			disabledRule: config.disabledRule
 		});
 		this.actionManager = new ActionManager(this.getActionManagerConfig(config));
+		this.flashHighlight = new StageFlashHighlight({ container: this.mask.content });
 		this.initRenderEvent();
 		this.initActionEvent();
 		this.initMaskEvent();
@@ -42,7 +48,7 @@ var StageCore = class extends EventEmitter {
 	* 单选选中元素
 	* @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) => {
@@ -73,6 +79,8 @@ var StageCore = class extends EventEmitter {
 		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);
 	}
 	/**
 	* 多选选中多个元素
@@ -198,16 +206,18 @@ var StageCore = class extends EventEmitter {
 	* 销毁实例
 	*/
 	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) {

package/dist/es/StageFlashHighlight.js

@@ -0,0 +1,110 @@
+import { ZIndex } from "./const.js";
+import { getOffset } from "./util.js";
+import { getDocument, injectStyle } from "@tmagic/core";
+//#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 {
+	/** 闪烁节点挂载的容器（蒙层的content） */
+	container;
+	el;
+	timer;
+	styleEl;
+	constructor(config) {
+		this.container = config.container;
+	}
+	/**
+	* 在目标元素所在区域做一次高亮闪烁
+	* @param el 选中组件的Dom节点元素
+	*/
+	flash(el) {
+		if (!el) return;
+		this.injectStyle();
+		this.clear();
+		const offset = getOffset(el);
+		const { transform } = getComputedStyle(el);
+		const flashEl = globalThis.document.createElement("div");
+		flashEl.className = FLASH_TIP_CLASS_NAME;
+		flashEl.style.cssText = `
+      position: absolute;
+      box-sizing: border-box;
+      pointer-events: none;
+      transform: ${transform};
+      left: ${offset.left}px;
+      top: ${offset.top}px;
+      width: ${el.clientWidth}px;
+      height: ${el.clientHeight}px;
+      z-index: ${ZIndex.SELECTED_EL};
+    `;
+		this.container.appendChild(flashEl);
+		this.el = flashEl;
+		this.timer = globalThis.setTimeout(() => {
+			this.clear();
+		}, FLASH_DURATION);
+	}
+	/**
+	* 清除闪烁节点
+	*/
+	clear() {
+		if (this.timer) {
+			globalThis.clearTimeout(this.timer);
+			this.timer = void 0;
+		}
+		this.el?.remove();
+		this.el = void 0;
+	}
+	/**
+	* 销毁实例
+	*/
+	destroy() {
+		this.clear();
+		this.styleEl?.remove();
+		this.styleEl = void 0;
+	}
+	/**
+	* 注入闪烁动画样式（仅注入一次）
+	*/
+	injectStyle() {
+		if (this.styleEl) return;
+		this.styleEl = injectStyle(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
+export { StageFlashHighlight as default };

package/dist/tmagic-stage.umd.cjs

@@ -3993,6 +3993,112 @@
 		};
 	};
 	//#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 {
+		/** 闪烁节点挂载的容器（蒙层的content） */
+		container;
+		el;
+		timer;
+		styleEl;
+		constructor(config) {
+			this.container = config.container;
+		}
+		/**
+		* 在目标元素所在区域做一次高亮闪烁
+		* @param el 选中组件的Dom节点元素
+		*/
+		flash(el) {
+			if (!el) return;
+			this.injectStyle();
+			this.clear();
+			const offset = getOffset(el);
+			const { transform } = getComputedStyle(el);
+			const flashEl = globalThis.document.createElement("div");
+			flashEl.className = FLASH_TIP_CLASS_NAME;
+			flashEl.style.cssText = `
+      position: absolute;
+      box-sizing: border-box;
+      pointer-events: none;
+      transform: ${transform};
+      left: ${offset.left}px;
+      top: ${offset.top}px;
+      width: ${el.clientWidth}px;
+      height: ${el.clientHeight}px;
+      z-index: ${ZIndex.SELECTED_EL};
+    `;
+			this.container.appendChild(flashEl);
+			this.el = flashEl;
+			this.timer = globalThis.setTimeout(() => {
+				this.clear();
+			}, FLASH_DURATION);
+		}
+		/**
+		* 清除闪烁节点
+		*/
+		clear() {
+			if (this.timer) {
+				globalThis.clearTimeout(this.timer);
+				this.timer = void 0;
+			}
+			this.el?.remove();
+			this.el = void 0;
+		}
+		/**
+		* 销毁实例
+		*/
+		destroy() {
+			this.clear();
+			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 {
@@ -4586,13 +4692,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 +4717,7 @@
 				disabledRule: config.disabledRule
 			});
 			this.actionManager = new ActionManager(this.getActionManagerConfig(config));
+			this.flashHighlight = new StageFlashHighlight({ container: this.mask.content });
 			this.initRenderEvent();
 			this.initActionEvent();
 			this.initMaskEvent();
@@ -4615,7 +4726,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 +4757,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);
 		}
 		/**
 		* 多选选中多个元素
@@ -4771,16 +4884,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) {

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.0-beta.2",
+  "version": "1.8.0-beta.3",
   "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.3"
   },
   "peerDependenciesMeta": {
     "typescript": {

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,7 @@ export default class StageCore extends EventEmitter {
       disabledRule: config.disabledRule,
     });
     this.actionManager = new ActionManager(this.getActionManagerConfig(config));
+    this.flashHighlight = new StageFlashHighlight({ container: this.mask.content });
 
     this.initRenderEvent();
     this.initActionEvent();
@@ -88,7 +94,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 +139,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);
+    }
   }
 
   /**
@@ -300,11 +313,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 +327,7 @@ export default class StageCore extends EventEmitter {
     this.renderer = null;
     this.mask = null;
     this.actionManager = null;
+    this.flashHighlight = null;
     this.pageResizeObserver = null;
   }
 

package/src/StageFlashHighlight.ts

@@ -0,0 +1,142 @@
+/*
+ * Tencent is pleased to support the open source community by making TMagicEditor available.
+ *
+ * Copyright (C) 2025 Tencent.  All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { getDocument, injectStyle } from '@tmagic/core';
+
+import { ZIndex } from './const';
+import { getOffset } from './util';
+
+/** 闪烁提示节点的 class name */
+export const FLASH_TIP_CLASS_NAME = 'tmagic-stage-flash-tip';
+/** 闪烁动画名称 */
+const FLASH_ANIMATION_NAME = 'tmagic-stage-flash';
+/** 闪烁动画时长（ms） */
+const FLASH_DURATION = 1500;
+
+/**
+ * 选中区域闪烁提示
+ * @description 当组件不是通过点击画布选中（如从图层树、面包屑等外部选中）时，在画布上对选中区域做一次高亮闪烁，
+ * 帮助用户快速定位组件在画布中的位置。
+ */
+export default class StageFlashHighlight {
+  /** 闪烁节点挂载的容器（蒙层的content） */
+  private container: HTMLElement;
+  private el?: HTMLElement;
+  private timer?: NodeJS.Timeout;
+  private styleEl?: HTMLStyleElement;
+
+  constructor(config: { container: HTMLElement }) {
+    this.container = config.container;
+  }
+
+  /**
+   * 在目标元素所在区域做一次高亮闪烁
+   * @param el 选中组件的Dom节点元素
+   */
+  public flash(el: HTMLElement): void {
+    if (!el) return;
+
+    this.injectStyle();
+    this.clear();
+
+    const offset = getOffset(el);
+    const { transform } = getComputedStyle(el);
+
+    const flashEl = globalThis.document.createElement('div');
+    flashEl.className = FLASH_TIP_CLASS_NAME;
+    flashEl.style.cssText = `
+      position: absolute;
+      box-sizing: border-box;
+      pointer-events: none;
+      transform: ${transform};
+      left: ${offset.left}px;
+      top: ${offset.top}px;
+      width: ${el.clientWidth}px;
+      height: ${el.clientHeight}px;
+      z-index: ${ZIndex.SELECTED_EL};
+    `;
+
+    this.container.appendChild(flashEl);
+    this.el = flashEl;
+
+    this.timer = globalThis.setTimeout(() => {
+      this.clear();
+    }, FLASH_DURATION);
+  }
+
+  /**
+   * 清除闪烁节点
+   */
+  public clear(): void {
+    if (this.timer) {
+      globalThis.clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+    this.el?.remove();
+    this.el = undefined;
+  }
+
+  /**
+   * 销毁实例
+   */
+  public destroy(): void {
+    this.clear();
+    this.styleEl?.remove();
+    this.styleEl = undefined;
+  }
+
+  /**
+   * 注入闪烁动画样式（仅注入一次）
+   */
+  private injectStyle(): void {
+    if (this.styleEl) return;
+
+    this.styleEl = injectStyle(
+      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;
+      }
+      `,
+    );
+  }
+}

package/src/types.ts

@@ -90,6 +90,11 @@ export interface StageCoreConfig {
    */
   alwaysMultiSelect?: boolean;
   disabledRule?: boolean;
+  /**
+   * 是否禁用「非点击画布选中组件时，对选中区域做高亮闪烁提示」，默认 false（即默认开启闪烁提示）。
+   * 用于从图层树、面包屑等外部选中组件时，帮助用户快速定位组件在画布中的位置。
+   */
+  disabledFlashTip?: boolean;
 }
 
 export interface ActionManagerConfig {

package/types/index.d.ts

@@ -215,6 +215,11 @@ interface StageCoreConfig {
    */
   alwaysMultiSelect?: boolean;
   disabledRule?: boolean;
+  /**
+   * 是否禁用「非点击画布选中组件时，对选中区域做高亮闪烁提示」，默认 false（即默认开启闪烁提示）。
+   * 用于从图层树、面包屑等外部选中组件时，帮助用户快速定位组件在画布中的位置。
+   */
+  disabledFlashTip?: boolean;
 }
 interface ActionManagerConfig {
   container: HTMLElement;
@@ -591,6 +596,40 @@ declare class ActionManager extends EventEmitter$1 {
   private dblclickHandler;
 }
 //#endregion
+//#region temp/packages/stage/src/StageFlashHighlight.d.ts
+/**
+ * 选中区域闪烁提示
+ * @description 当组件不是通过点击画布选中（如从图层树、面包屑等外部选中）时，在画布上对选中区域做一次高亮闪烁，
+ * 帮助用户快速定位组件在画布中的位置。
+ */
+declare class StageFlashHighlight {
+  /** 闪烁节点挂载的容器（蒙层的content） */
+  private container;
+  private el?;
+  private timer?;
+  private styleEl?;
+  constructor(config: {
+    container: HTMLElement;
+  });
+  /**
+   * 在目标元素所在区域做一次高亮闪烁
+   * @param el 选中组件的Dom节点元素
+   */
+  flash(el: HTMLElement): void;
+  /**
+   * 清除闪烁节点
+   */
+  clear(): void;
+  /**
+   * 销毁实例
+   */
+  destroy(): void;
+  /**
+   * 注入闪烁动画样式（仅注入一次）
+   */
+  private injectStyle;
+}
+//#endregion
 //#region temp/packages/stage/src/Rule.d.ts
 declare class Rule extends EventEmitter$1 {
   hGuides?: Guides;
@@ -790,15 +829,20 @@ declare class StageCore extends EventEmitter {
   renderer: StageRender | null;
   mask: StageMask | null;
   actionManager: ActionManager | null;
+  flashHighlight: StageFlashHighlight | null;
   private pageResizeObserver;
   private autoScrollIntoView;
   private customizedRender?;
+  /** 非点击画布选中组件时，是否对选中区域做高亮闪烁提示，默认开启 */
+  private disabledFlashTip;
   constructor(config: StageCoreConfig);
   /**
    * 单选选中元素
    * @param id 选中的id
    */
-  select(id: Id, event?: MouseEvent): Promise<void>;
+  select(id: Id, event?: MouseEvent, options?: {
+    flash?: boolean;
+  }): Promise<void>;
   /**
    * 多选选中多个元素
    * @param ids 选中元素的id列表