chartflow 0.1__py3-none-any.whl

chartflow/node/port_item.py

@@ -0,0 +1,591 @@
+"""
+端口项模块 - 节点的输入/输出端口
+
+视觉参考 uipcweb（pyipcore 原生风格）:
+  - 左侧(left/input)=绿色 dot，右侧(right/output)=橙色 dot
+  - dot 形状: triangle / circle / trapezoid / square
+  - hover 进入 dot 时使用 DodgerBlue 描边(outline 宽度，默认 2)
+  - hit: 常驻于 dot 靠近节点中心一侧的灰色小字(字号略小于节点)
+  - label: 默认隐藏，节点 hover>0.5s 或 hover 进入端口时显示于外侧；
+           未指定时默认等同 name
+
+遵循代码规范: dataclass 仅承载数据，渲染/布局逻辑分离到 QNodePort
+(原 ``_PortGraphic``，已公开化) 与模块级辅助函数。
+
+类型分层(对外公开):
+  - ``QNodePortSpec``: @dataclass, 端口**数据**描述(name/shape/size/...)
+  - ``IQNodePort``:    Protocol, 端口渲染项**契约**(见 ``_port_interface.py``)
+  - ``QNodePort``:     QGraphicsObject, 端口**渲染项**实现, 满足 ``IQNodePort``
+"""
+
+import math
+from dataclasses import dataclass
+from typing import Optional, List, Dict, Any, ClassVar, TYPE_CHECKING
+
+from PyQt6.QtCore import Qt, QPointF, QRectF, QPropertyAnimation, QEasingCurve, QTimer
+from PyQt6.QtGui import QBrush, QPen, QColor, QFont, QPainterPath, QPainter
+from PyQt6.QtWidgets import QGraphicsObject, QGraphicsTextItem
+
+from chartflow.node._node_base import (
+    ANIMATION_DURATION_SHOW,
+    ANIMATION_DURATION_HIDE,
+)
+
+if TYPE_CHECKING:
+    from chartflow.node.node_item import QNodeItem
+
+
+# ---- label 弹出/收回动画 ----
+# 出现: scale 0.85 -> 1.0(原地弹出); 消失: scale 1.0 -> 0.85(收回)
+_PORT_LABEL_POP_SCALE = 0.85
+
+
+# ---- 配色(与 uipcweb / styles.py 对齐) ----
+PORT_COLOR_LEFT = QColor("#1E7C5A")     # input  - SGGREEN
+PORT_COLOR_RIGHT = QColor("#EE7942")    # output - OLVORANGE
+PORT_HOVER_OUTLINE = QColor("#1E90FF")  # DodgerBlue
+PORT_ERROR_OUTLINE = QColor("#E53935")  # 红色(不合规连接闪烁)
+PORT_HIT_COLOR = QColor("#9AA1AB")      # 灰色小字
+PORT_LABEL_COLOR = QColor("#1F232A")    # 节点文本色
+
+VALID_PORT_SHAPES = ("triangle", "circle", "trapezoid", "square")
+DEFAULT_PORT_SIZE = 8
+DEFAULT_PORT_OUTLINE = 2
+
+# 节点 hover 多久后显示全部端口 label
+PORT_LABEL_HOVER_DELAY_MS = 500
+
+# 文本间距
+HIT_GAP = 1.0    # dot 与 hit 文本的间距(hit 更贴近 dot)
+LABEL_GAP = 3.0  # dot 与 label 文本的间距(label 在节点外侧)
+
+
+@dataclass
+class QNodePortSpec:
+    """端口数据类型(纯数据，不含渲染逻辑)
+
+    用户配置端口时使用本类的实例(或同构 dict), 经节点 ``ports`` 属性
+    重建为 :class:`QNodePort` 渲染项。
+
+    Attributes:
+        name: 端口名称；当 label 未指定时，label 默认等同 name
+        shape: dot 形状，取值 "triangle" / "circle" / "trapezoid" / "square"
+        size: dot 尺寸(像素)
+        hit: 显示在 dot 靠近节点 y 轴一侧的灰色小字，字号略小于节点字号
+        label: 显示在外侧的显式文本，默认不显示，节点 hover>0.5s
+               或 hover 进入端口时显示；None 时等同 name
+        outline: hover 进入 dot 时 DodgerBlue 描边的宽度，<=0 表示不描边
+        color: 自定义 dot 填充色(QColor)；None 时按所在侧使用
+               LEFT_COLOR(left/input)或 RIGHT_COLOR(right/output)
+    """
+    # 默认配色静态字段: 左侧(input)/右侧(output)。color=None 时据此着色
+    LEFT_COLOR: ClassVar[QColor] = PORT_COLOR_LEFT
+    RIGHT_COLOR: ClassVar[QColor] = PORT_COLOR_RIGHT
+
+    name: str
+    shape: str = "circle"
+    size: int = DEFAULT_PORT_SIZE
+    hit: str = ""
+    label: Optional[str] = None
+    outline: int = DEFAULT_PORT_OUTLINE
+    color: Optional[QColor] = None
+
+
+def port_effective_label(port: QNodePortSpec) -> str:
+    """label 未指定时默认等同 name"""
+    return port.name if port.label is None else port.label
+
+
+def port_depth(port: QNodePortSpec) -> float:
+    """dot 向内延伸的深度(横向像素): square=size, 其余=size/2"""
+    s = max(1, port.size)
+    return float(s) if port.shape == "square" else s / 2.0
+
+
+def port_to_dict(port: QNodePortSpec) -> Dict[str, Any]:
+    """将 QNodePortSpec 序列化为字典"""
+    return {
+        "name": port.name,
+        "shape": port.shape,
+        "size": port.size,
+        "hit": port.hit,
+        "label": port.label,
+        "outline": port.outline,
+        "color": port.color.name() if port.color is not None else None,
+    }
+
+
+def port_from_dict(data: Dict[str, Any]) -> QNodePortSpec:
+    """从字典构造 QNodePortSpec"""
+    raw_color = data.get("color")
+    color = QColor(raw_color) if raw_color else None
+    return QNodePortSpec(
+        name=data.get("name", ""),
+        shape=data.get("shape", "circle"),
+        size=data.get("size", DEFAULT_PORT_SIZE),
+        hit=data.get("hit", ""),
+        label=data.get("label"),
+        outline=data.get("outline", DEFAULT_PORT_OUTLINE),
+        color=color,
+    )
+
+
+class QNodePort(QGraphicsObject):
+    """端口渲染项
+
+    绘制 dot、hit 文本、label 文本，处理 hover 与连线拖拽。满足
+    :class:`~chartflow.node._port_interface.IQNodePort` 契约(结构子类型,
+    无需显式继承 Protocol)。
+
+    - dot 本地坐标系原点位于节点边缘上的端口锚点。
+    - 接受 hover 事件以驱动描边与 label 显示。
+    - 接受左键按下以发起 port↔port 连线拖拽(优先级高于 node 外环);
+      拖拽期间由画布接管 move/release, 本项仅负责起始按下与描边态。
+    - ``_active`` 标志: 连线进行中保持起点 port 描边, 不随 hover 离开消失。
+    """
+
+    def __init__(
+        self,
+        spec: QNodePortSpec,
+        side: str,
+        node: "QNodeItem",
+        parent=None,
+    ) -> None:
+        super().__init__(parent if parent is not None else node)
+        self._spec: QNodePortSpec = spec
+        self._side: str = side  # 'left' | 'right'
+        self._node: "QNodeItem" = node
+        self._radial: bool = False         # 圆形节点: dot 沿弧线径向放置
+        self._diamond: bool = False        # 菱形节点: dot 旋转贴合斜边法线
+        self._orient_angle: float = 0.0    # 径向/斜边放置时的旋转角(度), apex 对准外法线
+        self._hovered: bool = False      # 鼠标是否进入 dot
+        self._show_all: bool = False     # 节点级 hover>0.5s 显示全部 label
+        self._solo: bool = False         # 本端口被 hover 时立即显示 label
+        self._active: bool = False       # 连线进行中: 保持起点描边(不随 hover 离开消失)
+        self._drop_target: bool = False  # 连线进行中: 作为落点(目标 port)被高亮
+        self._flash_error: bool = False  # 不合规连接: 红色描边闪烁中
+        self._flash_timer: Optional[QTimer] = None
+
+        self.setAcceptHoverEvents(True)
+        self.setAcceptedMouseButtons(Qt.MouseButton.LeftButton)
+        self.setFlag(QGraphicsObject.GraphicsItemFlag.ItemIsSelectable, False)
+        self.setFlag(QGraphicsObject.GraphicsItemFlag.ItemIsFocusable, False)
+        self.setZValue(90)
+
+        # hit 文本: 常驻、灰色、字号略小、位于 dot 靠近节点中心一侧
+        self._hit_item: Optional[QGraphicsTextItem] = None
+        if spec.hit:
+            self._hit_item = QGraphicsTextItem(spec.hit, self)
+            self._hit_item.setDefaultTextColor(PORT_HIT_COLOR)
+            self._hit_item.setAcceptHoverEvents(False)
+            self._hit_item.setAcceptedMouseButtons(Qt.MouseButton.NoButton)
+            self._hit_item.setTextInteractionFlags(Qt.TextInteractionFlag.NoTextInteraction)
+
+        # label 文本: 默认隐藏、外侧、hover 时显示
+        self._label_item: Optional[QGraphicsTextItem] = None
+        eff_label = port_effective_label(spec)
+        if eff_label:
+            self._label_item = QGraphicsTextItem(eff_label, self)
+            self._label_item.setDefaultTextColor(PORT_LABEL_COLOR)
+            self._label_item.setAcceptHoverEvents(False)
+            self._label_item.setAcceptedMouseButtons(Qt.MouseButton.NoButton)
+            self._label_item.setTextInteractionFlags(Qt.TextInteractionFlag.NoTextInteraction)
+            # 初始即处于"消失末态": 隐藏 + 透明 + 收缩, 避免首次显示前闪现
+            self._label_item.setVisible(False)
+            self._label_item.setOpacity(0.0)
+            self._label_item.setScale(_PORT_LABEL_POP_SCALE)
+
+        # label 出现/消失动画状态(opacity 动画 + scale 动画各持一份引用, 避免 GC)
+        self._label_visible: bool = False          # label 的逻辑目标可见态
+        self._label_show_anim: Optional[QPropertyAnimation] = None
+        self._label_hide_anim: Optional[QPropertyAnimation] = None
+        self._label_scale_show: Optional[QPropertyAnimation] = None
+        self._label_scale_hide: Optional[QPropertyAnimation] = None
+
+        self.applyNodeFont()
+
+    # ---- 公共接口 ----
+    @property
+    def spec(self) -> QNodePortSpec:
+        return self._spec
+
+    @property
+    def node(self) -> "QNodeItem":
+        """端口所属的节点"""
+        return self._node
+
+    @property
+    def side(self) -> str:
+        return self._side
+
+    def setNodeHoverShowAll(self, on: bool) -> None:
+        """节点级 hover>0.5s: 显示/隐藏本端口 label"""
+        self._show_all = on
+        self._updateLabelVisible()
+
+    def applyNodeFont(self) -> None:
+        """根据节点字体刷新 hit/label 字号并重排文本"""
+        nf = self._node.font
+        ps = nf.pointSize()
+        if self._hit_item is not None:
+            hit_font = QFont(nf)
+            hit_font.setPointSize(max(1, ps - 2) if ps > 0 else 8)
+            self._hit_item.setFont(hit_font)
+        if self._label_item is not None:
+            self._label_item.setFont(QFont(nf))
+        self._layoutText()
+
+    # ---- 几何 ----
+    def _is_left(self) -> bool:
+        return self._side == "left"
+
+    def _inward_sign(self) -> int:
+        """dot 路径的朝向(用于绘制): 圆形(radial)/菱形(diamond)统一 +x
+        (由旋转对准外法线); 否则 left -> +1, right -> -1"""
+        if self._radial or self._diamond:
+            return 1
+        return 1 if self._is_left() else -1
+
+    def _text_sign(self) -> int:
+        """文本水平排布的朝向: left -> +1(hit 在右/label 在左), right -> -1"""
+        return 1 if self._is_left() else -1
+
+    def _depth(self) -> float:
+        """dot 向内延伸的深度(横向)"""
+        return port_depth(self._spec)
+
+    def _dot_path(self) -> QPainterPath:
+        """dot 本地路径: 原点位于端口锚点(节点边界), 向内延伸(sign 方向)。
+
+        外缘贴在边界上, 整个 dot 在节点内侧, 不会超出形状边界。
+        圆形(radial)/菱形(diamond)模式下 sign 统一为 +1, 由 paint() 中的
+        rotate(_orient_angle) 把 dot 转到对准外法线(底边贴合该处切线/斜边)。
+        """
+        s = max(1, self._spec.size)
+        half = s / 2.0
+        sign = self._inward_sign()  # left -> +1(dot 向 +x 内延伸), right -> -1
+        path = QPainterPath()
+        sh = self._spec.shape
+        if sh == "circle":
+            # 内侧半圆: 平边(直径)贴在边界 x=0, 向内凸出
+            r = half
+            n = 24
+            path.moveTo(0.0, -r)
+            for i in range(1, n + 1):
+                ang = -math.pi / 2 + math.pi * i / n
+                path.lineTo(sign * r * math.cos(ang), r * math.sin(ang))
+            path.closeSubpath()
+        elif sh == "square":
+            # 整个方块贴边向内
+            x0 = 0.0 if sign > 0 else -s
+            path.addRect(x0, -half, s, s)
+        elif sh == "triangle":
+            # 底边贴边界, 顶点向内
+            d = half
+            path.moveTo(0.0, -half)
+            path.lineTo(0.0, half)
+            path.lineTo(sign * d, 0.0)
+            path.closeSubpath()
+        else:  # trapezoid: 宽底贴边界, 窄端向内
+            d = half
+            q = half / 2.0
+            path.moveTo(0.0, -half)
+            path.lineTo(0.0, half)
+            path.lineTo(sign * d, q)
+            path.lineTo(sign * d, -q)
+            path.closeSubpath()
+        return path
+
+    def boundingRect(self) -> QRectF:
+        s = max(1, self._spec.size)
+        half = s / 2.0
+        m = max(self._spec.outline, 0) + 1
+        if self._radial or self._diamond:
+            # dot 旋转后, 以原点为中心的最大半径 = hypot(depth, half)
+            r = math.hypot(self._depth(), half) + m
+            return QRectF(-r, -r, r * 2, r * 2)
+        sign = self._inward_sign()
+        depth = self._depth()
+        xmin = min(0.0, sign * depth) - m
+        xmax = max(0.0, sign * depth) + m
+        ymin = -half - m
+        ymax = half + m
+        return QRectF(xmin, ymin, xmax - xmin, ymax - ymin)
+
+    def shape(self) -> QPainterPath:
+        """命中区域: 覆盖 dot 并保证至少 12px 便于 hover(不影响点击)"""
+        s = max(1, self._spec.size)
+        depth = self._depth()
+        if self._radial or self._diamond:
+            r = max(12.0, math.hypot(depth, s / 2.0) + 2.0)
+            path = QPainterPath()
+            path.addRect(-r, -r, r * 2, r * 2)
+            return path
+        sign = self._inward_sign()
+        w = max(12.0, depth + 4.0)
+        h = max(12.0, s + 4.0)
+        x0 = 0.0 if sign > 0 else -w
+        path = QPainterPath()
+        path.addRect(x0, -h / 2.0, w, h)
+        return path
+
+    def isPointOnDot(self, scene_pos: QPointF) -> bool:
+        """场景坐标是否落在 dot 实际几何(非 12px 放大命中区)内。
+
+        ``shape()`` 为方便 hover 故意放大到至少 12px, 会导致节点外环点击
+        误命中 port; 本方法用 dot 的真实路径做判定, 供画布区分
+        "点击 port dot 本身" 与 "点击节点外环"。
+        """
+        local = self.mapFromScene(scene_pos)
+        return self._dot_path().contains(local)
+
+    def _layoutText(self) -> None:
+        """排布 hit(内侧, 节点内)与 label(外侧, 节点外)文本(始终水平)"""
+        sign = self._text_sign()
+        depth = self._depth()
+        if self._hit_item is not None:
+            r = self._hit_item.boundingRect()
+            # hit 位于 dot 内侧(朝向节点中心), 更贴近 dot
+            if sign > 0:  # left -> dot 右侧
+                x = depth + HIT_GAP
+            else:          # right -> dot 左侧
+                x = -(depth + HIT_GAP) - r.width()
+            self._hit_item.setPos(x, -r.height() / 2)
+        if self._label_item is not None:
+            r = self._label_item.boundingRect()
+            # label 位于边界外侧(节点外)
+            if sign > 0:  # left -> 边界左侧
+                x = -LABEL_GAP - r.width()
+            else:          # right -> 边界右侧
+                x = LABEL_GAP
+            self._label_item.setPos(x, -r.height() / 2)
+            # 文本变化后 boundingRect 改变, 重设缩放锰点保持"原地弹出"中心
+            if self._label_visible:
+                self._label_item.setTransformOriginPoint(r.center())
+
+    def _updateLabelVisible(self) -> None:
+        """根据 _solo/_show_all 计算 label 目标可见态, 驱动弹出/收回动画。
+
+        用 _label_visible 去重: 目标态未变时直接返回, 避免 hover move 等
+        高频调用反复重启动画。
+        """
+        if self._label_item is None:
+            return
+        target = self._solo or self._show_all
+        if target == self._label_visible:
+            return
+        if target:
+            self._animateLabelShow()
+        else:
+            self._animateLabelHide()
+
+    # ---- label 动画(弹出+淡入 / 淡出+收回) ----
+    def _animateLabelShow(self) -> None:
+        """显示 label: 弹出(scale -> 1.0, OutBack 回弹) + 淡入(opacity -> 1.0)。
+
+        缩放以 label 自身中心为锰点(原地弹出, 文本不位移)。
+        """
+        if self._label_item is None:
+            return
+        self._label_visible = True
+        self._stopLabelAnims()
+        # 缩放锰点 = label 自身中心(文本变化后需重设, 见 _layoutText)
+        r = self._label_item.boundingRect()
+        self._label_item.setTransformOriginPoint(r.center())
+        self._label_item.show()
+
+        # opacity: 当前值 -> 1.0(线性淡入)
+        anim = QPropertyAnimation(self._label_item, b"opacity")
+        anim.setDuration(ANIMATION_DURATION_SHOW)
+        anim.setStartValue(self._label_item.opacity())
+        anim.setEndValue(1.0)
+
+        # scale: 当前值 -> 1.0(OutBack 轻微回弹 = 弹出感)
+        s_anim = QPropertyAnimation(self._label_item, b"scale")
+        s_anim.setDuration(ANIMATION_DURATION_SHOW)
+        s_anim.setStartValue(max(_PORT_LABEL_POP_SCALE, self._label_item.scale()))
+        s_anim.setEndValue(1.0)
+        s_anim.setEasingCurve(QEasingCurve.Type.OutBack)
+
+        self._label_show_anim = anim
+        self._label_scale_show = s_anim
+        anim.start()
+        s_anim.start()
+
+    def _animateLabelHide(self) -> None:
+        """隐藏 label: 淡出(opacity -> 0.0) + 收回(scale -> 0.85, InQuad)。
+
+        动画结束后才真正 hide item, 避免中途消失造成视觉跳变。
+        """
+        if self._label_item is None:
+            return
+        self._label_visible = False
+        self._stopLabelAnims()
+
+        # opacity: 当前值 -> 0.0(线性淡出)
+        anim = QPropertyAnimation(self._label_item, b"opacity")
+        anim.setDuration(ANIMATION_DURATION_HIDE)
+        anim.setStartValue(self._label_item.opacity())
+        anim.setEndValue(0.0)
+        anim.finished.connect(self._onLabelHideFinished)
+
+        # scale: 当前值 -> 0.85(InQuad 平滑收回)
+        s_anim = QPropertyAnimation(self._label_item, b"scale")
+        s_anim.setDuration(ANIMATION_DURATION_HIDE)
+        s_anim.setStartValue(self._label_item.scale())
+        s_anim.setEndValue(_PORT_LABEL_POP_SCALE)
+        s_anim.setEasingCurve(QEasingCurve.Type.InQuad)
+
+        self._label_hide_anim = anim
+        self._label_scale_hide = s_anim
+        anim.start()
+        s_anim.start()
+
+    def _onLabelHideFinished(self) -> None:
+        """淡出收回完成后, 真正隐藏 item(若期间未又被切回显示)。"""
+        if (not self._label_visible) and (self._label_item is not None):
+            self._label_item.hide()
+
+    def _stopLabelAnims(self) -> None:
+        """停止所有进行中的 label 动画(切换方向时调用, 避免动画互相干扰)"""
+        for attr in ("_label_show_anim", "_label_hide_anim",
+                     "_label_scale_show", "_label_scale_hide"):
+            a = getattr(self, attr, None)
+            if a is not None:
+                a.stop()
+
+    # ---- 绘制 ----
+    def _fill_color(self) -> QColor:
+        """dot 填充色: 自定义色优先, 未指定时按所在侧回退到静态默认色"""
+        if self._spec.color is not None:
+            return self._spec.color
+        return QNodePortSpec.LEFT_COLOR if self._is_left() else QNodePortSpec.RIGHT_COLOR
+
+    def paint(self, painter: QPainter, option, widget=None) -> None:
+        painter.setRenderHint(QPainter.RenderHint.Antialiasing, True)
+        fill = self._fill_color()
+        # 圆形/菱形节点: 把 dot 旋转到对准外法线(底边贴合该处切线/斜边)
+        if self._radial or self._diamond:
+            painter.save()
+            painter.rotate(self._orient_angle)
+        path = self._dot_path()
+        outlined = (self._hovered or self._active or self._drop_target
+                    or self._flash_error)
+        if outlined and self._spec.outline > 0:
+            ow = self._spec.outline
+            # 外描边: 先以 2*ow 宽居中描边(不填), 再用 fill 覆盖路径内部,
+            # 只保留路径外侧 ow 宽的描边带 -> 形成纯外侧描边
+            # _flash_error 用红色(不合规反馈), 其余用 DodgerBlue
+            outline_color = PORT_ERROR_OUTLINE if self._flash_error else PORT_HOVER_OUTLINE
+            pen = QPen(outline_color, ow * 2)
+            pen.setJoinStyle(Qt.PenJoinStyle.MiterJoin)
+            painter.setPen(pen)
+            painter.setBrush(Qt.BrushStyle.NoBrush)
+            painter.drawPath(path)
+            painter.setPen(QPen(Qt.PenStyle.NoPen))
+            painter.setBrush(QBrush(fill))
+            painter.drawPath(path)
+        else:
+            painter.setPen(QPen(Qt.PenStyle.NoPen))
+            painter.setBrush(QBrush(fill))
+            painter.drawPath(path)
+        if self._radial or self._diamond:
+            painter.restore()
+
+    # ---- hover ----
+    def hoverEnterEvent(self, event) -> None:
+        self._hovered = True
+        self._solo = True
+        self._updateLabelVisible()
+        self.update()
+        # 通知节点: 悬停 dot 时只展示本 dot, 取消"显示全部"
+        self._node._onPortHoverEnter(self)
+        super().hoverEnterEvent(event)
+
+    def hoverLeaveEvent(self, event) -> None:
+        self._hovered = False
+        self._solo = False
+        self._updateLabelVisible()
+        self.update()
+        self._node._onPortHoverLeave(self)
+        super().hoverLeaveEvent(event)
+
+    def clearHoverVisuals(self) -> None:
+        """清除本端口的 hover 视觉(描边/solo), 由节点在离开时统一调用"""
+        if self._hovered or self._solo:
+            self._hovered = False
+            self._solo = False
+            self._updateLabelVisible()
+            self.update()
+
+    # ---- 不合规连接反馈 ----
+    def flashError(self) -> None:
+        """红色外描边闪烁(试图创建不合规连接时的反馈)。
+
+        QTimer 驱动 3 次闪烁(150ms 间隔), 在红色描边与无描边间 toggle。
+        """
+        # 停掉正在进行的闪烁, 重新开始
+        if self._flash_timer is not None:
+            self._flash_timer.stop()
+            self._flash_timer.deleteLater()
+            self._flash_timer = None
+        self._flash_error = True
+        self.update()
+
+        flash_count = [0]
+
+        def toggleFlash():
+            flash_count[0] += 1
+            # 奇数次: 显示红色描边(_flash_error=True); 偶数次: 关闭
+            self._flash_error = (flash_count[0] % 2 == 0)
+            self.update()
+            if flash_count[0] >= 6:  # 3 次闪烁 = 6 次切换
+                self._flash_timer.stop()
+                self._flash_timer.deleteLater()
+                self._flash_timer = None
+                self._flash_error = False
+                self.update()
+
+        self._flash_timer = QTimer()
+        self._flash_timer.timeout.connect(toggleFlash)
+        self._flash_timer.start(150)
+
+    # ---- 连线拖拽 ----
+    def setActive(self, active: bool) -> None:
+        """标记/取消连线进行中的起点态。
+
+        置 ``True`` 时, 即使光标已离开本 port, 描边仍保持(复用 hover 描边视觉);
+        由画布在连线成功或失败后调用 ``setActive(False)`` 清除。
+        """
+        self._active = active
+        self.update()
+
+    def setDropTarget(self, on: bool) -> None:
+        """标记/取消本 port 作为连线落点(目标端)的高亮态。
+
+        连线拖拽期间画布接管鼠标移动事件, 光标下的目标 port 不会收到
+        hoverEnter/hoverLeave(场景 hover 派发被压制), 故由画布在
+        mouseMoveEvent 中手动命中检测后调用本方法驱动描边与 label。
+        复用 hover 描边视觉(DodgerBlue 外描边), 并立即显示 label。
+        """
+        if self._drop_target == on:
+            return
+        self._drop_target = on
+        # 同步 solo 态: 落点高亮时显示 label, 离开时恢复(不覆盖节点级 show_all)
+        self._solo = on
+        self._updateLabelVisible()
+        self.update()
+
+    def mousePressEvent(self, event) -> None:
+        """左键按下: 从本 port 发起连线拖拽(port 优先于 node 外环)。
+
+        拖拽期间的 move/release 由画布(NodeCanvas)统一接管, 与 node 外环
+        拖拽一致; 此处仅负责起始按下并通知画布。
+        """
+        if event.button() == Qt.MouseButton.LeftButton:
+            self._active = True
+            self.update()
+            self._node._onPortDragStart(self, event.scenePos())
+            event.accept()
+        else:
+            super().mousePressEvent(event)

chartflow/node/qnode_editor.py

@@ -0,0 +1,73 @@
+"""
+
+
+节点编辑器基类模块
+
+提供QNodeEditor基类，用户可以通过继承此类来创建自定义的节点编辑器
+"""
+
+from chartflow.node.node_item import QNodeItem
+
+
+from PyQt6.QtWidgets import QWidget
+from typing import Optional, TYPE_CHECKING
+
+class QNodeEditor(QWidget):
+    """
+    节点编辑器基类
+    
+    用户可以通过继承此类来创建自定义的节点编辑器。
+    当节点被双击时，会实例化对应的编辑器，并将节点作为参数传入。
+    
+    Example:
+        class MyNodeEditor(QNodeEditor):
+            def __init__(self, node: NodeItem, parent=None):
+                super().__init__(node, parent)
+                # 自定义初始化
+                
+            def getTitle(self) -> str:
+                return f"Editing: {self.node.name}"
+    """
+    
+    def __init__(self, node: 'QNodeItem', parent: Optional[QWidget] = None) -> None:
+        """
+        初始化节点编辑器
+        
+        Args:
+            node: 要编辑的节点
+            parent: 父窗口
+        """
+        super().__init__(parent)
+        self._node = node
+        self._setupUi()
+    
+    def _setupUi(self) -> None:
+        """设置UI界面，子类可以重写此方法"""
+        pass
+    
+    @property
+    def node(self) -> 'QNodeItem':
+        """获取当前编辑的节点"""
+        return self._node
+    
+    def getTitle(self) -> str:
+        """获取编辑器窗口标题"""
+        return f"Node Editor - {self._node.name}"
+    
+    def save(self) -> bool:
+        """
+        保存编辑器内容到节点
+        
+        Returns:
+            True if save successful, False otherwise
+        """
+        return True
+    
+    def load(self) -> bool:
+        """
+        从节点加载内容到编辑器
+        
+        Returns:
+            True if load successful, False otherwise
+        """
+        return True