From 80fa9ec00e96ca52c12f72c142095d189871b13e Mon Sep 17 00:00:00 2001 From: sbosse Date: Mon, 21 Jul 2025 23:35:26 +0200 Subject: [PATCH] Mon 21 Jul 22:43:21 CEST 2025 --- js/ui/chart/docs/developers/axes.md | 134 ++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 js/ui/chart/docs/developers/axes.md diff --git a/js/ui/chart/docs/developers/axes.md b/js/ui/chart/docs/developers/axes.md new file mode 100644 index 0000000..682e93e --- /dev/null +++ b/js/ui/chart/docs/developers/axes.md @@ -0,0 +1,134 @@ +# New Axes + +Axes in Chart.js can be individually extended. Axes should always derive from `Chart.Scale` but this is not a mandatory requirement. + +```javascript +let MyScale = Chart.Scale.extend({ + /* extensions ... */ +}); + +// MyScale is now derived from Chart.Scale +``` + +Once you have created your scale class, you need to register it with the global chart object so that it can be used. A default config for the scale may be provided when registering the constructor. The first parameter to the register function is a string key that is used later to identify which scale type to use for a chart. + +```javascript +Chart.scaleService.registerScaleType('myScale', MyScale, defaultConfigObject); +``` + +To use the new scale, simply pass in the string key to the config when creating a chart. + +```javascript +var lineChart = new Chart(ctx, { + data: data, + type: 'line', + options: { + scales: { + yAxes: [{ + type: 'myScale' // this is the same key that was passed to the registerScaleType function + }] + } + } +}); +``` + +## Scale Properties + +Scale instances are given the following properties during the fitting process. + +```javascript +{ + left: number, // left edge of the scale bounding box + right: number, // right edge of the bounding box + top: number, + bottom: number, + width: number, // the same as right - left + height: number, // the same as bottom - top + + // Margin on each side. Like css, this is outside the bounding box. + margins: { + left: number, + right: number, + top: number, + bottom: number + }, + + // Amount of padding on the inside of the bounding box (like CSS) + paddingLeft: number, + paddingRight: number, + paddingTop: number, + paddingBottom: number +} +``` + +## Scale Interface +To work with Chart.js, custom scale types must implement the following interface. + +```javascript +{ + // Determines the data limits. Should set this.min and this.max to be the data max/min + determineDataLimits: function() {}, + + // Generate tick marks. this.chart is the chart instance. The data object can be accessed as this.chart.data + // buildTicks() should create a ticks array on the axis instance, if you intend to use any of the implementations from the base class + buildTicks: function() {}, + + // Get the value to show for the data at the given index of the the given dataset, ie this.chart.data.datasets[datasetIndex].data[index] + getLabelForIndex: function(index, datasetIndex) {}, + + // Get the pixel (x coordinate for horizontal axis, y coordinate for vertical axis) for a given value + // @param index: index into the ticks array + getPixelForTick: function(index) {}, + + // Get the pixel (x coordinate for horizontal axis, y coordinate for vertical axis) for a given value + // @param value : the value to get the pixel for + // @param index : index into the data array of the value + // @param datasetIndex : index of the dataset the value comes from + getPixelForValue: function(value, index, datasetIndex) {}, + + // Get the value for a given pixel (x coordinate for horizontal axis, y coordinate for vertical axis) + // @param pixel : pixel value + getValueForPixel: function(pixel) {} +} +``` + +Optionally, the following methods may also be overwritten, but an implementation is already provided by the `Chart.Scale` base class. + +```javascript +{ + // Transform the ticks array of the scale instance into strings. The default implementation simply calls this.options.ticks.callback(numericalTick, index, ticks); + convertTicksToLabels: function() {}, + + // Determine how much the labels will rotate by. The default implementation will only rotate labels if the scale is horizontal. + calculateTickRotation: function() {}, + + // Fits the scale into the canvas. + // this.maxWidth and this.maxHeight will tell you the maximum dimensions the scale instance can be. Scales should endeavour to be as efficient as possible with canvas space. + // this.margins is the amount of space you have on either side of your scale that you may expand in to. This is used already for calculating the best label rotation + // You must set this.minSize to be the size of your scale. It must be an object containing 2 properties: width and height. + // You must set this.width to be the width and this.height to be the height of the scale + fit: function() {}, + + // Draws the scale onto the canvas. this.(left|right|top|bottom) will have been populated to tell you the area on the canvas to draw in + // @param chartArea : an object containing four properties: left, right, top, bottom. This is the rectangle that lines, bars, etc will be drawn in. It may be used, for example, to draw grid lines. + draw: function(chartArea) {} +} +``` + +The Core.Scale base class also has some utility functions that you may find useful. +```javascript +{ + // Returns true if the scale instance is horizontal + isHorizontal: function() {}, + + // Get the correct value from the value from this.chart.data.datasets[x].data[] + // If dataValue is an object, returns .x or .y depending on the return of isHorizontal() + // If the value is undefined, returns NaN + // Otherwise returns the value. + // Note that in all cases, the returned value is not guaranteed to be a number + getRightValue: function(dataValue) {}, + + // Returns the scale tick objects ({label, major}) + getTicks: function() {} +} +```