Chart.js 轴Axes完全指南笛卡尔轴与径向轴的配置、映射与扩展【免费下载链接】Chart.jsSimple HTML5 Charts using thetag项目地址: https://gitcode.com/gh_mirrors/ch/Chart.js导读轴Axes是 Chart.js 图表中数据与像素坐标之间的桥梁负责将数据值映射到画布上的像素位置。本篇指南以 docs/axes/index.md 为主干系统讲解 Chart.js 中轴的分类笛卡尔轴与径向轴、默认 scale 的创建规则、数据集如何通过xAxisID/yAxisID/rAxisID绑定到具体轴以及通用的配置项、刻度配置、范围控制、堆叠和生命周期回调。读完本文你将能熟练配置多轴图表、自定义轴范围与刻度并理解 Chart.js 轴系统的底层更新流程与扩展方式。轴在 Chart.js 中的角色轴用于决定数据如何映射到图表上的像素值。在笛卡尔坐标系图表中有 1 个或多个 X 轴和 1 个或多个 Y 轴用于将点映射到二维画布上这类轴被称为笛卡尔轴用于折线图line、柱状图bar和气泡图bubble。在径向图表中如雷达图、极区图则只有单个轴同时在角度和径向两个方向上映射点这类轴被称为径向轴。Chart.js v2.0 之后的 scale 系统相比 v1.0 功能显著增强主要体现在支持多个 X 轴与 Y 轴内置标签自动跳过auto-skip特性检测可能重叠的刻度与标签并按间隔移除多余的标签以保证显示正常支持轴标题scale titles可以扩展新的 scale 类型而无需编写全新的图表类型。默认 scale 与数据集映射规则所有笛卡尔图表的默认scaleId是x和y径向图表默认是r。每个数据集会根据其所需的每个轴x、y 或 r映射到一个 scale映射关系由xAxisID、yAxisID或rAxisID决定。映射规则如下如果某轴的 ID 未指定则使用该轴类型的第一个 scale如果找不到该轴的 scale则自动创建一个新的 scale。以下示例展示了这一规则的实际效果。只有x和y两个 scalelet chart new Chart(ctx, { type: line });scale 为x和myScaleposition: right决定了它是 y 轴方向let chart new Chart(ctx, { type: bar, data: { datasets: [{ data: [1, 2, 3] }] }, options: { scales: { myScale: { type: logarithmic, position: right, // axis 由 position 推导为 y } } } });scale 为xAxis和yAxisaxis 类型由 ID 首字母推断let chart new Chart(ctx, { type: bar, data: { datasets: [{ yAxisID: yAxis }] }, options: { scales: { xAxis: { // 该 scale 的轴方向由 ID 首字母 x 推导 // 建议显式指定 position 和 / 或 axis type: time, } } } });只有r一个 scalelet chart new Chart(ctx, { type: radar });只有myScale一个 scale显式声明径向轴let chart new Chart(ctx, { type: radar, scales: { myScale: { axis: r } } });从源码实现看scale 的注册与实例化由 src/core/core.registry.js 中的Registry类统一管理其中this.scales new TypedRegistry(Scale, scales)负责维护所有已注册的 scale 类型内置的 linear、logarithmic、category、time、timeseries、radialLinear 等均注册于此而 scale 实例的默认 id 由 src/scales/scale.linearbase.js 等具体实现按上述规则确定。所有轴共有的通用配置命名空间options.scales[scaleId]注意以下仅为所有轴共有的选项各轴类型的具体可用选项请参见对应轴的专门文档。名称类型默认值说明typestring所使用的 scale 类型。可以创建自定义 scale 并用字符串键注册从而为某张图更换轴的类型。alignToPixelsbooleanfalse将像素值对齐到设备像素。backgroundColorColorscale 区域的背景色。borderobject边框配置。更多...displayboolean|stringtrue控制轴的全局可见性true可见false隐藏。设为auto时仅当至少有一个关联数据集可见时才显示该轴。gridobject网格线配置。更多...minnumber用户自定义的 scale 最小值覆盖来自数据的取值。更多...maxnumber用户自定义的 scale 最大值覆盖来自数据的取值。更多...reversebooleanfalse反转 scale 方向。stackedboolean|stringfalse数据是否堆叠。更多...suggestedMaxnumber计算最大数据值时使用的调整量。更多...suggestedMinnumber计算最小数据值时使用的调整量。更多...ticksobject刻度配置。更多...weightnumber0用于轴排序的权重权重越高离图表区域越远。这些默认值在 src/core/core.scale.defaults.js 中定义例如display: true、reverse: false、bounds: ticks、clip: true以及grace: 0。其中grace用于在 max 上增加、min 上减少额外余量自 v3.0 引入配合suggested*使用可以平滑扩展轴的显示范围。笛卡尔轴特有的通用配置命名空间options.scales[scaleId]仅适用于笛卡尔轴名称类型默认值说明boundsstringticks决定 scale 的边界策略被min/max选项绕过。更多...clipbooleantrue为 true 时按 scale 的尺寸而非图表区域裁剪数据集绘制。positionstring|object轴的位置。更多...stackstring堆叠组。处于相同position且相同stack的轴会被堆叠。stackWeightnumber1轴在堆叠组中的权重用于决定该轴在组内分配到的空间。axisstring该轴的轴型可选x、y。未设置时根据 ID 首字符应为x或y推断。offsetbooleanfalse为 true 时在两侧边缘添加额外空间并将轴缩放以适配图表区域。柱状图默认开启。titleobject轴标题配置。更多...径向轴的结构径向轴专用于雷达图和极区图覆盖在图表区域之上而非位于边缘。内置的径向轴是 radialLinear。径向轴的视觉组件包括角度线angle lines、网格线grid lines、点标签point labels和刻度ticks每个组件都可独立配置具体可参考径向轴文档。所有轴共有的刻度Tick配置命名空间options.scales[scaleId].ticks名称类型脚本化默认值说明backdropColorColor是rgba(255, 255, 255, 0.75)标签背板的颜色。backdropPaddingPadding2标签背板的内边距。callbackfunction返回刻度值在图表上显示的字符串表示。查看 callback 用法displaybooleantrue为 true 时显示刻度标签。colorColor是Chart.defaults.color刻度颜色。fontFont是Chart.defaults.font字体见 Fontsmajorobject{}主刻度配置。paddingnumber3刻度标签相对于轴的偏移量。showLabelBackdropboolean是径向轴为true其他为false为 true 时在刻度标签后绘制背景。textStrokeColorColor是文本描边颜色。textStrokeWidthnumber是0文本描边宽度。znumber0刻度层的 z-index。当刻度绘制在图表区域上时有用。值 0 绘制在数据集之下 0 绘制在数据集之上。笛卡尔轴特有的刻度配置命名空间options.scales[scaleId].ticks仅适用于笛卡尔轴名称类型默认值说明alignstringcenter刻度沿轴方向的对齐方式可选start、center、end、inner。inner表示水平轴上第一个刻度按start对齐、最后一个刻度按end对齐。crossAlignstringnear刻度在垂直于轴方向上的对齐方式可选near、center、far。查看 Tick AlignmentsampleSizenumberticks.length决定可容纳多少标签时检查的刻度数量。设置更小的值更快但在标签长度差异较大时可能不够精确。autoSkipbooleantrue自动计算可显示的标签数并隐藏多余标签。隐藏前标签会旋转到maxRotation。关闭autoSkip可显示全部标签。autoSkipPaddingnumber3启用autoSkip时水平轴上刻度之间的内边距。includeBoundsbooleantrue已定义的min和max值是否作为刻度显示即使它们不是整齐的值。labelOffsetnumber0标签从刻度中心点偏移的像素距离x 轴为 x 方向y 轴为 y 方向。注意可能导致边缘标签被画布边缘裁剪。maxRotationnumber50旋转刻度标签以压缩空间时的最大旋转角度。仅在实际需要时才旋转。仅适用于水平轴。minRotationnumber0刻度标签的最小旋转角度。仅适用于水平轴。mirrorbooleanfalse翻转刻度标签使其显示在图表内部而非外部。仅适用于垂直轴。paddingnumber0刻度标签与轴之间的内边距。垂直轴上作用于水平X方向水平轴上作用于垂直Y方向。maxTicksLimitnumber11显示的最大刻度与网格线数量。autoSkip的底层实现在 src/core/core.scale.autoskip.js函数autoSkip(scale, ticks)首先通过determineMaxTicks依据轴的像素长度与刻度尺寸估算可容纳的最大刻度数再结合maxTicksLimit取较小值作为上限若启用了主刻度major会优先保留主刻度并让次刻度均匀地填充其间calculateSpacing利用_factorize分解等间距的因子最终通过skip/skipMajors按计算出的间隔挑选要保留的刻度。这就是自动跳过重叠标签特性的完整实现逻辑。轴的视觉组件无论是笛卡尔轴还是径向轴都由可独立配置的视觉组件组成笛卡尔轴边框border、网格线grid lines、刻度tick、刻度标记tick mark、标题title。其中刻度代表轴上的数据值以标签形式出现刻度标记是网格线从轴边框延伸到标签的部分。径向轴角度线angle lines、网格线grid lines、点标签point labels、刻度ticks。角度线从中心向画布边缘伸展点标签标注每个角度线对应的值刻度用于标注距中心不同距离的取值。轴范围设置Axis Range Settings轴的取值范围设置项较多理解它们之间的相互作用至关重要。suggestedMax与suggestedMin只改变用于缩放轴的数据值适合在保持自动适配auto-fit行为的同时扩展轴的范围。其计算逻辑等价于let minDataValue Math.min(mostNegativeValue, options.suggestedMin); let maxDataValue Math.max(mostPositiveValue, options.suggestedMax);在下面的示例中最大正值为 50但数据最大值被扩展到 100而由于最低数据值低于suggestedMin设置suggestedMin被忽略let chart new Chart(ctx, { type: line, data: { datasets: [{ label: First dataset, data: [0, 20, 40, 50] }], labels: [January, February, March, April] }, options: { scales: { y: { suggestedMin: 50, suggestedMax: 100 } } } });与suggested*相对min和max设置的是轴的显式端点。一旦设置部分数据点可能因超出范围而不可见。此外src/core/core.scale.defaults.js 中定义的grace配置项会在 max 上增加、min 上减少额外余量它同样作用于范围计算可与其他范围设置组合使用以实现更精细的显示控制。笛卡尔轴的边界策略与位置Scale Bounds边界策略bounds属性控制 scale 的边界策略会被min/max选项绕过。data确保数据完全可见范围外的标签被移除ticks默认确保刻度完全可见范围外的数据被截断。Axis Position轴位置轴可位于图表边缘、图表区域中心或相对某个数据值动态定位边缘位置position设为top、left、bottom、right中心位置position设为center此时必须指定axis选项或让轴 ID 以x/y开头以便 Chart.js 判断轴是水平还是垂直数据值定位position设为对象例如{ x: -20 }即将轴定位在 ID 为x的轴上取值为 -20 的位置。笛卡尔轴只能指定一个轴。Tick Alignment刻度对齐主要由align沿轴方向与crossAlign垂直方向两个配置控制。crossAlign仅在以下前提满足时生效刻度旋转为0且轴位置为top、left、bottom或right。多轴图表与数据集绑定dataset.xAxisID或dataset.yAxisID属性必须与scales属性中的键匹配这在多轴图表中尤其重要const myChart new Chart(ctx, { type: line, data: { datasets: [{ // 该数据集出现在第一个轴上 yAxisID: first-y-axis }, { // 该数据集出现在第二个轴上 yAxisID: second-y-axis }] }, options: { scales: { first-y-axis: { type: linear }, second-y-axis: { type: linear } } } });对于笛卡尔轴可以创建多个 X 轴和 Y 轴方法是在scales中增加多个配置对象。新增轴时必须显式指定新轴的类型因为此场景下不会使用默认类型。下面的示例创建了两个 Y 轴并通过yAxisID将数据集绑定到正确的轴const myChart new Chart(ctx, { type: line, data: { datasets: [{ data: [20, 50, 100, 75, 25, 0], label: Left dataset, // 将数据集绑定到左侧 y 轴 yAxisID: left-y-axis }, { data: [0.1, 0.5, 1.0, 2.0, 1.5, 0], label: Right dataset, // 将数据集绑定到右侧 y 轴 yAxisID: right-y-axis }], labels: [Jan, Feb, Mar, Apr, May, Jun] }, options: { scales: { left-y-axis: { type: linear, position: left }, right-y-axis: { type: linear, position: right } } } });堆叠Stacking默认情况下数据不堆叠。如果数值轴水平图表的 y 轴的stacked选项为true正值和负值会分别堆叠。此外还可以在每个数据集上定义stack选项进一步划分堆叠组详见数据集配置。对于某些图表你可能希望正值与负值一起堆叠可以通过指定stacked: single实现。笛卡尔轴还支持stack与stackWeight处于相同position且相同stack的轴会被堆叠stackWeight决定该轴在组内分配到的空间比例。轴更新流程回调Callbacks可以在轴更新过程的不同阶段使用一组配置回调来修改 scale 参数这些选项位于轴选项的顶层。命名空间options.scales[scaleId]名称参数说明beforeUpdateaxis更新流程开始前调用。beforeSetDimensionsaxis设置尺寸前调用。afterSetDimensionsaxis设置尺寸后调用。beforeDataLimitsaxis确定数据范围data limits前调用。afterDataLimitsaxis确定数据范围后调用。beforeBuildTicksaxis创建刻度前调用。afterBuildTicksaxis创建刻度后调用。常用于过滤刻度。beforeTickToLabelConversionaxis刻度转换为字符串前调用。afterTickToLabelConversionaxis刻度转换为字符串后调用。beforeCalculateLabelRotationaxis确定刻度旋转前调用。afterCalculateLabelRotationaxis确定刻度旋转后调用。beforeFitaxisscale 适配画布前调用。afterFitaxisscale 适配画布后调用。afterUpdateaxis更新流程结束时调用。这些回调在 src/core/core.scale.js 的update()流程中被按序触发与源码中的调用点一一对应beforeUpdate()约 L381在update()开始时首先执行随后依次是beforeSetDimensions()L416、beforeDataLimits()L426、beforeBuildTicks()L433以及beforeFit()L468等最终由afterUpdate()收尾。这也是文档中在更新过程的不同点改变参数说法的源码级印证——例如在afterBuildTicks中过滤掉不需要的刻度是官方推荐的刻度裁剪手段。更新轴默认配置scale 的默认配置可以很容易地全局修改只需将新选项写入Chart.defaults.scales[type]即可。例如要让所有线性 scale 的最小值都变为 0Chart.defaults.scales.linear.min 0;此后创建的任何线性 scale 都会默认拥有最小值为 0 的配置。这一机制的底层实现在 src/core/core.scale.defaults.js其中defaults.route(scale.ticks, color, , color)等路由声明让ticks.color、grid.color、border.color、title.color等子配置能自动回退到Chart.defaults.color并定义了_scriptable/_indexable白名单例如before*/after*回调与callback、parser不被当作脚本化配置处理从而保证全局默认值合并的健壮性。创建自定义轴要创建新的轴类型请参阅开发者文档。Chart.js 的注册表机制src/core/core.registry.js支持通过Chart.register()注册自定义 scale注册后即可在scales配置中通过type字符串键使用。内置的五种笛卡尔轴linear、logarithmic、category、time、timeseries与径向轴 radialLinear 均以同一套机制注册可参考 src/scales/index.js 了解内置 scale 的注册方式。【免费下载链接】Chart.jsSimple HTML5 Charts using thetag项目地址: https://gitcode.com/gh_mirrors/ch/Chart.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考