chartflow 0.1__py3-none-any.whl

chartflow/node/connection_item.py

@@ -0,0 +1,939 @@
+"""
+连接项模块 - 表示两个节点之间的连线
+包含两个独立的箭头项
+"""
+
+import math
+from typing import Optional, List, Callable
+
+from PyQt6.QtWidgets import QGraphicsItem, QGraphicsPathItem
+from PyQt6.QtCore import Qt, QPointF, QTimer
+from PyQt6.QtGui import QPainterPath, QPen, QColor, QLinearGradient, QBrush
+
+from chartflow.node.styles import ConnectionStyle
+from chartflow.node.arrow_item import ArrowItem
+from chartflow.node.enums import ConnectionType, NodeShape
+from chartflow.node.color_utils import (
+    PORT_GRADIENT_NEUTRAL_LUMINANCE,
+    color_at_relative_luminance,
+    neutral_grey_at_relative_luminance,
+)
+
+# 箭头尖端距离目标边缘的偏移(像素): 0 = 尖端紧贴目标边缘
+ARROW_TIP_EDGE_OFFSET: float = 0.0
+
+
+class ConnectionItem(QGraphicsPathItem):
+    """
+    连接项 - 表示两个节点之间的连线
+    包含两个独立的箭头项，可以单独选中
+    """
+    
+    def __init__(
+        self,
+        source_node: 'NodeItem',
+        target_node: 'NodeItem',
+        is_bidirectional: bool = False,
+        connection_type: ConnectionType = ConnectionType.BEZIER,
+        parent: Optional[QGraphicsItem] = None,
+        *,
+        source_port=None,
+        target_port=None,
+    ) -> None:
+        """
+        初始化连接线
+
+        Args:
+            source_node: 源节点
+            target_node: 目标节点
+            is_bidirectional: 是否是双向连接
+            connection_type: 连线类型（贝塞尔曲线或直线）
+            parent: 父项
+            source_port: 源端端口(QNodePort), 锚定到该 port 中心; None 表示用节点边缘
+            target_port: 目标端端口(QNodePort), 锚定到该 port 中心; None 表示用节点边缘
+        """
+        super().__init__(parent)
+
+        self._source_node: 'NodeItem' = source_node
+        self._target_node: 'NodeItem' = target_node
+        self._source_port = source_port  # Optional[QNodePort], None=节点边缘
+        self._target_port = target_port  # Optional[QNodePort], None=节点边缘
+        self._is_bidirectional: bool = is_bidirectional
+        self._connection_type: ConnectionType = connection_type
+        self._style: ConnectionStyle = ConnectionStyle()
+
+        # 状态标志(须在 _setupStyle 前初始化: _setupStyle -> _refreshPen 读取它们)
+        self._flash_timer: Optional[QTimer] = None
+        self._is_flashing: bool = False  # flashError/flashHighlight 期间临时禁用渐变
+        self._is_selected: bool = False  # setSelected 维护的选中态(用于禁用渐变)
+        # 最近一次 updatePath 计算出的端点(场景坐标), 供 _refreshPen 构造渐变用
+        self._source_edge: QPointF = QPointF()
+        self._target_edge: QPointF = QPointF()
+
+        # 设置样式
+        self._setupStyle()
+
+        # 设置可选项标志（连接线本身可选中，用于右键菜单）
+        self.setFlag(QGraphicsItem.GraphicsItemFlag.ItemIsSelectable, True)
+        self.setAcceptHoverEvents(True)
+        self.setZValue(1)
+
+        # 创建箭头项
+        self._target_arrow: ArrowItem = ArrowItem(self, is_source_arrow=False)
+        self._source_arrow: Optional[ArrowItem] = None
+
+        # 箭头拖拽回调
+        self._arrow_drag_started_callback: Optional[Callable[[QPointF], None]] = None
+        self._arrow_drag_moved_callback: Optional[Callable[[QPointF], None]] = None
+        self._arrow_drag_finished_callback: Optional[Callable[[QPointF, bool], None]] = None
+
+        # 更新路径
+        self.updatePath()
+    
+    def setArrowDragCallbacks(
+        self,
+        started: Optional[Callable[[QPointF], None]] = None,
+        moved: Optional[Callable[[QPointF], None]] = None,
+        finished: Optional[Callable[[QPointF, bool], None]] = None
+    ) -> None:
+        """设置箭头拖拽回调函数"""
+        self._arrow_drag_started_callback = started
+        self._arrow_drag_moved_callback = moved
+        self._arrow_drag_finished_callback = finished
+        
+        # 更新现有箭头的回调
+        if self._target_arrow:
+            self._target_arrow.setDragCallbacks(started, moved, finished)
+        if self._source_arrow:
+            self._source_arrow.setDragCallbacks(started, moved, finished)
+    
+    def _setupStyle(self) -> None:
+        """设置连接线样式"""
+        self._normal_pen = QPen(self._style.normal_color, self._style.stroke_width)
+        self._normal_pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+
+        self._selected_pen = QPen(self._style.selected_color, self._style.selected_stroke_width)
+        self._selected_pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+
+        self._hover_pen = QPen(self._style.hover_color, self._style.stroke_width + 1)
+        self._hover_pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+
+        self._refreshPen()
+
+    def styleToDict(self) -> dict:
+        """将连线样式序列化为字典(仅含与默认值不同的字段)。
+
+        用于 export/import 往返。颜色存为 ``#rrggbb`` 字符串, 宽度存为数值;
+        字段名与 ``ConnectionStyle`` dataclass 一致。默认连线不产生任何键,
+        避免污染导出。
+        """
+        from chartflow.node.styles import (
+            DEFAULT_CONNECTION_NORMAL, DEFAULT_CONNECTION_SELECTED,
+            DEFAULT_CONNECTION_HOVER,
+        )
+        result: dict = {}
+        if self._style.normal_color.name() != DEFAULT_CONNECTION_NORMAL:
+            result["normal_color"] = self._style.normal_color.name()
+        if self._style.selected_color.name() != DEFAULT_CONNECTION_SELECTED:
+            result["selected_color"] = self._style.selected_color.name()
+        if self._style.hover_color.name() != DEFAULT_CONNECTION_HOVER:
+            result["hover_color"] = self._style.hover_color.name()
+        if self._style.stroke_width != 2.0:
+            result["stroke_width"] = self._style.stroke_width
+        if self._style.selected_stroke_width != 3.0:
+            result["selected_stroke_width"] = self._style.selected_stroke_width
+        return result
+
+    def applyStyleFromDict(self, style: dict) -> None:
+        """从字典恢复连线样式(增量, 忽略未知键), 并重建 pen。
+
+        Args:
+            style: 由 :meth:`styleToDict` 产生(或同构)的字典; 可为空。
+        """
+        if not style or not isinstance(style, dict):
+            return
+        if "normal_color" in style:
+            self._style.normal_color = QColor(style["normal_color"])
+        if "selected_color" in style:
+            self._style.selected_color = QColor(style["selected_color"])
+        if "hover_color" in style:
+            self._style.hover_color = QColor(style["hover_color"])
+        if "stroke_width" in style:
+            self._style.stroke_width = style["stroke_width"]
+        if "selected_stroke_width" in style:
+            self._style.selected_stroke_width = style["selected_stroke_width"]
+        self._setupStyle()
+        self.updatePath()
+    
+    @property
+    def sourceNode(self) -> 'NodeItem':
+        """获取源节点"""
+        return self._source_node
+
+    @property
+    def targetNode(self) -> 'NodeItem':
+        """获取目标节点"""
+        return self._target_node
+
+    @property
+    def sourcePort(self):
+        """获取源端端口(QNodePort), 无端口连线返回 None"""
+        return self._source_port
+
+    @property
+    def targetPort(self):
+        """获取目标端端口(QNodePort), 无端口连线返回 None"""
+        return self._target_port
+    
+    @property
+    def targetArrow(self) -> ArrowItem:
+        """获取目标端箭头"""
+        return self._target_arrow
+    
+    @property
+    def sourceArrow(self) -> Optional[ArrowItem]:
+        """获取源端箭头（如果是双向连接）"""
+        return self._source_arrow
+    
+    @property
+    def arrows(self) -> List[ArrowItem]:
+        """获取所有箭头"""
+        arrows = [self._target_arrow]
+        if self._source_arrow:
+            arrows.append(self._source_arrow)
+        return arrows
+    
+    @property
+    def isBidirectional(self) -> bool:
+        """是否是双向连接"""
+        return self._is_bidirectional
+    
+    @isBidirectional.setter
+    def isBidirectional(self, value: bool) -> None:
+        """设置是否为双向连接"""
+        self._is_bidirectional = value
+        self.updatePath()
+    
+    @property
+    def connectionType(self) -> ConnectionType:
+        """获取连线类型"""
+        return self._connection_type
+    
+    @connectionType.setter
+    def connectionType(self, value: ConnectionType) -> None:
+        """设置连线类型"""
+        self._connection_type = value
+        self.updatePath()
+    
+    def toggleConnectionType(self) -> None:
+        """切换连线类型（贝塞尔曲线 <-> 直线）"""
+        if self._connection_type == ConnectionType.BEZIER:
+            self._connection_type = ConnectionType.STRAIGHT
+        else:
+            self._connection_type = ConnectionType.BEZIER
+        self.updatePath()
+
+    def swapDirection(self) -> None:
+        """
+        交换源节点和目标节点，用于保留反向连接时
+        调用后，原来的 target->source 变成 source->target
+        """
+        # 交换节点引用
+        self._source_node, self._target_node = self._target_node, self._source_node
+
+        # 交换箭头引用（因为箭头方向也变了）
+        self._target_arrow, self._source_arrow = self._source_arrow, self._target_arrow
+
+        # 更新箭头的 is_source_arrow 标志
+        if self._target_arrow:
+            self._target_arrow._is_source_arrow = False
+        if self._source_arrow:
+            self._source_arrow._is_source_arrow = True
+        
+        # 如果交换后目标箭头为None（原本是源箭头），需要创建新的目标箭头
+        if self._target_arrow is None:
+            self._target_arrow = ArrowItem(self, is_source_arrow=False)
+            if self.scene():
+                self.scene().addItem(self._target_arrow)
+            # 设置箭头拖拽回调
+            self._target_arrow.setDragCallbacks(
+                started=self._arrow_drag_started_callback,
+                moved=self._arrow_drag_moved_callback,
+                finished=self._arrow_drag_finished_callback
+            )
+
+        # 更新路径
+        self.updatePath()
+
+    def isSelfLoop(self) -> bool:
+        """是否为自环(同一节点)。
+
+        任意 source_node is target_node 的连线都视为自环(NodeCanvas.addConnection
+        已按 node.selfrefs 过滤, 凡能创建的自指都允许)。渲染为绕节点外侧的
+        环/椭圆环, 不经过节点自身。覆盖五类自指: node→node / port→port /
+        node→port / port→node / left→right。
+        """
+        return self._source_node is self._target_node
+
+    def _portRadialDirection(self, port) -> Optional[QPointF]:
+        """port 所在端的外法线方向, 作为该端连线的出射方向。
+
+        - 圆形(ELLIPSE): port 位于圆弧上, 外法线 = 从圆心指向 port 的单位向量
+          (与该处切线垂直)。
+        - 菱形(DIAMOND): port 贴在斜边上, 外法线 = 该处斜边的外法线。布局阶段
+          已将 ``port._orient_angle`` 设为"指向圆心"(内法线)方向, 故外法线为其
+          反方向(角度 + 180°)。用 scene 坐标系下的方向向量返回。
+        - 矩形(RECTANGLE): port 位于左/右垂直边缘上, 外法线恒为水平方向
+          (left -> -x, right -> +x), 即垂直于边缘。返回此方向使连线在该端
+          总是垂直于边, 而非沿用会随另一端位置变化的水平/垂直启发式。
+        - port 为空: 返回 None(沿用既有水平/垂直启发式)。
+
+        Args:
+            port: 某端的 ``QNodePort``, 可为 None。
+
+        Returns:
+            外法线单位向量(场景坐标), 或 None。
+        """
+        if port is None:
+            return None
+        node = port._node
+        shape = getattr(node, "_shape", None)
+        if shape == NodeShape.ELLIPSE:
+            cx = node.sceneBoundingRect().center()
+            p = port.scenePos()
+            dx = p.x() - cx.x()
+            dy = p.y() - cx.y()
+            length = math.hypot(dx, dy)
+            if length < 1e-6:
+                return None
+            return QPointF(dx / length, dy / length)
+        if shape == NodeShape.DIAMOND:
+            # _orient_angle 为内法线(apex 指向圆心); 外法线 = 反方向。
+            # 注意 node 可能有旋转, 故用 mapToScene 把本地方向转到场景。
+            ang = math.radians(getattr(port, "_orient_angle", 0.0) + 180.0)
+            local_dir = QPointF(math.cos(ang), math.sin(ang))
+            # 将本地方向向量经 node 的变换映射到场景(仅方向, 忽略平移)
+            scene_dir = node.mapToScene(local_dir) - node.mapToScene(QPointF(0, 0))
+            length = math.hypot(scene_dir.x(), scene_dir.y())
+            if length < 1e-6:
+                return None
+            return QPointF(scene_dir.x() / length, scene_dir.y() / length)
+        if shape == NodeShape.RECTANGLE:
+            # 矩形 port 位于左/右垂直边缘, 外法线恒为水平(垂直于边)。
+            # 用 port.side 判定方向(left -> -x, right -> +x); 经 node 变换
+            # 映射到场景以兼容节点旋转。
+            sign = -1.0 if port.side == "left" else 1.0
+            local_dir = QPointF(sign, 0.0)
+            scene_dir = node.mapToScene(local_dir) - node.mapToScene(QPointF(0, 0))
+            length = math.hypot(scene_dir.x(), scene_dir.y())
+            if length < 1e-6:
+                return None
+            return QPointF(scene_dir.x() / length, scene_dir.y() / length)
+        return None
+
+    def updatePath(self) -> None:
+        """更新连线路径和箭头位置。
+
+        端点锚定规则: 某端若绑定了 port, 则直接用该 port 的场景中心
+        (scenePos); 否则回退到节点中心 + getEdgePoint 的边缘交点。
+        port↔port / port↔node / node↔node 三种组合均由此自然支持。
+        自环(isSelfLoop)绘制为绕节点外侧的环(不经过节点自身)。
+        """
+        # 自环特殊绘制: 从节点边缘/port 出发, 向外绕一圈后指回
+        if self.isSelfLoop():
+            self._source_edge = QPointF()
+            self._target_edge = QPointF()
+            self._updateSelfLoopPath()
+            return
+
+        if self._source_port is not None:
+            source_edge = self._source_port.scenePos()
+        else:
+            target_pos = (self._target_node.sceneBoundingRect().center()
+                          if self._target_node is not None else QPointF())
+            source_edge = self._source_node.getEdgePoint(target_pos)
+
+        if self._target_port is not None:
+            target_edge = self._target_port.scenePos()
+        else:
+            source_pos = (self._source_node.sceneBoundingRect().center()
+                          if self._source_node is not None else QPointF())
+            target_edge = self._target_node.getEdgePoint(source_pos)
+
+        # 端点处连线的"出射方向"(None = 用既有水平/垂直启发式)。
+        # 当该端 port 所在 node 为圆形时, 出射方向沿径向(圆心 -> port),
+        # 即与该处切线垂直。
+        source_dir = self._portRadialDirection(self._source_port)
+        target_dir = self._portRadialDirection(self._target_port)
+
+        # 记录端点(场景坐标), 供 _refreshPen 构造端口渐变
+        self._source_edge = QPointF(source_edge)
+        self._target_edge = QPointF(target_edge)
+
+        # 根据连线类型创建路径
+        if self._connection_type == ConnectionType.BEZIER:
+            self._updateBezierPath(source_edge, target_edge, source_dir, target_dir)
+        else:
+            self._updateStraightPath(source_edge, target_edge)
+
+        # 端点变化后刷新 pen(端口渐变需按新端点重建渐变画刷)
+        self._refreshPen()
+
+    def _updateSelfLoopPath(self) -> None:
+        """绘制自环: 从源端点出发, 绕节点外侧一圈后落到目标端点。
+
+        覆盖全部 5 类自指(node→node / port→port / node→port / port→node /
+        left→right)。端点取值: 某端若绑定 port 则用其 scenePos, 否则取节点
+        边缘上偏离中心的一个点, 保证两端不重合。
+
+        环方向按主轴判定(左右优先):
+        - **左右环**: 两端 x 都在节点同一侧(左/右)且含 port 时, 环画在该侧
+          (如 left→left 画左侧, right→right 画右侧)。
+        - **上下环**: 两端跨左右(如 left→right)或 node→node 时, 环画上方/下方。
+          下方判定: 含 port 且两端相对 y 均值(自然轴) < 0 时画下方, 否则上方。
+
+        环不经过节点自身; 大小按节点尺寸成比例, 适配矩形/菱形等非正方形。
+        自环不支持双向。
+        """
+        node = self._source_node
+        if node is None:
+            return
+        rect = node.sceneBoundingRect()
+        w = rect.width()
+        h = rect.height()
+        cx = rect.center().x()
+        cy = rect.center().y()
+
+        # ---- 确定源/目标端点 ----
+        # 某端绑定 port: 用 port 场景中心; 否则取节点边缘上偏离中心的点。
+        # 非 port 端点的初始取值仅占位, 实际边缘(顶/底/左/右)由后续方向判定决定。
+        if self._source_port is not None:
+            source_edge = self._source_port.scenePos()
+        else:
+            source_edge = QPointF(cx, rect.top())
+        if self._target_port is not None:
+            target_edge = self._target_port.scenePos()
+        else:
+            target_edge = QPointF(cx, rect.top())
+
+        has_port = (self._source_port is not None
+                    or self._target_port is not None)
+        spread = max(w * 0.18, 14.0)
+        spread_h = max(h * 0.18, 14.0)  # 左右环时 node 端点纵向偏离间距
+
+        # ---- 主轴方向判定: 左右优先, 其次上下 ----
+        # 用 port.side 判定(而非端点 x): node 端点无可靠 x 信息(初始在 cx),
+        # 其"侧"由关联的 port 端推断。node<->node 两端均无 port -> 无侧(上环)。
+        # 左右环: 两端同侧(left/left 或 right/right, 含 node<->port 单侧)。
+        # 上下环: 两端异侧(如 left->right)或两端均 node。
+        def _port_side(port):
+            return port.side if port is not None else None
+
+        src_side = _port_side(self._source_port)
+        tgt_side = _port_side(self._target_port)
+        # node 端的侧跟随另一端 port; 两端均无 port 则无侧
+        eff_src = src_side or tgt_side
+        eff_tgt = tgt_side or src_side
+        if has_port and eff_src == "left" and eff_tgt == "left":
+            side_dir = "left"
+        elif has_port and eff_src == "right" and eff_tgt == "right":
+            side_dir = "right"
+        else:
+            side_dir = None  # 上下环
+
+        if side_dir is not None:
+            # ---- 左右环(水平拱起, 与上下环正交对偶) ----
+            # base_x: 环所贴的节点左/右边缘; arch_sign: x 偏移方向(左=-1/右=+1)
+            base_x = rect.left() if side_dir == "left" else rect.right()
+            arch_sign = -1.0 if side_dir == "left" else 1.0
+            # loop_w: 水平拱起深度(w/h 互换的 loop_h 公式)
+            loop_w = max(w * 0.75, h * 0.55, 50.0) * 1.5
+            side = max(h * 0.5, 30.0) * 1.5  # 控制点纵向外拉量
+            apex = QPointF(base_x + arch_sign * loop_w, cy)
+            # 非 port 端点: 贴左/右边缘, 纵向偏离中心(源偏上、目标偏下)
+            if self._source_port is None:
+                source_edge = QPointF(base_x, cy - spread_h / 2.0)
+            if self._target_port is None:
+                target_edge = QPointF(base_x, cy + spread_h / 2.0)
+            # 两端点重合(如同一 port 自指)时, 沿纵向人为分离, 让环有可见宽度
+            _sep = spread_h if spread_h >= 14.0 else 14.0
+            if (source_edge - target_edge).manhattanLength() < 1.0:
+                source_edge = QPointF(source_edge.x(), source_edge.y() - _sep / 2.0)
+                target_edge = QPointF(target_edge.x(), target_edge.y() + _sep / 2.0)
+            vertical = False  # 主轴为水平
+        else:
+            # ---- 上下环(垂直拱起, 原有逻辑) ----
+            # 相对 y 均值(自然轴, 上正下负): port 在下半部时 < 0。
+            _BELOW_TOL = 1.0  # 容差: 排除浮点误差(矩形中部 port 的 ~1e-15 残留)
+
+            def _rel_y(edge, port):
+                return (cy - edge.y()) if port is not None else 0.0
+
+            rel_y_avg = (_rel_y(source_edge, self._source_port)
+                         + _rel_y(target_edge, self._target_port)) / 2.0
+            below = has_port and (rel_y_avg < -_BELOW_TOL)
+
+            arch_sign = 1.0 if below else -1.0  # y 偏移(上=-1/下=+1)
+            base_y = rect.bottom() if below else rect.top()
+            loop_h = max(h * 0.75, w * 0.55, 50.0) * 1.5
+            side = max(w * 0.5, 30.0) * 1.5
+            apex = QPointF(cx, base_y + arch_sign * loop_h)
+            # 非 port 端点: 贴顶/底边缘, 水平偏离中心(源偏左、目标偏右)
+            if self._source_port is None:
+                source_edge = QPointF(cx - spread / 2.0, base_y)
+            if self._target_port is None:
+                target_edge = QPointF(cx + spread / 2.0, base_y)
+            # 两端点重合(如同一 port 自指)时, 沿横向人为分离, 让环有可见宽度
+            _sep = spread if spread >= 14.0 else 14.0
+            if (source_edge - target_edge).manhattanLength() < 1.0:
+                source_edge = QPointF(source_edge.x() - _sep / 2.0, source_edge.y())
+                target_edge = QPointF(target_edge.x() + _sep / 2.0, target_edge.y())
+            vertical = True  # 主轴为垂直
+
+        # ---- 端点出射方向 ----
+        # port 端: 沿 port 外法线(矩形 port = 垂直边界), 与普通 port 连线一致;
+        # 非 port 端: None -> 沿用启发式(按主轴方向偏离边缘出射)。
+        source_dir = self._portRadialDirection(self._source_port)
+        target_dir = self._portRadialDirection(self._target_port)
+
+        # ---- 两段三次贝塞尔, 在拱顶 apex 处 C¹ 连续拼接 ----
+        # 单段贝塞尔无法同时满足"两端切线沿法线"与"中间拱起"
+        # (控制点与端点同高/宽时曲线贴边), 故用两段: 每段负责"端点出射 -> 弯向拱顶"。
+        #
+        # 段1: source -> c1a -> c1b -> apex   (source 端切线 = c1a - source)
+        # 段2: apex  -> c2a -> c2b -> target  (target 端切线 = target - c2b)
+        # 拱顶 C¹ 连续: c2a = 2·apex − c1b (段1终端切线 = 段2源端切线, 无折角)
+        #
+        # 控制点构造(c_a 第一控制点):
+        #   port: 沿外法线外推 side 距离 -> 切线 = 法线(垂直边界)
+        #   非 port: 沿主轴 arch_sign 方向偏离边缘, 外推 loop·0.45
+        # c_b(第二控制点): c_a 与 apex 间插值(BEZEL=0.6), 引导曲线弯向拱顶
+        BEZEL = 0.6  # c_b 在 c_a 与 apex 间的插值比(0.6 在稳定区, flips=0)
+        loop_len = loop_h if vertical else loop_w
+
+        def _ctrl_a(edge, dir_):
+            if dir_ is not None:
+                # port: 沿外法线外推, 切线 = 法线方向(垂直边界)
+                return QPointF(edge.x() + side * dir_.x(),
+                               edge.y() + side * dir_.y())
+            # 非 port: 沿主轴 arch_sign 方向外推 loop·0.45
+            if vertical:
+                return QPointF(edge.x(), edge.y() + arch_sign * loop_len * 0.45)
+            return QPointF(edge.x() + arch_sign * loop_len * 0.45, edge.y())
+
+        c1a = _ctrl_a(source_edge, source_dir)
+        c1b = QPointF(c1a.x() * (1 - BEZEL) + apex.x() * BEZEL,
+                      c1a.y() * (1 - BEZEL) + apex.y() * BEZEL)
+        # C¹ 镜像: 段2第一控制点 = 2·apex − c1b
+        c2a = QPointF(2 * apex.x() - c1b.x(), 2 * apex.y() - c1b.y())
+        c2b = _ctrl_a(target_edge, target_dir)
+
+        path = QPainterPath()
+        path.moveTo(source_edge)
+        path.cubicTo(c1a, c1b, apex)            # 段1: source → 拱顶
+        path.cubicTo(c2a, c2b, target_edge)     # 段2: 拱顶 → target
+        self.setPath(path)
+
+        # 记录端点供渐变/绘制
+        self._source_edge = QPointF(source_edge)
+        self._target_edge = QPointF(target_edge)
+
+        # ---- 箭头: 终点处沿曲线切线(c2b -> target_edge) ----
+        # 两段贝塞尔在终点(target, 段2 t=1)的切线方向 = 最后控制点(c2b)指向终点
+        dx = target_edge.x() - c2b.x()
+        dy = target_edge.y() - c2b.y()
+        dlen = math.hypot(dx, dy)
+        if dlen > 0:
+            target_direction = QPointF(dx / dlen, dy / dlen)
+        else:
+            target_direction = QPointF(0.0, 1.0)
+
+        arrow_tip_offset = ARROW_TIP_EDGE_OFFSET
+        arrow_tip = QPointF(
+            target_edge.x() - arrow_tip_offset * target_direction.x(),
+            target_edge.y() - arrow_tip_offset * target_direction.y()
+        )
+        self._target_arrow.updateArrow(arrow_tip, target_direction, c2b)
+        if self._target_arrow.scene() is None and self.scene():
+            self.scene().addItem(self._target_arrow)
+
+        # 自环不支持双向; 若曾被设为双向, 移除源端箭头
+        if self._source_arrow is not None:
+            if self._source_arrow.scene():
+                self._source_arrow.scene().removeItem(self._source_arrow)
+            self._source_arrow = None
+
+        # 端点变化后刷新 pen(端口渐变需按新端点重建渐变画刷)
+        self._refreshPen()
+
+    def _updateBezierPath(
+        self,
+        source_edge: QPointF,
+        target_edge: QPointF,
+        source_dir: Optional[QPointF] = None,
+        target_dir: Optional[QPointF] = None,
+    ) -> None:
+        """更新贝塞尔曲线路径。
+
+        Args:
+            source_edge / target_edge: 两端点(场景坐标)。
+            source_dir / target_dir: 端点处连线的出射方向(单位向量, 场景坐标)。
+                非空时, 该端控制点沿此方向放置, 使曲线在该端点的切线 = 此方向
+                (用于圆形节点的 port: 径向 = 与切线垂直)。为 None 时, 该端沿用
+                既有水平/垂直主轴启发式(控制点朝向另一端)。
+        """
+        # 计算控制点（三次贝塞尔曲线）
+        dx = target_edge.x() - source_edge.x()
+        dy = target_edge.y() - source_edge.y()
+        distance = math.sqrt(dx * dx + dy * dy)
+
+        # 控制点偏移量（基于距离的比例）
+        offset = min(distance * 0.5, 150)
+
+        # 源端控制点: 优先按指定出射方向; 否则沿主轴(水平/垂直)朝向目标延伸
+        if source_dir is not None:
+            ctrl1 = QPointF(
+                source_edge.x() + offset * source_dir.x(),
+                source_edge.y() + offset * source_dir.y(),
+            )
+        elif abs(dx) > abs(dy):
+            ctrl1 = QPointF(source_edge.x() + offset * (1 if dx > 0 else -1), source_edge.y())
+        else:
+            ctrl1 = QPointF(source_edge.x(), source_edge.y() + offset * (1 if dy > 0 else -1))
+
+        # 目标端控制点: 优先按指定出射方向(径向外法线)放置, 使曲线从外侧沿径向
+        # 进入端点; 否则沿主轴朝向源端延伸
+        if target_dir is not None:
+            ctrl2 = QPointF(
+                target_edge.x() + offset * target_dir.x(),
+                target_edge.y() + offset * target_dir.y(),
+            )
+        elif abs(dx) > abs(dy):
+            ctrl2 = QPointF(target_edge.x() - offset * (1 if dx > 0 else -1), target_edge.y())
+        else:
+            ctrl2 = QPointF(target_edge.x(), target_edge.y() - offset * (1 if dy > 0 else -1))
+        
+        # 创建路径
+        path = QPainterPath()
+        path.moveTo(source_edge)
+        path.cubicTo(ctrl1, ctrl2, target_edge)
+        
+        self.setPath(path)
+        
+        # 更新目标端箭头（正方向）
+        target_direction = QPointF(
+            (target_edge.x() - ctrl2.x()) / distance if distance > 0 else 1,
+            (target_edge.y() - ctrl2.y()) / distance if distance > 0 else 0
+        )
+        # 归一化
+        dir_len = math.sqrt(target_direction.x() ** 2 + target_direction.y() ** 2)
+        if dir_len > 0:
+            target_direction = QPointF(target_direction.x() / dir_len, target_direction.y() / dir_len)
+
+        arrow_tip_offset = ARROW_TIP_EDGE_OFFSET  # 箭头尖端距离边缘的偏移
+        arrow_tip = QPointF(
+            target_edge.x() - arrow_tip_offset * target_direction.x(),
+            target_edge.y() - arrow_tip_offset * target_direction.y()
+        )
+
+        self._target_arrow.updateArrow(arrow_tip, target_direction, ctrl2)
+        
+        # 确保箭头在场景中
+        if self._target_arrow.scene() is None and self.scene():
+            self.scene().addItem(self._target_arrow)
+
+        # 如果是双向连线，更新源端箭头
+        if self._is_bidirectional:
+            if self._source_arrow is None:
+                self._source_arrow = ArrowItem(self, is_source_arrow=True)
+                if self.scene():
+                    self.scene().addItem(self._source_arrow)
+                # 设置箭头拖拽回调（如果已设置）
+                if self._arrow_drag_started_callback:
+                    self._source_arrow.setDragCallbacks(
+                        self._arrow_drag_started_callback,
+                        self._arrow_drag_moved_callback,
+                        self._arrow_drag_finished_callback
+                    )
+
+            # 计算源端箭头方向：曲线在源端点的切线方向（使用控制点计算）
+            source_direction = QPointF(
+                (source_edge.x() - ctrl1.x()) / distance if distance > 0 else -1,
+                (source_edge.y() - ctrl1.y()) / distance if distance > 0 else 0
+            )
+            # 归一化
+            dir_len = math.sqrt(source_direction.x() ** 2 + source_direction.y() ** 2)
+            if dir_len > 0:
+                source_direction = QPointF(source_direction.x() / dir_len, source_direction.y() / dir_len)
+
+            source_arrow_tip = QPointF(
+                source_edge.x() - arrow_tip_offset * source_direction.x(),
+                source_edge.y() - arrow_tip_offset * source_direction.y()
+            )
+
+            self._source_arrow.updateArrow(source_arrow_tip, source_direction, ctrl1)
+        else:
+            # 如果不是双向，移除源端箭头
+            if self._source_arrow:
+                if self._source_arrow.scene():
+                    self._source_arrow.scene().removeItem(self._source_arrow)
+                self._source_arrow = None
+    
+    def _updateStraightPath(self, source_edge: QPointF, target_edge: QPointF) -> None:
+        """更新直线路径"""
+        # 创建直线路径
+        path = QPainterPath()
+        path.moveTo(source_edge)
+        path.lineTo(target_edge)
+        
+        self.setPath(path)
+        
+        # 计算方向向量
+        dx = target_edge.x() - source_edge.x()
+        dy = target_edge.y() - source_edge.y()
+        distance = math.sqrt(dx * dx + dy * dy)
+        
+        # 归一化方向向量
+        if distance > 0:
+            direction = QPointF(dx / distance, dy / distance)
+        else:
+            direction = QPointF(1, 0)
+        
+        # 更新目标端箭头
+        arrow_tip_offset = ARROW_TIP_EDGE_OFFSET
+        arrow_tip = QPointF(
+            target_edge.x() - arrow_tip_offset * direction.x(),
+            target_edge.y() - arrow_tip_offset * direction.y()
+        )
+
+        self._target_arrow.updateArrow(arrow_tip, direction, source_edge)
+        
+        # 确保箭头在场景中
+        if self._target_arrow.scene() is None and self.scene():
+            self.scene().addItem(self._target_arrow)
+
+        # 如果是双向连线，更新源端箭头
+        if self._is_bidirectional:
+            if self._source_arrow is None:
+                self._source_arrow = ArrowItem(self, is_source_arrow=True)
+                if self.scene():
+                    self.scene().addItem(self._source_arrow)
+                # 设置箭头拖拽回调（如果已设置）
+                if self._arrow_drag_started_callback:
+                    self._source_arrow.setDragCallbacks(
+                        self._arrow_drag_started_callback,
+                        self._arrow_drag_moved_callback,
+                        self._arrow_drag_finished_callback
+                    )
+
+            # 源端箭头方向相反
+            source_direction = QPointF(-direction.x(), -direction.y())
+
+            source_arrow_tip = QPointF(
+                source_edge.x() - arrow_tip_offset * source_direction.x(),
+                source_edge.y() - arrow_tip_offset * source_direction.y()
+            )
+
+            self._source_arrow.updateArrow(source_arrow_tip, source_direction, target_edge)
+        else:
+            # 如果不是双向，移除源端箭头
+            if self._source_arrow:
+                if self._source_arrow.scene():
+                    self._source_arrow.scene().removeItem(self._source_arrow)
+                self._source_arrow = None
+    
+    def _hasPortGradient(self) -> bool:
+        """是否应绘制端口渐变(至少一端绑定 port)。
+
+        自环也适用: port→port / port→node / node→port 自环的水平线性渐变
+        沿 source_edge→target_edge 分布, 左 port 端为端口色、拱顶为中性灰、
+        右 port 端为端口色(两端均 port 时), 符合端口配色语义。
+        """
+        return (self._source_port is not None
+                or self._target_port is not None)
+
+    def _portSideColor(self, source_side: bool) -> Optional[QColor]:
+        """取端口侧的端口色(自定义色优先, 否则所在侧默认色)。
+
+        Args:
+            source_side: True 取源端 port, False 取目标端 port。
+
+        Returns:
+            该端为 port 时返回端口色(已调整到 PORT_GRADIENT_NEUTRAL_LUMINANCE);
+            该端非 port 时返回 None。
+        """
+        port = self._source_port if source_side else self._target_port
+        if port is None:
+            return None
+        base = port._fill_color()  # 自定义色 or 所在侧默认色
+        return color_at_relative_luminance(base, PORT_GRADIENT_NEUTRAL_LUMINANCE)
+
+    def _buildGradientBrush(self) -> Optional[QBrush]:
+        """构造端口渐变画刷。
+
+        渐变沿 source_edge -> target_edge 方向:
+          - source 端为 port: source 端为端口色(L0), 向中点过渡到中性灰(L0);
+          - target 端为 port: target 端为端口色(L0), 向中点过渡到中性灰(L0);
+          - 两端均 port: 两端各为端口色(L0), 中点为中性灰(L0)。
+          - 仅一端 port: 另一端(非端口端)取中性灰(L0)。
+        两端点同相对亮度(中间 RGB 插值不严格保证, 近似)。
+        """
+        if not self._hasPortGradient():
+            return None
+        neutral = neutral_grey_at_relative_luminance(PORT_GRADIENT_NEUTRAL_LUMINANCE)
+        src_color = self._portSideColor(True) or neutral
+        tgt_color = self._portSideColor(False) or neutral
+
+        p1, p2 = self._source_edge, self._target_edge
+        # 退化(两端点重合)时给定一个默认方向, 避免渐变面积为 0
+        if p1 == p2:
+            p2 = QPointF(p1.x() + 1.0, p1.y())
+        grad = QLinearGradient(p1, p2)
+        grad.setColorAt(0.0, src_color)
+        grad.setColorAt(1.0, tgt_color)
+        # 中点为中性灰: 用三个 stop 让两侧各自向中点过渡
+        grad.setColorAt(0.5, neutral)
+        return QBrush(grad)
+
+    def _refreshPen(self) -> None:
+        """根据当前状态刷新连线 pen。
+
+        选中 -> 选中色 pen; 闪烁中 -> 保持 flash pen(由 flash* 设置); 其余:
+          - 含 port 且非自环 -> 带端口渐变画刷的 normal pen
+          - 否则 -> 普通 normal pen
+        pen 由 QGraphicsPathItem 默认 paint() 直接消费, 故无需覆写 paint。
+        """
+        if self._is_selected:
+            self.setPen(self._selected_pen)
+            return
+        if self._is_flashing:
+            return  # flashError/flashHighlight 已临时 setPen, 不覆盖
+        if self._hasPortGradient():
+            brush = self._buildGradientBrush()
+            pen = QPen(self._normal_pen)
+            pen.setBrush(brush)
+            pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+            self.setPen(pen)
+        else:
+            self.setPen(self._normal_pen)
+
+    def setSelected(self, selected: bool) -> None:
+        """设置连接线和所有箭头的选中状态"""
+        self._is_selected = bool(selected)
+        self._refreshPen()
+
+        # 同时选中/取消选中所有箭头
+        self._target_arrow.setSelected(selected)
+        if self._source_arrow:
+            self._source_arrow.setSelected(selected)
+        self.update()
+    
+    def flashError(self) -> None:
+        """闪烁显示错误（连线更改失败）"""
+        error_color = QColor("#8B0000")  # 暗灰红色
+        error_pen = QPen(error_color, self._style.stroke_width + 2)
+        error_pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+
+        # 闪烁3次
+        flash_count = [0]
+
+        def toggleFlash():
+            flash_count[0] += 1
+            if flash_count[0] % 2 == 1:
+                self.setPen(error_pen)
+            else:
+                # 闪烁期间用纯色 normal pen(不带渐变), 渐变由结束时的 _refreshPen 恢复
+                self.setPen(self._normal_pen)
+
+            if flash_count[0] >= 6:  # 3次闪烁 = 6次切换
+                self._flash_timer.stop()
+                self._flash_timer.deleteLater()
+                self._flash_timer = None
+                self._is_flashing = False
+                self._refreshPen()
+
+        self._is_flashing = True
+        self.setPen(error_pen)  # 立即显示错误色, 不等首次 timeout(也避免渐变残留)
+        self._flash_timer = QTimer()
+        self._flash_timer.timeout.connect(toggleFlash)
+        self._flash_timer.start(150)  # 150ms间隔
+
+    def flashHighlight(self) -> None:
+        """天蓝灰色高亮闪烁（用于子窗口中双击定位连线）"""
+        highlight_color = QColor("#87CEEB")  # 天蓝灰色 (Sky Blue)
+        highlight_pen = QPen(highlight_color, self._style.stroke_width + 4)
+        highlight_pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+
+        original_z = self.zValue()
+
+        # 提升到最上层显示
+        self.setZValue(100)
+
+        # 闪烁3次
+        flash_count = [0]
+
+        def toggleFlash():
+            flash_count[0] += 1
+            if flash_count[0] % 2 == 1:
+                self.setPen(highlight_pen)
+            else:
+                self.setPen(self._normal_pen)
+
+            if flash_count[0] >= 6:  # 3次闪烁 = 6次切换
+                self._flash_timer.stop()
+                self._flash_timer.deleteLater()
+                self._flash_timer = None
+                self._is_flashing = False
+                self._refreshPen()
+                self.setZValue(original_z)  # 恢复原始层级
+
+        self._is_flashing = True
+        self.setPen(highlight_pen)  # 立即显示高亮色, 不等首次 timeout
+        self._flash_timer = QTimer()
+        self._flash_timer.timeout.connect(toggleFlash)
+        self._flash_timer.start(150)  # 150ms间隔
+
+    def setColor(self, color: QColor) -> None:
+        """
+        设置连接线的主颜色
+
+        Args:
+            color: 主颜色
+        """
+        self._style.normal_color = color
+        self._style.selected_color = color
+        self._style.hover_color = color
+        self._setupStyle()
+
+    def setBorder(self, width: int = 1, color: QColor = None) -> None:
+        """
+        设置连接线的边框宽度（线宽）和颜色
+
+        Args:
+            width: 线宽，<=0 使用默认宽度
+            color: 线颜色，None 表示使用默认颜色
+        """
+        if width > 0:
+            self._style.stroke_width = width
+            self._style.selected_stroke_width = width + 1
+        if color is not None:
+            self._style.normal_color = color
+            self._style.selected_color = color
+            self._style.hover_color = color
+        self._setupStyle()
+
+    def hoverEnterEvent(self, event) -> None:
+        """鼠标进入事件"""
+        super().hoverEnterEvent(event)
+    
+    def hoverLeaveEvent(self, event) -> None:
+        """鼠标离开事件"""
+        super().hoverLeaveEvent(event)
+    
+    def removeArrows(self) -> None:
+        """移除所有箭头项"""
+        if self._target_arrow and self._target_arrow.scene():
+            self._target_arrow.scene().removeItem(self._target_arrow)
+        
+        if self._source_arrow and self._source_arrow.scene():
+            self._source_arrow.scene().removeItem(self._source_arrow)