@nocobase/flow-engine 2.1.0-beta.10 → 2.1.0-beta.12

package/src/components/settings/wrappers/contextual/FlowsFloatContextMenu.tsx

@@ -8,6 +8,7 @@
  */
 
 import React, { useState, useCallback, useRef, useEffect, useMemo } from 'react';
+import { createPortal } from 'react-dom';
 import { Alert, Space } from 'antd';
 import { css } from '@emotion/css';
 import { FlowModel } from '../../../../models';
@@ -18,16 +19,255 @@ import { FlowEngine } from '../../../../flowEngine';
 import { getT } from '../../../../utils';
 import { useFlowContext } from '../../../..';
 import { observer } from '../../../../reactive';
+import {
+  omitToolbarPortalInsetStyle,
+  ToolbarPortalRect,
+  ToolbarPortalRenderSnapshot,
+  useFloatToolbarPortal,
+} from './useFloatToolbarPortal';
+import { useFloatToolbarVisibility } from './useFloatToolbarVisibility';
 
-// 检测DOM中直接子元素是否包含button元素的辅助函数
+const TOOLBAR_Z_INDEX = 999;
+
+type ToolbarPosition = 'inside' | 'above' | 'below';
+
+interface BaseFloatContextMenuProps {
+  children?: React.ReactNode;
+  enabled?: boolean;
+  showDeleteButton?: boolean;
+  showCopyUidButton?: boolean;
+  containerStyle?: React.CSSProperties;
+  /** 自定义工具栏样式，`top/left/right/bottom` 会作为 portal overlay 的 inset 使用。 */
+  toolbarStyle?: React.CSSProperties;
+  className?: string;
+  /**
+   * @default true
+   */
+  showBorder?: boolean;
+  /**
+   * @default true
+   */
+  showBackground?: boolean;
+  /**
+   * @default false
+   */
+  showTitle?: boolean;
+  /**
+   * @default false
+   */
+  showDragHandle?: boolean;
+  /**
+   * Settings menu levels: 1=current model only (default), 2=include sub-models
+   */
+  settingsMenuLevel?: number;
+  /**
+   * Extra toolbar items to add to this context menu instance
+   */
+  extraToolbarItems?: ToolbarItemConfig[];
+  /**
+   * @default 'inside'
+   */
+  toolbarPosition?: ToolbarPosition;
+}
+
+const hostContainerStyles = css`
+  position: relative;
+
+  &.has-button-child {
+    display: inline-block;
+  }
+`;
+
+const toolbarPositionClassNames: Record<ToolbarPosition, string> = {
+  inside: 'nb-toolbar-position-inside',
+  above: 'nb-toolbar-position-above',
+  below: 'nb-toolbar-position-below',
+};
+
+const toolbarContainerStyles = ({
+  showBackground,
+  showBorder,
+  ctx,
+}: {
+  showBackground: boolean;
+  showBorder: boolean;
+  ctx: any;
+}) => css`
+  z-index: ${TOOLBAR_Z_INDEX};
+  opacity: 0;
+  pointer-events: none;
+  overflow: visible;
+  transition: opacity 0.12s ease;
+  background: ${showBackground ? 'var(--colorBgSettingsHover)' : 'transparent'};
+  border: ${showBorder ? '2px solid var(--colorBorderSettingsHover)' : 'none'};
+  border-radius: ${ctx.themeToken.borderRadiusLG}px;
+
+  &.nb-toolbar-visible {
+    opacity: 1;
+    transition-delay: 0.1s;
+  }
+
+  &.nb-toolbar-portal {
+    top: 0;
+    left: 0;
+  }
+
+  &.nb-toolbar-portal-fixed {
+    position: fixed;
+  }
+
+  &.nb-toolbar-portal-absolute {
+    position: absolute;
+  }
+
+  &.nb-in-template {
+    background: var(--colorTemplateBgSettingsHover);
+  }
+
+  > .nb-toolbar-container-title {
+    pointer-events: none;
+    position: absolute;
+    top: 2px;
+    left: 2px;
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    height: 16px;
+    padding: 0;
+    font-size: 12px;
+    line-height: 16px;
+    border-bottom-right-radius: 2px;
+    border-radius: 2px;
+
+    .title-tag {
+      display: inline-flex;
+      padding: 0 3px;
+      border-radius: 2px;
+      background: var(--colorSettings);
+      color: #fff;
+    }
+  }
+
+  > .nb-toolbar-container-icons {
+    display: none;
+    position: absolute;
+    right: 2px;
+    line-height: 16px;
+    pointer-events: all;
+
+    &.nb-toolbar-position-inside {
+      top: 2px;
+    }
+
+    &.nb-toolbar-position-above {
+      top: 0;
+      transform: translateY(-100%);
+      padding-bottom: 0;
+      margin-bottom: -2px;
+    }
+
+    &.nb-toolbar-position-below {
+      top: 0;
+      transform: translateY(100%);
+      padding-top: 2px;
+      margin-top: -2px;
+    }
+
+    .ant-space-item {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      width: 16px;
+      height: 16px;
+      padding: 2px;
+      line-height: 16px;
+      background-color: var(--colorSettings);
+      color: #fff;
+    }
+  }
+
+  &.nb-toolbar-visible > .nb-toolbar-container-icons {
+    display: block;
+  }
+
+  > .resize-handle {
+    position: absolute;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    pointer-events: all;
+    opacity: 0.6;
+    border-radius: 4px;
+    background: var(--colorSettings);
+
+    &:hover {
+      opacity: 0.9;
+      background: var(--colorSettingsHover, var(--colorSettings));
+    }
+
+    &::before {
+      content: '';
+      position: absolute;
+      border-radius: 50%;
+      background: rgba(255, 255, 255, 0.9);
+    }
+
+    &::after {
+      content: '';
+      position: absolute;
+      border-radius: 50%;
+      background: rgba(255, 255, 255, 0.9);
+    }
+  }
+
+  > .resize-handle-left {
+    top: 50%;
+    left: -4px;
+    width: 6px;
+    height: 20px;
+    cursor: ew-resize;
+    transform: translateY(-50%);
+
+    &::before {
+      top: 6px;
+      left: 50%;
+      width: 2px;
+      height: 2px;
+      transform: translateX(-50%);
+      box-shadow:
+        0 4px 0 rgba(255, 255, 255, 0.9),
+        0 8px 0 rgba(255, 255, 255, 0.9);
+    }
+  }
+
+  > .resize-handle-right {
+    top: 50%;
+    right: -4px;
+    width: 6px;
+    height: 20px;
+    cursor: ew-resize;
+    transform: translateY(-50%);
+
+    &::before {
+      top: 6px;
+      left: 50%;
+      width: 2px;
+      height: 2px;
+      transform: translateX(-50%);
+      box-shadow:
+        0 4px 0 rgba(255, 255, 255, 0.9),
+        0 8px 0 rgba(255, 255, 255, 0.9);
+    }
+  }
+`;
+
+// 检测直接子节点里是否有按钮，保留原来的 inline-block 兼容行为。
 const detectButtonInDOM = (container: HTMLElement): boolean => {
   if (!container) return false;
 
-  // 只检测直接子元素中的button
   const directChildren = container.children;
   for (let i = 0; i < directChildren.length; i++) {
     const child = directChildren[i];
-    // 检查是否是button元素或具有button特征的元素
     if (child.tagName === 'BUTTON' || child.getAttribute('role') === 'button' || child.classList.contains('ant-btn')) {
       return true;
     }
@@ -36,7 +276,7 @@ const detectButtonInDOM = (container: HTMLElement): boolean => {
   return false;
 };
 
-// 渲染工具栏项目的辅助函数
+// 渲染工具栏项目，并让设置菜单与工具栏共享同一个 popup 容器。
 const renderToolbarItems = (
   model: FlowModel,
   showDeleteButton: boolean,
@@ -44,428 +284,175 @@ const renderToolbarItems = (
   flowEngine: FlowEngine,
   settingsMenuLevel?: number,
   extraToolbarItems?: ToolbarItemConfig[],
+  onSettingsMenuOpenChange?: (open: boolean) => void,
+  getPopupContainer?: (triggerNode?: HTMLElement) => HTMLElement,
 ) => {
   const toolbarItems = flowEngine?.flowSettings?.getToolbarItems?.() || [];
-
-  // 合并额外的工具栏项目
   const allToolbarItems = [...toolbarItems, ...(extraToolbarItems || [])];
 
-  // 按 sort 字段排序
   allToolbarItems.sort((a, b) => (a.sort || 0) - (b.sort || 0)).reverse();
 
   return allToolbarItems
     .filter((itemConfig: ToolbarItemConfig) => {
-      // 检查项目是否应该显示
       return itemConfig.visible ? itemConfig.visible(model) : true;
     })
     .map((itemConfig: ToolbarItemConfig) => {
-      // 渲染项目组件
       const ItemComponent = itemConfig.component;
 
-      // 对于默认设置项目，传递额外的 props
       if (itemConfig.key === 'settings-menu') {
         return (
           <ItemComponent
             key={itemConfig.key}
             model={model}
-            id={model.uid} // 用于拖拽的 id
+            id={model.uid}
             showDeleteButton={showDeleteButton}
             showCopyUidButton={showCopyUidButton}
             menuLevels={settingsMenuLevel}
+            onDropdownVisibleChange={onSettingsMenuOpenChange}
+            getPopupContainer={getPopupContainer}
           />
         );
       }
 
-      // 其他项目只传递 model
       return <ItemComponent key={itemConfig.key} model={model} />;
     });
 };
 
-// Width in pixels per toolbar item (icon width + spacing)
-const TOOLBAR_ITEM_WIDTH = 19;
-
-const toolbarPositionToCSS = {
-  inside: `
-    top: 2px;
-  `,
-  above: `
-    top: 0px;
-    transform: translateY(-100%);
-    padding-bottom: 0px;
-    margin-bottom: -2px;
-  `,
-  below: `
-    top: 0px;
-    transform: translateY(100%);
-    padding-top: 2px;
-    margin-top: -2px;
-  `,
-};
-
-// 使用与 NocoBase 一致的悬浮工具栏样式
-const floatContainerStyles = ({ showBackground, showBorder, ctx, toolbarPosition = 'inside', toolbarCount }) => css`
-  position: relative;
-
-  /* 当检测到button时使用inline-block */
-  &.has-button-child {
-    display: inline-block;
-  }
-
-  /* 正常的hover行为 - 添加延迟显示 */
-  &:hover > .nb-toolbar-container {
-    opacity: 1;
-    transition-delay: 0.1s;
-
-    .nb-toolbar-container-icons {
-      display: block;
-    }
-  }
-
-  /* 当有.hide-parent-menu类时隐藏菜单 */
-  &.hide-parent-menu > .nb-toolbar-container {
-    opacity: 0 !important;
-  }
-
-  > .nb-toolbar-container {
-    position: absolute;
-    top: 0;
-    bottom: 0;
-    left: 0;
-    right: 0;
-    z-index: 999;
-    opacity: 0;
-    background: ${showBackground ? 'var(--colorBgSettingsHover)' : ''};
-    border: ${showBorder ? '2px solid var(--colorBorderSettingsHover)' : ''};
-    border-radius: ${ctx.themeToken.borderRadiusLG}px;
-    pointer-events: none;
-    min-width: ${TOOLBAR_ITEM_WIDTH * toolbarCount}px;
-
-    &.nb-in-template {
-      background: var(--colorTemplateBgSettingsHover);
-    }
-
-    > .nb-toolbar-container-title {
-      pointer-events: none;
-      position: absolute;
-      font-size: 12px;
-      padding: 0;
-      line-height: 16px;
-      height: 16px;
-      border-bottom-right-radius: 2px;
-      border-radius: 2px;
-      top: 2px;
-      left: 2px;
-      display: flex;
-      align-items: center;
-      gap: 4px;
-
-      .title-tag {
-        padding: 0 3px;
-        border-radius: 2px;
-        background: var(--colorSettings);
-        color: #fff;
-        display: inline-flex;
-      }
-    }
-
-    > .nb-toolbar-container-icons {
-      display: none; // 防止遮挡其它 icons
-      position: absolute;
-      right: 2px;
-      ${toolbarPositionToCSS[toolbarPosition] || ''}
-      line-height: 16px;
-      pointer-events: all;
-
-      .ant-space-item {
-        background-color: var(--colorSettings);
-        color: #fff;
-        line-height: 16px;
-        width: 16px;
-        height: 16px;
-        padding: 2px;
-        display: flex;
-        align-items: center;
-        justify-content: center;
-      }
-    }
-
-    /* 拖拽把手样式 - 参考 AirTable 样式 */
-    > .resize-handle {
-      position: absolute;
-      pointer-events: all;
-      background: var(--colorSettings);
-      opacity: 0.6;
-      border-radius: 4px;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-
-      &:hover {
-        opacity: 0.9;
-        background: var(--colorSettingsHover, var(--colorSettings));
-      }
-
-      &::before {
-        content: '';
-        position: absolute;
-        background: rgba(255, 255, 255, 0.9);
-        border-radius: 50%;
-      }
-
-      &::after {
-        content: '';
-        position: absolute;
-        background: rgba(255, 255, 255, 0.9);
-        border-radius: 50%;
-      }
-    }
-
-    > .resize-handle-left {
-      left: -4px;
-      top: 50%;
-      transform: translateY(-50%);
-      width: 6px;
-      height: 20px;
-      cursor: ew-resize;
-
-      &::before {
-        width: 2px;
-        height: 2px;
-        top: 6px;
-        left: 50%;
-        transform: translateX(-50%);
-        box-shadow:
-          0 4px 0 rgba(255, 255, 255, 0.9),
-          0 8px 0 rgba(255, 255, 255, 0.9);
-      }
-    }
-
-    > .resize-handle-right {
-      right: -4px;
-      top: 50%;
-      transform: translateY(-50%);
-      width: 6px;
-      height: 20px;
-      cursor: ew-resize;
-
-      &::before {
-        width: 2px;
-        height: 2px;
-        top: 6px;
-        left: 50%;
-        transform: translateX(-50%);
-        box-shadow:
-          0 4px 0 rgba(255, 255, 255, 0.9),
-          0 8px 0 rgba(255, 255, 255, 0.9);
-      }
-    }
-
-    > .resize-handle-bottom {
-      bottom: -4px;
-      left: 50%;
-      transform: translateX(-50%);
-      width: 20px;
-      height: 6px;
-      cursor: ns-resize;
-
-      &::before {
-        width: 2px;
-        height: 2px;
-        left: 6px;
-        top: 50%;
-        transform: translateY(-50%);
-        box-shadow:
-          4px 0 0 rgba(255, 255, 255, 0.9),
-          8px 0 0 rgba(255, 255, 255, 0.9);
-      }
-    }
-  }
-`;
+const buildToolbarContainerClassName = ({
+  showBackground,
+  showBorder,
+  ctx,
+  portalRenderSnapshot,
+  isToolbarVisible,
+  className,
+}: {
+  showBackground: boolean;
+  showBorder: boolean;
+  ctx: any;
+  portalRenderSnapshot: ToolbarPortalRenderSnapshot | null;
+  isToolbarVisible: boolean;
+  className?: string;
+}) =>
+  [
+    toolbarContainerStyles({ showBackground, showBorder, ctx }),
+    'nb-toolbar-portal',
+    portalRenderSnapshot?.positioningMode === 'absolute' ? 'nb-toolbar-portal-absolute' : 'nb-toolbar-portal-fixed',
+    isToolbarVisible ? 'nb-toolbar-visible' : '',
+    className?.includes('nb-in-template') ? 'nb-in-template' : '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+const buildToolbarContainerStyle = (
+  portalRect: ToolbarPortalRect,
+  toolbarStyle?: React.CSSProperties,
+): React.CSSProperties => ({
+  top: `${portalRect.top}px`,
+  left: `${portalRect.left}px`,
+  width: `${portalRect.width}px`,
+  height: `${portalRect.height}px`,
+  ...omitToolbarPortalInsetStyle(toolbarStyle),
+});
 
-// 悬浮右键菜单组件接口
-interface ModelProvidedProps {
+interface ModelProvidedProps extends BaseFloatContextMenuProps {
   model: FlowModel<any>;
-  children?: React.ReactNode;
-  enabled?: boolean;
-  showDeleteButton?: boolean;
-  showCopyUidButton?: boolean;
-  containerStyle?: React.CSSProperties;
-  toolbarStyle?: React.CSSProperties;
-  className?: string;
-  /**
-   * @default true
-   */
-  showBorder?: boolean;
-  /**
-   * @default true
-   */
-  showBackground?: boolean;
-  /**
-   * @default false
-   */
-  showTitle?: boolean;
-  /**
-   * @default false
-   */
-  showDragHandle?: boolean;
-  /**
-   * Settings menu levels: 1=current model only (default), 2=include sub-models
-   */
-  settingsMenuLevel?: number;
-  /**
-   * Extra toolbar items to add to this context menu instance
-   */
-  extraToolbarItems?: ToolbarItemConfig[];
-  /**
-   * @default 'inside'
-   */
-  toolbarPosition?: 'inside' | 'above' | 'below';
 }
 
-interface ModelByIdProps {
+interface ModelByIdProps extends BaseFloatContextMenuProps {
   uid: string;
   modelClassName: string;
-  children?: React.ReactNode;
-  enabled?: boolean;
-  showDeleteButton?: boolean;
-  showCopyUidButton?: boolean;
-  containerStyle?: React.CSSProperties;
-  className?: string;
-  /**
-   * @default true
-   */
-  showBorder?: boolean;
-  /**
-   * @default true
-   */
-  showBackground?: boolean;
-  /**
-   * @default false
-   */
-  showTitle?: boolean;
-  /**
-   * Settings menu levels: 1=current model only (default), 2=include sub-models
-   */
-  settingsMenuLevel?: number;
-  /**
-   * Extra toolbar items to add to this context menu instance
-   */
-  extraToolbarItems?: ToolbarItemConfig[];
-  /**
-   * @default 'inside'
-   */
-  toolbarPosition?: 'inside' | 'above' | 'below';
 }
 
 type FlowsFloatContextMenuProps = ModelProvidedProps | ModelByIdProps;
 
-// 判断是否是通过ID获取模型的props
+// 判断是否是通过ID获取模型的 props
 const isModelByIdProps = (props: FlowsFloatContextMenuProps): props is ModelByIdProps => {
   return 'uid' in props && 'modelClassName' in props && Boolean(props.uid) && Boolean(props.modelClassName);
 };
 
 /**
- * FlowsFloatContextMenu组件 - 悬浮配置图标组件
+ * FlowsFloatContextMenu组件 - 悬浮配置工具栏组件
  *
  * 功能特性：
  * - 鼠标悬浮显示右上角配置图标
  * - 点击图标显示配置菜单
  * - 支持删除功能
  * - Wrapper 模式支持
- * - 使用与 NocoBase x-settings 一致的样式
- * - 按flow分组显示steps
+ * - 使用 portal overlay 避免被宿主或祖先裁剪
+ * - 设置菜单与工具栏共享同一个 popup 容器
  *
  * 支持两种使用方式：
- * 1. 直接提供model: <FlowsFloatContextMenu model={myModel}>{children}</FlowsFloatContextMenu>
- * 2. 通过uid和modelClassName获取model: <FlowsFloatContextMenu uid="model1" modelClassName="MyModel">{children}</FlowsFloatContextMenu>
+ * 1. 直接提供 model: `<FlowsFloatContextMenu model={myModel}>{children}</FlowsFloatContextMenu>`
+ * 2. 通过 uid 和 modelClassName 获取 model:
+ *    `<FlowsFloatContextMenu uid="model1" modelClassName="MyModel">{children}</FlowsFloatContextMenu>`
  *
  * @param props.children 子组件，必须提供
- * @param props.enabled 是否启用悬浮菜单，默认为true
- * @param props.showDeleteButton 是否显示删除按钮，默认为true
- * @param props.showCopyUidButton 是否显示复制UID按钮，默认为true
+ * @param props.enabled 是否启用悬浮菜单，默认为 true
+ * @param props.showDeleteButton 是否显示删除按钮，默认为 true
+ * @param props.showCopyUidButton 是否显示复制 UID 按钮，默认为 true
  * @param props.containerStyle 容器自定义样式
+ * @param props.toolbarStyle 工具栏自定义样式；`top/left/right/bottom` 会作为 portal overlay 的 inset 使用
  * @param props.className 容器自定义类名
- * @param props.showTitle 是否在边框左上角显示模型title，默认为false
+ * @param props.showTitle 是否在边框左上角显示模型 title，默认为 false
  * @param props.settingsMenuLevel 设置菜单层级：1=仅当前模型(默认)，2=包含子模型
  * @param props.extraToolbarItems 额外的工具栏项目，仅应用于此实例
  */
 const FlowsFloatContextMenu: React.FC<FlowsFloatContextMenuProps> = observer((props) => {
   const ctx = useFlowContext();
-  // Only render if flowSettings is enabled
   if (!ctx.flowSettingsEnabled) {
     return <>{props.children}</>;
   }
   if (isModelByIdProps(props)) {
     return <FlowsFloatContextMenuWithModelById {...props} />;
-  } else {
-    return <FlowsFloatContextMenuWithModel {...props} />;
   }
+  return <FlowsFloatContextMenuWithModel {...props} />;
 });
 
-const ResizeHandles: React.FC<{ model: FlowModel; onDragStart: () => void; onDragEnd: () => void }> = (props) => {
+const ResizeHandles: React.FC<{
+  model: FlowModel;
+  onDragStart: () => void;
+  onDragEnd: () => void;
+  onMouseEnter?: React.MouseEventHandler<HTMLDivElement>;
+  onMouseLeave?: React.MouseEventHandler<HTMLDivElement>;
+}> = (props) => {
   const isDraggingRef = useRef<boolean>(false);
-  const dragTypeRef = useRef<'left' | 'right' | 'bottom' | 'corner' | null>(null);
+  const dragTypeRef = useRef<'left' | 'right' | null>(null);
   const dragStartPosRef = useRef<{ x: number; y: number }>({ x: 0, y: 0 });
   const { onDragStart, onDragEnd } = props;
 
-  // 拖拽移动处理函数
+  // 把拖拽位移转成上层已约定的 resize 事件。
   const handleDragMove = useCallback(
     (e: MouseEvent) => {
       if (!isDraggingRef.current || !dragTypeRef.current) return;
 
       const deltaX = e.clientX - dragStartPosRef.current.x;
-      const deltaY = e.clientY - dragStartPosRef.current.y;
-
-      let resizeDistance = 0;
 
       switch (dragTypeRef.current) {
         case 'left':
-          // 左侧把手：向左拖为正数，向右拖为负数
-          resizeDistance = -deltaX;
-          props.model.parent.emitter.emit('onResizeLeft', { resizeDistance, model: props.model });
+          props.model.parent.emitter.emit('onResizeLeft', { resizeDistance: -deltaX, model: props.model });
           break;
-
         case 'right':
-          // 右侧把手：向右拖为正数，向左拖为负数
-          resizeDistance = deltaX;
-          props.model.parent.emitter.emit('onResizeRight', { resizeDistance, model: props.model });
-          break;
-
-        case 'bottom':
-          // 底部把手：向下拖为正数，向上拖为负数
-          resizeDistance = deltaY;
-          props.model.parent.emitter.emit('onResizeBottom', { resizeDistance, model: props.model });
-          break;
-
-        case 'corner': {
-          // 右下角把手：同时计算宽度和高度变化
-          const widthDelta = deltaX;
-          const heightDelta = deltaY;
-          props.model.parent.emitter.emit('onResizeCorner', { widthDelta, heightDelta, model: props.model });
+          props.model.parent.emitter.emit('onResizeRight', { resizeDistance: deltaX, model: props.model });
           break;
-        }
       }
     },
     [props.model],
   );
 
-  // 拖拽结束处理函数
   const handleDragEnd = useCallback(() => {
     isDraggingRef.current = false;
     dragTypeRef.current = null;
     dragStartPosRef.current = { x: 0, y: 0 };
 
-    // 移除全局事件监听
     document.removeEventListener('mousemove', handleDragMove);
     document.removeEventListener('mouseup', handleDragEnd);
 
     props.model.parent.emitter.emit('onResizeEnd');
     onDragEnd?.();
-  }, [handleDragMove, props.model, onDragEnd]);
+  }, [handleDragMove, onDragEnd, props.model]);
 
-  // 拖拽开始处理函数
   const handleDragStart = useCallback(
-    (e: React.MouseEvent, type: 'left' | 'right' | 'bottom' | 'corner') => {
+    (e: React.MouseEvent, type: 'left' | 'right') => {
       e.preventDefault();
       e.stopPropagation();
 
@@ -473,7 +460,6 @@ const ResizeHandles: React.FC<{ model: FlowModel; onDragStart: () => void; onDra
       dragTypeRef.current = type;
       dragStartPosRef.current = { x: e.clientX, y: e.clientY };
 
-      // 添加全局事件监听
       document.addEventListener('mousemove', handleDragMove);
       document.addEventListener('mouseup', handleDragEnd);
 
@@ -484,27 +470,25 @@ const ResizeHandles: React.FC<{ model: FlowModel; onDragStart: () => void; onDra
 
   return (
     <>
-      {/* 拖拽把手 */}
       <div
         className="resize-handle resize-handle-left"
         title="拖拽调节宽度"
+        onMouseEnter={props.onMouseEnter}
+        onMouseLeave={props.onMouseLeave}
         onMouseDown={(e) => handleDragStart(e, 'left')}
-      ></div>
+      />
       <div
         className="resize-handle resize-handle-right"
         title="拖拽调节宽度"
+        onMouseEnter={props.onMouseEnter}
+        onMouseLeave={props.onMouseLeave}
         onMouseDown={(e) => handleDragStart(e, 'right')}
-      ></div>
-      {/* <div
-            className="resize-handle resize-handle-bottom"
-            title="拖拽调节高度"
-            onMouseDown={(e) => handleDragStart(e, 'bottom')}
-          ></div> */}
+      />
     </>
   );
 };
 
-// 使用传入的model
+// 使用直接传入的 model 渲染工具栏。
 const FlowsFloatContextMenuWithModel: React.FC<ModelProvidedProps> = observer(
   ({
     model,
@@ -523,34 +507,93 @@ const FlowsFloatContextMenuWithModel: React.FC<ModelProvidedProps> = observer(
     toolbarStyle,
     toolbarPosition = 'inside',
   }: ModelProvidedProps) => {
-    const [hideMenu, setHideMenu] = useState<boolean>(false);
-    const [hasButton, setHasButton] = useState<boolean>(false);
+    const [hasButton, setHasButton] = useState(false);
     const containerRef = useRef<HTMLDivElement>(null);
-    const flowEngine = useFlowEngine();
-    const [style, setStyle] = useState<React.CSSProperties>({});
     const toolbarContainerRef = useRef<HTMLDivElement>(null);
-    const toolbarContainerStyle: any = useMemo(() => ({ ...toolbarStyle, ...style }), [style, toolbarStyle]);
+    const portalActionsRef = useRef<{
+      updatePortalRect: () => void;
+      schedulePortalRectUpdate: () => void;
+    }>({
+      updatePortalRect: () => {},
+      schedulePortalRectUpdate: () => {},
+    });
+    const modelUid = model?.uid || '';
+    const flowEngine = useFlowEngine();
+    const updatePortalRectProxy = useCallback(() => {
+      portalActionsRef.current.updatePortalRect();
+    }, []);
+    const schedulePortalRectUpdateProxy = useCallback(() => {
+      portalActionsRef.current.schedulePortalRectUpdate();
+    }, []);
+    const {
+      isToolbarVisible,
+      shouldRenderToolbar,
+      handleSettingsMenuOpenChange,
+      handleChildHover,
+      handleHostMouseEnter,
+      handleHostMouseLeave,
+      handleToolbarMouseEnter,
+      handleToolbarMouseLeave,
+      handleResizeDragStart,
+      handleResizeDragEnd,
+    } = useFloatToolbarVisibility({
+      modelUid,
+      containerRef,
+      toolbarContainerRef,
+      updatePortalRect: updatePortalRectProxy,
+      schedulePortalRectUpdate: schedulePortalRectUpdateProxy,
+    });
+    const { portalRect, portalRenderSnapshot, getPopupContainer, updatePortalRect, schedulePortalRectUpdate } =
+      useFloatToolbarPortal({
+        active: shouldRenderToolbar,
+        containerRef,
+        toolbarContainerRef,
+        toolbarStyle,
+      });
+
+    portalActionsRef.current.updatePortalRect = updatePortalRect;
+    portalActionsRef.current.schedulePortalRectUpdate = schedulePortalRectUpdate;
+
+    const toolbarItems = useMemo(
+      () =>
+        model
+          ? renderToolbarItems(
+              model,
+              showDeleteButton,
+              showCopyUidButton,
+              flowEngine,
+              settingsMenuLevel,
+              extraToolbarItems,
+              handleSettingsMenuOpenChange,
+              getPopupContainer,
+            )
+          : [],
+      [
+        extraToolbarItems,
+        flowEngine,
+        getPopupContainer,
+        handleSettingsMenuOpenChange,
+        model,
+        settingsMenuLevel,
+        showCopyUidButton,
+        showDeleteButton,
+      ],
+    );
 
-    // 检测DOM中是否包含button元素
     useEffect(() => {
-      if (containerRef.current) {
-        const hasButtonElement = detectButtonInDOM(containerRef.current);
-        setHasButton(hasButtonElement);
+      const container = containerRef.current;
+      if (!container) {
+        return;
       }
-    }, [children]); // 当children变化时重新检测
 
-    // 使用MutationObserver监听DOM变化
-    useEffect(() => {
-      if (!containerRef.current) return;
+      const syncHasButton = () => {
+        setHasButton(detectButtonInDOM(container));
+      };
 
-      const observer = new MutationObserver(() => {
-        if (containerRef.current) {
-          const hasButtonElement = detectButtonInDOM(containerRef.current);
-          setHasButton(hasButtonElement);
-        }
-      });
+      syncHasButton();
 
-      observer.observe(containerRef.current, {
+      const observer = new MutationObserver(syncHasButton);
+      observer.observe(container, {
         childList: true,
         subtree: true,
         attributes: true,
@@ -562,75 +605,79 @@ const FlowsFloatContextMenuWithModel: React.FC<ModelProvidedProps> = observer(
       };
     }, []);
 
-    const handleChildHover = useCallback((e: React.MouseEvent) => {
-      const target = e.target as HTMLElement;
-      const childWithMenu = target.closest('[data-has-float-menu]');
-
-      // 如果悬浮的是子元素（且不是当前容器），则隐藏当前菜单
-      if (childWithMenu && childWithMenu !== containerRef.current) {
-        setHideMenu(true);
-      } else {
-        setHideMenu(false);
-      }
-    }, []);
-
     if (!model) {
       const t = getT(model || ({} as FlowModel));
       return <Alert message={t('Invalid model provided')} type="error" />;
     }
 
-    // 如果未启用或没有children，直接返回children
     if (!enabled || !children) {
       return <>{children}</>;
     }
 
+    const toolbarContainerClassName = buildToolbarContainerClassName({
+      showBackground,
+      showBorder,
+      ctx: model.context,
+      portalRenderSnapshot,
+      isToolbarVisible,
+      className,
+    });
+    const toolbarContainerStyle = buildToolbarContainerStyle(portalRect, toolbarStyle);
+
+    const toolbarNode = shouldRenderToolbar ? (
+      <div
+        ref={toolbarContainerRef}
+        className={`nb-toolbar-container ${toolbarContainerClassName}`}
+        style={toolbarContainerStyle}
+        data-model-uid={model.uid}
+      >
+        {showTitle && (model.title || model.extraTitle) && (
+          <div className="nb-toolbar-container-title">
+            {model.title && <span className="title-tag">{model.title}</span>}
+            {model.extraTitle && <span className="title-tag">{model.extraTitle}</span>}
+          </div>
+        )}
+        <div
+          className={`nb-toolbar-container-icons ${toolbarPositionClassNames[toolbarPosition]}`}
+          onClick={(e) => e.stopPropagation()}
+          onMouseDown={(e) => e.stopPropagation()}
+          onMouseMove={(e) => e.stopPropagation()}
+          onMouseEnter={handleToolbarMouseEnter}
+          onMouseLeave={handleToolbarMouseLeave}
+        >
+          <Space size={3} align="center">
+            {toolbarItems}
+          </Space>
+        </div>
+
+        {showDragHandle && (
+          <ResizeHandles
+            model={model}
+            onMouseEnter={handleToolbarMouseEnter}
+            onMouseLeave={handleToolbarMouseLeave}
+            onDragStart={handleResizeDragStart}
+            onDragEnd={handleResizeDragEnd}
+          />
+        )}
+      </div>
+    ) : null;
+
     return (
       <div
         ref={containerRef}
-        className={`${floatContainerStyles({
-          showBackground,
-          showBorder,
-          ctx: model.context,
-          toolbarPosition,
-          toolbarCount: getToolbarCount(flowEngine, extraToolbarItems),
-        })} ${hideMenu ? 'hide-parent-menu' : ''} ${hasButton ? 'has-button-child' : ''} ${className || ''}`}
+        className={`${hostContainerStyles} ${hasButton ? 'has-button-child' : ''} ${className || ''}`}
         style={containerStyle}
         data-has-float-menu="true"
+        data-float-menu-model-uid={model.uid}
         onMouseMove={handleChildHover}
+        onMouseEnter={handleHostMouseEnter}
+        onMouseLeave={handleHostMouseLeave}
       >
         {children}
-
-        {/* 悬浮工具栏 - 使用与 NocoBase 一致的结构 */}
-        <div ref={toolbarContainerRef} className="nb-toolbar-container" style={toolbarContainerStyle}>
-          {showTitle && (model.title || model.extraTitle) && (
-            <div className="nb-toolbar-container-title">
-              {model.title && <span className="title-tag">{model.title}</span>}
-              {model.extraTitle && <span className="title-tag">{model.extraTitle}</span>}
-            </div>
-          )}
-          <div
-            className="nb-toolbar-container-icons"
-            onClick={(e) => e.stopPropagation()}
-            onMouseDown={(e) => e.stopPropagation()}
-            onMouseMove={(e) => e.stopPropagation()}
-          >
-            <Space size={3} align="center">
-              {renderToolbarItems(
-                model,
-                showDeleteButton,
-                showCopyUidButton,
-                flowEngine,
-                settingsMenuLevel,
-                extraToolbarItems,
-              )}
-            </Space>
-          </div>
-
-          {/* 拖拽把手 */}
-          {showDragHandle && (
-            <ResizeHandles model={model} onDragStart={() => setStyle({ opacity: 1 })} onDragEnd={() => setStyle({})} />
-          )}
-        </div>
+        {toolbarNode &&
+          (portalRenderSnapshot?.mountElement
+            ? createPortal(toolbarNode, portalRenderSnapshot.mountElement)
+            : toolbarNode)}
       </div>
     );
   },
@@ -639,22 +686,9 @@ const FlowsFloatContextMenuWithModel: React.FC<ModelProvidedProps> = observer(
   },
 );
 
-// 通过useModelById hook获取model
+// 通过 uid + modelClassName 解析 model，再复用主实现。
 const FlowsFloatContextMenuWithModelById: React.FC<ModelByIdProps> = observer(
-  ({
-    uid,
-    modelClassName,
-    children,
-    enabled = true,
-    showDeleteButton = true,
-    showCopyUidButton = true,
-    containerStyle,
-    className,
-    showTitle = false,
-    settingsMenuLevel,
-    extraToolbarItems: extraToolbarItems,
-    toolbarPosition,
-  }) => {
+  ({ uid, modelClassName, children, ...restProps }) => {
     const model = useFlowModelById(uid, modelClassName);
     const flowEngine = useFlowEngine();
 
@@ -663,18 +697,7 @@ const FlowsFloatContextMenuWithModelById: React.FC<ModelByIdProps> = observer(
     }
 
     return (
-      <FlowsFloatContextMenuWithModel
-        model={model}
-        enabled={enabled}
-        showDeleteButton={showDeleteButton}
-        showCopyUidButton={showCopyUidButton}
-        containerStyle={containerStyle}
-        className={className}
-        showTitle={showTitle}
-        settingsMenuLevel={settingsMenuLevel}
-        extraToolbarItems={extraToolbarItems}
-        toolbarPosition={toolbarPosition}
-      >
+      <FlowsFloatContextMenuWithModel model={model} {...restProps}>
         {children}
       </FlowsFloatContextMenuWithModel>
     );
@@ -685,9 +708,3 @@ const FlowsFloatContextMenuWithModelById: React.FC<ModelByIdProps> = observer(
 );
 
 export { FlowsFloatContextMenu };
-
-function getToolbarCount(flowEngine, extraToolbarItems) {
-  const toolbarItems = flowEngine?.flowSettings?.getToolbarItems?.() || [];
-  const allToolbarItems = [...toolbarItems, ...(extraToolbarItems || [])];
-  return allToolbarItems.length;
-}