Chart.js Cartesian 轴通用配置完全指南：bounds、position、stack 与 clip 等 8 个核心选项详解

Chart.js Cartesian 轴通用配置完全指南bounds、position、stack 与 clip 等 8 个核心选项详解【免费下载链接】Chart.jsSimple HTML5 Charts using thetag项目地址: https://gitcode.com/gh_mirrors/ch/Chart.js在 Chart.js 中笛卡尔坐标系Cartesian轴是折线图、柱状图、气泡图等常见图表类型的数据映射基础。本指南以官方文档 docs/axes/cartesian/_common.md 为核心骨架逐一剖析所有笛卡尔轴通用的 8 个配置选项bounds、clip、position、stack、stackWeight、axis、offset、title并补充 Cartesian 轴总览、轴标签配置 及源码实现证据帮助你精准控制轴的范围、位置、堆叠与留白行为读完即可在自己的图表中直接落地使用。配置入口Namespace所有笛卡尔轴共用的配置都位于轴对象的顶层即options.scales[scaleId]其中scaleId是你在options.scales中为某条轴起的标识符Chart.js 内置笛卡尔图表默认使用x与y两个 scaleId参见 docs/axes/index.md 中的默认轴说明。例如const chart new Chart(ctx, { type: line, data: data, options: { scales: { x: { // scaleId x这是笛卡尔 X 轴 bounds: data, clip: true }, y: { // scaleId y这是笛卡尔 Y 轴 position: left } } } });以下 8 个选项由所有笛卡尔轴共享具体轴类型linear、logarithmic、category、time、timeseries还会在此基础上提供各自专属的选项。通用配置选项总览名称类型默认值说明boundsstringticks决定轴的边界策略详见 Scale Boundsclipbooleantrue为true时数据集绘制按轴的尺寸而非图表区域进行裁剪positionstring|object无轴的位置详见 Axis Positionstackstring无堆叠分组。位于同一position且具有相同stack的轴会被堆叠在一起stackWeightnumber1轴在堆叠组内的权重用于决定该轴在组内分配到的空间大小axisstring无轴的类型可取x或y。未设置时根据 ID 的首字符应为x或y自动推断offsetbooleanfalse为true时在轴两端额外增加空间并将轴缩放以适配图表区域。柱状图默认将其设为truetitleobject无轴标题配置详见 Scale Title Configuration注意以上仅是所有笛卡尔轴共享的通用选项每种轴类型linear、time、category 等还有自己的专属选项请查阅对应的轴类型文档。与所有轴通用配置的关系在 Chart.js 中配置分层为所有轴含径向轴通用的配置见 docs/axes/_common.md包含type、display、min/max、reverse、stacked、grid、border、ticks、weight等以及笛卡尔轴专属的通用配置即本文表格。后者叠加在前者之上实际生效的选项是两者的并集。bounds刻度边界策略bounds控制轴的边界最小/最大值策略可取值data保证数据完全可见超出范围之外的标签tick被移除ticks默认保证刻度tick完全可见范围之外的数据被截断。从源码看该策略直接作用于刻度生成环节。在 src/scales/scale.linearbase.js 的generateTicks中if (bounds ticks) { niceMin Math.floor(rmin / spacing) * spacing; niceMax Math.ceil(rmax / spacing) * spacing; } else { niceMin rmin; niceMax rmax; }即ticks模式会将边界取整到整齐的刻度值上如 0、5、10、15而data模式直接以数据极值作为边界。随后在buildTicksscale.linearbase.js中若bounds ticks还会根据生成的刻度值反推并更新轴的min/max。默认值为ticks定义于 src/core/core.scale.defaults.js。注意bounds会被显式设置的min/max选项绕过即用户手动指定范围时以手动值为准。clip绘制裁剪范围clip为boolean默认true。为true时数据集的绘制会被裁剪到该轴自身的尺寸范围内而不是整个图表区域chart area。这在多条轴共存、数据点可能溢出到其他轴区域时非常有用可以避免数据集串画到别的轴区域。关闭裁剪clip: false常用于需要让数据点如气泡、散点在图表边界处溢出显示的场景。裁剪机制在 src/core/core.scale.js 中通过clipArea(ctx, area)与unclipArea(ctx)实现。position轴的位置轴可以被放置在图表边缘、图表区域中心或相对于某个数据值动态定位详见 Axis Position。边缘定位设置position为top、left、bottom、right之一即可把轴放到对应边缘options: { scales: { x: { position: bottom }, y: { position: left } } }居中定位设置position: center可将轴放到图表区域中心例如雷达式的十字轴效果。此模式下必须满足以下条件之一Chart.js 才能识别轴的朝向水平或垂直显式指定axis选项轴 ID 以字母x或y开头。源码中 src/core/core.scale.js 及绘制部分对position center有专门分支处理轴的xCenter/yCenter计算也由此驱动core.scale.js 等处的中心位置逻辑。按数据值定位也可以把position设置为对象让轴穿过某个数据值例如{ x: -20 }表示将该轴定位在 ID 为x的轴上数值-20处。对于笛卡尔轴position对象中只能指定一个轴要么x要么y不可同时指定两个。stack 与 stackWeight堆叠分组与空间分配stackstack用于给轴分组位于同一position且stack值相同的轴会被视为同一堆叠组。典型场景是同一侧如左侧存在多条 Y 轴通过stack将它们组合让空间分配按组进行。stackWeightstackWeight默认1表示轴在堆叠组内的权重权重越大该轴在组内分配到的空间越多。这是实现左侧两条 Y 轴按 1:2 分屏的关键参数。布局引擎在 src/core/core.layouts.js 中实现了完整的分组与加权逻辑构建布局时按stack: pos stack聚合core.layouts.jsbuildStacks累加每组的总权重_stack.weight stackWeight见 core.layouts.js分配空间时按layout.stackWeight / stack.weight计算比例core.layouts.js 与placeBoxes中的加权分配见 core.layouts.js。options: { scales: { leftY1: { type: linear, position: left, stack: left-stack, stackWeight: 1 }, leftY2: { type: linear, position: left, stack: left-stack, stackWeight: 2 // 占用约 2/3 的组内空间 } } }axis轴类型推断axis声明该轴是水平x还是垂直y。默认情况下 Chart.js 会从轴 ID 的首字符推断——ID 以x开头视为水平轴以y开头视为垂直轴。当你使用非x/y开头的自定义 ID如myScale时建议显式设置axis或position否则 Chart.js 无法判断轴的朝向居中定位等依赖朝向的能力将无法生效。官方在 docs/axes/index.md 中也有同样提示It is recommended to specifypositionand / oraxisexplicitly.offset两端留白offset为boolean默认false。为true时轴会在两端额外增加空间并将轴缩放以适配图表区域。最典型的应用是柱状图默认柱状图会把offset设为true保证首根柱和末根柱不会紧贴图表边缘。从源码看默认值定义于 src/core/core.scale.defaults.js柱状图控制器会针对其关联轴开启该行为。offset在数值轴上还会影响刻度宽度计算见 core.scale.js 中options.offset分支并在configure()中通过对start/end各外扩半个刻度间距来实现scale.linearbase.js。title轴标题title为对象类型用于配置轴标题例如 月份、销售额。命名空间为options.scales[scaleId].title完整参数见 Scale Title Configuration名称类型默认值说明displaybooleanfalse为true时显示轴标题alignstringcenter标题对齐方式start、center、endtextstring|string[]标题文本如 # of People传数组可实现多行标题colorColorChart.defaults.color标题颜色strokeColorColor无文字描边颜色strokeWidthnumber无文字描边宽度像素fontFontChart.defaults.font字体配置见 FontspaddingPadding4标题周围的内边距仅top、bottom、y生效示例options: { scales: { x: { title: { display: true, text: Month, color: red } } } }标题的默认配置display: false、text: 、padding: {top: 4, bottom: 4}定义于 src/core/core.scale.defaults.js同时通过defaults.route(scale.title, color, , color)将标题颜色默认路由到全局colorcore.scale.defaults.js。组合示例一个完整的笛卡尔轴配置将以上选项组合起来一个双 Y 轴、带留白与标题的完整配置如下const myChart new Chart(ctx, { type: line, data: { datasets: [{ data: [20, 50, 100, 75, 25, 0], label: Left dataset, yAxisID: left-y-axis // 绑定左侧 Y 轴 }, { data: [0.1, 0.5, 1.0, 2.0, 1.5, 0], label: Right dataset, yAxisID: right-y-axis // 绑定右侧 Y 轴 }], labels: [Jan, Feb, Mar, Apr, May, Jun] }, options: { scales: { x: { bounds: data, // 保证数据完全可见 offset: true, // 两端留白柱状图风格 title: { display: true, text: Month } }, left-y-axis: { type: linear, position: left, title: { display: true, text: Left Axis } }, right-y-axis: { type: linear, position: right, title: { display: true, text: Right Axis } } } } });多轴映射的关键是数据集上的xAxisID/yAxisID必须与options.scales中的 scaleId 完全匹配否则数据集会落到错误的轴上多轴用法详见 docs/axes/cartesian/index.md 与 docs/axes/cartesian/index.md。小结这 8 个通用选项构成了笛卡尔轴行为的基础骨架bounds决定数据与刻度的可见边界clip控制绘制裁剪范围position决定轴的摆放位置边缘/居中/数据值stack与stackWeight负责多轴堆叠与空间加权分配axis声明轴的朝向offset提供两端留白title则为轴添加语义化标签。理解它们之间的协作关系例如position: center依赖axis或 ID 前缀、stack依赖相同position即可在复杂多轴图表中游刃有余。【免费下载链接】Chart.jsSimple HTML5 Charts using thetag项目地址: https://gitcode.com/gh_mirrors/ch/Chart.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考