@tmagic/editor 1.7.13-beta.0 → 1.7.14-beta.0

package/src/editorProps.ts

@@ -11,6 +11,7 @@ import StageCore, {
 import { getIdFromEl } from '@tmagic/utils';
 
 import type {
+  CanDropInFunction,
   ComponentGroup,
   CustomContentMenuFunction,
   DatasourceTypeOption,
@@ -21,6 +22,7 @@ import type {
   PageBarSortOptions,
   SideBarData,
   StageRect,
+  TreeNodeData,
 } from './type';
 
 export interface EditorProps {
@@ -75,6 +77,11 @@ export interface EditorProps {
   guidesOptions?: Partial<GuidesOptions>;
   /** 禁止多选 */
   disabledMultiSelect?: boolean;
+  /**
+   * 始终启用多选模式：开启后无需按住 Ctrl/Meta，点击即多选；
+   * 默认 false。当 `disabledMultiSelect` 为 true 时本配置失效
+   */
+  alwaysMultiSelect?: boolean;
   /** 禁用页面片 */
   disabledPageFragment?: boolean;
   /** 禁用双击在浮层中单独编辑选中组件 */
@@ -101,8 +108,20 @@ export interface EditorProps {
   customContentMenu?: CustomContentMenuFunction;
   /** 用于自定义判断组件树节点是否可展开（即是否要展示为拥有子节点的形态） */
   layerNodeIsExpandable?: IsExpandableFunction;
+  /**
+   * 用于自定义判断当前正在拖动的源是否可以拖入目标节点内部
+   *
+   * 同时覆盖以下两类场景，通过第三个参数 scene 区分：
+   * - `'layer'` ："已选组件"面板组件树拖动（返回 false 时仅禁用 inner，不影响 before/after）
+   * - `'stage'`：画布拖入组件（返回 false 时阻止该容器被高亮命中；适用于"组件列表拖入新组件"和"画布上拖动已有组件"两种细分情况）
+   *
+   * 注意：layer 场景目前只识别同步返回值；返回 Promise 时会按 true 处理（即允许）
+   */
+  canDropIn?: CanDropInFunction;
   /** 画布双击前的钩子函数，返回 false 则阻止默认的双击行为 */
   beforeDblclick?: (event: MouseEvent) => Promise<boolean | void> | boolean | void;
+  /** 组件树节点双击前的钩子函数，返回 false 则阻止默认的双击行为 */
+  beforeLayerNodeDblclick?: (event: MouseEvent, data: TreeNodeData) => Promise<boolean | void> | boolean | void;
   extendFormState?: (state: FormState) => Record<string, any> | Promise<Record<string, any>>;
   /** 页面顺序拖拽配置参数 */
   pageBarSortOptions?: PageBarSortOptions;
@@ -113,6 +132,7 @@ export interface EditorProps {
 export const defaultEditorProps = {
   renderType: RenderType.IFRAME,
   disabledMultiSelect: false,
+  alwaysMultiSelect: false,
   disabledPageFragment: false,
   disabledStageOverlay: false,
   containerHighlightClassName: CONTAINER_HIGHLIGHT_CLASS_NAME,

package/src/hooks/use-stage.ts

@@ -24,6 +24,7 @@ export const useStage = (stageOptions: StageOptions) => {
     zoom: stageOptions.zoom ?? zoom.value,
     autoScrollIntoView: stageOptions.autoScrollIntoView,
     isContainer: stageOptions.isContainer,
+    canDropIn: stageOptions.canDropIn,
     containerHighlightClassName: stageOptions.containerHighlightClassName,
     containerHighlightDuration: stageOptions.containerHighlightDuration,
     containerHighlightType: stageOptions.containerHighlightType,
@@ -45,6 +46,7 @@ export const useStage = (stageOptions: StageOptions) => {
     updateDragEl: stageOptions.updateDragEl,
     guidesOptions: stageOptions.guidesOptions,
     disabledMultiSelect: stageOptions.disabledMultiSelect,
+    alwaysMultiSelect: stageOptions.alwaysMultiSelect,
     disabledRule: stageOptions.disabledRule,
   });
 
@@ -59,6 +61,13 @@ export const useStage = (stageOptions: StageOptions) => {
     },
   );
 
+  watch(
+    () => editorService.get('alwaysMultiSelect'),
+    (alwaysMultiSelect) => {
+      stage.setAlwaysMultiSelect(Boolean(alwaysMultiSelect));
+    },
+  );
+
   const hGuidesCache = getGuideLineFromCache(getGuideLineKey(H_GUIDE_LINE_STORAGE_KEY));
   const vGuidesCache = getGuideLineFromCache(getGuideLineKey(V_GUIDE_LINE_STORAGE_KEY));
 

package/src/initService.ts

@@ -72,6 +72,16 @@ export const initServiceState = (
     },
   );
 
+  watch(
+    () => props.alwaysMultiSelect,
+    (alwaysMultiSelect) => {
+      editorService.set('alwaysMultiSelect', alwaysMultiSelect || false);
+    },
+    {
+      immediate: true,
+    },
+  );
+
   watch(
     () => props.componentGroupList,
     (componentGroupList) => componentGroupList && componentListService.setList(componentGroupList),

package/src/layouts/sidebar/Sidebar.vue

@@ -162,6 +162,7 @@ import { useEditorContentHeight } from '@editor/hooks/use-editor-content-height'
 import { useFloatBox } from '@editor/hooks/use-float-box';
 import { useServices } from '@editor/hooks/use-services';
 import {
+  type CanDropInFunction,
   ColumnLayout,
   CustomContentMenuFunction,
   type IsExpandableFunction,
@@ -172,6 +173,7 @@ import {
   type SideComponent,
   type SideItem,
   SideItemKey,
+  type TreeNodeData,
 } from '@editor/type';
 
 import CodeBlockListPanel from './code-block/CodeBlockListPanel.vue';
@@ -185,6 +187,10 @@ defineOptions({
   name: 'MEditorSidebar',
 });
 
+const emit = defineEmits<{
+  'layer-node-dblclick': [event: MouseEvent, data: TreeNodeData];
+}>();
+
 const props = withDefaults(
   defineProps<{
     data?: SideBarData;
@@ -194,6 +200,10 @@ const props = withDefaults(
     customContentMenu: CustomContentMenuFunction;
     /** 自定义判断组件树节点是否可展开（即是否要展示为拥有子节点的形态）的函数 */
     layerNodeIsExpandable?: IsExpandableFunction;
+    /** 自定义判断当前正在拖动的源是否可以拖入目标节点内部，详见 EditorProps.canDropIn */
+    canDropIn?: CanDropInFunction;
+    /** 组件树节点双击前的钩子函数，返回 false 则阻止默认的双击行为 */
+    beforeLayerNodeDblclick?: (_event: MouseEvent, _data: TreeNodeData) => Promise<boolean | void> | boolean | void;
   }>(),
   {
     data: () => ({
@@ -252,6 +262,11 @@ const getItemConfig = (data: SideItem): SideComponent => {
         indent: props.indent,
         nextLevelIndentIncrement: props.nextLevelIndentIncrement,
         isExpandable: props.layerNodeIsExpandable,
+        canDropIn: props.canDropIn,
+        beforeNodeDblclick: props.beforeLayerNodeDblclick,
+      },
+      listeners: {
+        'node-dblclick': (event: MouseEvent, nodeData: TreeNodeData) => emit('layer-node-dblclick', event, nodeData),
       },
       component: LayerPanel,
       slots: {},

package/src/layouts/sidebar/layer/LayerPanel.vue

@@ -20,6 +20,7 @@
       @node-contextmenu="nodeContentMenuHandler"
       @node-mouseenter="mouseenterHandler"
       @node-click="nodeClickHandler"
+      @node-dblclick="dblclickHandler"
     >
       <template #tree-node-content="{ data: nodeData }">
         <slot name="layer-node-content" :data="nodeData"> </slot>
@@ -58,6 +59,7 @@ import Tree from '@editor/components/Tree.vue';
 import { useFilter } from '@editor/hooks/use-filter';
 import { useServices } from '@editor/hooks/use-services';
 import type {
+  CanDropInFunction,
   CustomContentMenuFunction,
   IsExpandableFunction,
   LayerPanelSlots,
@@ -79,13 +81,21 @@ defineOptions({
   name: 'MEditorLayerPanel',
 });
 
-defineProps<{
+const props = defineProps<{
   layerContentMenu: (MenuButton | MenuComponent)[];
   indent?: number;
   nextLevelIndentIncrement?: number;
   customContentMenu: CustomContentMenuFunction;
   /** 自定义判断组件树节点是否可展开（即是否要展示为拥有子节点的形态）的函数 */
   isExpandable?: IsExpandableFunction;
+  /** 自定义判断当前拖动节点是否可以拖入目标节点内部的函数，返回 false 则禁止拖入 */
+  canDropIn?: CanDropInFunction;
+  /** 组件树节点双击前的钩子函数，返回 false 则阻止默认的双击行为 */
+  beforeNodeDblclick?: (_event: MouseEvent, _data: TreeNodeData) => Promise<boolean | void> | boolean | void;
+}>();
+
+const emit = defineEmits<{
+  'node-dblclick': [event: MouseEvent, data: TreeNodeData];
 }>();
 
 const services = useServices();
@@ -123,13 +133,27 @@ const collapseAllHandler = () => {
   }
 };
 
-const { handleDragStart, handleDragEnd, handleDragLeave, handleDragOver } = useDrag(services);
+const { handleDragStart, handleDragEnd, handleDragLeave, handleDragOver } = useDrag(services, {
+  canDropIn: (sourceIds, targetId) => props.canDropIn?.(sourceIds, targetId, 'layer'),
+});
 
 // 右键菜单
 const menuRef = useTemplateRef<InstanceType<typeof LayerMenu>>('menu');
 const {
   nodeClickHandler,
+  nodeDblclickHandler,
   nodeContentMenuHandler,
   highlightHandler: mouseenterHandler,
 } = useClick(services, isCtrlKeyDown, nodeStatusMap, menuRef);
+
+const dblclickHandler = async (event: MouseEvent, data: TreeNodeData) => {
+  if (props.beforeNodeDblclick) {
+    const result = await props.beforeNodeDblclick(event, data);
+    if (result === false) return;
+  }
+
+  nodeDblclickHandler(event, data);
+
+  emit('node-dblclick', event, data);
+};
 </script>

package/src/layouts/sidebar/layer/use-click.ts

@@ -2,7 +2,7 @@ import { computed, type ComputedRef, nextTick, type Ref, type ShallowRef } from
 import { throttle } from 'lodash-es';
 
 import { Id, MNode } from '@tmagic/core';
-import { isPage, isPageFragment } from '@tmagic/utils';
+import { getElById, isPage, isPageFragment } from '@tmagic/utils';
 
 import type { LayerNodeStatus, Services, TreeNodeData } from '@editor/type';
 import { UI_SELECT_MODE_EVENT_NAME } from '@editor/utils/const';
@@ -16,7 +16,9 @@ export const useClick = (
   nodeStatusMap: ComputedRef<Map<Id, LayerNodeStatus> | undefined>,
   menuRef: ShallowRef<InstanceType<typeof LayerMenu> | null>,
 ) => {
-  const isMultiSelect = computed(() => isCtrlKeyDown.value && !editorService.get('disabledMultiSelect'));
+  const isMultiSelect = computed(
+    () => !editorService.get('disabledMultiSelect') && (isCtrlKeyDown.value || editorService.get('alwaysMultiSelect')),
+  );
 
   // 触发画布选中
   const select = async (data: MNode) => {
@@ -81,6 +83,19 @@ export const useClick = (
     stageOverlayService.get('stage')?.highlight(data.id);
   };
 
+  const isNodeCanSelect = async (data: TreeNodeData) => {
+    const canSelect = stageOverlayService.get('stageOptions')?.canSelect;
+    if (!canSelect) return true;
+
+    const doc = editorService.get('stage')?.renderer?.contentWindow?.document;
+    if (!doc) return true;
+
+    const el = getElById()(doc, data.id);
+    if (!el) return true;
+
+    return Boolean(await canSelect(el));
+  };
+
   const nodeClickHandler = (event: MouseEvent, data: TreeNodeData): void => {
     if (!nodeStatusMap?.value) return;
 
@@ -95,16 +110,34 @@ export const useClick = (
       });
     }
 
-    nextTick(() => {
+    nextTick(async () => {
+      if (!(await isNodeCanSelect(data))) return;
+
       select(data);
     });
   };
 
+  const nodeDblclickHandler = (event: MouseEvent, data: TreeNodeData): void => {
+    if (!nodeStatusMap?.value) return;
+
+    if (uiService.get('uiSelectMode')) return;
+
+    // 双击切换展开/收起状态
+    if (data.items && data.items.length > 0) {
+      const status = nodeStatusMap.value.get(data.id);
+      updateStatus(nodeStatusMap.value, data.id, {
+        expand: !status?.expand,
+      });
+    }
+  };
+
   return {
     menuRef,
 
     nodeClickHandler,
 
+    nodeDblclickHandler,
+
     nodeContentMenuHandler(event: MouseEvent, data: TreeNodeData): void {
       event.preventDefault();
 

package/src/layouts/sidebar/layer/use-drag.ts

@@ -11,6 +11,8 @@ const dragState: {
   dropType: NodeDropType | '';
   container: HTMLElement | null;
   nodeId?: Id;
+  /** canDropIn 返回 Id 时记录的重定向目标 id，handleDragEnd 阶段会改用该 id 对应的节点作为 inner 拖入的父节点 */
+  redirectedTargetId?: Id;
 } = {
   dragOverNodeId: '',
   dropType: '',
@@ -37,12 +39,22 @@ const removeStatusClass = (el: HTMLElement | null) => {
   });
 };
 
+export interface UseDragOptions {
+  /**
+   * 用于判断某个节点是否能被拖动到另一个节点内部
+   * - 返回 `false`：阻止 inner 拖入（before/after 仍然可用）
+   * - 返回 `Id`：将 inner 拖入的目标重定向到该 id 对应的节点
+   * - 其他：按原 targetId 正常拖入
+   */
+  canDropIn?: (sourceIds: Id[], targetId: Id) => Id | boolean | void;
+}
+
 /**
  * dragstart/dragleave/dragend 属于源节点
  * dragover 属于目标节点
  * 这些方法并不是同一个dom事件触发的
  */
-export const useDrag = ({ editorService }: Services) => {
+export const useDrag = ({ editorService }: Services, options: UseDragOptions = {}) => {
   const handleDragStart = (event: DragEvent) => {
     if (!event.dataTransfer || !event.target || !event.currentTarget) return;
 
@@ -102,13 +114,43 @@ export const useDrag = ({ editorService }: Services) => {
       }
     }
 
-    if (distance < targetHeight / 3) {
+    // 通过用户配置的钩子判断当前拖动节点是否允许拖入目标节点内部
+    //   - false：禁止 inner 拖入
+    //   - Id   ：将 inner 拖入的父节点重定向为该 id 对应的节点
+    //   - 其他：按原 targetNodeId 正常拖入
+    let canDropInTarget = isContainer;
+    let redirectedTargetId: Id | undefined;
+    if (canDropInTarget && options.canDropIn && nodeId && targetNodeId !== nodeId) {
+      const result = options.canDropIn([nodeId], targetNodeId);
+      if (result === false) {
+        canDropInTarget = false;
+      } else if (typeof result === 'string' || typeof result === 'number') {
+        redirectedTargetId = result;
+      }
+    }
+
+    // before/after 模式下新节点会成为 target 的兄弟（即 target 的直接父节点的子节点），
+    // 所以应该用 target 的直接父节点 id 再次调用 canDropIn 校验。
+    // 若该父节点禁止拖入（false）或要求重定向（Id），都视为"不应放入此父节点"，
+    // 故对应的 before/after 也禁用——避免绕过 inner 限制。
+    let canDropAsSibling = true;
+    const directParentId = parentsId?.[parentsId.length - 1];
+    if (options.canDropIn && nodeId && directParentId && directParentId !== nodeId) {
+      const siblingResult = options.canDropIn([nodeId], directParentId);
+      if (siblingResult === false || typeof siblingResult === 'string' || typeof siblingResult === 'number') {
+        canDropAsSibling = false;
+      }
+    }
+
+    // 显式重置 dropType，避免上一次 dragover 的残留值影响本次判断
+    dragState.dropType = '';
+    if (distance < targetHeight / 3 && canDropAsSibling) {
       dragState.dropType = 'before';
       addClassName(labelEl, globalThis.document, 'drag-before');
-    } else if (distance > (targetHeight * 2) / 3) {
+    } else if (distance > (targetHeight * 2) / 3 && canDropAsSibling) {
       dragState.dropType = 'after';
       addClassName(labelEl, globalThis.document, 'drag-after');
-    } else if (isContainer) {
+    } else if (canDropInTarget) {
       dragState.dropType = 'inner';
       addClassName(labelEl, globalThis.document, 'drag-inner');
     }
@@ -119,6 +161,8 @@ export const useDrag = ({ editorService }: Services) => {
 
     dragState.dragOverNodeId = targetNodeId;
     dragState.container = event.currentTarget as HTMLElement;
+    // 仅 inner 时才使用重定向，before/after 是相对于 dragOverNodeId 的兄弟插入，重定向无意义
+    dragState.redirectedTargetId = dragState.dropType === 'inner' ? redirectedTargetId : undefined;
 
     event.preventDefault();
   };
@@ -158,8 +202,19 @@ export const useDrag = ({ editorService }: Services) => {
       let targetIndex = -1;
 
       if (Array.isArray(targetNode.items) && dragState.dropType === 'inner') {
-        targetIndex = targetNode.items.length;
-        targetParent = targetNode as MContainer;
+        // 优先使用 canDropIn 返回的重定向 id 对应的节点作为父节点
+        if (dragState.redirectedTargetId !== undefined) {
+          const redirectedNode = editorService.getNodeInfo(dragState.redirectedTargetId, false).node;
+          if (!redirectedNode || !Array.isArray((redirectedNode as MContainer).items)) {
+            // 重定向目标无效或不是容器，放弃此次拖入
+            return;
+          }
+          targetParent = redirectedNode as MContainer;
+          targetIndex = (redirectedNode as MContainer).items!.length;
+        } else {
+          targetIndex = targetNode.items.length;
+          targetParent = targetNode as MContainer;
+        }
       } else {
         targetIndex = getNodeIndex(dragState.dragOverNodeId, targetParent);
       }
@@ -180,6 +235,7 @@ export const useDrag = ({ editorService }: Services) => {
     dragState.dragOverNodeId = '';
     dragState.dropType = '';
     dragState.container = null;
+    dragState.redirectedTargetId = undefined;
   };
 
   return {

package/src/layouts/workspace/viewer/Stage.vue

@@ -317,12 +317,34 @@ const dropHandler = async (e: DragEvent) => {
   );
 
   let parent: MContainer | undefined | null = page.value;
+  let resolvedParentEl: HTMLElement | null | undefined = parentEl;
   const parentId = getIdFromEl()(parentEl);
   if (parentId) {
     parent = editorService.getNodeById(parentId, false) as MContainer;
   }
 
   if (parent && stageContainerEl.value && stage) {
+    // 通过用户配置的钩子再次确认当前拖入的新组件是否允许放入命中的高亮容器，
+    // 防止 delayedMarkContainer 的延迟/异步未生效或残留高亮导致命中错误容器
+    //   - 返回 false：取消此次拖入
+    //   - 返回 Id  ：将父节点重定向到该 id 对应的节点（layout 坐标也基于其 DOM 重新计算）
+    //   - 其他    ：使用原命中节点
+    // 从组件列表拖入新组件时 sourceIds 为空数组（尚无 id）
+    if (props.stageOptions.canDropIn) {
+      const result = props.stageOptions.canDropIn([], parent.id);
+      if (result === false) {
+        return;
+      }
+      if (typeof result === 'string' || typeof result === 'number') {
+        const redirectedNode = editorService.getNodeById(result, false) as MContainer | undefined;
+        if (!redirectedNode) {
+          return;
+        }
+        parent = redirectedNode;
+        resolvedParentEl = stage.renderer?.getTargetElement(result) ?? null;
+      }
+    }
+
     const layout = await editorService.getLayout(parent);
 
     const containerRect = stageContainerEl.value.getBoundingClientRect();
@@ -342,8 +364,8 @@ const dropHandler = async (e: DragEvent) => {
       top = e.clientY - containerRect.top + scrollTop;
       left = e.clientX - containerRect.left + scrollLeft;
 
-      if (parentEl) {
-        const { left: parentLeft, top: parentTop } = getOffset(parentEl);
+      if (resolvedParentEl) {
+        const { left: parentLeft, top: parentTop } = getOffset(resolvedParentEl);
         left = left - parentLeft * zoom.value;
         top = top - parentTop * zoom.value;
       }

package/src/services/editor.ts

@@ -79,6 +79,7 @@ class Editor extends BaseService {
     pageLength: 0,
     pageFragmentLength: 0,
     disabledMultiSelect: false,
+    alwaysMultiSelect: false,
   });
   private isHistoryStateChange = false;
   private selectionBeforeOp: Id[] | null = null;

package/src/services/props.ts

@@ -93,6 +93,10 @@ class Props extends BaseService {
     this.emit('props-configs-change');
   }
 
+  public getPropsConfigs(): Record<string, FormConfig> {
+    return this.state.propsConfigMap;
+  }
+
   public async fillConfig(config: FormConfig, labelWidth?: string) {
     return fillConfig(config, {
       labelWidth: typeof labelWidth !== 'function' ? labelWidth : '80px',
@@ -125,12 +129,20 @@ class Props extends BaseService {
     return cloneDeep(this.state.propsConfigMap[toLine(type)] || (await this.fillConfig([])));
   }
 
+  public hasPropsConfig(type: string): boolean {
+    return !!this.state.propsConfigMap[toLine(type)];
+  }
+
   public setPropsValues(values: Record<string, Partial<MNode> | PropsFormValueFunction>) {
     Object.keys(values).forEach((type: string) => {
       this.setPropsValue(toLine(type), values[type]);
     });
   }
 
+  public getPropsValues(): Record<string, Partial<MNode>> {
+    return this.state.propsValueMap;
+  }
+
   /**
    * 为指点类型组件设置组件初始值
    * @param type 组件类型
@@ -178,6 +190,10 @@ class Props extends BaseService {
     };
   }
 
+  public hasPropsValue(type: string): boolean {
+    return !!this.state.propsValueMap[toLine(type)];
+  }
+
   public createId(type: string | number): string {
     return `${type}_${guid()}`;
   }

package/src/type.ts

@@ -26,6 +26,7 @@ import type { CodeBlockContent, CodeBlockDSL, Id, MApp, MContainer, MNode, MPage
 import type { ChangeRecord, FormConfig, TableColumnConfig, TypeFunction } from '@tmagic/form';
 import type StageCore from '@tmagic/stage';
 import type {
+  CanDropIn,
   ContainerHighlightType,
   CustomizeMoveableOptions,
   GuidesOptions,
@@ -168,10 +169,23 @@ export interface StageOptions {
   moveableOptions?: CustomizeMoveableOptions;
   canSelect?: (el: HTMLElement) => boolean | Promise<boolean>;
   isContainer?: (el: HTMLElement) => boolean | Promise<boolean>;
+  /**
+   * 画布上拖入组件（包括从组件列表拖入新组件、画布上拖动已有组件）时，
+   * 对已通过 isContainer 命中的候选容器进行二次过滤；返回 false 时阻止该容器被高亮命中
+   * - 在画布上拖动已有组件时：sourceIds 为被拖动组件的 id 列表
+   * - 从组件列表拖入新组件时：sourceIds 为空数组（尚无 id，仅可依据 targetId 判断）
+   * 该选项会被透传给 StageCore 的 canDropIn
+   */
+  canDropIn?: CanDropIn;
   updateDragEl?: UpdateDragEl;
   renderType?: RenderType;
   guidesOptions?: Partial<GuidesOptions>;
   disabledMultiSelect?: boolean;
+  /**
+   * 始终启用多选模式（无需按住 Ctrl/Meta），默认 false。
+   * 当 `disabledMultiSelect` 为 true 时本配置失效。
+   */
+  alwaysMultiSelect?: boolean;
   disabledRule?: boolean;
   zoom?: number;
   /** 画布双击前的钩子函数，返回 false 则阻止默认的双击行为 */
@@ -191,6 +205,8 @@ export interface StoreState {
   pageLength: number;
   pageFragmentLength: number;
   disabledMultiSelect: boolean;
+  /** 是否始终启用多选模式（无需按住 Ctrl/Meta） */
+  alwaysMultiSelect: boolean;
 }
 
 export type StoreStateKey = keyof StoreState;
@@ -682,6 +698,34 @@ export interface TreeNodeData {
 /** 判断组件树节点是否可展开（即是否要展示为拥有子节点的形态）的函数 */
 export type IsExpandableFunction = (_data: TreeNodeData, _nodeStatusMap: Map<Id, LayerNodeStatus>) => boolean;
 
+/** canDropIn 的调用场景 */
+export type CanDropInScene =
+  /** 在"已选组件"面板的组件树中拖动节点 */
+  | 'layer'
+  /** 在画布上拖动已有组件（被拖动组件本身已经存在于画布中，sourceIds 包含其 id） */
+  | 'stage-drag'
+  /** 从组件列表拖入新组件到画布（被拖入的组件尚不存在，sourceIds 为空数组） */
+  | 'stage-add';
+
+/**
+ * 判断当前正在拖动的源节点是否可以拖入目标节点内部的函数
+ * @param _sourceIds 当前正在拖动的源节点 id 列表
+ *   - `layer`：被拖动的组件树节点 id（单选时长度为 1）
+ *   - `stage-drag`：被拖动组件的 id 列表（多选拖动时为多个）
+ *   - `stage-add`：始终为空数组（从组件列表新增的组件尚无 id）
+ * @param _targetId 目标容器的节点 id
+ * @param _scene 调用场景：见 {@link CanDropInScene}
+ * @returns
+ *   - `false`：阻止该容器被视为合法拖入目标
+ *     - `layer`：禁用 inner 高亮（before/after 仍然可用）
+ *     - `stage-drag`：阻止该容器被高亮命中
+ *     - `stage-add`：阻止该容器被高亮命中并退化为放入当前页面
+ *   - `Id`（string | number）：将拖入目标重定向到该 id 对应的节点
+ *     （例如把命中的"卡片外壳"节点重定向到其内层"卡片内容"容器节点）
+ *   - 其他（`true` / `void` / `undefined`）：按原 targetId 正常拖入
+ */
+export type CanDropInFunction = (_sourceIds: Id[], _targetId: Id, _scene: CanDropInScene) => Id | boolean | void;
+
 export type AsyncBeforeHook<Value extends Array<string>, C extends Record<Value[number], (...args: any) => any>> = {
   [K in Value[number]]?: (...args: Parameters<C[K]>) => Promise<Parameters<C[K]>> | Parameters<C[K]>;
 };