企业官网建设流程全解析

• 测试
• 质量保障

本指南围绕 Apache JMeter 开源仓库中随 HTML 报告模板一同分发的 flot-axislabels 插件文档 展开，讲解该 Flot 图表插件如何为坐标轴添加文字标签、其三种渲染模式（CSS 变换 / Canvas / HTML）的原理与降级策略，并结合 JMeter 报告模板中真实图表（响应时间百分位图、随时间变化图等）的调用代码，给出可直接复制的配置示例。读完本文，你将掌握 flot-axislabels 的全部配置项、渲染模式的选择逻辑，并能看懂并改造 JMeter HTML 报告里任意一张 Flot 图表的轴标签配置。

插件定位：为 Flot 图表补上"轴的名称"

flot-axislabels 是 Flot 图表库的轴标签插件，最初由 Xuan Luo 编写，由 Mark Cote 维护，后续吸收了大量社区贡献（stdexcept、Clemens Stolle、Michael Haddon、andig、Alex Pinkney 等）。它的核心能力很简单：让 Flot 图表可以为任意数量的坐标轴显示文字标签，例如让 X 轴显示"Percentiles"、Y 轴显示"Percentile value in ms"。

在 Apache JMeter 中，这个插件被内置于 HTML 报告模板中，用于给性能报告的所有图表（响应时间百分位图、响应时间随时间变化图、吞吐量图、活跃线程数图等）标注坐标轴含义。插件本体位于：

• 插件源码：bin/report-template/sbadmin2-1.0.7/bower_components/flot-axislabels/jquery.flot.axislabels.js
• 插件文档：bin/report-template/sbadmin2-1.0.7/bower_components/flot-axislabels/README.md

在报告模板的多个页面中，该插件与 Flot 核心、flot.tooltip 等一并加载，例如：

• bin/report-template/content/pages/ResponseTimes.html.fmkr 第 365 行
• bin/report-template/content/pages/OverTime.html.fmkr 第 506 行
• bin/report-template/content/pages/Throughput.html.fmkr 第 459 行
• bin/report-template/content/pages/CustomsGraphs.html.fmkr 第 232 行
• bin/report-template/index.html.fmkr 第 198 行

也就是说，凡是在 JMeter HTML 报告中看到的带轴标题的图表，底层都是这个插件在工作。

三分钟上手：最小可用配置

插件通过向 Flot 的options对象注入axisLabels配置和每个轴对象上的axisLabel字段来工作。以下是最小示例（原文档示例，已修正括号笔误）：

$(function () { var options = { axisLabels: { show: true }, xaxes: [{ axisLabel: 'foo', }], yaxes: [{ position: 'left', axisLabel: 'bar', }, { position: 'right', axisLabel: 'bleem' }] }; $.plot($("#placeholder"), yourData, options); });

要点拆解：

• axisLabels.show：全局开关，控制是否渲染所有轴标签；
• xaxes[].axisLabel/yaxes[].axisLabel：具体轴的标签文本；
• yaxes数组中可以同时声明左侧（position: 'left'）和右侧（position: 'right'）两个轴，印证了插件"支持任意数量坐标轴"的设计。

从源码看，插件通过$.plot.plugins.push()注册自己（见 jquery.flot.axislabels.js 第 460-465 行），插件名为axisLabels、版本为2.0，默认配置即axisLabels: { show: true }。也就是说，即便不写axisLabels.show，标签默认也会显示。

配置项全解：从全局开关到轴级样式

原文档将配置分为两层：全局axisLabels对象与各轴对象上的属性。下表汇总了全部配置项及其默认值：

各配置项的行为细节

• show：源码中init钩子首先检查options.axisLabels.show，为假时直接返回（见 jquery.flot.axislabels.js 第 341-342 行），因此它是渲染流程的入口开关。
• axisLabelPadding：源码在读取时使用opts.axisLabelPadding === undefined ? defaultPadding : opts.axisLabelPadding进行兜底，defaultPadding即为 2（第 357、410-411 行）。该值会叠加进轴标签所占的宽度/高度，从而影响图表绘制区域的预留空间。
• axisLabelUseCanvas/axisLabelUseHtml：默认情况下插件会自动选择渲染模式，设置这两个选项可以强制降级到次优模式（Canvas 或 HTML）。二者的优先级判断贯穿了整条渲染器选择逻辑（见下文"渲染模式"一节）。
• Canvas 专属三项：axisLabelFontSizePixels、axisLabelFontFamily、axisLabelColour只有在 Canvas 渲染模式下才生效。在 CSS 与 HTML 模式下，样式应通过 CSS 类定制。

三种渲染模式与优雅降级机制

插件提供三种渲染标签的方式，并按能力自动降级：

各实现类的关系在源码中体现为原型继承链：AxisLabel（基类）→CanvasAxisLabel/HtmlAxisLabel，而HtmlAxisLabel又派生出CssTransformAxisLabel与针对旧版 IE 的IeTransformAxisLabel（见 jquery.flot.axislabels.js 第 58-335 行）。

渲染模式选择逻辑（源码级）

渲染器的选择发生在plot.hooks.draw钩子中（第 358 行起），完整优先级如下：

1. IE 分支（navigator.appName == 'Microsoft Internet Explorer'且未强制 HTML）：
   • IE 9+ 且未强制 Canvas/HTML →CssTransformAxisLabel；
   • 旧版 IE 且未强制 →IeTransformAxisLabel（使用DXImageTransform.Microsoft.BasicImage(rotation=...)滤镜实现旋转，见第 281-301 行）；
   • 强制 Canvas →CanvasAxisLabel；
   • 否则 →HtmlAxisLabel。
2. 非 IE 分支：
   • 强制 HTML，或既不支持 CSS 过渡也不支持 Canvas 文本绘制 →HtmlAxisLabel；
   • 强制 Canvas，或不支持 CSS 过渡 →CanvasAxisLabel；
   • 否则（现代浏览器）→CssTransformAxisLabel。

"是否支持 CSS 过渡"与"是否支持 Canvas 文本绘制"分别由css3TransitionSupported()与canvasTextSupported()探测（第 36-55 行）。因此原文档所说的"从 CSS 到 Canvas 再到 HTML 的优雅降级"是逐级能力探测的结果，也可以通过axisLabelUseCanvas/axisLabelUseHtml强制停留在某个较低模式。

三种模式的旋转与定位差异

• CSS 与 Canvas 模式：Y 轴标签会旋转以面向图表——左侧标签逆时针旋转 90 度，右侧标签顺时针旋转 90 度（CSS 模式见calculateOffsets中offsets.degrees = -90/90，第 245-253 行；Canvas 模式见draw中angle = -Math.PI/2/Math.PI/2，第 113-120 行）。
• HTML 模式：Y 轴标签保持水平排列，原文档明确警告这会占用大量空间。

双 pass 绘制技巧

插件源码注释揭示了一个关键实现细节（第 344-351 行）：Flot 在"生成刻度、测量刻度标签"与"绘制刻度与绘图区"之间没有可用钩子，因此插件采用将绘制流程运行两遍的技巧——第一遍先测量刻度尺寸并增大轴的labelHeight/labelWidth为轴标签预留空间，然后调用plot.setupGrid()和plot.draw()触发第二遍真正的绘制。源码第 438-442 行展示了这一重绘逻辑：

if (hasAxisLabels) { secondPass = true; plot.setupGrid(); plot.draw(); }

用 CSS 定制标签外观

在 CSS 与 HTML 模式下，每个轴标签都会带上两个 CSS 类：

• 通用类：axisLabels
• 按轴命名的类：[axisName]Label，例如.xaxisLabel、.yaxisLabel、.y2axisLabel

这意味着你可以在样式表中这样定制：

.xaxisLabel { font-weight: bold; color: #333; } .yaxisLabel { font-size: 13px; } .y2axisLabel { fill: #999; }

在 Canvas 模式下，样式无法通过 CSS 控制，只能使用axisLabelFontSizePixels、axisLabelFontFamily、axisLabelColour三个选项。

JMeter HTML 报告中的真实调用：来自仓库的证据

插件在 JMeter 报告模板中的应用非常典型——所有图表都显式设置axisLabelUseCanvas: true并给出 12px 字体。例如 bin/report-template/content/js/graph.js.fmkr 中的响应时间百分位图（第 52-66 行）：

xaxis: { tickDecimals: 1, axisLabel: "Percentiles", axisLabelUseCanvas: true, axisLabelFontSizePixels: 12, axisLabelFontFamily: 'Verdana, Arial', axisLabelPadding: 20, }, yaxis: { axisLabel: "Percentile value in ms", axisLabelUseCanvas: true, axisLabelFontSizePixels: 12, axisLabelFontFamily: 'Verdana, Arial', axisLabelPadding: 20 }

同一文件中的响应时间随时间变化图则把 X 轴标签设为getElapsedTimeLabel(this.data.result.granularity)（第 276 行），Y 轴为"Average response time in ms"（第 283 行附近），标签文本会根据统计粒度动态生成。此外：

• bin/report-template/content/js/customGraph.js.fmkr 中，自定义图的轴标签从用户配置动态读取：'${graphConfigurations[key].getProperties()["set_X_Axis"]!"Default X Axis Title"}'（第 56、63 行），未配置时回退到 "Default X Axis Title" 等默认文案；
• bin/report-template/content/js/dashboard-commons.js.fmkr 第 256-263 行在生成缩略概览图（overview）时将axisLabel: null，配合prepareOverviewOptions()关闭标签，避免小图上文字拥挤；
• flot.tooltip 插件支持在提示框模板中使用%lx、%ly占位符引用轴标签（见 bin/report-template/sbadmin2-1.0.7/bower_components/flot.tooltip/js/jquery.flot.tooltip.source.js 第 10-11 行），这两个占位符依赖 flot-axislabels 提供轴标签，未加载该插件时会被自动忽略。

下图即为上述配置产出的真实效果：JMeter HTML 报告中的响应时间百分位图（X 轴标签 "Percentiles"，Y 轴标签 "Percentile value in ms"）与响应时间随时间变化图（X 轴 "Elapsed Time (granularity: 1 min)"，Y 轴 "Average response time in ms"）：

从这些调用可以看出 JMeter 选择 Canvas 模式的原因：报告图表需要精确、一致的字体渲染（统一 Verdana/Arial 12px），并希望标签与图表主体一同导出为 PNG 图片——Canvas 模式把标签直接画在画布上，随图导出不会丢失。

兼容性说明

原文档给出的兼容性结论：

• 支持 Firefox、Chrome、Opera、Safari 的近期版本，以及 IE 8、IE 9；
• Canvas 模式在 IE 8 下无效，即使配合 excanvas 也不行（建议在需要兼容 IE 8 的场景强制使用 HTML 模式）。

结合源码可以进一步理解：IE 8 没有canvas元素的getContext实现，canvasSupported()探测会失败，因而自动回退到 IE 专用路径，而 CanvasAxisLabel 的draw()依赖plot.getCanvas().getContext('2d')，这正是它无法在 IE 8 工作的根本原因。

许可证

flot-axislabels 以 MIT 许可证发布。插件源码头注释补充了版权沿革：原始代码 2010 年 9 月由 Xuan Luo 以 GPLv3 发布，2012 年 4 月改为 MIT 重新发布（见 jquery.flot.axislabels.js 第 1-27 行）。这意味着你可以自由地在 JMeter 报告模板基础上二次开发、修改图表轴标签样式与文案。

总结

flot-axislabels 是一个设计精巧的轻量 Flot 插件：三个渲染模式配合能力探测实现优雅降级，axisLabels.show+ 轴级axisLabel的两层配置模型简洁直观，双 pass 绘制技巧则保证了轴标签不会与刻度标签重叠。在 Apache JMeter 中，它构成了 HTML 报告所有图表坐标轴标注的基础设施，无论你是想定制自己的报告模板、修改轴标签文案，还是研究 Flot 插件的写法，插件源码与报告模板图表脚本都是理想的参考起点。

• 测试
• 质量保障