@tmagic/editor 1.8.0-manmanyu.8 → 1.8.0

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.0-manmanyu.8",
+  "version": "1.8.0",
   "name": "@tmagic/editor",
   "type": "module",
   "sideEffects": [
@@ -17,6 +17,11 @@
       "import": "./dist/es/index.js",
       "require": "./dist/tmagic-editor.umd.cjs"
     },
+    "./headless": {
+      "types": "./types/headless.d.ts",
+      "import": "./dist/es/headless.js",
+      "require": "./dist/tmagic-editor-headless.umd.cjs"
+    },
     "./dist/style.css": {
       "import": "./dist/style.css",
       "require": "./dist/style.css"
@@ -54,29 +59,29 @@
     "events": "^3.3.0",
     "gesto": "^1.19.4",
     "keycon": "^1.4.0",
-    "lodash-es": "^4.17.21",
+    "lodash-es": "^4.18.1",
     "moveable": "^0.53.0",
-    "serialize-javascript": "^7.0.0",
-    "sortablejs": "^1.15.6",
-    "@tmagic/design": "1.8.0-manmanyu.8",
-    "@tmagic/form": "1.8.0-manmanyu.8",
-    "@tmagic/utils": "1.8.0-manmanyu.8",
-    "@tmagic/table": "1.8.0-manmanyu.8",
-    "@tmagic/stage": "1.8.0-manmanyu.8"
+    "serialize-javascript": "^7.1.1",
+    "sortablejs": "^1.15.7",
+    "@tmagic/design": "1.8.0",
+    "@tmagic/form": "1.8.0",
+    "@tmagic/stage": "1.8.0",
+    "@tmagic/utils": "1.8.0",
+    "@tmagic/table": "1.8.0"
   },
   "devDependencies": {
     "@types/events": "^3.0.3",
-    "@types/lodash-es": "^4.17.4",
+    "@types/lodash-es": "^4.17.12",
     "@types/serialize-javascript": "^5.0.4",
     "@types/sortablejs": "^1.15.9",
-    "@vue/test-utils": "^2.4.6"
+    "@vue/test-utils": "^2.5.1"
   },
   "peerDependencies": {
     "monaco-editor": "^0.55.1 ",
     "type-fest": "^5.2.0",
     "typescript": "^6.0.3",
-    "vue": "^3.5.34",
-    "@tmagic/core": "1.8.0-manmanyu.8"
+    "vue": "^3.5.43",
+    "@tmagic/core": "1.8.0"
   },
   "peerDependenciesMeta": {
     "typescript": {

package/src/Editor.vue

@@ -101,7 +101,6 @@
     <template #props-panel>
       <slot name="props-panel">
         <PropsPanel
-          :extend-state="extendFormState"
           :disabled-show-src="disabledShowSrc"
           @mounted="propsPanelMountedHandler"
           @unmounted="propsPanelUnmountedHandler"
@@ -140,7 +139,9 @@ import { computed, provide } from 'vue';
 
 import type { MApp } from '@tmagic/core';
 import { M_THEME_KEY } from '@tmagic/design';
+import { FORM_CONTEXT_KEY } from '@tmagic/form';
 
+import { useEditorFormContext } from './hooks/use-form-context';
 import Framework from './layouts/Framework.vue';
 import TMagicNavMenu from './layouts/NavMenu.vue';
 import FormPanel from './layouts/props-panel/FormPanel.vue';
@@ -160,7 +161,7 @@ import stageOverlayService from './services/stageOverlay';
 import storageService from './services/storage';
 import uiService from './services/ui';
 import keybindingConfig from './utils/keybinding-config';
-import { defaultEditorProps, EditorProps } from './editorProps';
+import { defaultEditorProps, EditorProps, ENABLE_PROPS_FORM_VALIDATE } from './editorProps';
 import { initServiceEvents, initServiceState } from './initService';
 import type { TreeNodeData } from './type';
 import type { EditorSlots, EventBus, Services, StageOptions } from './type';
@@ -218,6 +219,7 @@ const stageOptions: StageOptions = {
   containerHighlightClassName: props.containerHighlightClassName,
   containerHighlightDuration: props.containerHighlightDuration,
   containerHighlightType: props.containerHighlightType,
+  containerHighlightAddOnly: props.containerHighlightAddOnly,
   disabledDragStart: props.disabledDragStart,
   renderType: props.renderType,
   guidesOptions: props.guidesOptions,
@@ -233,13 +235,28 @@ provide('services', services);
 
 provide('codeOptions', props.codeOptions);
 provide('stageOptions', stageOptions);
+/** 是否启用「属性配置表单校验」联动能力，供 PropsPanel / FormPanel 判断校验失败时是否仍更新节点并记录错误 */
+provide(ENABLE_PROPS_FORM_VALIDATE, props.enablePropsFormValidate ?? false);
 /**
- * 把顶层 `extendFormState` 提供给非 PropsPanel 链路上的组件使用（例如历史差异对话框 HistoryDiffDialog
- * 内部的 CompareForm）。这样所有依赖业务上下文的表单 filterFunction 都能拿到一致的扩展状态，
- * 与 PropsPanel 通过 `:extend-state` 显式传入的方式保持等价。
+ * 编辑器注入给整棵表单树的业务上下文（`services` / `stage`），属性面板、对比表单、
+ * 侧边栏里的嵌套 MForm 都通过 inject 自动继承。
+ *
+ * 业务方要追加自己的字段，在 `<MEditor>` 外层再 `provide(FORM_CONTEXT_KEY, computed(...))`
+ * 即可，配置回调统一通过 `mForm.xxx` 读取。
  */
-provide('extendFormState', props.extendFormState);
+provide(
+  FORM_CONTEXT_KEY,
+  useEditorFormContext(() => services),
+);
 
+// 用 computed 包一层再 provide，否则传下去的是 provide 那一刻的值快照，
+// props.isLargeStageContainer 后续变化不会同步到子孙（如 @tmagic/design/ColorPicker）。
+// 子孙侧 `inject<ComputedRef<boolean>>('isLargeStageContainer', computed(() => false))`
+// 用 `.value` 或模板自动解包读取即可拿到最新值。
+provide(
+  'isLargeStageContainer',
+  computed(() => props.isLargeStageContainer),
+);
 /**
  * 把历史记录面板的自定义扩展 tab 提供给深层的 HistoryListPanel（它挂在 NavMenu 中，
  * 以 markRaw component 形式渲染，无法直接通过 props 透传）。业务方可借此在历史记录

package/src/components/CodeBlockEditor.vue

@@ -4,7 +4,9 @@
     v-model:visible="boxVisible"
     v-model:width="width"
     v-model:height="codeBlockEditorHeight"
+    :body-style="{ padding: '0 16px' }"
     :title="content.name ? `${disabled ? '查看' : '编辑'}${content.name}` : '新增代码'"
+    :framework-width="frameworkWidth"
     :position="boxPosition"
     :before-close="beforeClose"
   >
@@ -206,6 +208,7 @@ const closedHandler = () => {
 
 const parentFloating = inject<Ref<HTMLDivElement | null>>('parentFloating', ref(null));
 const { boxPosition, calcBoxPosition } = useNextFloatBoxPosition(uiService, parentFloating);
+const frameworkWidth = computed(() => uiService.get('frameworkRect')?.width || 0);
 
 watch(boxVisible, (visible) => {
   nextTick(() => {

package/src/components/CodeParams.vue

@@ -15,7 +15,13 @@
 <script lang="ts" setup>
 import { computed, useTemplateRef } from 'vue';
 
-import { type ContainerChangeEventData, type FormItemConfig, type FormValue, MForm } from '@tmagic/form';
+import {
+  type ContainerChangeEventData,
+  defineFormItem,
+  type FormItemConfig,
+  type FormValue,
+  MForm,
+} from '@tmagic/form';
 
 import type { CodeParamStatement } from '@editor/type';
 import { error } from '@editor/utils';
@@ -41,13 +47,13 @@ const emit = defineEmits(['change']);
 const formRef = useTemplateRef<InstanceType<typeof MForm>>('form');
 
 const getFormConfig = (items: FormItemConfig[] = []) => [
-  {
+  defineFormItem({
     type: 'fieldset',
     items,
     legend: '参数',
-    labelWidth: '120px',
+    labelPosition: 'top',
     name: props.name,
-  },
+  }),
 ];
 
 const codeParamsConfig = computed(() =>

package/src/components/CompareForm.vue

@@ -10,104 +10,45 @@
       :is-compare="true"
       :disabled="true"
       :label-width="labelWidth"
-      :extend-state="extendState"
+      :context="formContext"
       :show-diff="showDiff"
+      :self-diff-field-types="selfDiffFieldTypes"
+      :size="size"
     ></MForm>
   </div>
 </template>
 
 <script lang="ts" setup>
-import { computed, inject, provide, type Ref, ref, type ShallowRef, useTemplateRef, watch, watchEffect } from 'vue';
+import { computed, type Ref, type ShallowRef } from 'vue';
 import { isEqual } from 'lodash-es';
 
-import { type CodeBlockContent, type DataSourceSchema, HookType, type MNode } from '@tmagic/core';
-import { type FormConfig, type FormState, type FormValue, MForm } from '@tmagic/form';
+import { type CodeBlockContent, HookType } from '@tmagic/core';
+import { type FormConfig, type FormValue, MForm } from '@tmagic/form';
 
-import { useServices } from '@editor/hooks/use-services';
-import type { CompareCategory, CompareFormLoadConfig, Services } from '@editor/type';
-import { getCodeBlockFormConfig } from '@editor/utils/code-block';
+import { useCompareForm } from '@editor/hooks/use-compare-form';
+import type { CompareFormBaseProps } from '@editor/type';
 
 defineOptions({
   name: 'MEditorCompareForm',
 });
 
 const props = withDefaults(
-  defineProps<{
-    /** 当前值（修改后的值） */
-    value: Partial<MNode> | Partial<DataSourceSchema> | Partial<CodeBlockContent> | Record<string, any>;
-    /** 用于对比的旧值（修改前的值） */
-    lastValue?: Partial<MNode> | Partial<DataSourceSchema> | Partial<CodeBlockContent> | Record<string, any>;
-    /**
-     * 类型说明：
-     * - `category` 为 `node` 时，`type` 为节点组件的类型，例如 'text'、'button'、'page'、'container' 等
-     * - `category` 为 `data-source` 时，`type` 为数据源类型，例如 'base'、'http'
-     * - `category` 为 `code-block` 时，`type` 可不传
-     */
-    type?: string;
-    /** 表单配置类别，决定从哪里取 FormConfig */
-    category?: CompareCategory;
-    /** 数据源代码块场景下的数据源类型（base/http），用于代码块表单中"执行时机"展示 */
-    dataSourceType?: string;
-    labelWidth?: string;
-    /**
-     * 外层容器高度。设置后表单内容超出时会在 CompareForm 内部出现滚动条，
-     * 避免 dialog / 面板使用方需要自行处理滚动。可传任意 CSS 长度，例如 `60vh` / `400px` / `100%`。
-     */
-    height?: string;
-    /**
-     * 用户自定义注入到 MForm.formState 的扩展字段，与 Editor 顶层的 `extendFormState`、
-     * PropsPanel 的 `extend-state` 语义一致。表单 item 的 `display` / `disabled` 等
-     * filterFunction 经常依赖这里注入的字段（如 stage、自定义业务上下文等），
-     * 因此在差异对比场景下也需要透传，避免出现 `formState.xxx is undefined` 的运行时错误。
-     */
-    extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
-    /**
-     * 自定义 FormConfig 加载逻辑。传入后将接管内置的按 `category`(node/data-source/code-block)
-     * 取配置逻辑，调用方可根据业务自行返回（或异步返回）表单配置。可通过
-     * `ctx.defaultLoadConfig()` 复用默认结果再做二次加工。返回的 config 直接用于对比展示。
-     */
-    loadConfig?: CompareFormLoadConfig;
-    /** 编辑器服务集合，由调用方传入（不再通过 inject('services') 获取）。 */
-    services: Services;
-  }>(),
+  defineProps<
+    CompareFormBaseProps & {
+      /** 用于对比的旧值（修改前的值） */
+      lastValue?: CompareFormBaseProps['value'];
+      /** 需要走 self diff 的字段类型（例如 mod-cond）。 */
+      selfDiffFieldTypes?: string[];
+    }
+  >(),
   {
     category: 'node',
     labelWidth: '120px',
-    services: () => useServices(),
   },
 );
 
-const { propsService, dataSourceService, codeBlockService, editorService } = props.services;
-
-provide('services', props.services);
-
-const config = ref<FormConfig>([]);
-
-/** vs-code 编辑器的 monaco 配置项，沿用 Editor 顶层 provide('codeOptions', ...) 的注入。 */
-const codeOptions = inject<Record<string, any>>('codeOptions', {});
-
-/** 将代码块的 content 字段统一成字符串，便于在表单/对比中展示 */
-const normalizeCodeBlockValue = (
-  v: Partial<CodeBlockContent> | Record<string, any> | undefined,
-): Record<string, any> => {
-  if (!v) return {};
-  const next: Record<string, any> = { ...v };
-  if (next.content && typeof next.content !== 'string') {
-    try {
-      next.content = next.content.toString();
-    } catch {
-      next.content = '';
-    }
-  }
-  return next;
-};
-
-const currentValues = computed<FormValue>(() => {
-  if (props.category === 'code-block') {
-    return normalizeCodeBlockValue(props.value as Partial<CodeBlockContent>);
-  }
-  return (props.value || {}) as FormValue;
-});
+const { config, currentValues, wrapperStyle, formContext, loadConfig, formRef, normalizeCodeBlockValue } =
+  useCompareForm(props);
 
 const lastValuesProcessed = computed<FormValue>(() => {
   if (props.category === 'code-block') {
@@ -116,24 +57,11 @@ const lastValuesProcessed = computed<FormValue>(() => {
   return (props.lastValue || {}) as FormValue;
 });
 
-/**
- * 外层包裹层的样式：当传入 `height` 时启用固定高度 + 内部滚动，
- * 这样滚动条会出现在 CompareForm 内部，避免父容器（如 Dialog）自身也产生滚动。
- */
-const wrapperStyle = computed(() => {
-  if (!props.height) return undefined;
-  return {
-    height: props.height,
-    overflow: 'auto',
-  } as Record<string, string>;
-});
-
 /**
  * `code-select` 字段在历史数据中存在两种"语义为空"的形态：
  * - 字符串 `''`（旧数据 / 用户从未配置过钩子）；
- * - `{ hookType: HookType.CODE, hookData: [] }`（CodeSelect.vue 在挂载时
- *   写入的默认结构，参见 packages/editor/src/fields/CodeSelect.vue 中
- *   `props.model[props.name] = { hookType: HookType.CODE, hookData: [] }`）。
+ * - `{ hookType: HookType.CODE, hookData: [] }`（`normalizeCodeSelectValue`
+ *   写入的默认结构）。
  *
  * 直接 `isEqual` 会把两者判为不等，从而在历史对比里对每个未配置过钩子的组件
  * 都展示一份"差异"，体验很糟糕。这里把它们视为相等，跳过对比。
@@ -156,104 +84,6 @@ const showDiff = ({ curValue, lastValue, config }: { curValue: any; lastValue: a
   return !isEqual(curValue, lastValue);
 };
 
-const removeStyleDisplayConfig = (formConfig: FormConfig): FormConfig =>
-  formConfig.map((item) => {
-    if (!('type' in item)) return item;
-    if (item?.type !== 'tab' || !Array.isArray(item.items)) return item;
-
-    return {
-      ...item,
-      items: item.items.map((tabPane) => {
-        if (tabPane?.title !== '样式' || !Array.isArray(tabPane.items)) return tabPane;
-
-        return {
-          ...tabPane,
-          display: true,
-        };
-      }),
-    };
-  });
-
-/**
- * 内置的默认 FormConfig 加载逻辑：按 `category` 从对应 service / 工具取配置。
- * 作为 ctx.defaultLoadConfig 透传给自定义 `loadConfig`，方便复用与二次加工。
- */
-const defaultLoadConfig = async (): Promise<FormConfig> => {
-  switch (props.category) {
-    case 'node': {
-      if (!props.type) {
-        return [];
-      }
-      return removeStyleDisplayConfig(
-        await propsService.getPropsConfig(props.type, { node: props.value as unknown as MNode }),
-      );
-    }
-    case 'data-source': {
-      const config = dataSourceService.getFormConfig(props.type || 'base');
-      // 数据源表单外层 tab 的「数据定义」项 status 为 'fields'，tab-pane name 随之为 'fields'。
-      // 未显式设置 active 时，Tabs 默认取 '0'，与 'fields' 不匹配会导致打开弹窗时无默认激活项，
-      // 这里与 DataSourceConfigPanel 保持一致，默认激活「数据定义」tab。
-      return config.map((item) => ('type' in item && item.type === 'tab' ? { ...item, active: 'fields' } : item));
-    }
-    case 'code-block': {
-      return getCodeBlockFormConfig({
-        paramColConfig: codeBlockService.getParamsColConfig(),
-        // 通过传入 dataSourceType 间接表达"是数据源代码块"——在对比场景下 props.dataSourceType
-        // 由调用方按 step 上下文显式传入，未传则视为普通代码块，「执行时机」字段隐藏。
-        isDataSource: () => Boolean(props.dataSourceType),
-        dataSourceType: () => props.dataSourceType,
-        codeOptions,
-        // 对比模式只读，不需要校验/语法检查
-        editable: false,
-      });
-    }
-    default:
-      return [];
-  }
-};
-
-const loadConfig = async () => {
-  if (props.loadConfig) {
-    config.value = await props.loadConfig({
-      category: props.category,
-      type: props.type,
-      dataSourceType: props.dataSourceType,
-      defaultLoadConfig,
-    });
-    return;
-  }
-
-  config.value = await defaultLoadConfig();
-};
-
-watch(
-  [() => props.category, () => props.type, () => props.dataSourceType, () => props.loadConfig],
-  () => {
-    loadConfig();
-  },
-  { immediate: true },
-);
-
-const formRef = useTemplateRef<InstanceType<typeof MForm>>('form');
-
-/**
- * 把 services / stage 注入 MForm 的 formState，避免 propsService 注入的表单配置中
- * 形如 `display: ({ services }) => services.uiService.get(...)` 的 filterFunction
- * 在执行时拿不到 `formState.services` 而报错。
- *
- * 与 props-panel/FormPanel.vue 中的注入方式保持一致：
- * - services：整个 useServices() 返回的服务集合；
- * - stage：当前 editorService.get('stage') 的最新值。
- */
-const stage = computed(() => editorService.get('stage'));
-
-watchEffect(() => {
-  if (formRef.value) {
-    formRef.value.formState.stage = stage.value;
-    formRef.value.formState.services = props.services;
-  }
-});
-
 defineExpose<{
   form: ShallowRef<InstanceType<typeof MForm> | null>;
   config: Ref<FormConfig>;

package/src/components/ContentMenu.vue

@@ -128,20 +128,42 @@ const outsideClickHideHandler = (e: MouseEvent) => {
   hide();
 };
 
-const setPosition = (e: { clientY: number; clientX: number }) => {
-  const menuHeight = menuEl.value?.clientHeight || 0;
+// 根据菜单实际尺寸修正位置，避免超出可视范围
+const fixPosition = () => {
+  const menu = menuEl.value;
+  if (!menu || !visible.value) return;
+
+  const menuHeight = menu.clientHeight;
+  const menuWidth = menu.clientWidth;
+
+  let { top, left } = menuPosition.value;
+
+  if (top + menuHeight > document.body.clientHeight) {
+    top = Math.max(0, document.body.clientHeight - menuHeight);
+  }
+
+  if (left + menuWidth > document.body.clientWidth) {
+    left = Math.max(0, document.body.clientWidth - menuWidth);
+  }
 
-  let top = e.clientY;
-  if (menuHeight + e.clientY > document.body.clientHeight) {
-    top = document.body.clientHeight - menuHeight;
+  if (top !== menuPosition.value.top || left !== menuPosition.value.left) {
+    menuPosition.value = { top, left };
   }
+};
 
+const setPosition = (e: { clientY: number; clientX: number }) => {
   menuPosition.value = {
-    top,
+    top: e.clientY,
     left: e.clientX,
   };
+  fixPosition();
 };
 
+// 菜单大小动态变化（如菜单项更新）后重新修正位置
+const resizeObserver = new ResizeObserver(() => {
+  fixPosition();
+});
+
 const show = (e?: { clientY: number; clientX: number }) => {
   visible.value = true;
 
@@ -186,12 +208,18 @@ const mouseenterHandler = () => {
 };
 
 onMounted(() => {
+  if (menuEl.value) {
+    resizeObserver.observe(menuEl.value);
+  }
+
   if (props.isSubMenu) return;
 
   globalThis.addEventListener('mousedown', outsideClickHideHandler, true);
 });
 
 onBeforeUnmount(() => {
+  resizeObserver.disconnect();
+
   if (props.isSubMenu) return;
 
   globalThis.removeEventListener('mousedown', outsideClickHideHandler, true);

package/src/components/FloatingBox.vue

@@ -3,6 +3,7 @@
     <div
       ref="target"
       :class="['m-editor-float-box', themeClass]"
+      v-bind="$attrs"
       :style="{ ...style, zIndex: curZIndex }"
       @mousedown="nextZIndex"
     >
@@ -14,7 +15,7 @@
           <TMagicButton link size="small" @click="closeHandler"><MIcon :icon="Close"></MIcon></TMagicButton>
         </div>
       </div>
-      <div class="m-editor-float-box-body" :style="{ height: `${bodyHeight}px` }">
+      <div class="m-editor-float-box-body" :style="{ height: `${bodyHeight}px`, ...bodyStyle }">
         <slot name="body"></slot>
       </div>
     </div>
@@ -22,14 +23,13 @@
 </template>
 
 <script setup lang="ts">
-import { computed, nextTick, onBeforeUnmount, provide, ref, useTemplateRef, watch } from 'vue';
+import { computed, type CSSProperties, nextTick, onBeforeUnmount, provide, ref, useTemplateRef, watch } from 'vue';
 import { Close } from '@element-plus/icons-vue';
 import VanillaMoveable from 'moveable';
 
 import { TMagicButton, useThemeClass, useZIndex } from '@tmagic/design';
 
 import MIcon from '@editor/components/Icon.vue';
-import { useServices } from '@editor/hooks/use-services';
 
 interface Position {
   left: number;
@@ -44,11 +44,18 @@ const props = withDefaults(
   defineProps<{
     position?: Position;
     title?: string;
+    bodyStyle?: CSSProperties;
+    /** 浮窗初始样式，会与内部计算样式合并，外部传入优先 */
+    initialStyle?: CSSProperties;
+    /** 用于约束浮窗 left 的容器宽度，传入时按宽度收敛 left，避免超出右边界；默认取视窗宽度 */
+    frameworkWidth?: number;
     beforeClose?: (_done: (_cancel?: boolean) => void) => void;
   }>(),
   {
     title: '',
     position: () => ({ left: 0, top: 0 }),
+    initialStyle: () => ({}),
+    frameworkWidth: 0,
   },
 );
 
@@ -77,12 +84,11 @@ const bodyHeight = computed(() => {
   return 'auto';
 });
 
-const { uiService } = useServices();
-const frameworkWidth = computed(() => uiService.get('frameworkRect').width || 0);
 const style = computed(() => {
   let { left } = props.position;
-  if (width.value) {
-    left = left + width.value > frameworkWidth.value ? frameworkWidth.value - width.value : left;
+  const frameworkWidth = props.frameworkWidth || globalThis.window?.innerWidth || 0;
+  if (width.value && frameworkWidth) {
+    left = left + width.value > frameworkWidth ? frameworkWidth - width.value : left;
   }
 
   return {
@@ -90,11 +96,60 @@ const style = computed(() => {
     top: `${props.position.top}px`,
     width: width.value ? `${width.value}px` : 'auto',
     height: height.value ? `${height.value}px` : 'auto',
+    ...props.initialStyle,
   };
 });
 
 let moveable: VanillaMoveable | null = null;
 
+// 拖拽/缩放时用于覆盖 iframe 的遮罩，防止鼠标进入 iframe 区域后事件被 iframe 吞掉导致拖拽丢失
+let dragMask: HTMLDivElement | null = null;
+let dragMaskVisible = false;
+
+// 兜底：正常情况下遮罩由 moveable 的 dragEnd/resizeEnd 移除；但某些极端场景
+// （拖拽中鼠标移出窗口后松开、alt-tab 切走窗口失焦、标签页被隐藏等）结束事件不会触发，
+// 会导致全屏透明遮罩残留、整个编辑器无法点击。这里挂全局 pointerup/blur/visibilitychange 强制收尾。
+const bindDragMaskSafety = () => {
+  globalThis.window?.addEventListener('pointerup', hideDragMask, true);
+  globalThis.window?.addEventListener('blur', hideDragMask);
+  globalThis.document?.addEventListener('visibilitychange', hideDragMask);
+};
+
+const unbindDragMaskSafety = () => {
+  globalThis.window?.removeEventListener('pointerup', hideDragMask, true);
+  globalThis.window?.removeEventListener('blur', hideDragMask);
+  globalThis.document?.removeEventListener('visibilitychange', hideDragMask);
+};
+
+const showDragMask = () => {
+  if (dragMaskVisible) {
+    return;
+  }
+  if (!dragMask) {
+    dragMask = globalThis.document.createElement('div');
+    dragMask.className = 'm-editor-float-box-drag-mask';
+  }
+  globalThis.document.body.appendChild(dragMask);
+  dragMaskVisible = true;
+  bindDragMaskSafety();
+
+  // 拖拽标题时，root 上的 @mousedown="nextZIndex" 会把浮窗 z-index 抬高，
+  // 若此时才读取会拿到旧值导致遮罩被浮窗（及其内部 iframe）盖住，故用 nextTick 在 z-index 稳定后再设置到浮窗之上
+  const setMaskZIndex = () => {
+    if (dragMask) {
+      dragMask.style.zIndex = `${curZIndex.value + 1}`;
+    }
+  };
+  setMaskZIndex();
+  nextTick(setMaskZIndex);
+};
+
+const hideDragMask = () => {
+  unbindDragMaskSafety();
+  dragMask?.parentNode?.removeChild(dragMask);
+  dragMaskVisible = false;
+};
+
 const initMoveable = () => {
   moveable = new VanillaMoveable(globalThis.document.body, {
     className: 'm-editor-floating-box-moveable',
@@ -112,6 +167,14 @@ const initMoveable = () => {
     bounds: { left: 0, top: 0, right: 0, bottom: 0, position: 'css' },
   });
 
+  // 仅在真正发生拖拽/缩放位移时插入遮罩：moveable 的 dragStart/resizeStart 在 mousedown 时即触发，
+  // 若此时就盖遮罩，会盖住浮窗本身导致 mouseup 落在遮罩上、关闭按钮的 click 无法触发（点击关闭不了）。
+  // 改为在 drag/resize（实际位移）时才显示，纯点击不再触发遮罩。
+  moveable.on('drag', showDragMask);
+  moveable.on('resize', showDragMask);
+  moveable.on('dragEnd', hideDragMask);
+  moveable.on('resizeEnd', hideDragMask);
+
   moveable.on('drag', (e) => {
     e.target.style.transform = e.transform;
   });
@@ -126,6 +189,7 @@ const initMoveable = () => {
 };
 
 const destroyMoveable = () => {
+  hideDragMask();
   moveable?.destroy();
   moveable = null;
 };