@tmagic/stage 1.8.0-manmanyu.9 → 1.8.1

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.0-manmanyu.9",
+  "version": "1.8.1",
   "name": "@tmagic/stage",
   "type": "module",
   "sideEffects": false,
@@ -30,21 +30,21 @@
   },
   "dependencies": {
     "@scena/guides": "^0.29.2",
+    "@zumer/snapdom": "^2.23.2",
     "events": "^3.3.0",
-    "@zumer/snapdom": "^2.8.0",
     "keycon": "^1.4.0",
-    "lodash-es": "^4.17.21",
+    "lodash-es": "^4.18.1",
     "moveable": "^0.53.0",
     "moveable-helper": "^0.4.0",
     "scenejs": "^1.10.3"
   },
   "devDependencies": {
     "@types/events": "^3.0.3",
-    "@types/lodash-es": "^4.17.4"
+    "@types/lodash-es": "^4.17.12"
   },
   "peerDependencies": {
     "typescript": "^6.0.3",
-    "@tmagic/core": "1.8.0-manmanyu.9"
+    "@tmagic/core": "1.8.1"
   },
   "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

@@ -263,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 {
@@ -363,11 +368,23 @@ export default class StageCore extends EventEmitter {
     }
   }
 
+  /**
+   * page-el-update 后，若当前选中节点仍在新页面文档中且需要自动滚动，则重新触发 scrollIntoView
+   */
+  private scrollSelectedIntoViewAfterPageUpdate(): void {
+    const selected = this.actionManager?.getSelectedEl();
+    if (!selected?.isConnected) return;
+    if (!(this.autoScrollIntoView || selected.dataset.autoScrollIntoView)) return;
+
+    this.mask?.observerIntersection(selected);
+  }
+
   private getActionManagerConfig(config: StageCoreConfig): ActionManagerConfig {
     const actionManagerConfig: ActionManagerConfig = {
       containerHighlightClassName: config.containerHighlightClassName,
       containerHighlightDuration: config.containerHighlightDuration,
       containerHighlightType: config.containerHighlightType,
+      containerHighlightAddOnly: config.containerHighlightAddOnly,
       moveableOptions: config.moveableOptions,
       container: this.mask!.content,
       disabledDragStart: config.disabledDragStart,
@@ -394,6 +411,10 @@ export default class StageCore extends EventEmitter {
       this.mask?.observe(el);
       this.observePageResize(el);
 
+      // observe 切页时会重置滚动；若 select + scrollIntoView 已先完成，这里对仍挂载的选中节点
+      // 重新触发一次，避免滚动被打回顶部
+      this.scrollSelectedIntoViewAfterPageUpdate();
+
       this.emit('page-el-update', el);
     });
   }

package/src/StageMask.ts

@@ -21,7 +21,7 @@ import { createDiv, getDocument, injectStyle } from '@tmagic/core';
 import { Mode, ZIndex } from './const';
 import Rule from './Rule';
 import type { MaskEvents, RuleOptions } from './types';
-import { getScrollParent, isFixedParent } from './util';
+import { getScrollParent, isDocumentVisible, isElementVisible, isFixedParent, scrollElementIntoView } from './util';
 
 const wrapperClassName = 'editor-mask-wrapper';
 
@@ -108,28 +108,50 @@ export default class StageMask extends Rule {
 
   /**
    * 初始化视窗和蒙层监听，监听元素是否在视窗区域、监听mask蒙层所在的wrapper大小变化
-   * @description 初始化视窗和蒙层监听
+   * @description 初始化视窗和蒙层监听；切换到新页面 DOM 时重置滚动
    * @param page 页面Dom节点
    */
   public observe(page: HTMLElement): void {
     if (!page) return;
 
+    const pageChanged = this.page !== page;
+
     this.page = page;
     this.initObserverIntersection();
     this.initObserverWrapper();
+
+    if (pageChanged) {
+      // runtime 按 pageId 重挂载后，滚动容器（多为 documentElement）可能仍残留上一页偏移；
+      // 新页默认从顶部展示：重置页面与 mask 滚动，并立刻 scroll() 刷新 transform/标尺。
+      // syncPageSize 在宽高为 0 时会提前返回，不能依赖它刷新视觉状态。
+      // 若 select 已先 scrollIntoView，由 StageCore 在 page-el-update 后重新触发一次补回。
+      this.pageScrollParent?.scrollTo({ top: 0, left: 0 });
+      this.scrollTop = 0;
+      this.scrollLeft = 0;
+      this.scroll();
+    }
+
+    // 页面切换后立即同步一次；ResizeObserver 首次回调可能仍上报旧页/0 尺寸
+    this.syncPageSize();
   }
 
   /**
-   * 处理页面大小变更，同步页面和mask大小
+   * 处理页面大小变更，同步页面和 mask 大小
+   * @description 仅处理当前 page 且仍挂载在文档中的 entry；非当前页、已卸载或宽高为 0 的回调会被忽略
    * @param entries ResizeObserverEntry，获取页面最新大小
    */
   public pageResize(entries: ResizeObserverEntry[]): void {
-    const [entry] = entries;
-    const { clientHeight, clientWidth } = entry.target;
-    this.setHeight(clientHeight);
-    this.setWidth(clientWidth);
+    if (!this.page || !entries.length) return;
 
-    this.scroll();
+    // 取当前 page 对应 entry，避免 batch 中首项是旧页时整批被丢弃
+    const entry = entries.find((item) => item.target === this.page);
+    if (!entry) return;
+
+    const { target } = entry;
+    // 旧页卸载后仍可能回调，已断开连接的节点不再同步尺寸
+    if (!target.isConnected) return;
+
+    this.applyPageSize(target.clientWidth, target.clientHeight);
   }
 
   /**
@@ -154,7 +176,14 @@ export default class StageMask extends Rule {
     this.setMode(isFixedParent(el) ? Mode.FIXED : Mode.ABSOLUTE);
   }
 
+  /**
+   * 将元素滚动到画布可视区域内
+   * @description 页面不可见时不做滚动：此时滚动既无视觉效果，又会记录错误的滚动偏移
+   * @param el 目标元素
+   */
   public scrollIntoView(el: Element): void {
+    if (!this.isPageVisible()) return;
+
     // 不可以有横向滚动
     if (!this.page || el.getBoundingClientRect().left >= this.page.scrollWidth) return;
 
@@ -165,10 +194,12 @@ export default class StageMask extends Rule {
       return;
     }
 
-    el.scrollIntoView();
-
     if (!this.pageScrollParent) return;
 
+    // 不使用原生 scrollIntoView，避免编辑器画布外层滚动容器被浏览器连带滚动导致整个 stage 位移，
+    // 只滚动页面所在的滚动容器
+    scrollElementIntoView(el, this.pageScrollParent);
+
     this.scrollLeft = this.pageScrollParent.scrollLeft;
     this.scrollTop = this.pageScrollParent.scrollTop;
 
@@ -184,6 +215,7 @@ export default class StageMask extends Rule {
     this.content?.remove();
     this.page = null;
     this.pageScrollParent = null;
+    this.intersectionObserver?.disconnect();
     this.wrapperResizeObserver?.disconnect();
   }
 
@@ -210,6 +242,10 @@ export default class StageMask extends Rule {
         (entries) => {
           entries.forEach((entry) => {
             const { target, intersectionRatio } = entry;
+
+            // 页面不可见时不滚动，同时保留监听，等页面恢复可见后由 IntersectionObserver 重新回调
+            if (!this.isPageVisible()) return;
+
             if (intersectionRatio <= 0) {
               this.scrollIntoView(target);
             }
@@ -285,6 +321,40 @@ export default class StageMask extends Rule {
     this.content.dispatchEvent(event);
   }
 
+  /**
+   * 页面是否可见
+   * @description 页面未挂载、或画布容器被隐藏（如编辑器切到其他面板）时页面不可见；
+   * 蒙层与页面所在的 iframe 挂载在同一容器中，容器隐藏时页面内部元素仍可能是"可见"的，因此额外判断蒙层；
+   * 浏览器 tab 不可见（切到其他标签页、窗口最小化）时同样视为不可见
+   */
+  private isPageVisible(): boolean {
+    if (!isDocumentVisible(this.page?.ownerDocument) || !isDocumentVisible(this.wrapper.ownerDocument)) return false;
+
+    if (!isElementVisible(this.page)) return false;
+
+    return !this.wrapper.isConnected || isElementVisible(this.wrapper);
+  }
+
+  /**
+   * 从当前页面同步蒙层宽高，并修正滚动偏移
+   */
+  private syncPageSize(): void {
+    if (!this.page?.isConnected) return;
+
+    this.applyPageSize(this.page.clientWidth, this.page.clientHeight);
+  }
+
+  /**
+   * 应用页面尺寸到蒙层；宽高为 0 时忽略，避免切换/布局过程中把 editor-mask 置空
+   */
+  private applyPageSize(clientWidth: number, clientHeight: number): void {
+    if (clientWidth <= 0 || clientHeight <= 0) return;
+
+    this.setHeight(clientHeight);
+    this.setWidth(clientWidth);
+    this.scroll();
+  }
+
   /**
    * 设置蒙层高度
    * @param height 高度

package/src/types.ts

@@ -53,7 +53,11 @@ export type GetTargetElement = (id: Id) => HTMLElement | null;
 /** render提供的接口，通过坐标获得坐标下所有HTML元素数组 */
 export type GetElementsFromPoint = (point: Point) => HTMLElement[];
 export type GetRenderDocument = () => Document | undefined;
-export type DelayedMarkContainer = (event: MouseEvent, exclude: Element[]) => NodeJS.Timeout | undefined;
+export type DelayedMarkContainer = (
+  event: MouseEvent,
+  exclude?: Element[],
+  isAdd?: boolean,
+) => NodeJS.Timeout | undefined;
 export type MarkContainerEnd = () => HTMLElement | null;
 export type GetRootContainer = () => HTMLDivElement | undefined;
 
@@ -74,6 +78,11 @@ export interface StageCoreConfig {
   containerHighlightClassName?: string;
   containerHighlightDuration?: number;
   containerHighlightType?: ContainerHighlightType;
+  /**
+   * 是否仅在新增组件（从组件列表拖入新组件）时才启用将组件拖入容器，
+   * 开启后在画布中拖动已有组件不会识别容器，默认 false
+   */
+  containerHighlightAddOnly?: boolean;
   moveableOptions?: CustomizeMoveableOptions;
   /** runtime 的HTML地址，可以是一个HTTP地址，如果和编辑器不同域，需要设置跨域，也可以是一个相对或绝对路径 */
   runtimeUrl?: string;
@@ -102,6 +111,8 @@ export interface ActionManagerConfig {
   containerHighlightClassName?: string;
   containerHighlightDuration?: number;
   containerHighlightType?: ContainerHighlightType;
+  /** 见 StageCoreConfig.containerHighlightAddOnly */
+  containerHighlightAddOnly?: boolean;
   moveableOptions?: CustomizeMoveableOptions;
   disabledDragStart?: boolean;
   disabledMultiSelect?: boolean;
@@ -224,6 +235,8 @@ export interface UpdateData {
   parent?: MContainer;
   parentId?: Id;
   root: MApp;
+  /** 插入到父节点 items 中的目标下标；runtime 优先按此同步，避免依赖选中态推算顺序 */
+  index?: number;
 }
 
 export interface RemoveData {

package/src/util.ts

@@ -126,7 +126,7 @@ export const getScrollParent = (element: HTMLElement, includeHidden = false): HT
 
   if (isFixed(style)) return null;
 
-  for (let parent = element; parent.parentElement; ) {
+  for (let parent = element; parent.parentElement;) {
     parent = parent.parentElement;
 
     if (parent.tagName === 'HTML') return parent;
@@ -141,6 +141,77 @@ export const getScrollParent = (element: HTMLElement, includeHidden = false): HT
   return null;
 };
 
+/**
+ * 判断文档是否可见
+ * @description 浏览器 tab 切到后台、窗口最小化时文档 visibilityState 为 hidden；
+ * 只将 hidden 视为不可见，避免 prerender 等中间态被误判
+ * @param doc 目标文档
+ */
+export const isDocumentVisible = (doc: Document | null | undefined): boolean => doc?.visibilityState !== 'hidden';
+
+/**
+ * 判断元素是否可见
+ * @description 元素未挂载到文档、或其自身/祖先被 display:none、visibility:hidden 隐藏时视为不可见；
+ * 优先使用浏览器提供的 checkVisibility，不支持时退化为沿祖先链检查计算样式
+ * @param el 目标元素
+ */
+export const isElementVisible = (el: Element | null | undefined): boolean => {
+  if (!el?.isConnected) return false;
+
+  if (typeof el.checkVisibility === 'function') {
+    return el.checkVisibility({ checkVisibilityCSS: true });
+  }
+
+  for (let node: Element | null = el; node; node = node.parentElement) {
+    const { display, visibility } = getComputedStyle(node);
+    if (display === 'none' || visibility === 'hidden') return false;
+  }
+
+  return true;
+};
+
+/**
+ * 将元素滚动到指定滚动容器的可视区域内（仅垂直方向，滚动最小距离）
+ * @description 与原生 scrollIntoView 不同，只滚动指定的容器自身，不会连带滚动外层祖先滚动容器，
+ * 避免编辑器画布外层容器（如 stage 外层使用 transform 模拟滚动的容器）被浏览器自动滚动导致整个画布位移
+ * @param el 目标元素
+ * @param container 滚动容器
+ */
+export const scrollElementIntoView = (el: Element, container: HTMLElement): void => {
+  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 {
+    const containerRect = container.getBoundingClientRect();
+    viewTop = containerRect.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;
+  }
+};
+
 export const removeSelectedClassName = (doc: Document) => {
   const oldEl = doc.querySelector(`.${SELECTED_CLASS}`);