chartflow 0.1.2__tar.gz → 0.1.4__tar.gz

{chartflow-0.1.2 → chartflow-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chartflow
-Version: 0.1.2
+Version: 0.1.4
 Summary: Self-use. with fsm. node. chart. edit. Used for fsm and run, structure graph. use pyqt to show and interact
 Author-email: 2229066748@qq.com
 Maintainer: Eagle'sBaby

{chartflow-0.1.2 → chartflow-0.1.4}/chartflow/node/__init__.py

@@ -19,12 +19,16 @@ from chartflow.node.node_item import QNodeItem
 from chartflow.node.port_item import QNodePort, QNodePortSpec
 from chartflow.node._port_interface import IQNodePort
 from chartflow.node.connection_item import ConnectionItem
+from chartflow.node._connection_interface import IConnectionItem, IQConnectionEditor
 from chartflow.node.arrow_item import ArrowItem
 from chartflow.node.selection_rect import SelectionRect
 from chartflow.node.style_panel import StylePanel
 from chartflow.node.node_canvas import QNodeCanvas
 from chartflow.node.main_window import NodeCanvasWindow
 from chartflow.node.qnode_editor import QNodeEditor
+from chartflow.node.qconnection_editor import (
+    QConnectionEditor, QConnectionNameEditor, openConnectionEditor,
+)
 from chartflow.node.popmenu import (
     ICanvasPopMenu, QCanvasPopMenu,
     INodePopMenu, QNodePopMenu,
@@ -50,6 +54,7 @@ __all__ = [
     "QNodePortSpec",
     "IQNodePort",
     "ConnectionItem",
+    "IConnectionItem",
     "ArrowItem",
     "SelectionRect",
     # UI Components
@@ -59,6 +64,10 @@ __all__ = [
     "NodeCanvasWindow",
     # Editor
     "QNodeEditor",
+    "QConnectionEditor",
+    "QConnectionNameEditor",
+    "IQConnectionEditor",
+    "openConnectionEditor",
     # Pop Menus
     "ICanvasPopMenu", "QCanvasPopMenu",
     "INodePopMenu", "QNodePopMenu",

chartflow-0.1.4/chartflow/node/_connection_interface.py

@@ -0,0 +1,196 @@
+"""
+连接项接口契约模块
+
+定义 IConnectionItem(Protocol) 与 IQConnectionEditor(Protocol) ——
+连接项(连线)及其编辑器的对外类型契约。
+
+Protocol 仅用于静态类型检查与文档, 不参与运行时继承(不进入 MRO),
+因此可安全地与 QGraphicsPathItem / QWidget 继承体系并存。
+
+IConnectionItem 声明了 ConnectionItem 对外暴露的名称/数据/编辑器/
+信号/序列化接口; IQConnectionEditor 声明了连线编辑器(见
+qconnection_editor.QConnectionEditor)的对外接口, 与节点编辑器
+QNodeEditor 的接口形态保持一致。
+
+约定: 本模块只含类型声明, 不得有运行时依赖, 以避免循环导入。
+"""
+
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+from PyQt6.QtCore import QPointF, pyqtSignal
+
+
+@runtime_checkable
+class IConnectionItem(Protocol):
+    """连接项接口契约
+
+    声明一条连线(ConnectionItem)在 名称 / 编辑器 / 序列化 方面应具备的
+    对外属性与方法。几何/样式/箭头/端口锚定等既有接口不在此重复声明。
+
+    契约分组:
+
+    - **名称与数据**: ``name`` / ``data``
+    - **编辑器**: ``editorClass`` / ``editorEmbedded`` / ``isEditWindowOpen`` /
+      :meth:`setEditWindowOpen` / :meth:`closeEditor`
+    - **几何**: ``center``(连线中点, 编辑器/名称 label 的锚点)
+    - **信号**: ``editRequested`` / ``nameChanged``
+    - **序列化**: :meth:`toDict` / :meth:`fromDict`
+
+    所有坐标默认为 **场景坐标(scene coordinate)**, 几何单位为像素。
+    """
+
+    # ---- 名称与数据 ----
+    @property
+    def name(self) -> str:
+        """连线名称(可读写)。
+
+        读取返回当前名称(可为空串); 赋值会更新连线中点的名称 label
+        (空串时隐藏)并发出 :attr:`nameChanged` 信号。名称会被
+        :meth:`toDict` / :meth:`fromDict` 序列化。
+        """
+        ...
+
+    @name.setter
+    def name(self, value: str) -> None: ...
+
+    @property
+    def data(self) -> Dict[str, Any]:
+        """连线自定义数据字典(只读引用, 内容可改)。
+
+        返回内部 ``_data`` 字典本身而非副本, 调用方可直接增删键值,
+        供自定义编辑器(如保存备注/参数)持久化内容使用。
+        会被 :meth:`toDict` / :meth:`fromDict` 序列化。
+        """
+        ...
+
+    # ---- 编辑器 ----
+    @property
+    def editorClass(self) -> Optional[type]:
+        """连线编辑器类(可读写)。
+
+        设为某个 ``QWidget`` 子类 ``type`` 时, 双击连线(或右键菜单
+        Edit Connection)会通过 :attr:`editRequested` 信号请求由该类创建
+        编辑面板; ``None`` 表示使用内置默认名称编辑器
+        (:class:`~chartflow.node.qconnection_editor.QConnectionNameEditor`)。
+        编辑器类本身不可序列化(与节点 editorClass 一致)。
+        """
+        ...
+
+    @editorClass.setter
+    def editorClass(self, value: Optional[type]) -> None: ...
+
+    @property
+    def editorEmbedded(self) -> bool:
+        """编辑器是否嵌入连线中点(可读写, 默认 ``True``)。
+
+        - ``True``: 编辑器经 ``QGraphicsProxyWidget`` 嵌入连线中点, 随连线
+          路径更新自动跟随;
+        - ``False``: 编辑器作为独立浮动窗口打开(与节点编辑器一致)。
+
+        该状态会被 :meth:`toDict` / :meth:`fromDict` 序列化(仅在
+        ``False`` 时落盘, 避免污染默认导出)。
+        """
+        ...
+
+    @editorEmbedded.setter
+    def editorEmbedded(self, value: bool) -> None: ...
+
+    @property
+    def isEditWindowOpen(self) -> bool:
+        """当前是否有编辑器窗口/嵌入面板打开(只读)。"""
+        ...
+
+    def setEditWindowOpen(self, open: bool) -> None:
+        """切换编辑窗口打开状态, 进而控制中点名称 label 的高亮提示。
+
+        由编辑器(如 :class:`QConnectionEditor`)在 show/close 时自动驱动;
+        打开时名称 label 显示高亮底衬(类比节点的 📖 悬浮标记)。
+
+        Args:
+            open: ``True`` 表示编辑器已打开, ``False`` 已关闭。
+        """
+        ...
+
+    def closeEditor(self) -> None:
+        """关闭当前打开的编辑器并清理嵌入代理(无打开编辑器时为空操作)。
+
+        画布在删除连线(:meth:`NodeCanvas.removeConnection`)时调用,
+        防止编辑器窗口/嵌入代理悬挂。
+        """
+        ...
+
+    # ---- 几何 ----
+    @property
+    def center(self) -> QPointF:
+        """连线中点的 **场景坐标**(只读), 取自 ``path().pointAtPercent(0.5)``。
+
+        作为名称 label 与嵌入编辑器的锚点; 自环连线同样按路径 50% 处取值。
+        """
+        ...
+
+    # ---- 信号(只读属性, 返回 pyqtSignal) ----
+    @property
+    def editRequested(self) -> pyqtSignal:
+        """编辑请求信号(只读)。
+
+        双击连线或点击右键菜单 Edit Connection 时发射, 载荷为本连线实例;
+        画布默认连接到打开编辑器的处理器(无 editorClass 时打开内置名称
+        编辑器), 宿主可自行断开/接管。
+        """
+        ...
+
+    @property
+    def nameChanged(self) -> pyqtSignal:
+        """名称变更信号(只读)。名称被修改时发射, 载荷为 (连线, 新名称)。"""
+        ...
+
+    # ---- 序列化 ----
+    def toDict(self) -> dict:
+        """将连线的 名称/数据/编辑器布局 序列化为字典。
+
+        仅包含非默认键: ``name``(非空) / ``data``(非空) /
+        ``editor_embedded``(仅 ``False``)。拓扑(source/target/port)与样式
+        由画布 export 与 styleToDict 负责, 不在此重复。
+
+        Returns:
+            连线数据字典(深拷贝, 修改返回值不影响连线)。
+        """
+        ...
+
+    def fromDict(self, data: dict) -> None:
+        """从字典恢复连线的 名称/数据/编辑器布局(增量合并, 忽略未知键)。
+
+        Args:
+            data: 由 :meth:`toDict` 产生(或同构)的字典。
+        """
+        ...
+
+
+@runtime_checkable
+class IQConnectionEditor(Protocol):
+    """连线编辑器接口契约
+
+    声明连线编辑器应具备的对外接口, 与节点编辑器
+    :class:`~chartflow.node.qnode_editor.QNodeEditor` 形态保持一致:
+    构造时传入被编辑对象, 提供 ``getTitle`` / ``save`` / ``load``。
+
+    具体实现由 :class:`~chartflow.node.qconnection_editor.QConnectionEditor`
+    承担; 用户自定义编辑器继承该类(或满足本契约)即可。
+    """
+
+    @property
+    def connection(self) -> IConnectionItem:
+        """获取当前编辑的连线(只读)。"""
+        ...
+
+    def getTitle(self) -> str:
+        """获取编辑器窗口标题(嵌入模式下一般不可见)。"""
+        ...
+
+    def save(self) -> bool:
+        """保存编辑器内容到连线。返回是否成功。"""
+        ...
+
+    def load(self) -> bool:
+        """从连线加载内容到编辑器。返回是否成功。"""
+        ...

{chartflow-0.1.2 → chartflow-0.1.4}/chartflow/node/_node_ports.py

@@ -56,6 +56,11 @@ class _NodePortMixin:
         self._port_label_timer.setSingleShot(True)
         self._port_label_timer.setInterval(PORT_LABEL_HOVER_DELAY_MS)
         self._port_label_timer.timeout.connect(self._showAllPortLabels)
+        # label 钉住态(始终可见)与闪现计时器(flashPortLabels 用)
+        self._port_labels_pinned: bool = False
+        self._port_flash_timer: QTimer = QTimer()
+        self._port_flash_timer.setSingleShot(True)
+        self._port_flash_timer.timeout.connect(self._unflashPortLabels)
 
     # ------------------------------------------------------------------ #
     # ports 属性
@@ -126,6 +131,50 @@ class _NodePortMixin:
             result[key] = ports
         return result
 
+    # ------------------------------------------------------------------ #
+    # 端口 label 显隐(钉住 / 闪现)
+    # ------------------------------------------------------------------ #
+    @property
+    def portLabelsVisible(self) -> bool:
+        """端口 label 是否始终可见(读写)。
+
+        True 时全部端口 label 钉住常显(优先于 hover 规则); False 时交还
+        hover 规则(节点 hover>0.5s 显示全部 / hover 单个 dot 显示该条)。
+        对重建端口(ports 重赋值)后新建的端口项同样生效。
+        """
+        return self._port_labels_pinned
+
+    @portLabelsVisible.setter
+    def portLabelsVisible(self, on: bool) -> None:
+        self._port_labels_pinned = bool(on)
+        self._setAllPortsLabelPinned(on)
+
+    def _setAllPortsLabelPinned(self, on: bool) -> None:
+        for side in ("left", "right"):
+            for item in self._port_items[side]:
+                item.setLabelPinned(on)
+
+    def flashPortLabels(self, continue_time: int = 1500) -> None:
+        """模拟弹出全部端口 label 并持续 ``continue_time`` 毫秒, 到期自动收回。
+
+        重复调用会重新计时。与 hover 规则正交: 闪现收回后 label 回到
+        hover/钉住所决定的可见态。continue_time <= 0 时立即收回。
+        """
+        for side in ("left", "right"):
+            for item in self._port_items[side]:
+                item.setLabelFlashed(True)
+        if continue_time <= 0:
+            self._unflashPortLabels()
+            return
+        self._port_flash_timer.start(max(0, int(continue_time)))
+
+    def _unflashPortLabels(self) -> None:
+        """闪现到期: 解除全部端口的闪现态(label 回到 hover/钉住规则)。"""
+        self._port_flash_timer.stop()
+        for side in ("left", "right"):
+            for item in self._port_items[side]:
+                item.setLabelFlashed(False)
+
     # ------------------------------------------------------------------ #
     # 端口渲染项构建/移除
     # ------------------------------------------------------------------ #
@@ -142,6 +191,7 @@ class _NodePortMixin:
         for side in ("left", "right"):
             for spec in self._ports_spec.get(side, []):
                 item = QNodePort(spec, side, self)
+                item.setLabelPinned(self._port_labels_pinned)  # 继承钉住态
                 self._port_items[side].append(item)
         self._layoutPorts()
 

{chartflow-0.1.2 → chartflow-0.1.4}/chartflow/node/connection_item.py

@@ -1,13 +1,17 @@
 """
 连接项模块 - 表示两个节点之间的连线
-包含两个独立的箭头项
+包含两个独立的箭头项, 以及中点的名称 label / 嵌入编辑器
 """
 
+import copy
 import math
-from typing import Optional, List, Callable
+from typing import Optional, List, Callable, Dict, Any
 
-from PyQt6.QtWidgets import QGraphicsItem, QGraphicsPathItem
-from PyQt6.QtCore import Qt, QPointF, QTimer, QRectF
+from PyQt6.QtWidgets import (
+    QGraphicsItem, QGraphicsPathItem, QGraphicsTextItem, QGraphicsRectItem,
+    QGraphicsProxyWidget, QWidget,
+)
+from PyQt6.QtCore import Qt, QPointF, QTimer, QRectF, QObject, pyqtSignal
 from PyQt6.QtGui import QPainterPath, QPainterPathStroker, QPen, QColor, QLinearGradient, QBrush
 
 from chartflow.node.styles import (
@@ -34,6 +38,26 @@ SELF_LOOP_RING_RADIUS = 18.0
 # 四分之一圆的贝塞尔控制点常数: 4/3*(sqrt(2)-1)
 _QUARTER_ARC_K = 0.5522847498
 
+# 名称 label 文本颜色(深岩灰, 与节点名称文本同色系)
+CONNECTION_LABEL_COLOR = QColor("#4A5568")
+# 编辑器打开时名称 label 的高亮底衬(类比节点的 📖 悬浮标记)
+CONNECTION_LABEL_EDIT_BG = QColor("#E3F0FF")
+CONNECTION_LABEL_EDIT_BORDER = QColor("#7FB2F0")
+
+
+class ConnectionSignalHelper(QObject):
+    """
+    信号辅助类 - 为 ConnectionItem 提供信号支持
+    因为 QGraphicsPathItem 继承自 QGraphicsItem 而不是 QObject,
+    所以需要通过组合方式来提供信号功能(与 NodeSignalHelper 同构)
+    """
+    editRequested = pyqtSignal(object)      # 编辑请求信号, 参数为连线自身
+    nameChanged = pyqtSignal(object, str)   # 名称改变信号, 参数为连线自身和新名称
+
+    def __init__(self, parent) -> None:
+        super().__init__()
+        self._parent = parent
+
 
 def _quarter_arc(path: QPainterPath, center: QPointF, r: float,
                  u_from: QPointF, u_to: QPointF) -> None:
@@ -194,6 +218,35 @@ class ConnectionItem(QGraphicsPathItem):
         self._arrow_drag_moved_callback: Optional[Callable[[QPointF], None]] = None
         self._arrow_drag_finished_callback: Optional[Callable[[QPointF, bool], None]] = None
 
+        # ------------------------------------------------------------------ #
+        # 名称 / 编辑器体系(镜像节点: 信号辅助 + 中点名称 label + 编辑器配置)
+        # ------------------------------------------------------------------ #
+        self._signal_helper = ConnectionSignalHelper(self)
+        self._name: str = ""
+        self._data: Dict[str, Any] = {}
+        self._editor_class: Optional[type] = None
+        # 编辑器嵌入(True, 默认, 嵌在连线中点) / 浮动(False, 独立窗口)
+        self._editor_embedded: bool = True
+        self._edit_window_open: bool = False
+        self._open_editor: Optional[QWidget] = None
+        self._embedded_proxy: Optional[QGraphicsProxyWidget] = None
+
+        # 编辑器打开时名称 label 的高亮底衬(子项, z=-1 位于 label 之下)
+        self._label_bg: QGraphicsRectItem = QGraphicsRectItem(self)
+        self._label_bg.setZValue(-1)
+        self._label_bg.setBrush(QBrush(CONNECTION_LABEL_EDIT_BG))
+        self._label_bg.setPen(QPen(CONNECTION_LABEL_EDIT_BORDER, 1.0))
+        self._label_bg.setVisible(False)
+
+        # 中点名称 label(子项; 连线 item 无位置偏移, 子项坐标即场景坐标)
+        self._text_item: QGraphicsTextItem = QGraphicsTextItem("", self)
+        self._text_item.setDefaultTextColor(CONNECTION_LABEL_COLOR)
+        # 禁用文本项的鼠标/hover 事件, 让事件完全传递给连线本体
+        self._text_item.setTextInteractionFlags(Qt.TextInteractionFlag.NoTextInteraction)
+        self._text_item.setAcceptHoverEvents(False)
+        self._text_item.setAcceptedMouseButtons(Qt.MouseButton.NoButton)
+        self._text_item.setVisible(False)
+
         # 更新路径
         self.updatePath()
     
@@ -409,6 +462,173 @@ class ConnectionItem(QGraphicsPathItem):
             self._connection_type = ConnectionType.BEZIER
         self.updatePath()
 
+    # ------------------------------------------------------------------ #
+    # 名称 / 数据 / 编辑器(镜像节点 QNodeItem 的同名体系)
+    # ------------------------------------------------------------------ #
+    @property
+    def name(self) -> str:
+        """获取连线名称(可为空串, 空串时中点名称 label 隐藏)"""
+        return self._name
+
+    @name.setter
+    def name(self, value: str) -> None:
+        """设置连线名称: 更新中点 label 并发 :attr:`nameChanged` 信号"""
+        value = value or ""
+        old_name = self._name
+        self._name = value
+        self._text_item.setPlainText(value)
+        if old_name != value:
+            self._signal_helper.nameChanged.emit(self, value)
+        self._layoutLabel()
+
+    @property
+    def data(self) -> Dict[str, Any]:
+        """连线自定义数据字典(只读引用, 内容可改; 供编辑器持久化内容)"""
+        return self._data
+
+    @property
+    def editorClass(self) -> Optional[type]:
+        """获取连线编辑器类(None = 使用内置默认名称编辑器)"""
+        return self._editor_class
+
+    @editorClass.setter
+    def editorClass(self, value: Optional[type]) -> None:
+        """设置连线编辑器类"""
+        self._editor_class = value
+
+    @property
+    def editorEmbedded(self) -> bool:
+        """编辑器是否嵌入连线中点(True, 默认) / 独立浮动窗口(False)"""
+        return self._editor_embedded
+
+    @editorEmbedded.setter
+    def editorEmbedded(self, value: bool) -> None:
+        """设置编辑器嵌入/浮动布局(对已打开的编辑器不追溯生效)"""
+        self._editor_embedded = bool(value)
+
+    @property
+    def center(self) -> QPointF:
+        """连线中点(场景坐标): 名称 label 与嵌入编辑器的锚点"""
+        return self.path().pointAtPercent(0.5)
+
+    @property
+    def isEditWindowOpen(self) -> bool:
+        """当前是否有编辑器(嵌入或浮动)打开"""
+        return self._edit_window_open
+
+    def setEditWindowOpen(self, open: bool) -> None:
+        """切换编辑窗口打开状态, 控制名称 label 的高亮底衬(类比节点📖)"""
+        open = bool(open)
+        if self._edit_window_open == open:
+            return
+        self._edit_window_open = open
+        self._layoutLabel()
+
+    def closeEditor(self) -> None:
+        """关闭当前打开的编辑器并清理嵌入代理(无打开编辑器时为空操作)。
+
+        画布删除连线(:meth:`NodeCanvas.removeConnection`)时调用, 防止
+        编辑器窗口 / QGraphicsProxyWidget 悬挂。
+        """
+        editor = self._open_editor
+        if editor is not None:
+            self._open_editor = None
+            try:
+                editor.close()  # closeEvent -> setEditWindowOpen(False)
+            except RuntimeError:
+                pass
+        # 兜底清理嵌入代理(正常由 editor.destroyed 回调清理, 此处防悬挂)
+        proxy = self._embedded_proxy
+        if proxy is not None:
+            self._embedded_proxy = None
+            try:
+                if proxy.scene() is not None:
+                    proxy.scene().removeItem(proxy)
+                proxy.setParentItem(None)
+            except RuntimeError:
+                pass
+        self._layoutLabel()
+
+    # ---- 信号(只读属性, 返回 pyqtSignal) ----
+    @property
+    def editRequested(self) -> pyqtSignal:
+        """编辑请求信号: 双击连线或右键菜单 Edit Connection 时发射"""
+        return self._signal_helper.editRequested
+
+    @property
+    def nameChanged(self) -> pyqtSignal:
+        """名称变更信号: 载荷为 (连线, 新名称)"""
+        return self._signal_helper.nameChanged
+
+    def _layoutLabel(self) -> None:
+        """将名称 label / 嵌入编辑器定位到连线中点。
+
+        在 updatePath()(含自环路径)、name 变更、编辑器开关时调用。
+        label 与 proxy 均为本连线子项; 连线 item 无位置偏移(path 直接建在
+        场景坐标), 故子项本地坐标即场景坐标。嵌入编辑器打开期间隐藏 label,
+        避免名称双重显示。
+        """
+        label = getattr(self, "_text_item", None)
+        if label is None:
+            return  # 构造早期防御(updatePath 先于 label 创建时不应发生)
+        mid = self.path().pointAtPercent(0.5)
+        proxy = self._embedded_proxy
+        show_label = bool(self._name) and proxy is None
+        label.setVisible(show_label)
+        bg = self._label_bg
+        if show_label:
+            rect = label.boundingRect()
+            label.setPos(mid.x() - rect.width() / 2.0,
+                         mid.y() - rect.height() / 2.0)
+            show_bg = self._edit_window_open
+            bg.setVisible(show_bg)
+            if show_bg:
+                pad = 3.0
+                bg.setRect(label.pos().x() - pad, label.pos().y() - pad,
+                           rect.width() + 2 * pad, rect.height() + 2 * pad)
+        else:
+            bg.setVisible(False)
+        if proxy is not None:
+            size = proxy.size()
+            proxy.setPos(mid.x() - size.width() / 2.0,
+                         mid.y() - size.height() / 2.0)
+
+    # ------------------------------------------------------------------ #
+    # 序列化(拓扑/样式由画布 export 与 styleToDict 负责)
+    # ------------------------------------------------------------------ #
+    def toDict(self) -> dict:
+        """将连线的 名称/数据/编辑器布局 序列化为字典(仅非默认键)。
+
+        Returns:
+            连线数据字典; 默认连线(无名称/数据, 嵌入布局)返回空 dict,
+            避免污染导出。
+        """
+        result: dict = {}
+        if self._name:
+            result["name"] = self._name
+        if self._data:
+            # deepcopy: data 可能含列表/字典等可变嵌套, 浅拷贝会让外部
+            # 就地修改污染原连线 _data(与节点 toDict 策略一致)。
+            result["data"] = copy.deepcopy(self._data)
+        if not self._editor_embedded:
+            result["editor_embedded"] = False
+        return result
+
+    def fromDict(self, data: dict) -> None:
+        """从字典恢复连线的 名称/数据/编辑器布局(增量合并, 忽略未知键)。
+
+        Args:
+            data: 由 :meth:`toDict` 产生(或同构)的字典。
+        """
+        if not isinstance(data, dict):
+            return
+        if "name" in data:
+            self.name = data["name"] or ""
+        if isinstance(data.get("data"), dict):
+            self._data.update(data["data"])
+        if "editor_embedded" in data:
+            self.editorEmbedded = bool(data["editor_embedded"])
+
     def swapDirection(self) -> None:
         """
         交换源节点和目标节点，用于保留反向连接时
@@ -508,6 +728,7 @@ class ConnectionItem(QGraphicsPathItem):
             self._source_edge = QPointF()
             self._target_edge = QPointF()
             self._updateSelfLoopPath()
+            self._layoutLabel()
             return
 
         if self._source_port is not None:
@@ -542,6 +763,8 @@ class ConnectionItem(QGraphicsPathItem):
 
         # 端点变化后刷新 pen(端口渐变需按新端点重建渐变画刷)
         self._refreshPen()
+        # 路径变化后重定位中点名称 label / 嵌入编辑器
+        self._layoutLabel()
 
     def _updateSelfLoopPath(self) -> None:
         """绘制自环: 圆弧+直线组合, 端点吸附实际边线。

{chartflow-0.1.2 → chartflow-0.1.4}/chartflow/node/example.py

@@ -4,7 +4,7 @@ qnode库使用示例
 展示如何使用qnode库创建节点图
 """
 
-from PyQt6.QtWidgets import QVBoxLayout, QLabel, QTextEdit
+from PyQt6.QtWidgets import QVBoxLayout, QLabel, QTextEdit, QPushButton
 
 
 import sys
@@ -13,7 +13,7 @@ from PyQt6.QtCore import QPointF
 
 from chartflow.node import (
     NodeCanvasWindow, QNodeCanvas, QNodeItem,
-    NodeShape, ConnectionType, QNodeEditor
+    NodeShape, ConnectionType, QNodeEditor, QConnectionEditor
 )
 
 
@@ -42,6 +42,31 @@ class MyNodeEditor(QNodeEditor):
         return True
 
 
+class MyConnectionEditor(QConnectionEditor):
+    """自定义连线编辑器示例(编辑连线备注, 经 connection.data 持久化)"""
+
+    def _setupUi(self) -> None:
+        layout = QVBoxLayout(self)
+
+        info_label = QLabel(f"Editing connection: {self.connection.name or '(unnamed)'}")
+        layout.addWidget(info_label)
+
+        # 备注编辑(存入 connection.data, 随画布 export/import 保存)
+        self.text_edit = QTextEdit()
+        self.text_edit.setPlaceholderText("Connection note...")
+        self.text_edit.setPlainText(self.connection.data.get("note", ""))
+        layout.addWidget(self.text_edit)
+
+        save_button = QPushButton("Save")
+        save_button.clicked.connect(self.save)
+        layout.addWidget(save_button)
+
+    def save(self) -> bool:
+        """保存编辑器内容到连线数据"""
+        self.connection.data["note"] = self.text_edit.toPlainText()
+        return True
+
+
 def main():
     """主函数"""
     app = QApplication(sys.argv)
@@ -64,10 +89,24 @@ def main():
     node2.data["content"] = "Process logic here..."
     
     # 创建连接
-    canvas.addConnection(node1, node2)
-    canvas.addConnection(node2, node3)
-    canvas.addConnection(node3, node4)
-    
+    conn12 = canvas.addConnection(node1, node2)
+    conn23 = canvas.addConnection(node2, node3)
+    conn34 = canvas.addConnection(node3, node4)
+
+    # 连线命名: 名称持久显示在连线中点(双击可编辑)
+    conn12.name = "init"
+    conn23.name = "process"
+
+    # 连线编辑器示例:
+    # - conn23: 自定义编辑器, 默认嵌入连线中点(QGraphicsProxyWidget)
+    # - conn34: 自定义编辑器, editorEmbedded=False 作为浮动窗口打开
+    conn23.editorClass = MyConnectionEditor
+    conn34.name = "finish"
+    conn34.editorClass = MyConnectionEditor
+    conn34.editorEmbedded = False
+
+    # 未设置 editorClass 的连线(如 conn12): 双击打开内置名称编辑器
+
     # 设置双向连接示例
     canvas.addConnection(node2, node4, is_bidirectional=True)