@tmagic/stage 1.8.0-beta.1 → 1.8.0-beta.10

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.0-beta.1",
+  "version": "1.8.0-beta.10",
   "name": "@tmagic/stage",
   "type": "module",
   "sideEffects": false,
@@ -44,7 +44,7 @@
   },
   "peerDependencies": {
     "typescript": "^6.0.3",
-    "@tmagic/core": "1.8.0-beta.1"
+    "@tmagic/core": "1.8.0-beta.10"
   },
   "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,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);
+    }
   }
 
   /**
@@ -300,11 +316,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 +330,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,135 @@
+/*
+ * 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 { FLASH_EL_ID_PREFIX, ZIndex } from './const';
+import TargetShadow from './TargetShadow';
+import type { StageFlashHighlightConfig } from './types';
+
+/** 闪烁提示节点的 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 {
+  /** 复用 TargetShadow 负责节点的定位校准（updateDragEl、fixed、滚动偏移等） */
+  private targetShadow: TargetShadow;
+  private timer?: NodeJS.Timeout;
+  private styleEl?: HTMLStyleElement;
+
+  constructor(config: StageFlashHighlightConfig) {
+    this.targetShadow = new TargetShadow({
+      container: config.container,
+      updateDragEl: config.updateDragEl,
+      zIndex: ZIndex.SELECTED_EL,
+      idPrefix: FLASH_EL_ID_PREFIX,
+    });
+  }
+
+  /**
+   * 在目标元素所在区域做一次高亮闪烁
+   * @param el 选中组件的Dom节点元素
+   */
+  public flash(el: HTMLElement): void {
+    if (!el) return;
+
+    this.injectStyle();
+    // 先销毁旧节点再 update，确保每次都拿到全新节点，让闪烁动画重新播放
+    this.clear();
+
+    const flashEl = this.targetShadow.update(el);
+    flashEl.classList.add(FLASH_TIP_CLASS_NAME);
+    flashEl.style.boxSizing = 'border-box';
+    flashEl.style.pointerEvents = 'none';
+    // getTargetElStyle 会写入 target 的内联 border，需清掉以让动画 class 的边框生效
+    flashEl.style.border = '';
+
+    this.timer = globalThis.setTimeout(() => {
+      this.clear();
+    }, FLASH_DURATION);
+  }
+
+  /**
+   * 清除闪烁节点
+   */
+  public clear(): void {
+    if (this.timer) {
+      globalThis.clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+    this.targetShadow.destroyEl();
+  }
+
+  /**
+   * 销毁实例
+   */
+  public destroy(): void {
+    this.clear();
+    this.targetShadow.destroy();
+    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/const.ts

@@ -25,6 +25,9 @@ export const DRAG_EL_ID_PREFIX = 'drag_el_';
 /** 高亮时需要在蒙层中创建一个占位节点，该节点的id前缀 */
 export const HIGHLIGHT_EL_ID_PREFIX = 'highlight_el_';
 
+/** 闪烁提示时需要在蒙层中创建一个占位节点，该节点的id前缀 */
+export const FLASH_EL_ID_PREFIX = 'flash_el_';
+
 export const CONTAINER_HIGHLIGHT_CLASS_NAME = 'tmagic-stage-container-highlight';
 
 export const PAGE_CLASS = 'magic-ui-page';

package/src/types.ts

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

package/types/index.d.ts

@@ -13,6 +13,8 @@ declare const GHOST_EL_ID_PREFIX = "ghost_el_";
 declare const DRAG_EL_ID_PREFIX = "drag_el_";
 /** 高亮时需要在蒙层中创建一个占位节点，该节点的id前缀 */
 declare const HIGHLIGHT_EL_ID_PREFIX = "highlight_el_";
+/** 闪烁提示时需要在蒙层中创建一个占位节点，该节点的id前缀 */
+declare const FLASH_EL_ID_PREFIX = "flash_el_";
 declare const CONTAINER_HIGHLIGHT_CLASS_NAME = "tmagic-stage-container-highlight";
 declare const PAGE_CLASS = "magic-ui-page";
 /** 默认放到缩小倍数 */
@@ -215,6 +217,11 @@ interface StageCoreConfig {
    */
   alwaysMultiSelect?: boolean;
   disabledRule?: boolean;
+  /**
+   * 是否禁用「非点击画布选中组件时，对选中区域做高亮闪烁提示」，默认 false（即默认开启闪烁提示）。
+   * 用于从图层树、面包屑等外部选中组件时，帮助用户快速定位组件在画布中的位置。
+   */
+  disabledFlashTip?: boolean;
 }
 interface ActionManagerConfig {
   container: HTMLElement;
@@ -363,6 +370,10 @@ interface TargetShadowConfig {
   updateDragEl?: UpdateDragEl;
   idPrefix?: string;
 }
+interface StageFlashHighlightConfig {
+  container: HTMLElement;
+  updateDragEl?: UpdateDragEl;
+}
 interface RuleOptions {
   guidesOptions?: Partial<GuidesOptions$1>;
   disabledRule?: boolean;
@@ -591,6 +602,37 @@ declare class ActionManager extends EventEmitter$1 {
   private dblclickHandler;
 }
 //#endregion
+//#region temp/packages/stage/src/StageFlashHighlight.d.ts
+/**
+ * 选中区域闪烁提示
+ * @description 当组件不是通过点击画布选中（如从图层树、面包屑等外部选中）时，在画布上对选中区域做一次高亮闪烁，
+ * 帮助用户快速定位组件在画布中的位置。
+ */
+declare class StageFlashHighlight {
+  /** 复用 TargetShadow 负责节点的定位校准（updateDragEl、fixed、滚动偏移等） */
+  private targetShadow;
+  private timer?;
+  private styleEl?;
+  constructor(config: StageFlashHighlightConfig);
+  /**
+   * 在目标元素所在区域做一次高亮闪烁
+   * @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 +832,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列表
@@ -1102,4 +1149,4 @@ declare const _default: (handler: (type: AbleActionEventType) => void, customize
   render(moveable: MoveableManagerInterface<any, any>, React: Renderer): any;
 };
 //#endregion
-export { AbleActionEventType, AbleCustomizedButton, ActionManagerConfig, ActionManagerEvents, CONTAINER_HIGHLIGHT_CLASS_NAME, CanDropIn, CanSelect, ContainerHighlightType, CoreEvents, CustomizeMoveableOptions, CustomizeMoveableOptionsCallbackConfig, CustomizeMoveableOptionsFunction, CustomizeRender, DEFAULT_ZOOM, DRAG_EL_ID_PREFIX, DelayedMarkContainer, DrEvents, DragResizeHelperConfig, GHOST_EL_ID_PREFIX, GetElementsFromPoint, GetRenderDocument, GetRootContainer, GetTargetElement, GuidesEventData, type GuidesOptions, GuidesType, HIGHLIGHT_EL_ID_PREFIX, IsContainer, Magic, MarkContainerEnd, MaskEvents, Mode, MouseButton, _default as MoveableActionsAble, MoveableOptionsManagerConfig, MultiDrEvents, Offset, PAGE_CLASS, Point, Rect, RemoveData, RemoveEventData, RenderEvents, RenderType, RuleOptions, Runtime, RuntimeWindow, SELECTED_CLASS, SelectStatus, SortEventData, StageCoreConfig, StageDragResize, StageDragResizeConfig, StageDragStatus, StageHighlightConfig, StageMask, StageMaskConfig, StageMultiDragResizeConfig, StageRender, StageRenderConfig, TargetElement, TargetShadowConfig, UpdateData, UpdateDragEl, UpdateEventData, ZIndex, addSelectedClassName, StageCore as default, down, getAbsolutePosition, getBorderWidth, getMarginValue, getMode, getOffset, getScrollParent, getTargetElStyle, isAbsolute, isFixed, isFixedParent, isMoveableButton, isRelative, isStatic, removeSelectedClassName, up };
+export { AbleActionEventType, AbleCustomizedButton, ActionManagerConfig, ActionManagerEvents, CONTAINER_HIGHLIGHT_CLASS_NAME, CanDropIn, CanSelect, ContainerHighlightType, CoreEvents, CustomizeMoveableOptions, CustomizeMoveableOptionsCallbackConfig, CustomizeMoveableOptionsFunction, CustomizeRender, DEFAULT_ZOOM, DRAG_EL_ID_PREFIX, DelayedMarkContainer, DrEvents, DragResizeHelperConfig, FLASH_EL_ID_PREFIX, GHOST_EL_ID_PREFIX, GetElementsFromPoint, GetRenderDocument, GetRootContainer, GetTargetElement, GuidesEventData, type GuidesOptions, GuidesType, HIGHLIGHT_EL_ID_PREFIX, IsContainer, Magic, MarkContainerEnd, MaskEvents, Mode, MouseButton, _default as MoveableActionsAble, MoveableOptionsManagerConfig, MultiDrEvents, Offset, PAGE_CLASS, Point, Rect, RemoveData, RemoveEventData, RenderEvents, RenderType, RuleOptions, Runtime, RuntimeWindow, SELECTED_CLASS, SelectStatus, SortEventData, StageCoreConfig, StageDragResize, StageDragResizeConfig, StageDragStatus, StageFlashHighlightConfig, StageHighlightConfig, StageMask, StageMaskConfig, StageMultiDragResizeConfig, StageRender, StageRenderConfig, TargetElement, TargetShadowConfig, UpdateData, UpdateDragEl, UpdateEventData, ZIndex, addSelectedClassName, StageCore as default, down, getAbsolutePosition, getBorderWidth, getMarginValue, getMode, getOffset, getScrollParent, getTargetElStyle, isAbsolute, isFixed, isFixedParent, isMoveableButton, isRelative, isStatic, removeSelectedClassName, up };