Mermaid 雷达图(radar-beta)完全指南:从语法、配置到源码渲染实现 Mermaid 雷达图radar-beta完全指南从语法、配置到源码渲染实现【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid本篇技术指南以 Mermaid 仓库中的雷达图语法文档为核心系统讲解radar-beta图形的完整语法axis / curve / options、配置参数与主题变量并结合packages/mermaid/src/diagrams/radar/下的数据层、渲染层与样式层源码深入剖析极坐标换算、曲线平滑、刻度上限保护等底层实现帮助读者既能直接编写可用的雷达图也能理解其渲染管线并正确定制样式与行为。什么是雷达图雷达图Radar Diagram是一种将低维数据以圆形格式绘制的图表在不同地区也被称为radar chart雷达图、spider chart蛛网图、star chart星图、cobweb chart蛛网图、polar chart极坐标图或Kiviat diagram基维亚特图。该图形类型特别适合需要以简洁圆形形式表示数据的开发者、数据科学家与工程师最常见的用途是在多个维度上图形化地总结并比较多个实体的表现——例如多个候选方案在若干评估指标上的对比、多门学科成绩的横向比较等。该图形自 Mermaid v11.6.0 起提供。快速上手一个最小的雷达图只需要radar-beta声明、axis轴定义和curve数据曲线三部分其中每条curve的大括号内数值依次对应axis中定义的各轴。声明行之后即为完整的语法规则集合。语法详解axis定义坐标轴axis关键字用于定义雷达图的坐标轴。每个轴由一个 ID 和一个可选的标签label组成多个轴可以在同一行内用逗号定义radar-beta axis id1[Label1] axis id2[Label2], id3[Label3] ...如果轴不提供[Label]形式的标签则标签回退为轴 ID 本身——这一行为在数据层 db.ts 的setAxes中得到印证label: axis.label ?? axis.name。curve定义数据曲线curve关键字用于定义一条曲线及其数据点。每条曲线由一个 ID、一个可选标签和一个数值列表组成多条曲线也可以写在同一行。数据值有两种写法纯数值列表{1, 2, 3}——数据点按axis定义的顺序对应各轴轴键值对{ axis3: 30, axis1: 20, axis2: 10 }——键为轴 ID值为该轴上的数据点此时书写顺序可以任意解析时会按轴定义顺序重新排列。完整示例radar-beta axis axis1, axis2, axis3 curve id1[Label1]{1, 2, 3} curve id2[Label2]{4, 5, 6}, id3{7, 8, 9} curve id4{ axis3: 30, axis1: 20, axis2: 10 } ...从源码实现看键值对模式的处理逻辑位于 db.ts 的computeCurveEntries函数中若首个数据项不含轴引用即纯数值写法直接取entry.value构成数组若含轴引用则遍历所有已定义的轴按轴 ID 匹配数据项——此时要求axis必须先于curve定义否则抛出Axes must be populated before curves for reference entries错误若某轴找不到对应数据项则抛出Missing entry for axis ...错误。这一按轴重排的行为在单元测试 radar.spec.ts 中有明确验证输入curve mycurve{ C: 3, A: 1, B: 2 }乱序书写解析后数据仍按A, B, C顺序输出为[1, 2, 3]。title图表标题title是可选字段用于在雷达图顶部渲染标题radar-beta title Title of the Radar Diagram ...渲染时标题通过radarTitle样式类定位在图表上方y 坐标为-height/2 - marginTop样式取自主题变量fontSize与titleColor。options图形级选项雷达图支持 5 个图形内选项选项说明默认值showLegend显示或隐藏图例图例默认显示truemax雷达图最大值用于缩放。未提供时由数据点自动计算数据最大值min雷达图最小值用于缩放0graticule网格类型circle同心圆或polygon同心多边形circleticks网格刻度数即同心圆/多边形的数量5radar-beta ... showLegend true max 100 min 0 graticule circle ticks 5 ...注意ticks的硬性上限db.ts 中定义了MAX_TICKS 32。若用户设置的ticks超过 32系统会输出警告Radar diagram ticks (N) exceeds maximum allowed (32). Using 32 instead.并强制取 32。源码注释明确指出这是为了防止用户设置百万级刻度导致渲染拒绝服务DoS。该保护逻辑在 radar.spec.ts 中有针对性测试12 → 1232 → 3233 → 32。完整示例示例一多轴成绩对比配合 title 与 max/min这里通过 frontmatter 的title设置图表标题并显式固定max 100/min 0的评分区间使两条曲线在同一标尺下可比。示例二餐厅多维度比较polygon 网格graticule polygon将网格从默认的同心圆切换为与数据形状一致的同心多边形更直观地呈现面积差异max 5固定 5 分制的刻度上限。配置参数config.radar通过initialize配置或 frontmatter 中的config.radar键可以覆盖雷达图的全局配置参数参数说明默认值width雷达图宽度600height雷达图高度600marginTop上边距50marginBottom下边距50marginLeft左边距50marginRight右边距50axisScaleFactor坐标轴线的长度缩放因子1axisLabelFactor轴标签位置调整因子1.05curveTension圆滑曲线的张力系数0.17这些参数在渲染源码 renderer.ts 中的作用是width/height决定 viewBox 尺寸同时radius Math.min(width, height) / 2直接决定雷达图半径四个 margindrawFrame中把它们加进总尺寸totalWidth/totalHeight并把绘制中心平移到marginLeft width/2, marginTop height/2标题 y 坐标还额外减去marginTopaxisScaleFactor轴线终点为radius * axisScaleFactor * cos/sin(angle)调小如0.25可让轴线明显短于数据区域axisLabelFactor轴标签放置在radius * axisLabelFactor处并附加 4px 外扩偏移因子越大标签离图心越远curveTension作为 Catmull-Rom 样条的张力传入closedRoundCurve见下文0时退化为直线多边形。测试用例 radar.spec.ts 中的 should handle radar diagram with config override 验证了通过%%{init: {radar: {marginTop: 80, axisLabelFactor: 1.25}}}%%覆盖配置的标准用法。主题变量Theme Variables全局主题变量雷达图支持颜色标度cScale${i}i为0到主题色阶上限的数字通常为12个用于各曲线的配色。默认值随主题变化可在配置的themeVariables中覆盖--- config: themeVariables: cScale0: #FF0000 cScale1: #00FF00 ---属性说明fontSize标题字号titleColor标题颜色cScale${i}第 i 条曲线的颜色radar 专属样式选项雷达图专属变量位于themeVariables的radar键下--- config: themeVariables: radar: axisColor: #FF0000 ---属性说明默认值axisColor轴线颜色blackaxisStrokeWidth轴线宽度1axisLabelFontSize轴标签字号12pxcurveOpacity曲线不透明度填充与图例色块均使用0.7curveStrokeWidth曲线线宽2graticuleColor网格颜色blackgraticuleOpacity网格不透明度0.5graticuleStrokeWidth网格线宽1legendBoxSize图例色块大小10legendFontSize图例字号14px样式生成逻辑在 styles.ts 中genIndexStyles会遍历THEME_COLOR_LIMIT范围内的cScale${i}为每条曲线生成.radarCurve-${i}与.radarLegendBox-${i}两个 CSS 类color、fill、fill-opacity: curveOpacity、stroke-width: curveStrokeWidth再拼装出.radarTitle、.radarAxisLine、.radarAxisLabel、.radarGraticule、.radarLegendText等类的完整 CSS。渲染器给每条曲线动态加上radarCurve-0、radarCurve-1……类名因此曲线数量超过 12 条时后续曲线将复用色阶上限内的类。组合 config 与 theme 的完整示例该示例同时使用了config.radar几何参数、theme主题与themeVariables颜色与曲线不透明度三层定制axisScaleFactor: 0.25缩短轴线curveOpacity: 0让曲线只描边不填充。源码实现剖析从文本到 SVG图形检测与按需加载雷达图作为外部图形external diagram注册其检测规则在 detector.ts 中非常简单——首行正则/^\s*radar-beta/.test(txt)命中即加载diagram.js模块。因此声明关键字必须是radar-beta保留 beta 后缀这也是它与xychart-beta等实验性图形一致的命名惯例。文法定义语法规则由 Langium 文法 radar.langium 定义核心规则包括入口Radar允许radar-beta或radar-beta:开头其后是TitleAndAccessibilities、axis列表、curve列表、options或换行符的零次以上重复AxisnameID (Label)?Label为[ labelSTRING ]CurvenameID (Label)? { Entries }Entries有两种形式纯数值序列NumberEntry或轴引用: 数值序列DetailedEntry对应文档中的键值对写法Option仅接受showLegend布尔、ticks/max/min数值与graticulecircle|polygon终端五种。解析流程在 parser.tsparse(radar, input)得到 AST 后经populate依次调用db.setAxes/db.setCurves/db.setOptions写入数据层。数据层默认值与校验db.ts 维护模块级单例数据默认选项为const defaultOptions: RadarOptions { showLegend: true, ticks: 5, max: null, min: 0, graticule: circle, };setOptions用用户值 ?? 默认值逐项合并并对ticks执行 32 上限保护getConfig则通过cleanAndMerge将defaultConfig.radar与initialize配置合并为RequiredRadarDiagramConfig保证渲染层始终拿到完整配置。渲染层极坐标换算、曲线与图例renderer.ts 的draw按五个阶段绘制drawFrame计算总尺寸与中心点configureSvgSize设置 viewBox追加一个 translate 到图表中心的g作为所有图元的坐标系原点maxValue 求解options.max ?? Math.max(...所有曲线数据点)——即文档所述未提供时由数据点计算drawGraticulecircle模式画ticks个半径递增的同心圆polygon模式对每个刻度用各轴角度2πi/N − π/2从正上方开始、顺时针分布生成多边形顶点drawAxes为每根轴绘制从原点出发的线段长度乘以axisScaleFactor并按角度余弦/正弦的正负动态选择text-anchorstart/middle/end与dominant-baselinehanging/auto/central使标签始终朝远离图心方向延伸避免溢出 viewBoxdrawCurves将每个数据值经relativeRadius换算为半径后求顶点坐标。值到半径的换算公式relativeRadius为clippedValue clamp(value, minValue, maxValue) // 越界值被裁剪 r radius * (clippedValue - minValue) / (maxValue - minValue)这解释了 radar.spec.ts 中relativeRadius(-5, 0, 10, 100) → 0、relativeRadius(15, 0, 10, 100) → 100等测试超出 min/max 的数据会被裁剪到边界而非溢出图表负数min也受支持relativeRadius(5, -10, 10, 100) → 75。曲线平滑由closedRoundCurve实现对首尾相接的顶点序列用相邻四点p0, p1, p2, p3计算 Catmull-Rom 控制点cp1 p1 (p2 − p0) * tension、cp2 p2 − (p3 − p1) * tension逐段输出三次贝塞尔C指令并以Z闭合。tension 0时控制点与端点重合路径退化为直线多边形——测试用例 should construct a polygon if tension is 0 对此有快照级验证。此外有两个值得注意的边界行为数据项数量与轴数量不匹配的曲线会被静默跳过if (curve.entries.length ! numAxes) return;不报错图例drawLegend固定渲染在图表右上角区域x (width/2 marginRight) * 3/4y 负方向每行高 20由 12×12 的色块矩形与radarLegendText文本组成showLegend false时整体省略。样式层CSS 动态生成如前所述styles.ts 先cleanAndMerge默认主题变量、当前themeVariables与radar专属样式再输出整段 CSS。渲染器在曲线上使用radarCurve-${index}类名使第 i 条曲线自动获得cScale${i}配色与图例色块radarLegendBox-${i}保持同色。测试用例速查radar.spec.ts 覆盖了以下关键场景可作为语法合法性的快速参照简单定义radar-beta\n axis A,B,C\n curve mycurve{1,2,3}正常解析title/accTitle:/accDescr:与轴、曲线、标签的快照断言五个 optionsticks 10 / showLegend false / graticule polygon / min 1 / max 10的解析快照乱序键值对曲线{ C: 3, A: 1, B: 2 }自动重排为[1, 2, 3]%%注释行的容忍%%{init: ...}%%形式的 config 覆盖、theme 覆盖与themeVariables.radar覆盖ticks上限保护12/32/33 → 12/32/32relativeRadius的 6 组数值边界测试与closedRoundCurve的 3 组路径快照。常见问题与注意事项声明关键字必须写radar-beta这是检测器正则的唯一匹配形式detector.ts键值对曲线需先定义轴curve使用axisID: value写法时axis语句必须在其之前且每个轴都要有对应数据项否则抛出解析错误数据项数量建议与轴数量严格一致不匹配时该曲线在渲染阶段被跳过不报错容易造成曲线消失了的困惑值域裁剪数据超出[min, max]会被夹取到边界若想让曲线顶格显示请显式设置maxticks 上限 32超过即被钳制并产生警告日志属刻意的资源保护设计曲线配色受主题色阶数量通常 12限制曲线过多时颜色会重复此时可借助themeVariables的cScale${i}或调整curveOpacity区分层级。相关文档雷达图语法原文档docs/syntax/radar.md图形模块源码目录packages/mermaid/src/diagrams/radar/Langium 文法packages/parser/src/language/radar/radar.langium【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考