From 1560f4a6eee81bf743440e9d37a066df5b7704d6 Mon Sep 17 00:00:00 2001 From: sbosse Date: Mon, 21 Jul 2025 23:35:17 +0200 Subject: [PATCH] Mon 21 Jul 22:43:21 CEST 2025 --- js/ui/chart/docs/configuration/legend.md | 171 +++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 js/ui/chart/docs/configuration/legend.md diff --git a/js/ui/chart/docs/configuration/legend.md b/js/ui/chart/docs/configuration/legend.md new file mode 100644 index 0000000..c7d1248 --- /dev/null +++ b/js/ui/chart/docs/configuration/legend.md @@ -0,0 +1,171 @@ +# Legend Configuration + +The chart legend displays data about the datasets that are appearing on the chart. + +## Configuration options +The legend configuration is passed into the `options.legend` namespace. The global options for the chart legend is defined in `Chart.defaults.global.legend`. + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| `display` | `boolean` | `true` | Is the legend shown? +| `position` | `string` | `'top'` | Position of the legend. [more...](#position) +| `fullWidth` | `boolean` | `true` | Marks that this box should take the full width of the canvas (pushing down other boxes). This is unlikely to need to be changed in day-to-day use. +| `onClick` | `function` | | A callback that is called when a click event is registered on a label item. +| `onHover` | `function` | | A callback that is called when a 'mousemove' event is registered on top of a label item. +| `onLeave` | `function` | | A callback that is called when a 'mousemove' event is registered outside of a previously hovered label item. +| `reverse` | `boolean` | `false` | Legend will show datasets in reverse order. +| `labels` | `object` | | See the [Legend Label Configuration](#legend-label-configuration) section below. + +## Position +Position of the legend. Options are: +* `'top'` +* `'left'` +* `'bottom'` +* `'right'` + +## Legend Label Configuration + +The legend label configuration is nested below the legend configuration using the `labels` key. + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| `boxWidth` | `number` | `40` | Width of coloured box. +| `fontSize` | `number` | `12` | Font size of text. +| `fontStyle` | `string` | `'normal'` | Font style of text. +| `fontColor` | `Color` | `'#666'` | Color of text. +| `fontFamily` | `string` | `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` | Font family of legend text. +| `padding` | `number` | `10` | Padding between rows of colored boxes. +| `generateLabels` | `function` | | Generates legend items for each thing in the legend. Default implementation returns the text + styling for the color box. See [Legend Item](#legend-item-interface) for details. +| `filter` | `function` | `null` | Filters legend items out of the legend. Receives 2 parameters, a [Legend Item](#legend-item-interface) and the chart data. +| `usePointStyle` | `boolean` | `false` | Label style will match corresponding point style (size is based on the mimimum value between boxWidth and fontSize). + +## Legend Item Interface + +Items passed to the legend `onClick` function are the ones returned from `labels.generateLabels`. These items must implement the following interface. + +```javascript +{ + // Label that will be displayed + text: string, + + // Fill style of the legend box + fillStyle: Color, + + // If true, this item represents a hidden dataset. Label will be rendered with a strike-through effect + hidden: boolean, + + // For box border. See https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap + lineCap: string, + + // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash + lineDash: number[], + + // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset + lineDashOffset: number, + + // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin + lineJoin: string, + + // Width of box border + lineWidth: number, + + // Stroke style of the legend box + strokeStyle: Color, + + // Point style of the legend box (only used if usePointStyle is true) + pointStyle: string +} +``` + +## Example + +The following example will create a chart with the legend enabled and turn all of the text red in color. + +```javascript +var chart = new Chart(ctx, { + type: 'bar', + data: data, + options: { + legend: { + display: true, + labels: { + fontColor: 'rgb(255, 99, 132)' + } + } + } +}); +``` + +## Custom On Click Actions + +It can be common to want to trigger different behaviour when clicking an item in the legend. This can be easily achieved using a callback in the config object. + +The default legend click handler is: +```javascript +function(e, legendItem) { + var index = legendItem.datasetIndex; + var ci = this.chart; + var meta = ci.getDatasetMeta(index); + + // See controller.isDatasetVisible comment + meta.hidden = meta.hidden === null ? !ci.data.datasets[index].hidden : null; + + // We hid a dataset ... rerender the chart + ci.update(); +} +``` + +Lets say we wanted instead to link the display of the first two datasets. We could change the click handler accordingly. + +```javascript +var defaultLegendClickHandler = Chart.defaults.global.legend.onClick; +var newLegendClickHandler = function (e, legendItem) { + var index = legendItem.datasetIndex; + + if (index > 1) { + // Do the original logic + defaultLegendClickHandler(e, legendItem); + } else { + let ci = this.chart; + [ + ci.getDatasetMeta(0), + ci.getDatasetMeta(1) + ].forEach(function(meta) { + meta.hidden = meta.hidden === null ? !ci.data.datasets[index].hidden : null; + }); + ci.update(); + } +}; + +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + legend: { + onClick: newLegendClickHandler + } + } +}); +``` + +Now when you click the legend in this chart, the visibility of the first two datasets will be linked together. + +## HTML Legends + +Sometimes you need a very complex legend. In these cases, it makes sense to generate an HTML legend. Charts provide a `generateLegend()` method on their prototype that returns an HTML string for the legend. + +To configure how this legend is generated, you can change the `legendCallback` config property. + +```javascript +var chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + legendCallback: function(chart) { + // Return the HTML string here. + } + } +}); +``` + +Note that legendCallback is not called automatically and you must call `generateLegend()` yourself in code when creating a legend using this method.