chartflow 0.1__py3-none-any.whl

chartflow/node/_node_base.py

@@ -0,0 +1,727 @@
+"""
+节点核心基类模块
+
+定义 _NodeCore(QGraphicsEllipseItem) —— 节点项的运行时根基类。
+承载节点最基础的属性、常量、信号、几何核心与样式核心, 并提供
+_init_ports / _init_interaction / _init_markers 三个初始化钩子,
+供 Mixin 子类覆写以填充各自层的属性。
+
+层次结构:
+    INodeItem (Protocol, 仅类型)            <- _node_interface.py
+        |
+    _NodeCore(QGraphicsEllipseItem)         <- 本模块
+        |
+    _NodePortMixin                          <- _node_ports.py
+        |
+    _NodeInteractionMixin                   <- _node_interaction.py
+        |
+    NodeItem                                <- node_item.py (paint/序列化)
+
+遵循代码规范: 本模块不含 paint/toDict/fromDict 等最终实现, 那些留在 node_item.py。
+"""
+
+import math
+import uuid
+from typing import Optional, Dict, Any, TYPE_CHECKING
+
+from PyQt6.QtWidgets import (
+    QGraphicsItem, QGraphicsEllipseItem, QGraphicsTextItem,
+)
+from PyQt6.QtCore import Qt, QPointF, QRectF, QTimer, pyqtSignal, QObject, \
+    QPropertyAnimation, QEasingCurve
+from PyQt6.QtGui import QBrush, QPen, QColor, QFont, QPainterPath
+
+from chartflow.node.styles import NodeStyle
+from chartflow.node.enums import NodeState, NodeShape
+
+if TYPE_CHECKING:
+    from chartflow.node.popmenu import QNodePopMenu
+
+
+# 常量定义
+MIN_RADIUS = 40.0
+PADDING = 15.0
+TEXT_EDIT_PADDING = 4.0
+BUTTON_RADIUS_RATIO = 0.2
+ANIMATION_DURATION_SHOW = 200
+ANIMATION_DURATION_HIDE = 100
+Z_VALUE_NODE = 50
+Z_VALUE_BUTTON = 100
+Z_VALUE_MARKER = 100
+
+# 节点尺寸相关
+INNER_RATIO = 0.75       # 内部区域占半径的比例(与边缘指示器一致)
+PORT_MIN_GAP = 5.0       # 端口之间的最小垂直间距
+NAME_INNER_PAD = 6.0     # 名称与内部区域边界的内边距
+# 命中/hover 外环厚度(像素): 节点几何之外的可交互边缘带, 用于发起/接收
+# 连线以及触发 hover 描边。须覆盖描边半宽 + 命中余量。
+NODE_HIT_EDGE_BAND = 5.0
+
+# "hover 显示全部端口" 要求鼠标静止: 移动超过该距离则打断并重置等待
+HOVER_MOVE_THRESHOLD_SQ = 25.0  # 5px 的平方
+
+# 圆形(椭圆)节点: 端口分布在左右侧弧的角度窗口(避开上下极点)
+CIRCLE_PORT_WINDOW_DEG = 65.0     # 侧弧半角度(从侧中心向上下各 65°)
+CIRCLE_PORT_MAX_STEP_DEG = 22.0   # 角度步进上限(端口少时向侧中心聚拢)
+
+
+class NodeSignalHelper(QObject):
+    """
+    信号辅助类 - 用于为 NodeItem 提供信号支持
+    因为 QGraphicsEllipseItem 继承自 QGraphicsItem 而不是 QObject,
+    所以需要通过组合方式来提供信号功能
+    """
+    editRequested = pyqtSignal(object)  # 编辑请求信号，参数为节点自身
+    nameChanged = pyqtSignal(object, str)  # 名称改变信号，参数为节点自身和新名称
+
+    def __init__(self, parent) -> None:
+        super().__init__()
+        self._parent = parent
+
+
+class _NodeCore(QGraphicsEllipseItem):
+    """节点核心基类
+
+    承载节点最基础的数据与行为: 身份(name/shape/state)、几何核心
+    (_calculateHalfSize/_setSize/_applySize/_centerText)、样式核心
+    (_applyStyle/setColor/setBorder)、字体、装饰器、信号、数据字典。
+
+    提供 _init_ports / _init_interaction / _init_markers 三个空钩子,
+    供 Mixin 子类覆写以初始化各自层的属性。__init__ 按依赖顺序调用它们。
+
+    本类不含 paint/toDict/fromDict/getEdgePoint —— 它们依赖跨层方法,
+    留给最终的 NodeItem 实现。
+    """
+
+    def __init__(
+        self,
+        name: str,
+        position: QPointF = QPointF(0, 0),
+        shape: NodeShape = NodeShape.ELLIPSE,
+        parent: Optional[QGraphicsItem] = None
+    ) -> None:
+        """初始化节点
+
+        Args:
+            name: 节点名称
+            position: 节点位置
+            shape: 节点形状
+            parent: 父项
+        """
+        # 先设置基本属性
+        self._name: str = name
+        # 稳定唯一标识(uuid4 hex 字符串), 跨进程持久化后仍可还原连线拓扑。
+        # 由 toDict 序列化、fromDict 还原; 不依赖 Python id()(内存地址, 进程
+        # 重启后会变, 导致重载 JSON 后所有连线 target/source 丢失)。
+        self._node_id: str = uuid.uuid4().hex
+        self._shape: NodeShape = shape
+        self._style: NodeStyle = NodeStyle()
+        self._state: NodeState = NodeState.IDLE
+        self._min_radius: float = MIN_RADIUS
+        self._padding: float = PADDING
+        # 连线进行中: 作为落点(目标节点)被高亮(画布手动驱动, hover 派发被压制)
+        self._drop_target: bool = False
+        # 不合规连接: 红色描边闪烁中
+        self._flash_error: bool = False
+        self._flash_timer: Optional[QTimer] = None
+
+        # 端口/hover 状态(尺寸计算可能依赖端口, 需先初始化)
+        self._ports_spec: Dict[str, list] = {"left": [], "right": []}
+        self._port_items: Dict[str, list] = {"left": [], "right": []}
+        self._node_hovered: bool = False
+        self._hovered_port_count: int = 0
+        self._hover_anchor: Optional[QPointF] = None  # 判断鼠标是否静止的锚点
+
+        # 调用各 Mixin 的初始化钩子(填充本层属性: timer / 按钮 / 标记等)
+        self._init_ports()
+        self._init_interaction()
+        self._init_markers()
+
+        # 计算半宽/半高(矩形且有端口时可长宽不等)
+        self._rw, self._rh = self._calculateHalfSize()
+        self._radius: float = self._rw
+
+        # 初始化QGraphicsEllipseItem（以(0,0)为中心）
+        super().__init__(QRectF(-self._rw, -self._rh, self._rw * 2, self._rh * 2), parent)
+
+        # 使用setPos设置位置（节点的中心点）
+        self.setPos(position)
+
+        # 设置节点的Z值，确保在连线上方（连线Z=1，箭头Z=10）
+        self.setZValue(Z_VALUE_NODE)
+
+        # 创建信号辅助对象
+        self._signal_helper = NodeSignalHelper(self)
+
+        # 创建文本项
+        self._text_item: QGraphicsTextItem = QGraphicsTextItem(self._name, self)
+        self._text_item.setDefaultTextColor(self._style.text_color)
+        # 禁用文本项的所有鼠标事件处理，让事件完全传递给父节点
+        self._text_item.setTextInteractionFlags(Qt.TextInteractionFlag.NoTextInteraction)
+        self._text_item.setAcceptHoverEvents(False)
+        self._text_item.setAcceptedMouseButtons(Qt.MouseButton.NoButton)
+        self._centerText()
+
+        # 设置可选项标志
+        self.setFlag(QGraphicsItem.GraphicsItemFlag.ItemIsSelectable, True)
+        self.setFlag(QGraphicsItem.GraphicsItemFlag.ItemIsMovable, True)
+        self.setFlag(QGraphicsItem.GraphicsItemFlag.ItemSendsGeometryChanges, True)
+        self.setAcceptHoverEvents(True)
+
+        # 此时 self 已是有效的 QGraphicsItem, 创建需要以本节点为父项的覆盖物
+        # (悬浮按钮等)。由 _NodeInteractionMixin 覆写。
+        self._setup_overlays()
+
+        # 数据存储（只读属性，用户可以自由添加数据）
+        self._data: Dict[str, Any] = {}
+
+        # 编辑器类（用户自定义编辑器）
+        self._editor_class: Optional[type] = None
+
+        # 节点右键菜单(由 NodeCanvas.addNode 注入; 构造时无 canvas 故默认 None)
+        self.menu: Optional["QNodePopMenu"] = None
+
+        # 名称编辑状态
+        self._is_editing_name: bool = False
+
+        # 更名区域（浅浅浅灰色虚线框）
+        self._name_edit_area: QRectF = self._calculateNameEditArea()
+
+        # 自定义样式属性（用于导出/导入和面板控制）
+        self._custom_fill_color: Optional[QColor] = None
+        self._custom_stroke_color: Optional[QColor] = None
+        self._custom_stroke_width: Optional[float] = None
+        self._custom_font_family: Optional[str] = None
+        self._custom_font_size: Optional[int] = None
+        self._custom_radius: Optional[float] = None
+
+        # 装饰器类型
+        self._decorator: Optional[str] = None
+
+        # 外环(可连线边缘指示器)可见性, 默认显示
+        self._edge_indicator_visible: bool = True
+
+        # 节点是否可参与连线(设为 False 时会清除其全部已有连线)
+        self._connectable: bool = True
+
+        # 自指规则: 控制同节点内 6 类自指连接是否允许创建。
+        # 默认值 = 既有逻辑(node→node / left→right / right→left 允许, 其余拒绝)。
+        # 通过 selfrefs property 暴露(返回内部 dict, 非副本, 可直接改值)。
+        self._selfrefs: Dict[str, bool] = {
+            "node->node": True,   # 同节点, 两端均无 port(node 自环)
+            "port->port": False,  # 同节点, 同极/同一 port 自指(不含异极)
+            "node->port": False,  # 同节点, 源为节点边缘、目标为本节点 port
+            "port->node": False,  # 同节点, 源为本节点 port、目标为节点边缘
+            "left->right": True,  # 同节点, 源=left port、目标=right port
+            "right->left": True,  # 同节点, 源=right port、目标=left port
+        }
+
+        # 应用样式
+        self._applyStyle()
+
+    # ------------------------------------------------------------------ #
+    # 初始化钩子(供 Mixin 子类覆写)
+    # ------------------------------------------------------------------ #
+    def _init_ports(self) -> None:
+        """端口层初始化钩子: _NodePortMixin 覆写以创建 port label timer 等"""
+
+    def _init_interaction(self) -> None:
+        """交互层初始化钩子: _NodeInteractionMixin 覆写以创建悬浮按钮等"""
+
+    def _init_markers(self) -> None:
+        """标记层初始化钩子: _NodeInteractionMixin 覆写以创建标记占位等"""
+
+    def _setup_overlays(self) -> None:
+        """覆盖物初始化钩子(在 QGraphicsItem 基类初始化完成后调用):
+        _NodeInteractionMixin 覆写以创建 HoverButton 等需以本节点为父项的对象"""
+
+    # ------------------------------------------------------------------ #
+    # 信号
+    # ------------------------------------------------------------------ #
+    @property
+    def editRequested(self):
+        """编辑请求信号"""
+        return self._signal_helper.editRequested
+
+    @property
+    def nameChanged(self):
+        """名称改变信号"""
+        return self._signal_helper.nameChanged
+
+    # ------------------------------------------------------------------ #
+    # 数据 / 编辑器
+    # ------------------------------------------------------------------ #
+    @property
+    def data(self) -> Dict[str, Any]:
+        """获取节点的数据字典（只读属性，但字典内容可修改）"""
+        return self._data
+
+    @property
+    def editorClass(self) -> Optional[type]:
+        """获取节点编辑器类"""
+        return self._editor_class
+
+    @editorClass.setter
+    def editorClass(self, value: Optional[type]) -> None:
+        """设置节点编辑器类"""
+        self._editor_class = value
+
+    # ------------------------------------------------------------------ #
+    # 装饰器
+    # ------------------------------------------------------------------ #
+    @property
+    def decorator(self) -> Optional[str]:
+        """获取节点装饰器类型"""
+        return self._decorator
+
+    @decorator.setter
+    def decorator(self, value: Optional[str]) -> None:
+        """设置节点装饰器类型
+
+        Args:
+            value: 装饰器类型，支持 'recursive', 'behavior', 'sequence', 'selector', 'parallel'
+        """
+        self._decorator = value
+        self.update()  # 重绘节点以应用新的边框颜色
+
+    def _getDecoratorStrokeColor(self) -> Optional[QColor]:
+        """根据装饰器类型获取边框颜色
+
+        Returns:
+            装饰器对应的边框颜色，如果没有装饰器则返回 None
+        """
+        if self._decorator is None:
+            return None
+
+        decorator = self._decorator.lower()
+
+        # recursive -> 紫罗兰色 (violet)
+        if decorator == 'recursive':
+            return QColor(238, 130, 238)  # Violet
+
+        # behavior, sequence, selector, parallel -> 皇家蓝色 (royal blue)
+        if decorator in ('behavior', 'sequence', 'selector', 'parallel'):
+            return QColor(65, 105, 225)  # Royal Blue
+
+        return None
+
+    # ------------------------------------------------------------------ #
+    # 字体
+    # ------------------------------------------------------------------ #
+    @property
+    def font(self) -> QFont:
+        """获取节点文本字体"""
+        return self._text_item.font()
+
+    @property
+    def fontFamily(self) -> str:
+        """获取当前字体家族"""
+        return self._text_item.font().family()
+
+    @property
+    def fontSize(self) -> int:
+        """获取当前字体大小"""
+        return self._text_item.font().pointSize()
+
+    def setFont(self, family: str = None, size: int = None) -> None:
+        """
+        设置节点文本的字体
+
+        Args:
+            family: 字体家族，None 表示不改变
+            size: 字体大小，None 表示不改变
+        """
+        font = self._text_item.font()
+        if family is not None:
+            self._custom_font_family = family
+            font.setFamily(family)
+        if size is not None and size > 0:
+            self._custom_font_size = size
+            font.setPointSize(size)
+        self._text_item.setFont(font)
+
+        # 始终重新居中文字，确保位置正确
+        self._centerText()
+
+        # 重新计算大小以适应新字体（如果没有自定义半径）
+        if not getattr(self, '_custom_radius', None):
+            rw, rh = self._calculateHalfSize()
+            if (rw, rh) != (self._rw, self._rh):
+                self._applySize(rw, rh)
+
+        # 字体变化后刷新端口文本字号与位置(由 _NodePortMixin 提供)
+        self._refreshPortFonts()
+
+    def _nameTextSize(self):
+        """测量当前名称文本的 (宽, 高)"""
+        temp = QGraphicsTextItem(self._name)
+        text_item = getattr(self, "_text_item", None)
+        if text_item is not None:
+            temp.setFont(text_item.font())
+        r = temp.boundingRect()
+        return r.width(), r.height()
+
+    def _hitFont(self) -> QFont:
+        """hit 文本的字体(节点字号 - 2)"""
+        text_item = getattr(self, "_text_item", None)
+        f = QFont(text_item.font()) if text_item is not None else QFont()
+        ps = f.pointSize()
+        f.setPointSize(max(1, ps - 2) if ps > 0 else 8)
+        return f
+
+    def _textWidth(self, text: str, font: QFont) -> float:
+        if not text:
+            return 0.0
+        t = QGraphicsTextItem(text)
+        t.setFont(font)
+        return t.boundingRect().width()
+
+    # ------------------------------------------------------------------ #
+    # 几何 / 尺寸
+    # ------------------------------------------------------------------ #
+    def _hasPorts(self) -> bool:
+        """是否配置了任意端口(由 _NodePortMixin 覆写; 此处提供安全默认)"""
+        return bool(self._ports_spec.get("left")) or bool(self._ports_spec.get("right"))
+
+    def _calculateHalfSize(self):
+        """计算节点半宽/半高 (rw, rh)。
+
+        - 名称需容纳在内部区域(INNER_RATIO 以内); 有 hit 时额外预留
+          (dot 深度 + 间距 + hit 文本宽度), 避免 hit 与名称重叠。
+        - 矩形且有端口时: 宽度由名称(+hit)决定, 高度由最多端口的一侧决定(可长宽不等)。
+        - 其余(椭圆/菱形/无端口矩形): 保持方形。
+        """
+        tw, th = self._nameTextSize()
+        name_half = tw / 2.0
+        rw_name = (name_half + NAME_INNER_PAD) / INNER_RATIO
+        rh_name = (th / 2.0 + NAME_INNER_PAD) / INNER_RATIO
+        has_ports = self._hasPorts()
+
+        if self._shape == NodeShape.RECTANGLE and has_ports:
+            port_extent = self._portInwardExtent()
+            rw = max(rw_name, name_half + port_extent + NAME_INNER_PAD, self._min_radius)
+            rh = max(rh_name, self._halfHeightForPorts(rw), self._min_radius)
+            return rw, rh
+
+        # 方形
+        R = max(rw_name, rh_name, self._min_radius)
+        if has_ports:
+            if self._shape == NodeShape.ELLIPSE:
+                # 圆形: 半径需容纳侧弧窗口内的端口
+                R = max(R, self._circlePortRadius())
+            else:
+                R = max(R, self._halfHeightForPorts(R))
+        return R, R
+
+    def _setSize(self, rw: float, rh: float) -> None:
+        """应用新的半宽/半高, 更新矩形、文本、标记(不重排端口)"""
+        if self._shape == NodeShape.ELLIPSE:
+            # 圆形节点固定为标准圆(宽高相等), 保证端口沿弧线布局正确
+            side = max(rw, rh)
+            rw = rh = side
+        self._rw = rw
+        self._rh = rh
+        self._radius = rw  # 兼容椭圆/菱形及旧代码
+        self.setRect(QRectF(-rw, -rh, rw * 2, rh * 2))
+        self._centerText()
+        for attr in ("_start_marker", "_single_marker", "_custom_marker"):
+            marker = getattr(self, attr, None)
+            if marker is not None:
+                marker._updatePosition()
+
+    def _applySize(self, rw: float, rh: float) -> None:
+        """应用新的半宽/半高, 并重排端口(端口项已存在时使用)"""
+        self._setSize(rw, rh)
+        self._layoutPorts()
+
+    def _hitShapeMargin(self) -> float:
+        """shape()/boundingRect() 在实际几何之外的外扩量(像素)。
+
+        = 描边半宽 + 外环厚度(NODE_HIT_EDGE_BAND), 使 hover 与命中覆盖到
+        可连线的外环区域。
+        """
+        sw = getattr(self._style, 'stroke_width', 2.0)
+        return sw / 2.0 + NODE_HIT_EDGE_BAND
+
+    def boundingRect(self) -> QRectF:
+        """边界矩形: 须覆盖 shape(), 否则 Qt 不会在该区域重绘/派发 hover。
+
+        返回外扩 _hitShapeMargin() 后的外接矩形(对圆/圆角矩形/菱形均成立)。
+        """
+        rect = self.rect()
+        m = self._hitShapeMargin()
+        return rect.adjusted(-m, -m, m, m)
+
+    def shape(self) -> QPainterPath:
+        """命中区域与 hover 区域: 贴合实际几何 + 外环(_hitShapeMargin)。
+
+        QGraphicsEllipseItem 默认 shape() 返回椭圆(与矩形/菱形不符), 且只含
+        描边半宽; 导致矩形四角、菱形边缘以及"外环"区域既无法命中节点、也
+        收不到 hover, 进而无法触发描边态、无法在角部/外环发起或接收连线。
+
+        本方法按当前形状返回贴合的轮廓并外扩 _hitShapeMargin(描边半宽+外环):
+          - ELLIPSE: 圆(半径 + 外环)
+          - RECTANGLE: 圆角矩形(外扩外环)
+          - DIAMOND: 菱形(四顶点外扩外环)
+        """
+        rect = self.rect()
+        m = self._hitShapeMargin()
+        path = QPainterPath()
+        if self._shape == NodeShape.ELLIPSE:
+            c = rect.center()
+            r = rect.width() / 2.0 + m
+            path.addEllipse(c, r, r)
+        elif self._shape == NodeShape.RECTANGLE:
+            outer = rect.adjusted(-m, -m, m, m)
+            # 圆角半径与 paint() 一致(基于原始 rect, 否则圆角位置错位)
+            corner = min(rect.width(), rect.height()) * 0.2
+            path.addRoundedRect(outer, corner, corner)
+        else:  # DIAMOND
+            c = rect.center()
+            hw = rect.width() / 2.0 + m
+            hh = rect.height() / 2.0 + m
+            path.moveTo(c.x(), c.y() - hh)
+            path.lineTo(c.x() + hw, c.y())
+            path.lineTo(c.x(), c.y() + hh)
+            path.lineTo(c.x() - hw, c.y())
+            path.closeSubpath()
+        return path
+
+    def _centerText(self) -> None:
+        """将文本居中到节点"""
+        if not getattr(self, "_text_item", None):
+            return
+        text_rect = self._text_item.boundingRect()
+        center = self.rect().center()
+
+        self._text_item.setPos(
+            center.x() - text_rect.width() / 2,
+            center.y() - text_rect.height() / 2
+        )
+
+        # 更新更名区域位置
+        self._name_edit_area = self._calculateNameEditArea()
+
+    def _calculateNameEditArea(self) -> QRectF:
+        """计算名称编辑区域（文本周围的虚线框区域）"""
+        text_rect = self._text_item.boundingRect()
+        text_pos = self._text_item.pos()
+        # 左右1px内边距，上下0px（文本本身已有足够空白）
+        hpad = 1.0
+        vpad = 0.0
+        return QRectF(
+            text_pos.x() + text_rect.x() - hpad,
+            text_pos.y() + text_rect.y() - vpad,
+            text_rect.width() + hpad * 2,
+            text_rect.height() + vpad * 2
+        )
+
+    def setRadius(self, radius: float) -> None:
+        """
+        设置节点半径（大小）—— 以方形覆盖原尺寸
+
+        Args:
+            radius: 新的半径值(半边长)
+        """
+        if radius < MIN_RADIUS:
+            radius = MIN_RADIUS
+        self._custom_radius = radius
+        self._applySize(radius, radius)
+
+    @property
+    def radius(self) -> float:
+        """获取节点半径(半宽)"""
+        return self._rw
+
+    @radius.setter
+    def radius(self, value: float) -> None:
+        """设置节点半径(以方形覆盖)"""
+        self.setRadius(value)
+
+    @property
+    def center(self) -> QPointF:
+        """获取节点中心点"""
+        return self.sceneBoundingRect().center()
+
+    @property
+    def id(self) -> str:
+        """节点稳定唯一标识(uuid4 hex 字符串, 只读)。
+
+        构造时生成, 由 :meth:`toDict` 序列化、:meth:`fromDict` 还原,
+        用作画布导出/导入时连线的 source/target 引用键。不依赖 Python
+        ``id()``(内存地址, 跨进程不稳定)。
+        """
+        return self._node_id
+
+    # ------------------------------------------------------------------ #
+    # 名称 / 形状 / 状态 属性
+    # ------------------------------------------------------------------ #
+    @property
+    def name(self) -> str:
+        """获取节点名称"""
+        return self._name
+
+    @name.setter
+    def name(self, value: str) -> None:
+        """设置节点名称"""
+        old_name = self._name
+        self._name = value
+        self._text_item.setPlainText(value)
+
+        # 发射名称改变信号
+        if old_name != value:
+            self._signal_helper.nameChanged.emit(self, value)
+
+        # 重新计算尺寸
+        rw, rh = self._calculateHalfSize()
+        if (rw, rh) != (self._rw, self._rh):
+            self._applySize(rw, rh)
+            # 更新所有连线
+            self._updateConnections()
+        else:
+            self._centerText()
+            self._layoutPorts()
+
+    @property
+    def nodeShape(self) -> NodeShape:
+        """获取节点形状"""
+        return self._shape
+
+    @nodeShape.setter
+    def nodeShape(self, value: NodeShape) -> None:
+        """设置节点形状"""
+        if self._shape != value:
+            self._shape = value
+            # 切换形状后重算尺寸: 椭圆会被强制为标准圆(宽高相等),
+            # _applySize 内含 _layoutPorts(重新决定 dot 径向/轴向)
+            if not getattr(self, "_custom_radius", None):
+                rw, rh = self._calculateHalfSize()
+                self._applySize(rw, rh)
+            else:
+                self._setSize(self._custom_radius, self._custom_radius)
+                self._layoutPorts()
+            self.update()
+            # 形状改变后, 边界交点算法(getEdgePoint)随之变化; 重新计算所有
+            # 相关连线, 避免端点仍锚在旧形状的边缘位置
+            self._updateConnections()
+
+    @property
+    def state(self) -> NodeState:
+        """获取节点状态"""
+        return self._state
+
+    @state.setter
+    def state(self, value: NodeState) -> None:
+        """设置节点状态"""
+        if self._state != value:
+            self._state = value
+            self._applyStyle()
+
+    # ------------------------------------------------------------------ #
+    # 样式
+    # ------------------------------------------------------------------ #
+    def _applyStyle(self) -> None:
+        """应用当前状态的样式"""
+        # 基础填充色
+        base_color = self._style.idle_fill
+
+        if self._state == NodeState.IDLE:
+            fill_color = base_color
+            stroke_color = self._style.idle_stroke
+        elif self._state == NodeState.HOVER:
+            fill_color = self._blendColors(base_color, self._style.hover_overlay)
+            stroke_color = self._style.idle_stroke
+        elif self._state == NodeState.SELECTED:
+            fill_color = self._blendColors(base_color, self._style.selected_overlay)
+            stroke_color = self._style.selected_stroke
+        else:
+            fill_color = base_color
+            stroke_color = self._style.idle_stroke
+
+        self.setBrush(QBrush(fill_color))
+        self.setPen(QPen(stroke_color, self._style.stroke_width))
+
+    def setColor(self, color: QColor) -> None:
+        """
+        设置节点的主颜色（填充色）
+
+        Args:
+            color: 主颜色
+        """
+        self._custom_fill_color = color
+        self._style.idle_fill = color
+        self._applyStyle()
+
+    def setBorder(self, width: int = 1, color: QColor = None) -> None:
+        """
+        设置节点的边框宽度和颜色
+
+        Args:
+            width: 边框宽度，<=0 表示无边框
+            color: 边框颜色，None 表示使用默认颜色
+        """
+        if width <= 0:
+            self.setPen(QPen(Qt.PenStyle.NoPen))
+            self._custom_stroke_width = 0
+        else:
+            self._custom_stroke_width = width
+            self._style.stroke_width = width
+            if color is not None:
+                self._custom_stroke_color = color
+                self._style.idle_stroke = color
+                self._style.selected_stroke = color
+            self._applyStyle()
+
+    @property
+    def strokeWidth(self) -> float:
+        """获取当前边框宽度"""
+        return self._style.stroke_width
+
+    @property
+    def fillColor(self) -> QColor:
+        """获取当前填充颜色"""
+        return self._style.idle_fill
+
+    @property
+    def strokeColor(self) -> QColor:
+        """获取当前边框颜色"""
+        return self._style.idle_stroke
+
+    def _blendColors(self, base: QColor, overlay: QColor, overlay_alpha: float = 0.5) -> QColor:
+        """混合两种颜色"""
+        result = QColor(overlay)
+        result.setAlpha(int(overlay_alpha * 255))
+
+        # 简单的颜色混合
+        r = int(base.red() * (1 - overlay_alpha) + overlay.red() * overlay_alpha)
+        g = int(base.green() * (1 - overlay_alpha) + overlay.green() * overlay_alpha)
+        b = int(base.blue() * (1 - overlay_alpha) + overlay.blue() * overlay_alpha)
+
+        return QColor(r, g, b)
+
+    # ------------------------------------------------------------------ #
+    # 端口相关占位(由 _NodePortMixin 提供实际实现)
+    # ------------------------------------------------------------------ #
+    def _layoutPorts(self) -> None:
+        """分布端口(由 _NodePortMixin 覆写; 此处为安全空实现)"""
+
+    def _refreshPortFonts(self) -> None:
+        """刷新端口文本字号(由 _NodePortMixin 覆写; 此处为安全空实现)"""
+
+    def _updateConnections(self) -> None:
+        """更新相关连线(由 _NodeInteractionMixin 覆写; 此处为安全空实现)"""
+
+    # ------------------------------------------------------------------ #
+    # 几何辅助(端口相关计算, 实际由 _NodePortMixin 覆写; 这里提供回退)
+    # ------------------------------------------------------------------ #
+    def _portInwardExtent(self) -> float:
+        """端口向内占据的横向深度(由 _NodePortMixin 覆写)"""
+        return 0.0
+
+    def _halfHeightForPorts(self, rw: float) -> float:
+        """端口所需半高(由 _NodePortMixin 覆写)"""
+        return 0.0
+
+    def _circlePortRadius(self) -> float:
+        """圆形节点端口所需半径(由 _NodePortMixin 覆写)"""
+        return 0.0