From: Jukka Kurkela Date: Sun, 14 Mar 2021 15:21:30 +0000 (+0200) Subject: Add x/y shorthand for padding options (#8637) X-Git-Tag: v3.0.0-beta.14~10 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=f744c3bde63cd74e598dabf4f59ea7ff96777e79;p=thirdparty%2FChart.js.git Add x/y shorthand for padding options (#8637) --- diff --git a/docs/docs/axes/labelling.md b/docs/docs/axes/labelling.md index 44e01892e..88f55e2d1 100644 --- a/docs/docs/axes/labelling.md +++ b/docs/docs/axes/labelling.md @@ -15,7 +15,7 @@ Namespace: `options.scales[scaleId].title`, it defines options for the scale tit | `text` | `string`\|`string[]` | `''` | The text for the title. (i.e. "# of People" or "Response Choices"). | `color` | [`Color`](../general/colors.md) | `Chart.defaults.color` | Color of label. | `font` | `Font` | `Chart.defaults.font` | See [Fonts](../general/fonts.md) -| `padding` | `number`\|`object` | `4` | Padding to apply around scale labels. Only `top` and `bottom` are implemented. +| `padding` | [`Padding`](../general/padding.md) | `4` | Padding to apply around scale labels. Only `top` and `bottom` are implemented. ## Creating Custom Tick Formats diff --git a/docs/docs/axes/radial/linear.mdx b/docs/docs/axes/radial/linear.mdx index caf88a5d8..e66f8a414 100644 --- a/docs/docs/axes/radial/linear.mdx +++ b/docs/docs/axes/radial/linear.mdx @@ -34,11 +34,11 @@ Namespace: `options.scales[scaleId].ticks` | Name | Type | Scriptable | Default | Description | ---- | ---- | ------- | ------- | ----------- | `backdropColor` | [`Color`](../../general/colors.md) | Yes | `'rgba(255, 255, 255, 0.75)'` | Color of label backdrops. -| `backdropPadding` | `number`\|`{top: number, bottom: number}` | | `2` | Padding of label backdrop. -| `format` | `object` | | | The [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) options used by the default label formatter -| `maxTicksLimit` | `number` | | `11` | Maximum number of ticks and gridlines to show. -| `precision` | `number` | | | if defined and `stepSize` is not specified, the step size will be rounded to this many decimal places. -| `stepSize` | `number` | | | User defined fixed step size for the scale. [more...](#step-size) +| `backdropPadding` | [`Padding`](../../general/padding.md) | Yes | `2` | Padding of label backdrop. +| `format` | `object` | Yes | | The [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) options used by the default label formatter +| `maxTicksLimit` | `number` | Yes | `11` | Maximum number of ticks and gridlines to show. +| `precision` | `number` | Yes | | if defined and `stepSize` is not specified, the step size will be rounded to this many decimal places. +| `stepSize` | `number` | Yes | | User defined fixed step size for the scale. [more...](#step-size) | `showLabelBackdrop` | `boolean` | Yes | `true` | If true, draw a background behind the tick labels. @@ -126,7 +126,7 @@ Namespace: `options.scales[scaleId].pointLabels` | Name | Type | Scriptable | Default | Description | ---- | ---- | ------- | ------- | ----------- | `backdropColor` | [`Color`](../../general/colors.md) | `true` | `undefined` | Background color of the point label. -| `backdropPadding` | `number`\|`{top: number, bottom: number}` | | `2` | Padding of label backdrop. +| `backdropPadding` | [`Padding`](../../general/padding.md) | | `2` | Padding of label backdrop. | `display` | `boolean` | | `true` | if true, point labels are shown. | `callback` | `function` | | | Callback function to transform data labels to point labels. The default implementation simply returns the current string. | `color` | [`Color`](../../general/colors.md) | Yes | `Chart.defaults.color` | Color of label. diff --git a/docs/docs/configuration/layout.md b/docs/docs/configuration/layout.md index 1dd7ded61..c61b60320 100644 --- a/docs/docs/configuration/layout.md +++ b/docs/docs/configuration/layout.md @@ -6,27 +6,4 @@ Namespace: `options.layout`, the global options for the chart layout is defined | Name | Type | Default | [Scriptable](../general/options.md#scriptable-options) | Description | ---- | ---- | ------- | :----: | ----------- -| `padding` | `number`\|`object` | `0` | Yes | The padding to add inside the chart. [more...](#padding) - -## Padding - -If this value is a number, it is applied to all sides of the chart (left, top, right, bottom). If this value is an object, the `left` property defines the left padding. Similarly the `right`, `top` and `bottom` properties can also be specified. - -Lets say you wanted to add 50px of padding to the left side of the chart canvas, you would do: - -```javascript -let chart = new Chart(ctx, { - type: 'line', - data: data, - options: { - layout: { - padding: { - left: 50, - right: 0, - top: 0, - bottom: 0 - } - } - } -}); -``` +| `padding` | [`Padding`](../general/padding.md) | `0` | Yes | The padding to add inside the chart. diff --git a/docs/docs/configuration/legend.md b/docs/docs/configuration/legend.md index 9b1f3114d..e7c4f101e 100644 --- a/docs/docs/configuration/legend.md +++ b/docs/docs/configuration/legend.md @@ -73,7 +73,7 @@ Namespace: `options.plugins.legend.title` | `color` | [`Color`](../general/colors.md) | `Chart.defaults.color` | Color of text. | `display` | `boolean` | `false` | Is the legend title displayed. | `font` | `Font` | `Chart.defaults.font` | See [Fonts](../general/fonts.md) -| `padding` | `number`\|`object` | `0` | Padding around the title. If specified as a number, it applies evenly to all sides. +| `padding` | [`Padding`](../general/padding.md) | `0` | Padding around the title. | `text` | `string` | | The string title. ## Legend Item Interface diff --git a/docs/docs/configuration/title.md b/docs/docs/configuration/title.md index 6fb6afc92..e7f39457a 100644 --- a/docs/docs/configuration/title.md +++ b/docs/docs/configuration/title.md @@ -16,7 +16,7 @@ Namespace: `options.plugins.title`, the global options for the chart title is de | `fullSize` | `boolean` | `true` | Marks that this box should take the full width/height of the canvas. If `false`, the box is sized and placed above/beside the chart area. | `position` | `string` | `'top'` | Position of title. [more...](#position) | `font` | `Font` | `{style: 'bold'}` | See [Fonts](../general/fonts.md) -| `padding` | `number`\|`{top: number, bottom: number}` | `10` | Adds padding above and below the title text if a single number is specified. It is also possible to change top and bottom padding separately. +| `padding` | [`Padding`](../general/padding.md) | `10` | Padding to apply around the title. Only `top` and `bottom` are implemented. | `text` | `string`\|`string[]` | `''` | Title text to display. If specified as an array, text is rendered on multiple lines. ### Position diff --git a/docs/docs/configuration/tooltip.md b/docs/docs/configuration/tooltip.md index 494fbb3bb..fc60a75ec 100644 --- a/docs/docs/configuration/tooltip.md +++ b/docs/docs/configuration/tooltip.md @@ -31,7 +31,7 @@ Namespace: `options.plugins.tooltip`, the global options for the chart tooltips | `footerAlign` | `string` | `'left'` | Horizontal alignment of the footer text lines. [more...](#alignment) | `footerSpacing` | `number` | `2` | Spacing to add to top and bottom of each footer line. | `footerMarginTop` | `number` | `6` | Margin to add before drawing the footer. -| `padding` | | `6` | Padding inside the tooltip on the 4 sides +| `padding` | [`Padding`](../general/padding.md) | `6` | Padding inside the tooltip. | `caretPadding` | `number` | `2` | Extra distance to move the end of the tooltip arrow away from the tooltip point. | `caretSize` | `number` | `5` | Size, in px, of the tooltip arrow. | `cornerRadius` | `number` | `6` | Radius of tooltip corner curves. diff --git a/docs/docs/general/padding.md b/docs/docs/general/padding.md new file mode 100644 index 000000000..5f8aaecf4 --- /dev/null +++ b/docs/docs/general/padding.md @@ -0,0 +1,68 @@ +--- +title: Padding +--- + +Padding values in Chart options can be supplied in couple of different formats. + +### Number + +If this value is a number, it is applied to all sides (left, top, right, bottom). + +For exmaple, defining a 20px padding to all sides of chart: + +```javascript +let chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + layout: + padding: 20 + } + } +}); +``` + +### {top, left, bottom, right} object + +If this value is an object, the `left` property defines the left padding. Similarly the `right`, `top` and `bottom` properties can also be specified. +Omitted properties default to `0`. + +Lets say you wanted to add 50px of padding to the left side of the chart canvas, you would do: + +```javascript +let chart = new Chart(ctx, { + type: 'line', + data: data, + options: { + layout: { + padding: { + left: 50 + } + } + } +}); +``` + +### {x, y} object + +This is a shorthand for defining left/right and top/bottom to same values. + +For example, 10px left / right and 4px top / bottom padding on a Radial Linear Axis [tick backdropPadding](../axes/radial/linear#tick-configuration): + +```javascript +let chart = new Chart(ctx, { + type: 'radar', + data: data, + options: { + scales: { + r: { + ticks: { + backdropPadding: { + x: 10, + y: 4 + } + } + } + } +}); +``` diff --git a/docs/sidebars.js b/docs/sidebars.js index dbdf2ed0a..29b99d3f7 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -17,6 +17,7 @@ module.exports = { 'general/options', 'general/colors', 'general/fonts', + 'general/padding', 'general/performance' ], Configuration: [ diff --git a/src/helpers/helpers.options.js b/src/helpers/helpers.options.js index 25302133a..829583183 100644 --- a/src/helpers/helpers.options.js +++ b/src/helpers/helpers.options.js @@ -38,11 +38,13 @@ export function toLineHeight(value, size) { } const numberOrZero = v => +v || 0; +const numberOrZero2 = (v1, v2) => numberOrZero(valueOrDefault(v1, v2)); /** * Converts the given value into a TRBL object. * @param {number|object} value - If a number, set the value to all TRBL component, * else, if an object, use defined properties and sets undefined ones to 0. + * x / y are shorthands for same value for left/right and top/bottom. * @returns {object} The padding values (top, right, bottom, left) * @since 3.0.0 */ @@ -50,10 +52,11 @@ export function toTRBL(value) { let t, r, b, l; if (isObject(value)) { - t = numberOrZero(value.top); - r = numberOrZero(value.right); - b = numberOrZero(value.bottom); - l = numberOrZero(value.left); + const {x, y} = value; + t = numberOrZero2(value.top, y); + r = numberOrZero2(value.right, x); + b = numberOrZero2(value.bottom, y); + l = numberOrZero2(value.left, x); } else { t = r = b = l = numberOrZero(value); } @@ -97,6 +100,7 @@ export function toTRBLCorners(value) { * Converts the given value into a padding object with pre-computed width/height. * @param {number|object} value - If a number, set the value to all TRBL component, * else, if an object, use defined properties and sets undefined ones to 0. + * x / y are shorthands for same value for left/right and top/bottom. * @returns {object} The padding values (top, right, bottom, left, width, height) * @since 2.7.0 */ diff --git a/test/specs/helpers.options.tests.js b/test/specs/helpers.options.tests.js index 8bbacba9a..a71c6f37f 100644 --- a/test/specs/helpers.options.tests.js +++ b/test/specs/helpers.options.tests.js @@ -95,6 +95,14 @@ describe('Chart.helpers.options', function() { expect(toPadding(undefined)).toEqual( {top: 0, right: 0, bottom: 0, left: 0, height: 0, width: 0}); }); + it('should support x / y shorthands', function() { + expect(toPadding({x: 1, y: 2})).toEqual( + {top: 2, right: 1, bottom: 2, left: 1, height: 4, width: 2}); + expect(toPadding({x: 1, left: 0})).toEqual( + {top: 0, right: 1, bottom: 0, left: 0, height: 0, width: 1}); + expect(toPadding({y: 5, bottom: 0})).toEqual( + {top: 5, right: 0, bottom: 0, left: 0, height: 5, width: 0}); + }); }); describe('toFont', function() { diff --git a/types/helpers/helpers.options.d.ts b/types/helpers/helpers.options.d.ts index 72a5fb2fe..c98404d1c 100644 --- a/types/helpers/helpers.options.d.ts +++ b/types/helpers/helpers.options.d.ts @@ -28,7 +28,7 @@ export function toLineHeight(value: string, size: number): number; * @since 2.7.0 */ export function toPadding( - value?: number | { top?: number; left?: number; right?: number; bottom?: number } + value?: number | { top?: number; left?: number; right?: number; bottom?: number; x?:number, y?: number } ): { top: number; left: number; right: number; bottom: number; width: number; height: number }; /**