QCustomPlot 提供了一系列可以在图表上叠加显示的对象（items），这些对象不属于数据本身，而是用于标注、辅助线等用途。以下是主要叠加对象的详细说明和使用方法。

1. QCPItemStraightLine (无限直线)

特性：

• 无限延伸的直线

• 常用于参考线、基准线

创建与设置：

QCPItemStraightLine *line = new QCPItemStraightLine(customPlot);
line->point1->setCoords(0, 5);  // 线上第一个点
line->point2->setCoords(1, 5);  // 线上第二个点（确定方向）
line->setPen(QPen(Qt::red, 2, Qt::DashLine));

常用方法：

• setPen() - 设置线条样式

• point1, point2 - 直线的两个定义点

2. QCPItemLine (有限线段)

特性：

• 两点之间的有限长度线段

• 可以添加箭头

创建与设置：

QCPItemLine *line = new QCPItemLine(customPlot);
line->start->setCoords(1, 1);  // 起点
line->end->setCoords(5, 3);    // 终点
line->setHead(QCPLineEnding::esSpikeArrow);  // 终点箭头
line->setPen(QPen(Qt::blue, 2));

常用方法：

• setHead(), setTail() - 设置起点/终点箭头样式

• setSelectedPen() - 设置选中时的线条样式

QCPItemStraightLine 与 QCPItemLine 的区别

几何特性区别

特性	QCPItemStraightLine	QCPItemLine
线条类型	无限延伸的直线	两点之间的有限线段
定义方式	通过一个点和方向定义	通过起点和终点定义
数学表示	参数方程或斜截式	两点之间的线段
实际绘制范围	总是延伸到整个绘图区域	仅在两点之间绘制

功能特性对比

功能	QCPItemStraightLine	QCPItemLine
箭头支持	❌ 不支持	✅ 支持
长度限制	❌ 无限	✅ 有限
方向表示	需要两个点定义方向	明确起点终点
适合场景	参考线、基准线	连接线、标注

坐标系统注意事项

两者都使用相同的坐标系统，但行为不同：

• QCPItemStraightLine：

  // 当图表缩放时，直线会自动延伸以适应新范围
  line->point1->setType(QCPItemPosition::ptPlotCoords);  // 使用绘图坐标

• QCPItemLine：

  // 线段长度固定，不会随缩放改变
  line->start->setType(QCPItemPosition::ptPlotCoords);
  line->end->setType(QCPItemPosition::ptPlotCoords);

性能考虑

• QCPItemStraightLine 通常性能稍好，因为它的几何计算更简单。

• QCPItemLine 在有大量箭头装饰时可能会有额外开销。

• 两者在常规使用中性能差异不明显。

3. QCPItemText (文本标签)

特性：

• 可放置在任意位置的文本

• 支持旋转和多种对齐方式

创建与设置：

QCPItemText *text = new QCPItemText(customPlot);
text->position->setCoords(3, 4);  // 文本位置
text->setText("Important Point");
text->setFont(QFont("Arial", 12));
text->setColor(Qt::darkGreen);
text->setRotation(45);  // 旋转45度
text->setTextAlignment(Qt::AlignCenter);

常用方法：

• setPadding() - 设置文本内边距

• setPositionAlignment() - 设置位置对齐方式

• setBrush() - 设置背景填充

4. QCPItemRect (矩形)

特性：

• 可设置边框和填充的矩形

• 常用于高亮显示区域

创建与设置：

QCPItemRect *rect = new QCPItemRect(customPlot);
rect->topLeft->setCoords(1, 6);
rect->bottomRight->setCoords(4, 3);
rect->setPen(QPen(Qt::black));
rect->setBrush(QBrush(QColor(255, 200, 200, 100)));  // 半透明填充

常用方法：

• setRadius() - 设置圆角半径

• setSelectedBrush() - 设置选中时的填充

5. QCPItemEllipse (椭圆)

特性：

• 可设置边框和填充的椭圆

• 实际上是基于矩形的内切椭圆

创建与设置：

QCPItemEllipse *ellipse = new QCPItemEllipse(customPlot);
ellipse->topLeft->setCoords(2, 5);
ellipse->bottomRight->setCoords(5, 2);
ellipse->setPen(QPen(Qt::darkBlue));
ellipse->setBrush(QBrush(QColor(200, 200, 255, 50)));

6. QCPItemPixmap (位图)

特性：

• 可以在图表上显示位图

• 支持缩放和保持宽高比

创建与设置：

QCPItemPixmap *pixmap = new QCPItemPixmap(customPlot);
pixmap->topLeft->setCoords(3, 7);
pixmap->setPixmap(QPixmap(":/images/logo.png"));
pixmap->setScaled(true, Qt::KeepAspectRatio);

通用属性和方法

所有叠加对象都继承自 QCPAbstractItem，具有以下通用功能：

1. 位置控制：

   • 使用锚点（QCPItemPosition）定义位置

   • 支持绝对坐标或相对坐标（轴坐标）

2. 可选择性：

   item->setSelectable(true);
   connect(customPlot, &QCustomPlot::itemClick, [](QCPAbstractItem *item, QMouseEvent *event) {qDebug() << "Item clicked:" << item;
   });

3. 可见性控制：

   item->setVisible(false);  // 隐藏项目

4. 图层控制：

   item->setLayer("overlay");  // 放置到特定图层

使用技巧

1. 动态更新：

   // 在重绘前更新项目位置
   connect(customPlot, &QCustomPlot::beforeReplot, [=](){textLabel->position->setCoords(customPlot->xAxis->range().center(), customPlot->yAxis->range().upper);
   });

2. 批量操作：

   // 隐藏所有项目
   foreach(QCPAbstractItem *item, customPlot->items()) {item->setVisible(false);
   }

3. 交互示例：

   // 创建可拖动的文本标签
   QCPItemText *dragText = new QCPItemText(customPlot);
   dragText->setText("Drag me");
   dragText->position->setType(QCPItemPosition::ptPlotCoords);
   dragText->position->setCoords(5, 5);
   dragText->setSelectable(true);// 启用拖动交互
   customPlot->setInteraction(QCP::iSelectItems, true);
   customPlot->setInteraction(QCP::iMoveItems, true);