深入解析Qt节点编辑器框架：交互逻辑与样式系统（二）

一、交互逻辑：从用户操作到模型变更的完整链路

节点编辑器的交互复杂度远高于普通GUI组件，需要处理节点拖拽、连接创建、端口交互等多种场景。框架通过分层处理机制，将用户操作转化为模型变更，并确保每一步操作可追踪、可撤销。

1. 节点拖拽与位置同步：坐标映射与性能优化

节点拖拽是最基础的交互之一，但在复杂场景（如大量节点、带连接线拖拽）下，需要解决坐标同步与性能问题。

NodeGraphicsObject（节点图形对象）继承自QGraphicsObject，重写了鼠标事件处理函数：

void NodeGraphicsObject::mousePressEvent(QGraphicsSceneMouseEvent* event)
{
    // 1. 记录初始位置，用于拖拽计算
    if (event->button() == Qt::LeftButton) {
        _draggingStarted = true;
        _originalPosition = pos();
        event->accept();
    }
    // 2. 处理其他事件（如右键菜单）
    else {
        QGraphicsObject::mousePressEvent(event);
    }
}

void NodeGraphicsObject::mouseMoveEvent(QGraphicsSceneMouseEvent* event)
{
    if (_draggingStarted) {
        // 1. 计算新位置（考虑网格吸附等约束）
        auto newPos = event->scenePos() - event->buttonDownScenePos(Qt::LeftButton) + _originalPosition;
        newPos = snapToGrid(newPos); // 网格吸附逻辑
        
        // 2. 更新图形对象位置（视图层）
        setPos(newPos);
        
        // 3. 通知模型更新节点位置（模型层）
        model()->setNodePosition(nodeId(), newPos);
        
        event->accept();
    } else {
        QGraphicsObject::mouseMoveEvent(event);
    }
}

核心难点：

• 坐标映射：视图层（QGraphicsScene）使用场景坐标，而模型层需存储全局坐标，通过setNodePosition实现双向同步。
• 性能优化：拖拽时连接线需实时重绘，框架通过ConnectionGraphicsObject::updatePath的局部刷新（而非全局重绘）减少性能消耗。
• 约束处理：支持网格吸附、边界限制等规则，通过snapToGrid等辅助函数实现。

2. 连接创建：从端口拖拽到连接生效的全流程

连接创建是节点编辑器最具特色的交互，涉及临时连线绘制、连接有效性实时检查、最终模型提交等步骤，由ConnectionState和ConnectionGraphicsObject协作完成。

（1）拖拽发起：从输出端口开始

当用户点击输出端口并开始拖拽时，NodeGraphicsObject触发连接创建流程：

// 端口点击事件处理
void NodeGraphicsObject::onPortClicked(PortType portType, PortIndex portIndex, QPointF const& scenePos)
{
    if (portType == PortType::Out) {
        // 1. 创建临时连接（仅存在于视图层）
        auto tempConn = std::make_unique<TemporaryConnection>(
            scene(), model(), portType, nodeId(), portIndex
        );
        _tempConnection = std::move(tempConn);
        
        // 2. 记录起点，开始拖拽跟踪
        _tempConnection->setStartPoint(scenePos);
        _tempConnection->setEndPoint(scenePos); // 初始终点与起点重合
    }
}

（2）拖拽过程：实时更新与有效性检查

拖拽过程中，临时连接线随鼠标移动更新，并实时检查与目标端口的兼容性：

// 临时连接的鼠标移动处理
void TemporaryConnection::mouseMoveEvent(QGraphicsSceneMouseEvent* event)
{
    // 1. 更新终点位置，重绘连接线
    setEndPoint(event->scenePos());
    update();
    
    // 2. 检测鼠标下的目标端口
    auto targetPort = scene()->portAt(event->scenePos());
    
    // 3. 实时检查连接有效性（复用模型的connectionPossible方法）
    bool valid = false;
    if (targetPort && targetPort.type == PortType::In) {
        ConnectionId tempId{
            _outNodeId, _outPortIndex,
            targetPort.nodeId, targetPort.portIndex
        };
        valid = model()->connectionPossible(tempId);
    }
    
    // 4. 视觉反馈：有效连接为绿色，无效为红色
    _color = valid ? Qt::green : Qt::red;
}

（3）连接确认：提交模型与创建正式连接

当用户释放鼠标且连接有效时，通过命令模式提交模型变更：

// 临时连接的鼠标释放处理
void TemporaryConnection::mouseReleaseEvent(QGraphicsSceneMouseEvent* event)
{
    auto targetPort = scene()->portAt(event->scenePos());
    if (targetPort && targetPort.type == PortType::In) {
        ConnectionId connId{
            _outNodeId, _outPortIndex,
            targetPort.nodeId, targetPort.portIndex
        };
        if (model()->connectionPossible(connId)) {
            // 通过命令模式添加连接（支持撤销）
            scene()->undoStack()->push(new AddConnectionCommand(scene(), connId));
        }
    }
    // 销毁临时连接
    scene()->removeItem(this);
}

核心设计：通过“临时连接（视图层）→ 有效性检查 → 命令提交（模型层）”的流程，将复杂的连接创建分解为可管控的步骤，同时通过视觉反馈提升用户体验。

3. 撤销/重做：基于命令模式的操作历史管理

节点编辑器需要支持操作回退，框架通过Qt的QUndoStack和命令模式实现这一功能。

所有对模型的修改（如添加节点、创建连接）都封装为QUndoCommand子类：

// 添加连接的命令类
class AddConnectionCommand : public QUndoCommand
{
public:
    AddConnectionCommand(BasicGraphicsScene* scene, ConnectionId const& connId)
        : _scene(scene), _connId(connId) {}

    void redo() override {
        // 执行：添加连接
        _scene->model()->addConnection(_connId);
    }

    void undo() override {
        // 撤销：删除连接
        _scene->model()->deleteConnection(_connId);
    }

private:
    BasicGraphicsScene* _scene;
    ConnectionId _connId;
};

关键机制：

• 命令类封装了“执行”与“撤销”逻辑，确保操作可逆。
• QUndoStack管理命令队列，支持多级撤销/重做。
• 模型的所有变更必须通过命令执行，保证操作历史的完整性。

二、样式系统：灵活定制节点与连接的视觉呈现

节点编辑器的视觉风格需要适应不同场景（如数据流、逻辑流程图），框架通过分层样式设计实现高度可定制性。

1. 节点样式：结构分离与委托绘制

节点的视觉呈现由NodeGraphicsObject和NodeStyle协作完成，支持标题栏、内容区、端口的独立样式配置。

// 节点样式类（简化版）
struct NodeStyle {
    // 标题栏样式
    QColor titleBackgroundColor = QColor(50, 50, 70);
    QColor titleTextColor = Qt::white;
    int titleBarHeight = 24;
    
    // 内容区样式
    QColor backgroundColor = QColor(30, 30, 50);
    QColor borderColor = QColor(70, 70, 100);
    int borderWidth = 1;
    
    // 端口样式
    QSize portSize = QSize(12, 12);
    QColor portColor[2] = {QColor(100, 100, 200), QColor(200, 100, 100)}; // 输入/输出端口
};

// 节点绘制逻辑（NodeGraphicsObject::paint）
void NodeGraphicsObject::paint(QPainter* painter, const QStyleOptionGraphicsItem*, QWidget*)
{
    auto const& style = _style;
    QRectF const rect = boundingRect();
    
    // 1. 绘制背景与边框
    painter->fillRect(rect, style.backgroundColor);
    painter->setPen(QPen(style.borderColor, style.borderWidth));
    painter->drawRect(rect.adjusted(0, 0, -1, -1));
    
    // 2. 绘制标题栏
    QRectF titleBar(0, 0, rect.width(), style.titleBarHeight);
    painter->fillRect(titleBar, style.titleBackgroundColor);
    painter->setPen(style.titleTextColor);
    painter->drawText(titleBar, Qt::AlignCenter, nodeCaption());
    
    // 3. 绘制端口（输入在左，输出在右）
    drawPorts(painter, PortType::In, style.portColor[0]);
    drawPorts(painter, PortType::Out, style.portColor[1]);
}

扩展机制：通过继承NodeGraphicsObject并重写paint方法，或修改NodeStyle的属性，可实现完全自定义的节点外观（如圆角矩形、图标装饰、动态颜色变化）。

2. 连接样式：路径计算与状态可视化

连接（线）的样式需反映连接状态（正常、选中、无效），并支持不同的线路类型（直线、贝塞尔曲线）。

ConnectionGraphicsObject的updatePath方法负责计算连接路径：

void ConnectionGraphicsObject::updatePath()
{
    // 1. 获取两端端口的场景坐标
    QPointF const outPos = sourcePortScenePosition();
    QPointF const inPos = sinkPortScenePosition();
    
    // 2. 计算路径（贝塞尔曲线，增加拐点使线路更美观）
    auto const c1 = outPos + QPointF(80, 0); // 起点控制点
    auto const c2 = inPos - QPointF(80, 0);  // 终点控制点
    _path = QPainterPath(outPos);
    _path.cubicTo(c1, c2, inPos);
    
    // 3. 根据状态更新样式
    if (isSelected()) {
        _pen.setColor(Qt::yellow);
        _pen.setWidth(3);
    } else {
        _pen.setColor(_normalColor);
        _pen.setWidth(2);
    }
}

核心技巧：

• 贝塞尔曲线通过控制点（c1, c2）使连接更平滑，避免直线交叉带来的视觉混乱。
• 选中状态通过加粗线条和颜色变化提供清晰反馈。
• 可通过扩展updatePath支持自定义路径算法（如正交线路径）。