简介这套C/Qt项目提供雷达图与摇杆图两种自定义控件的完整实现基于VS2019与Qt5.15.2构建使用CMake管理工程未引入第三方库。雷达图可用于目标探测、数据可视化展示摇杆图支持方向扩展开发者可按需增加方向数适合游戏操控面板、机器人远程控制或监控界面开发。资源总计10个文件包含5个cpp、4个h及1个txt说明源码文件分工明确界面绘制与逻辑控制均有注释便于二次修改。压缩包仅13KB体量轻但工程结构完整可直接对照CMakeLists构建。目前已有521人学习/下载代码注释清晰遇到编译环境问题还可私信作者协助排查适合需要快速集成绘图控件或学习QPainter自定义绘制的入门及中级开发者。1. 一张实时控制面板为什么要同时做雷达图和摇杆图做设备状态监控或操控面板时最常遇到的诉求是一边要直观看到设备多个维度的实时状态一边要伸手就能操控它的走向。雷达图在这种场景里几乎是默认选项五个维度五十个维度都塞得下一眼就能看出哪个指标失衡摇杆图则承担“方向输入”的角色手感接近物理摇杆比一堆方向按钮更符合操作直觉。把两者放在同一个页面上实际上是把“感知”和“操控”两件事闭环了。这篇文章就围绕这个组合展开先讲雷达图怎么在 ECharts 里最快跑起来并解决动态更新再讲摇杆图为什么值得自己用 Canvas 手写以及事件处理和坐标换算的具体实现然后重点展开标题里那句“方向可以根据你自己的需要增加”——方向列表会做成配置项四向、八向、任意角度都能加。最后是联调阶段的踩坑清单和一套可用的控制闭环验证方式。适合做可视化面板、机器人控制台、物联网仪表盘的前端开发者带着“我要在项目里落地”的诉求来读每个代码块都可以直接抄进工程改参数用。2. 雷达图用 ECharts 五步跑通动态更新的核心问题在“数据形态”2.1 雷达图为什么适合多维度状态展示以及图形库怎么选雷达图适合展示“同一个对象在多个指标上的分布”它的坐标轴不像直角坐标系那样共享一根横轴而是每个维度都有自己的轴线从中心向外辐射。状态面板里最常见的用法是一台设备的信号强度、电量、CPU 负载、内存占用、连接质量五个量纲完全不同的指标放在折线图里会因为单位差异变得难以比较而雷达图天然把每个维度归一化到自己的 max 值范围内用户扫一眼面积形状就够了。面积大而圆说明各项均衡某一角塌陷下去那一路就是短板——这种“形状直觉”是折线图给不了的。做雷达图有两条路。一是用现成图形库首选 ECharts 的 radar 系列配置简单、动画和 tooltip 现成大版本迭代稳定社区资料也多二是用 Canvas 自己画适合对包体积敏感、或者需要完全定制交互的场景。我的判断标准很简单项目里已经引入 ECharts 就用它没有引入且只为了雷达图单独拉一个大库那才考虑自绘。ECharts 的 radar 用起来成本极低下面这份配置就是从零跑通的最小实例。2.2 最小可运行实例indicator 数组与 series.data 的对应关系雷达图的配置核心就两块indicator 定义每个维度的名称和最大值series.data 给每个维度的具体数值。两者通过数组下标一一对应下标错一位图上就会张冠李戴。// 引入 echarts 后初始化一个 div 容器 const chart echarts.init(document.getElementById(radarContainer)); const option { radar: { indicator: [ { name: 信号强度, max: 100 }, { name: 电量, max: 100 }, { name: CPU 负载, max: 100 }, { name: 内存占用, max: 100 }, { name: 连接质量, max: 100 } ], radius: 65%, // 相对容器宽高 splitNumber: 4, // 同心圆层数4 层看起来不拥挤 axisName: { color: #666, fontSize: 13 } }, series: [{ type: radar, symbol: circle, symbolSize: 6, lineStyle: { width: 2, color: #4a7fdb }, areaStyle: { opacity: 0.25 }, data: [{ value: [80, 62, 90, 55, 70], name: 当前状态 }] }] }; chart.setOption(option);需要留意的三个参数。radius按百分比设置雷达图会随容器自适应缩放写死像素值在移动端容易溢出。splitNumber决定网格层数它只影响背景层数和坐标轴刻度标注不影响数据本身的精度一般 4 到 5 层视觉上最舒服。areaStyle.opacity控制面积填充透明度多组数据叠加对比时透明一点能看出重叠部分单组数据可以把透明度提到 0.3 以上面积存在感更强。2.3 动态更新setOption 的合并策略以及 NaN 数据会让整个网格空白状态面板的核心动作是周期性刷新。常见做法是用 setInterval 定时拿到新数据后调用chart.setOption(newOption)但我第一次做动态雷达图时在这里翻过车连续 setOption 几次之后图例里堆出一排“当前状态1、当前状态2”面积图叠了七八层。原因是 ECharts 的 setOption 默认走 merge 合并series 里的 data 数组是追加逻辑。解决办法是每次更新时明确告诉它替换整个 series// 模拟每 2 秒推送一组新状态 setInterval(() { const newValues [ randomInt(60, 95), // 信号强度 randomInt(30, 90), // 电量 randomInt(20, 80), // CPU 负载 randomInt(20, 80), // 内存占用 randomInt(50, 95) // 连接质量 ]; chart.setOption({ series: [{ data: [{ value: newValues, name: 当前状态 }] }] }, { replaceMerge: [series] // 关键让 series 整体替换而不是追加 }); }, 2000); function randomInt(min, max) { return Math.floor(Math.random() * (max - min 1)) min; }replaceMerge是 ECharts 5 里处理这类场景的显式声明数组里写哪个组件更新时就整体替换哪个组件的数据不写它默认的 merge 会把旧 data 项一直保留下去。除了这个还要注意一个隐藏的坑雷达图不接受 null 或 undefined 数值一旦某个维度取到 NaN整个雷达图网格都会空白而不是只缺那一角。所以推送数据前必须做一层清洗把非法值替换成兜底数比如信号断连时把该项置 0 而不是 null。提示如果你的数据源真实会返回 NaN建议在进入 setOption 前统一处理不要依赖图表库做容错。3. 摇杆图Canvas 手写一个事件处理和坐标换算一次讲清3.1 为什么摇杆图用 Canvas 而不是 DOM 拖拽实现摇杆图没有现成的成熟图形库可以直接用常见的做法是自己实现实现路线有两条DOM CSS 拖拽或者 Canvas 绘制加事件监听。DOM 方案看似简单——一个外圈 div、一个内圈 div拖拽时用 transform 平移就行——但真正做下去会遇到三个问题拖拽距离限制需要自己算三角函数并钳制坐标手柄回中动画要用 requestAnimationFrame 管理状态写起来并不轻松最麻烦的是方向扩展如果要在摇杆外圈渲染八个方向的提示刻度DOM 元素的旋转和定位会变得非常啰嗦。Canvas 方案把绘制和交互拆得干净绘制只管画圆、画刻度、画手柄事件只负责记录指针位置并换算坐标。将来要加方向提示、加范围环、加拖尾效果都是在 draw 函数里加几笔的事不需要动 DOM 结构。我一般会选 Canvas维护成本低而且四向改八向、增加自定义方向都只是改配置和画线的问题。3.2 核心绘制与拖拽事件半径限制是数学题回中动画是状态题先看一个能直接用的摇杆类核心逻辑都在里面。它支持鼠标和触摸统一走 Pointer Events省得分别监听 mouse 和 touch 两套事件。class Joystick { constructor(canvas, options {}) { this.canvas canvas; this.ctx canvas.getContext(2d); this.cx options.cx || canvas.width / 2; // 摇杆中心点 this.cy options.cy || canvas.height / 2; this.maxRadius options.maxRadius || 60; // 手柄可拖动的最大偏移 this.baseRadius options.baseRadius || 46; // 外圈半径 this.knobRadius options.knobRadius || 18; // 手柄半径 this.deadZone options.deadZone || 0.08; // 归一化后的死区阈值 this.knobX this.cx; // 手柄当前绘制位置 this.knobY this.cy; this.dragging false; this.onOutput options.onOutput || (() {}); // 输出回调 this._bindEvents(); this.draw(); } _bindEvents() { this.canvas.addEventListener(pointerdown, (e) { this.dragging true; this.canvas.setPointerCapture(e.pointerId); this._updateKnob(e); }); this.canvas.addEventListener(pointermove, (e) { if (this.dragging) this._updateKnob(e); }); this.canvas.addEventListener(pointerup, (e) { this.dragging false; this._resetKnob(); this.onOutput({ dx: 0, dy: 0, deg: null, direction: null }); }); } _updateKnob(e) { const rect this.canvas.getBoundingClientRect(); // 指针相对画布中心的偏移 let dx e.clientX - rect.left - this.cx; let dy e.clientY - rect.top - this.cy; // 钳制在 maxRadius 范围内 const dist Math.sqrt(dx * dx dy * dy); if (dist this.maxRadius) { dx dx / dist * this.maxRadius; dy dy / dist * this.maxRadius; } this.knobX this.cx dx; this.knobY this.cy dy; this.draw(); // 归一化输出 const nx dx / this.maxRadius; const ny dy / this.maxRadius; const mag Math.sqrt(nx * nx ny * ny); if (mag this.deadZone) { this.onOutput({ dx: 0, dy: 0, deg: null, direction: null }); return; } const deg (Math.atan2(ny, nx) * 180 / Math.PI 360) % 360; this.onOutput({ dx: nx, dy: ny, deg, direction: null }); } _resetKnob() { this.knobX this.cx; this.knobY this.cy; this.draw(); } draw() { const ctx this.ctx; ctx.clearRect(0, 0, this.canvas.width, this.canvas.height); // 外圈 ctx.beginPath(); ctx.arc(this.cx, this.cy, this.baseRadius, 0, Math.PI * 2); ctx.fillStyle rgba(40, 40, 40, 0.6); ctx.fill(); ctx.strokeStyle rgba(255, 255, 255, 0.25); ctx.lineWidth 2; ctx.stroke(); // 手柄 ctx.beginPath(); ctx.arc(this.knobX, this.knobY, this.knobRadius, 0, Math.PI * 2); ctx.fillStyle this.dragging ? #6f9eff : #9db8e8; ctx.fill(); } }这段代码里有三个关键技术点。第一是半径钳制不直接限制手柄坐标而是先算出指针相对中心的距离 dist超过 maxRadius 时按比例把 dx、dy 缩回 maxRadius 内这样手柄永远贴在外圈边界上滑动不会出现“杆已经拖出圈外但数值还在涨”的诡异手感。第二是归一化输出dx、dy 除以 maxRadius得到 -1 到 1 之间的值方向性完整保留方便下游直接乘以速度、油门等标量。第三是死区手柄偏离中心很近时输出重置为零避免摇杆轻微抖动导致误触发死区阈值一般取 0.05 到 0.1太大会让摇杆“变钝”。3.3 方向输出的角度约定atan2 的象限和屏幕坐标系的关系很多人自己写摇杆时栽在角度换算上。JavaScript 的Math.atan2(y, x)返回的是 -π 到 π 之间的弧度弧度转角度要乘 180 再除以 π。注意它和屏幕坐标系的关系屏幕 y 轴向下为正所以向上推摇杆时 dy 是负的换算出的角度是 -90 度向右推是 0 度向下是 90 度向左是 ±180 度。我在代码里做了(deg 360) % 360的处理把负角度统一映射到 0 到 360 的范围这样后续做方向判定只用一组绝对值比较。// 角度换算的完整形式 const rad Math.atan2(ny, nx); // -PI 到 PI const deg (rad * 180 / Math.PI 360) % 360; // 结果上270或 -90右0下90左180习惯上我更倾向于以“右 0 度逆时针增大”作为约定也就是把上方视作 270 度而不是 -90 度。这样在方向配置表里写起来更直观避免负角度带来的比较逻辑混乱。需要自定义方向时只要按这个角度约定写出各个方向的基准角度即可。4. 方向扩展做成配置项四向、八向、任意角度都能加4.1 角度差最小原则怎么判断摇杆当前到底指向哪个方向标题里说“方向可以根据你自己的需要增加”这意味着方向判定逻辑不能写死成四个 if。常见做法是维护一张方向配置表摇杆输出角度后遍历这张表找到夹角最小的方向作为当前方向。夹角要用“环形距离”来算不能直接相减——比如目标方向是 0 度当前角度是 359 度直接相减得 359但实际只差了 1 度。const directions [ { key: up, angle: 270, label: 前进 }, { key: right, angle: 0, label: 右移 }, { key: down, angle: 90, label: 后退 }, { key: left, angle: 180, label: 左移 } ]; function angleDiff(a, b) { const diff Math.abs(a - b) % 360; return diff 180 ? 360 - diff : diff; } function nearestDirection(deg) { let best directions[0]; let minDiff Infinity; for (const dir of directions) { const diff angleDiff(deg, dir.angle); if (diff minDiff) { minDiff diff; best dir; } } return best; }angleDiff处理的就是 0/360 边界问题。核心思路是取两个角度差值的绝对值若超过 180 度就取补角因为圆周上任意两点之间的夹角一定在 0 到 180 度之间。这个函数在扩展方向时同样适用无论方向表里加了多少项判定逻辑一行都不用改。我一般在摇杆的输出回调里把 onOutput 的 direction 字段填充为nearestDirection(deg)让面板直接拿到语义化的方向名而不是裸角度。4.2 方向表配置文件化从四向改成八向只动数据不动逻辑摇杆应用最典型的场景是机器人遥控或游戏角色移动四向模式下斜方向没有独立的指令八向模式下左上、右上这类斜方向需要映射到组合指令。利用上面配置表的结构从四向切到八向只需要在 directions 数组里补四项判定算法本身完全不用变const directions [ { key: up, angle: 270, label: 前进 }, { key: upRight, angle: 315, label: 前进右移 }, { key: right, angle: 0, label: 右移 }, { key: downRight, angle: 45, label: 后退右移 }, { key: down, angle: 90, label: 后退 }, { key: downLeft, angle: 135, label: 后退左移 }, { key: left, angle: 180, label: 左移 }, { key: upLeft, angle: 225, label: 前进左移 } ];同理如果你的项目只需要三个方向——比如左、右、刹车——直接在表里删掉不需要的项即可。新增一个 30 度方向的特殊操作加一行{ key: special, angle: 30, label: 自定义动作 }判定自然生效。这套设计的本质是把“方向”从硬编码变成数据驱动下游消费方不管方向表怎么变收到的始终是 dx、dy、deg、direction 四个字段。这也是我做摇杆组件时坚持的协议输出结构固定方向语义由配置决定。提示方向表里的 angle 最好保持“右0、逆时针增大”的约定否则写配置的人容易搞混线上排错也费劲。4.3 边界稳定性45 度线上的来回跳和死区放大方向判定在理想条件下没问题实际使用中会有个讨厌的现象摇杆恰好停在 45 度附近时角度轻微抖动会让方向在“右”和“右下”之间来回跳。原因是 45 度线正好是两个方向的等距线任何一点微小波动都会改变判定结果。常见做法是给方向判定加滞回。判定到目标方向后要求角度偏离超过一定阈值比如 10 度才允许切换到相邻方向在阈值内保持原方向不变。let currentKey null; function updateDirection(deg) { const nearest nearestDirection(deg); // 滞回逻辑新方向与当前方向的距离小于 10 度时保持原方向 if (currentKey nearest.key ! currentKey) { const diff angleDiff(deg, directions.find(d d.key currentKey).angle); if (diff 10) return currentKey; } currentKey nearest.key; return currentKey; }这段代码的效果是当摇杆从右往右下转动时必须转过 45 度线超过 10 度方向才开始切换反过来从右下往右转也是一样。代价是方向切换会轻微滞后但换来了稳定性在手操设备控制场景里稳定比那几毫秒的响应更重要。另外一个辅助策略是适度调大 deadZone角度抖动通常伴随着手柄接近中心死区阈值从 0.08 提到 0.12可以有效过滤掉“还没真正打方向”时的误判。5. 避坑雷达图与摇杆图联调的 4 个高频问题5.1 雷达图维度数据出现 NaN整个网格变空白现象后台推送的数据里某个维度偶尔是空值雷达图不是少一个角而是整个图表区域直接空白看起来像崩溃了。 原因ECharts 雷达图在数据清洗阶段遇到非法数值时不会做局部降级而是直接放弃整个数据项。 解决推送数据前统一过滤把空值替换为 0 或者按业务语义填充兜底值。我习惯在拉伸后台数据到前端时写一个sanitize(values)函数遍历每个维度遇到非有限数值就置 0并且用 console.warn 打日志这样后台数据源的问题不会静默吞掉。function sanitize(values) { return values.map(v Number.isFinite(v) ? v : 0); }5.2 移动端摇杆拖拽时页面跟着滚动手柄位置错乱现象手机浏览器里拖摇杆页面随之滚动松手后手柄停在不该停的位置。 原因触摸拖动触发了浏览器的默认滚动行为。Pointer Events 虽然统一了鼠标和触摸事件但不会自动阻止滚动。 解决在 canvas 样式里加touch-action: none这个属性告诉浏览器该元素上的触摸操作不交给默认手势处理。注意它要加在 CSS 上而不是靠e.preventDefault()因为 Pointer Events 的 preventDefault 在部分浏览器里阻止不了滚动。.joystick-canvas { touch-action: none; -webkit-user-select: none; user-select: none; }5.3 摇杆回中使用 setInterval 导致动画卡顿手柄回中路径发飘现象松手后手柄回中过程一顿一顿帧率不稳定连续快速操作时回调输出跟不上。 原因setInterval 的回调间隔不受屏幕刷新率控制显示器刷新 60Hz 时 setInterval 如果用 16ms 会累积回调用 50ms 又显得拖沓。 解决用 requestAnimationFrame 做回中动画。它是跟随屏幕刷新率的浏览器会帮你在合适的时机调用绘制函数省电且稳定。回中动画的插值逻辑放在帧回调里每帧让手柄当前位置向中心收敛一个比例。_resetKnob() { this.dragging false; const step () { const dx this.cx - this.knobX; const dy this.cy - this.knobY; this.knobX dx * 0.2; // 0.2 是回中速度系数越大越快 this.knobY dy * 0.2; this.draw(); if (Math.abs(dx) 0.5 || Math.abs(dy) 0.5) { requestAnimationFrame(step); // 没回到中心就继续下一帧 } else { this.knobX this.cx; this.knobY this.cy; this.draw(); } }; requestAnimationFrame(step); }回中速度系数 0.2 意味着每帧向中心收敛 20%大约 10 帧内回到中心手感偏“弹性”想更利落就调到 0.3 到 0.4。注意收敛终止条件用 0.5 像素视觉上已经看不出偏差。5.4 摇杆打斜方向时方向判定在两个方向之间抖现象摇杆固定在某个斜角不动方向输出在“右”和“右下”之间反复横跳。 原因摇杆没有机械限位手持时抖动的角度幅度常常超过 5 度刚好踩在方向等距线上。 解决优先使用上一节讲的滞回逻辑这是最有效的方案。其次检查手柄是否完全贴在外圈边界如果没有贴住意味着用户没打满方向角度本身就处于不稳定的过渡区可以考虑把 maxRadius 调小一点让更小幅度的物理移动就能打满从而更快进入稳定区域。第三个帮手是滤波对连续输出的角度做轻量平均比如保留最近 3 帧角度取均值再判定能明显降低输出抖动但会引入一两帧延迟实时控制场景要权衡。6. 双图联动把摇杆输出接到雷达图验证整套控制闭环雷达图和摇杆图各自能跑不等于它们组合起来能工作。联调时我会先画一条数据流摇杆输出方向 → 控制指令发出 → 设备状态变化 → 状态数据回传 → 雷达图刷新。前两步是前端的事后两步可以用模拟数据代替把闭环跑通后再对接真实设备或真实后端。// 摇杆输出接入控制逻辑 joystick.onOutput (out) { if (!out.direction) return; // 死区内不产生指令 const cmd { direction: out.direction.key, strength: Math.min(1, Math.hypot(out.dx, out.dy)), // 杆幅作为力度 ts: Date.now() }; // 模拟发送指令实际项目里这里替换为 WebSocket / MQTT 发布 sendControl(cmd); }; // 模拟设备状态变化方向不同指标曲线不同 function sendControl(cmd) { setStatus({ signal: randAround(cmd.strength * 80, 10), battery: randAround(70, 5), cpu: randAround(cmd.strength * 50, 15), memory: randAround(60, 8), connection: randAround(85, 5) }); } function setStatus(values) { chart.setOption({ series: [{ data: [{ value: values, name: 当前状态 }] }] }, { replaceMerge: [series] }); }这套联调的价值在于摇杆的方向变化能实时反映到雷达图的形状变化上数据流闭合。如果方向输出和雷达图刷新之间有明显延迟优先排查两处——setOption 是否在一个高频循环里被反复调用导致性能瓶颈以及摇杆输出的回调是否被多次注册造成重复指令。按这套流程从零搭建一个状态感知加方向操控的面板通常小半天就能跑通。做这类项目我有个习惯先把摇杆输出协议和雷达图数据字段固定下来写清楚字段名、取值区间和单位再做界面。协议一旦定死后面换图形库、换设备接口都伤不到业务层。调试过程中也吃过亏有次摇杆回中动画没做清除快速拖拽松手后多个动画帧同时跑手柄来回弹了好几下看着很滑稽——后来统一用“动画开始时先取消上一轮请求帧”解决。这类坑不深但总会在意想不到的地方冒出来。上面这些实现和避坑点都是从实际调试里反复打磨出来的希望帮到你。本文还有配套的精品资源点击获取