@tmagic/stage 1.8.0 → 1.8.1

package/dist/es/StageMask.js

@@ -1,5 +1,5 @@
 import { Mode, ZIndex } from "./const.js";
-import { getScrollParent, isFixedParent, scrollElementIntoView } from "./util.js";
+import { getScrollParent, isDocumentVisible, isElementVisible, isFixedParent, scrollElementIntoView } from "./util.js";
 import Rule from "./Rule.js";
 import { createDiv, getDocument, injectStyle } from "@tmagic/core";
 //#region packages/stage/src/StageMask.ts
@@ -124,7 +124,13 @@ var StageMask = class extends Rule {
 	setLayout(el) {
 		this.setMode(isFixedParent(el) ? Mode.FIXED : Mode.ABSOLUTE);
 	}
+	/**
+	* 将元素滚动到画布可视区域内
+	* @description 页面不可见时不做滚动：此时滚动既无视觉效果，又会记录错误的滚动偏移
+	* @param el 目标元素
+	*/
 	scrollIntoView(el) {
+		if (!this.isPageVisible()) return;
 		if (!this.page || el.getBoundingClientRect().left >= this.page.scrollWidth) return;
 		const scrollParent = getScrollParent(el);
 		if (scrollParent && scrollParent !== this.pageScrollParent) {
@@ -163,6 +169,7 @@ var StageMask = class extends Rule {
 		if (typeof IntersectionObserver !== "undefined") this.intersectionObserver = new IntersectionObserver((entries) => {
 			entries.forEach((entry) => {
 				const { target, intersectionRatio } = entry;
+				if (!this.isPageVisible()) return;
 				if (intersectionRatio <= 0) this.scrollIntoView(target);
 				this.intersectionObserver?.unobserve(target);
 			});
@@ -216,6 +223,17 @@ var StageMask = class extends Rule {
 		this.content.dispatchEvent(event);
 	}
 	/**
+	* 页面是否可见
+	* @description 页面未挂载、或画布容器被隐藏（如编辑器切到其他面板）时页面不可见；
+	* 蒙层与页面所在的 iframe 挂载在同一容器中，容器隐藏时页面内部元素仍可能是"可见"的，因此额外判断蒙层；
+	* 浏览器 tab 不可见（切到其他标签页、窗口最小化）时同样视为不可见
+	*/
+	isPageVisible() {
+		if (!isDocumentVisible(this.page?.ownerDocument) || !isDocumentVisible(this.wrapper.ownerDocument)) return false;
+		if (!isElementVisible(this.page)) return false;
+		return !this.wrapper.isConnected || isElementVisible(this.wrapper);
+	}
+	/**
 	* 从当前页面同步蒙层宽高，并修正滚动偏移
 	*/
 	syncPageSize() {

package/dist/es/index.js

@@ -1,5 +1,5 @@
 import { AbleActionEventType, CONTAINER_HIGHLIGHT_CLASS_NAME, ContainerHighlightType, DEFAULT_ZOOM, DRAG_EL_ID_PREFIX, FLASH_EL_ID_PREFIX, GHOST_EL_ID_PREFIX, GuidesType, HIGHLIGHT_EL_ID_PREFIX, Mode, MouseButton, PAGE_CLASS, RenderType, SELECTED_CLASS, SelectStatus, StageDragStatus, ZIndex } from "./const.js";
-import { addSelectedClassName, down, getAbsolutePosition, getBorderWidth, getMarginValue, getMode, getOffset, getScrollParent, getTargetElStyle, isAbsolute, isFixed, isFixedParent, isMoveableButton, isRelative, isStatic, removeSelectedClassName, scrollElementIntoView, up } from "./util.js";
+import { addSelectedClassName, down, getAbsolutePosition, getBorderWidth, getMarginValue, getMode, getOffset, getScrollParent, getTargetElStyle, isAbsolute, isDocumentVisible, isElementVisible, isFixed, isFixedParent, isMoveableButton, isRelative, isStatic, removeSelectedClassName, scrollElementIntoView, up } from "./util.js";
 import MoveableActionsAble_default from "./MoveableActionsAble.js";
 import StageDragResize from "./StageDragResize.js";
 import StageMask from "./StageMask.js";
@@ -9,4 +9,4 @@ export * from "moveable";
 //#region packages/stage/src/index.ts
 var src_default = StageCore;
 //#endregion
-export { AbleActionEventType, CONTAINER_HIGHLIGHT_CLASS_NAME, ContainerHighlightType, DEFAULT_ZOOM, DRAG_EL_ID_PREFIX, FLASH_EL_ID_PREFIX, GHOST_EL_ID_PREFIX, GuidesType, HIGHLIGHT_EL_ID_PREFIX, Mode, MouseButton, MoveableActionsAble_default as MoveableActionsAble, PAGE_CLASS, RenderType, SELECTED_CLASS, SelectStatus, StageDragResize, StageDragStatus, StageMask, StageRender, ZIndex, addSelectedClassName, src_default as default, down, getAbsolutePosition, getBorderWidth, getMarginValue, getMode, getOffset, getScrollParent, getTargetElStyle, isAbsolute, isFixed, isFixedParent, isMoveableButton, isRelative, isStatic, removeSelectedClassName, scrollElementIntoView, up };
+export { AbleActionEventType, CONTAINER_HIGHLIGHT_CLASS_NAME, ContainerHighlightType, DEFAULT_ZOOM, DRAG_EL_ID_PREFIX, FLASH_EL_ID_PREFIX, GHOST_EL_ID_PREFIX, GuidesType, HIGHLIGHT_EL_ID_PREFIX, Mode, MouseButton, MoveableActionsAble_default as MoveableActionsAble, PAGE_CLASS, RenderType, SELECTED_CLASS, SelectStatus, StageDragResize, StageDragStatus, StageMask, StageRender, ZIndex, addSelectedClassName, src_default as default, down, getAbsolutePosition, getBorderWidth, getMarginValue, getMode, getOffset, getScrollParent, getTargetElStyle, isAbsolute, isDocumentVisible, isElementVisible, isFixed, isFixedParent, isMoveableButton, isRelative, isStatic, removeSelectedClassName, scrollElementIntoView, up };

package/dist/es/util.js

@@ -92,6 +92,28 @@ var getScrollParent = (element, includeHidden = false) => {
 	return null;
 };
 /**
+* 判断文档是否可见
+* @description 浏览器 tab 切到后台、窗口最小化时文档 visibilityState 为 hidden；
+* 只将 hidden 视为不可见，避免 prerender 等中间态被误判
+* @param doc 目标文档
+*/
+var isDocumentVisible = (doc) => doc?.visibilityState !== "hidden";
+/**
+* 判断元素是否可见
+* @description 元素未挂载到文档、或其自身/祖先被 display:none、visibility:hidden 隐藏时视为不可见；
+* 优先使用浏览器提供的 checkVisibility，不支持时退化为沿祖先链检查计算样式
+* @param el 目标元素
+*/
+var isElementVisible = (el) => {
+	if (!el?.isConnected) return false;
+	if (typeof el.checkVisibility === "function") return el.checkVisibility({ checkVisibilityCSS: true });
+	for (let node = el; node; node = node.parentElement) {
+		const { display, visibility } = getComputedStyle(node);
+		if (display === "none" || visibility === "hidden") return false;
+	}
+	return true;
+};
+/**
 * 将元素滚动到指定滚动容器的可视区域内（仅垂直方向，滚动最小距离）
 * @description 与原生 scrollIntoView 不同，只滚动指定的容器自身，不会连带滚动外层祖先滚动容器，
 * 避免编辑器画布外层容器（如 stage 外层使用 transform 模拟滚动的容器）被浏览器自动滚动导致整个画布位移
@@ -216,4 +238,4 @@ var getBorderWidth = (el) => {
 	};
 };
 //#endregion
-export { addSelectedClassName, down, getAbsolutePosition, getBorderWidth, getMarginValue, getMode, getOffset, getScrollParent, getTargetElStyle, isAbsolute, isFixed, isFixedParent, isMoveableButton, isRelative, isStatic, removeSelectedClassName, scrollElementIntoView, up };
+export { addSelectedClassName, down, getAbsolutePosition, getBorderWidth, getMarginValue, getMode, getOffset, getScrollParent, getTargetElStyle, isAbsolute, isDocumentVisible, isElementVisible, isFixed, isFixedParent, isMoveableButton, isRelative, isStatic, removeSelectedClassName, scrollElementIntoView, up };

package/dist/tmagic-stage.umd.cjs

@@ -2386,6 +2386,28 @@
 		return null;
 	};
 	/**
+	* 判断文档是否可见
+	* @description 浏览器 tab 切到后台、窗口最小化时文档 visibilityState 为 hidden；
+	* 只将 hidden 视为不可见，避免 prerender 等中间态被误判
+	* @param doc 目标文档
+	*/
+	var isDocumentVisible = (doc) => doc?.visibilityState !== "hidden";
+	/**
+	* 判断元素是否可见
+	* @description 元素未挂载到文档、或其自身/祖先被 display:none、visibility:hidden 隐藏时视为不可见；
+	* 优先使用浏览器提供的 checkVisibility，不支持时退化为沿祖先链检查计算样式
+	* @param el 目标元素
+	*/
+	var isElementVisible = (el) => {
+		if (!el?.isConnected) return false;
+		if (typeof el.checkVisibility === "function") return el.checkVisibility({ checkVisibilityCSS: true });
+		for (let node = el; node; node = node.parentElement) {
+			const { display, visibility } = getComputedStyle(node);
+			if (display === "none" || visibility === "hidden") return false;
+		}
+		return true;
+	};
+	/**
 	* 将元素滚动到指定滚动容器的可视区域内（仅垂直方向，滚动最小距离）
 	* @description 与原生 scrollIntoView 不同，只滚动指定的容器自身，不会连带滚动外层祖先滚动容器，
 	* 避免编辑器画布外层容器（如 stage 外层使用 transform 模拟滚动的容器）被浏览器自动滚动导致整个画布位移
@@ -4422,7 +4444,13 @@
 		setLayout(el) {
 			this.setMode(isFixedParent(el) ? Mode.FIXED : Mode.ABSOLUTE);
 		}
+		/**
+		* 将元素滚动到画布可视区域内
+		* @description 页面不可见时不做滚动：此时滚动既无视觉效果，又会记录错误的滚动偏移
+		* @param el 目标元素
+		*/
 		scrollIntoView(el) {
+			if (!this.isPageVisible()) return;
 			if (!this.page || el.getBoundingClientRect().left >= this.page.scrollWidth) return;
 			const scrollParent = getScrollParent(el);
 			if (scrollParent && scrollParent !== this.pageScrollParent) {
@@ -4461,6 +4489,7 @@
 			if (typeof IntersectionObserver !== "undefined") this.intersectionObserver = new IntersectionObserver((entries) => {
 				entries.forEach((entry) => {
 					const { target, intersectionRatio } = entry;
+					if (!this.isPageVisible()) return;
 					if (intersectionRatio <= 0) this.scrollIntoView(target);
 					this.intersectionObserver?.unobserve(target);
 				});
@@ -4514,6 +4543,17 @@
 			this.content.dispatchEvent(event);
 		}
 		/**
+		* 页面是否可见
+		* @description 页面未挂载、或画布容器被隐藏（如编辑器切到其他面板）时页面不可见；
+		* 蒙层与页面所在的 iframe 挂载在同一容器中，容器隐藏时页面内部元素仍可能是"可见"的，因此额外判断蒙层；
+		* 浏览器 tab 不可见（切到其他标签页、窗口最小化）时同样视为不可见
+		*/
+		isPageVisible() {
+			if (!isDocumentVisible(this.page?.ownerDocument) || !isDocumentVisible(this.wrapper.ownerDocument)) return false;
+			if (!isElementVisible(this.page)) return false;
+			return !this.wrapper.isConnected || isElementVisible(this.wrapper);
+		}
+		/**
 		* 从当前页面同步蒙层宽高，并修正滚动偏移
 		*/
 		syncPageSize() {
@@ -5178,6 +5218,8 @@
 	exports.getScrollParent = getScrollParent;
 	exports.getTargetElStyle = getTargetElStyle;
 	exports.isAbsolute = isAbsolute;
+	exports.isDocumentVisible = isDocumentVisible;
+	exports.isElementVisible = isElementVisible;
 	exports.isFixed = isFixed;
 	exports.isFixedParent = isFixedParent;
 	exports.isMoveableButton = isMoveableButton;

package/package.json

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

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, scrollElementIntoView } from './util';
+import { getScrollParent, isDocumentVisible, isElementVisible, isFixedParent, scrollElementIntoView } from './util';
 
 const wrapperClassName = 'editor-mask-wrapper';
 
@@ -176,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;
 
@@ -235,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);
             }
@@ -310,6 +321,20 @@ 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);
+  }
+
   /**
    * 从当前页面同步蒙层宽高，并修正滚动偏移
    */

package/src/util.ts

@@ -141,6 +141,35 @@ 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 不同，只滚动指定的容器自身，不会连带滚动外层祖先滚动容器，

package/types/index.d.ts

@@ -727,6 +727,11 @@ declare class StageMask extends Rule {
    */
   mount(el: HTMLDivElement): void;
   setLayout(el: HTMLElement): void;
+  /**
+   * 将元素滚动到画布可视区域内
+   * @description 页面不可见时不做滚动：此时滚动既无视觉效果，又会记录错误的滚动偏移
+   * @param el 目标元素
+   */
   scrollIntoView(el: Element): void;
   /**
    * 销毁实例
@@ -744,6 +749,13 @@ declare class StageMask extends Rule {
   private initObserverWrapper;
   private scroll;
   private scrollTo;
+  /**
+   * 页面是否可见
+   * @description 页面未挂载、或画布容器被隐藏（如编辑器切到其他面板）时页面不可见；
+   * 蒙层与页面所在的 iframe 挂载在同一容器中，容器隐藏时页面内部元素仍可能是"可见"的，因此额外判断蒙层；
+   * 浏览器 tab 不可见（切到其他标签页、窗口最小化）时同样视为不可见
+   */
+  private isPageVisible;
   /**
    * 从当前页面同步蒙层宽高，并修正滚动偏移
    */
@@ -1123,6 +1135,20 @@ export declare const isFixed: (style: {
 export declare const isFixedParent: (el: Element) => boolean;
 export declare const getMode: (el: Element) => Mode;
 export declare const getScrollParent: (element: HTMLElement, includeHidden?: boolean) => HTMLElement | null;
+/**
+ * 判断文档是否可见
+ * @description 浏览器 tab 切到后台、窗口最小化时文档 visibilityState 为 hidden；
+ * 只将 hidden 视为不可见，避免 prerender 等中间态被误判
+ * @param doc 目标文档
+ */
+export declare const isDocumentVisible: (doc: Document | null | undefined) => boolean;
+/**
+ * 判断元素是否可见
+ * @description 元素未挂载到文档、或其自身/祖先被 display:none、visibility:hidden 隐藏时视为不可见；
+ * 优先使用浏览器提供的 checkVisibility，不支持时退化为沿祖先链检查计算样式
+ * @param el 目标元素
+ */
+export declare const isElementVisible: (el: Element | null | undefined) => boolean;
 /**
  * 将元素滚动到指定滚动容器的可视区域内（仅垂直方向，滚动最小距离）
  * @description 与原生 scrollIntoView 不同，只滚动指定的容器自身，不会连带滚动外层祖先滚动容器，