From: Jukka Kurkela Date: Mon, 16 Nov 2020 20:05:29 +0000 (+0200) Subject: Update axis documentation (#8061) X-Git-Tag: v3.0.0-beta.7~35 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ed846f62f7ef61cdc9bf3855506b2bcaeb5fc91b;p=thirdparty%2FChart.js.git Update axis documentation (#8061) --- diff --git a/docs/docs/axes/_common.md b/docs/docs/axes/_common.md new file mode 100644 index 000000000..027ced318 --- /dev/null +++ b/docs/docs/axes/_common.md @@ -0,0 +1,14 @@ +### Common to all axes + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| `type` | `string` | | Type of scale being employed. Custom scales can be created and registered with a string key. This allows changing the type of an axis for a chart. +| `display` | `boolean`\|`string` | `true` | Controls the axis global visibility (visible when `true`, hidden when `false`). When `display: 'auto'`, the axis is visible only if at least one associated dataset is visible. +| `gridLines` | `object` | | Grid line configuration. [more...](./styling.mdx#grid-line-configuration) +| `min` | `number` | | User defined minimum number for the scale, overrides minimum value from data. [more...](./index.mdx#axis-range-settings) +| `max` | `number` | | User defined maximum number for the scale, overrides maximum value from data. [more...](./index.mdx#axis-range-settings) +| `reverse` | `boolean` | `false` | Reverse the scale. +| `suggestedMax` | `number` | | Adjustment used when calculating the maximum data value. [more...](./index.mdx#axis-range-settings) +| `suggestedMin` | `number` | | Adjustment used when calculating the minimum data value. [more...](./index.mdx#axis-range-settings) +| `ticks` | `object` | | Tick configuration. [more...](#tick-configuration) +| `weight` | `number` | `0` | The weight used to sort the axis. Higher weights are further away from the chart area. diff --git a/docs/docs/axes/_common_ticks.md b/docs/docs/axes/_common_ticks.md new file mode 100644 index 000000000..dd4f540e3 --- /dev/null +++ b/docs/docs/axes/_common_ticks.md @@ -0,0 +1,10 @@ +### Common to all axes + +| Name | Type | Scriptable | Default | Description +| ---- | ---- | :-------------------------------: | ------- | ----------- +| `callback` | `function` | | | Returns the string representation of the tick value as it should be displayed on the chart. See [callback](../axes/labelling.md#creating-custom-tick-formats). +| `display` | `boolean` | | `true` | If true, show tick labels. +| `font` | `Font` | Yes | `defaults.font` | See [Fonts](../general/fonts.md) +| `major` | `object` | | `{}` | [Major ticks configuration](./styling.mdx#major-tick-configuration). +| `padding` | `number` | | `0` | Sets the offset of the tick labels from the axis +| `z` | `number` | | `0` | z-index of tick layer. Useful when ticks are drawn on chart area. Values <= 0 are drawn under datasets, > 0 on top. diff --git a/docs/docs/axes/cartesian/_common.md b/docs/docs/axes/cartesian/_common.md new file mode 100644 index 000000000..c122398a3 --- /dev/null +++ b/docs/docs/axes/cartesian/_common.md @@ -0,0 +1,9 @@ +### Common options to all cartesian axes + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| `bounds` | `string` | `'ticks'` | Determines the scale bounds. [more...](./index.mdx#scale-bounds) +| `position` | `string` | | Position of the axis. [more...](./index.mdx#axis-position) +| `axis` | `string` | | Which type of axis this is. Possible values are: `'x'`, `'y'`. If not set, this is inferred from the first character of the ID which should be `'x'` or `'y'`. +| `offset` | `boolean` | `false` | If true, extra space is added to the both edges and the axis is scaled to fit into the chart area. This is set to `true` for a bar chart by default. +| `scaleLabel` | `object` | | Scale title configuration. [more...](../labelling.md#scale-title-configuration) diff --git a/docs/docs/axes/cartesian/_common_ticks.md b/docs/docs/axes/cartesian/_common_ticks.md new file mode 100644 index 000000000..1ec635fba --- /dev/null +++ b/docs/docs/axes/cartesian/_common_ticks.md @@ -0,0 +1,14 @@ +### Common options to all cartesian axes + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| `align` | `string` | `'center'` | The tick alignment along the axis. Can be `'start'`, `'center'`, or `'end'`. +| `crossAlign` | `string` | `'near'` | The tick alignment perpendicular to the axis. Can be `'near'`, `'center'`, or `'far'`. See [Tick Alignment](./index#tick-alignment) +| `sampleSize` | `number` | `ticks.length` | The number of ticks to examine when deciding how many labels will fit. Setting a smaller value will be faster, but may be less accurate when there is large variability in label length. +| `autoSkip` | `boolean` | `true` | If true, automatically calculates how many labels can be shown and hides labels accordingly. Labels will be rotated up to `maxRotation` before skipping any. Turn `autoSkip` off to show all labels no matter what. +| `autoSkipPadding` | `number` | `0` | Padding between the ticks on the horizontal axis when `autoSkip` is enabled. +| `labelOffset` | `number` | `0` | Distance in pixels to offset the label from the centre point of the tick (in the x-direction for the x-axis, and the y-direction for the y-axis). *Note: this can cause labels at the edges to be cropped by the edge of the canvas* +| `maxRotation` | `number` | `50` | Maximum rotation for tick labels when rotating to condense labels. Note: Rotation doesn't occur until necessary. *Note: Only applicable to horizontal scales.* +| `minRotation` | `number` | `0` | Minimum rotation for tick labels. *Note: Only applicable to horizontal scales.* +| `mirror` | `boolean` | `false` | Flips tick labels around axis, displaying the labels inside the chart instead of outside. *Note: Only applicable to vertical scales.* +| `padding` | `number` | `0` | Padding between the tick label and the axis. When set on a vertical axis, this applies in the horizontal (X) direction. When set on a horizontal axis, this applies in the vertical (Y) direction. diff --git a/docs/docs/axes/cartesian/category.md b/docs/docs/axes/cartesian/category.mdx similarity index 75% rename from docs/docs/axes/cartesian/category.md rename to docs/docs/axes/cartesian/category.mdx index 1b83a1b8d..3b0d0d4be 100644 --- a/docs/docs/axes/cartesian/category.md +++ b/docs/docs/axes/cartesian/category.mdx @@ -2,6 +2,11 @@ title: Category Axis --- +import CommonAll from '../_common.md' +import CommonCartesian from './_common.md' +import CommonTicks from './_common_ticks.md' +import CommonTicksAll from '../_common_ticks.md' + If the global configuration is used, labels are drawn from one of the label arrays included in the chart data. If only `data.labels` is defined, this will be used. If `data.xLabels` is defined and the axis is horizontal, this will be used. Similarly, if `data.yLabels` is defined and the axis is vertical, this property will be used. Using both `xLabels` and `yLabels` together can create a chart that uses strings for both the X and Y axes. Specifying any of the settings above defines the x-axis as `type: 'category'` if not defined otherwise. For more fine-grained control of category labels, it is also possible to add `labels` as part of the category axis definition. Doing so does not apply the global defaults. @@ -39,13 +44,21 @@ let chart = new Chart(ctx, { ## Configuration Options -These options extend the [common configuration for all cartesian axes](index.md#configuration-options). +### Category Axis specific options | Name | Type | Description | ---- | ---- | ----------- -| `min` | `string`\|`number` | | The minimum item to display. [more...](#min-max-configuration) -| `max` | `string`\|`number` | | The maximum item to display. [more...](#min-max-configuration) -| `labels` | `string[]|string[][]` | - | An array of labels to display. When an individual label is an array of strings, each item is rendered on a new line. +| `min` | `string`\|`number` | The minimum item to display. [more...](#min-max-configuration) +| `max` | `string`\|`number` | The maximum item to display. [more...](#min-max-configuration) +| `labels` | `string[]`\|`string[][]` | An array of labels to display. When an individual label is an array of strings, each item is rendered on a new line. + + + + +## Tick Configuration + + + ## Min Max Configuration diff --git a/docs/docs/axes/cartesian/index.mdx b/docs/docs/axes/cartesian/index.mdx index 06b7245b8..1a2f524d0 100644 --- a/docs/docs/axes/cartesian/index.mdx +++ b/docs/docs/axes/cartesian/index.mdx @@ -2,30 +2,26 @@ title: Cartesian Axes --- +import CommonAll from '../_common.md' +import CommonCartesian from './_common.md' +import CommonTicks from './_common_ticks.md' +import CommonTicksAll from '../_common_ticks.md' + import { useEffect } from 'react'; Axes that follow a cartesian grid are known as 'Cartesian Axes'. Cartesian axes are used for line, bar, and bubble charts. Four cartesian axes are included in Chart.js by default. -* [linear](./linear.md#linear-cartesian-axis) -* [logarithmic](./logarithmic.md#logarithmic-cartesian-axis) -* [category](./category.md#category-cartesian-axis) -* [time](./time.md#time-cartesian-axis) +* [linear](./linear) +* [logarithmic](./logarithmic) +* [category](./category) +* [time](./time) +* [timeseries](./timeseries) ## Common Configuration -All of the included cartesian axes support a number of common options. These options extend the [common configuration available to all types of axes](../index.md#common-configuration). + -| Name | Type | Default | Description -| ---- | ---- | ------- | ----------- -| `type` | `string` | | Type of scale being employed. Custom scales can be created and registered with a string key. This allows changing the type of an axis for a chart. -| `position` | `string` | | Position of the axis. [more...](#axis-position) -| `axis` | `string` | | Which type of axis this is. Possible values are: `'x'`, `'y'`. If not set, this is inferred from the first character of the ID which should be `'x'` or `'y'`. -| `min` | `number` | | User-defined minimum value for the scale, overrides minimum value from data. -| `max` | `number` | | User-defined maximum value for the scale, overrides maximum value from data. -| `offset` | `boolean` | `false` | If true, extra space is added to the both edges and the axis is scaled to fit into the chart area. This is set to `true` for a bar chart by default. -| `gridLines` | `object` | | Grid line configuration. [more...](../styling.md#grid-line-configuration) -| `scaleLabel` | `object` | | Scale title configuration. [more...](../labelling.md#scale-title-configuration) -| `ticks` | `object` | | Tick configuration. [more...](#tick-configuration) + ### Axis Position @@ -43,22 +39,17 @@ To position the axis with respect to a data value, set the `position` option to This will position the axis at a value of -20 on the axis with ID "x". For cartesian axes, only 1 axis may be specified. +### Scale Bounds + +The `bounds` property controls the scale boundary strategy (bypassed by `min`/`max` options). + +* `'data'`: makes sure data are fully visible, labels outside are removed +* `'ticks'`: makes sure ticks are fully visible, data outside are truncated + ### Tick Configuration -The following options are common to all cartesian axes but do not apply to other axes. - -| Name | Type | Default | Description -| ---- | ---- | ------- | ----------- -| `align` | `string` | | `'center'` | The tick alignment along the axis. Can be `'start'`, `'center'`, or `'end'`. -| `crossAlign` | `string` | | `'near'` | The tick alignment perpendicular to the axis. Can be `'near'`, `'center'`, or `'far'`. See [Tick Alignment](#tick-alignment) -| `sampleSize` | `number` | `ticks.length` | The number of ticks to examine when deciding how many labels will fit. Setting a smaller value will be faster, but may be less accurate when there is large variability in label length. -| `autoSkip` | `boolean` | `true` | If true, automatically calculates how many labels can be shown and hides labels accordingly. Labels will be rotated up to `maxRotation` before skipping any. Turn `autoSkip` off to show all labels no matter what. -| `autoSkipPadding` | `number` | `0` | Padding between the ticks on the horizontal axis when `autoSkip` is enabled. -| `labelOffset` | `number` | `0` | Distance in pixels to offset the label from the centre point of the tick (in the x-direction for the x-axis, and the y-direction for the y-axis). *Note: this can cause labels at the edges to be cropped by the edge of the canvas* -| `maxRotation` | `number` | `50` | Maximum rotation for tick labels when rotating to condense labels. Note: Rotation doesn't occur until necessary. *Note: Only applicable to horizontal scales.* -| `minRotation` | `number` | `0` | Minimum rotation for tick labels. *Note: Only applicable to horizontal scales.* -| `mirror` | `boolean` | `false` | Flips tick labels around axis, displaying the labels inside the chart instead of outside. *Note: Only applicable to vertical scales.* -| `padding` | `number` | `0` | Padding between the tick label and the axis. When set on a vertical axis, this applies in the horizontal (X) direction. When set on a horizontal axis, this applies in the vertical (Y) direction. + + ### Tick Alignment @@ -75,7 +66,6 @@ function exampleAlignment() { axis: 'y', label: 'My First Dataset', data: [65, 59, 80, 81, 56, 55, 40], - fill: false, backgroundColor: [ 'rgba(255, 99, 132, 0.2)', 'rgba(255, 159, 64, 0.2)', @@ -100,9 +90,6 @@ function exampleAlignment() { options: { indexAxis: 'y', scales: { - x: { - beginAtZero: true - }, y: { ticks: { crossAlign: 'far', diff --git a/docs/docs/axes/cartesian/linear.md b/docs/docs/axes/cartesian/linear.md deleted file mode 100644 index 4904cdf50..000000000 --- a/docs/docs/axes/cartesian/linear.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Linear Axis ---- - -The linear scale is used to chart numerical data. It can be placed on either the x or y-axis. The scatter chart type automatically configures a line chart to use one of these scales for the x-axis. As the name suggests, linear interpolation is used to determine where a value lies on the axis. - -## Configuration Options - -These options extend the [common configuration for all cartesian axes](index.md#configuration-options). - -| Name | Type | Description -| ---- | ---- | ----------- -| `beginAtZero` | `boolean` | if true, scale will include 0 if it is not already included. -| `suggestedMax` | `number` | Adjustment used when calculating the maximum data value. [more...](#axis-range-settings) -| `suggestedMin` | `number` | Adjustment used when calculating the minimum data value. [more...](#axis-range-settings) - -## Tick Configuration Options - -The following tick options are provided by the linear scale. They are all located in the `ticks` sub-options. These options extend the [common tick configuration](index.md#tick-configuration). - -| Name | Type | Default | Description -| ---- | ---- | ------- | ----------- -| `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) - -## Axis Range Settings - -Given the number of axis range settings, it is important to understand how they all interact with each other. - -The `suggestedMax` and `suggestedMin` settings only change the data values that are used to scale the axis. These are useful for extending the range of the axis while maintaining the auto fit behaviour. - -```javascript -let minDataValue = Math.min(mostNegativeValue, options.suggestedMin); -let maxDataValue = Math.max(mostPositiveValue, options.suggestedMax); -``` - -In this example, the largest positive value is 50, but the data maximum is expanded out to 100. However, because the lowest data value is below the `suggestedMin` setting, it is ignored. - -```javascript -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 - } - } - } -}); -``` - -In contrast to the `suggested*` settings, the `min` and `max` settings set explicit ends to the axes. When these are set, some data points may not be visible. - -## Step Size - -If set, the scale ticks will be enumerated by multiple of `stepSize`, having one tick per increment. If not set, the ticks are labeled automatically using the nice numbers algorithm. - -This example sets up a chart with a y axis that creates ticks at `0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5`. - -```javascript -let options = { - scales: { - y: { - max: 5, - min: 0, - ticks: { - stepSize: 0.5 - } - } - } -}; -``` - -## Internal data format - -Internally, the linear scale uses numeric data diff --git a/docs/docs/axes/cartesian/linear.mdx b/docs/docs/axes/cartesian/linear.mdx new file mode 100644 index 000000000..3a2f6f15c --- /dev/null +++ b/docs/docs/axes/cartesian/linear.mdx @@ -0,0 +1,59 @@ +--- +title: Linear Axis +--- + +import CommonAll from '../_common.md' +import CommonCartesian from './_common.md' +import CommonTicks from './_common_ticks.md' +import CommonTicksAll from '../_common_ticks.md' + +The linear scale is used to chart numerical data. It can be placed on either the x or y-axis. The scatter chart type automatically configures a line chart to use one of these scales for the x-axis. As the name suggests, linear interpolation is used to determine where a value lies on the axis. + +## Configuration Options + +### Linear Axis specific options + +| Name | Type | Description +| ---- | ---- | ----------- +| `beginAtZero` | `boolean` | if true, scale will include 0 if it is not already included. + + + + +## Tick Configuration + +### Linear Axis specific options + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| `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) + + + + +## Step Size + +If set, the scale ticks will be enumerated by multiple of `stepSize`, having one tick per increment. If not set, the ticks are labeled automatically using the nice numbers algorithm. + +This example sets up a chart with a y axis that creates ticks at `0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5`. + +```javascript +let options = { + scales: { + y: { + max: 5, + min: 0, + ticks: { + stepSize: 0.5 + } + } + } +}; +``` + +## Internal data format + +Internally, the linear scale uses numeric data diff --git a/docs/docs/axes/cartesian/logarithmic.md b/docs/docs/axes/cartesian/logarithmic.md deleted file mode 100644 index 07b483387..000000000 --- a/docs/docs/axes/cartesian/logarithmic.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Logarithmic Axis ---- - -The logarithmic scale is used to chart numerical data. It can be placed on either the x or y-axis. As the name suggests, logarithmic interpolation is used to determine where a value lies on the axis. - -## Configuration Options - -These options extend the [common configuration for all cartesian axes](index.md#configuration-options). - -| Name | Type | Description -| ---- | ---- | ----------- -| `suggestedMax` | `number` | Adjustment used when calculating the maximum data value. [more...](#axis-range-settings) -| `suggestedMin` | `number` | Adjustment used when calculating the minimum data value. [more...](#axis-range-settings) - -## Tick Configuration Options - -The following options are provided by the logarithmic scale. They are all located in the `ticks` sub-options. These options extend the [common tick configuration](index.md#tick-configuration). - -| Name | Type | Default | Description -| ---- | ---- | ------- | ----------- -| `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 - -## Internal data format - -Internally, the logarithmic scale uses numeric data. diff --git a/docs/docs/axes/cartesian/logarithmic.mdx b/docs/docs/axes/cartesian/logarithmic.mdx new file mode 100644 index 000000000..10fd7d9a2 --- /dev/null +++ b/docs/docs/axes/cartesian/logarithmic.mdx @@ -0,0 +1,30 @@ +--- +title: Logarithmic Axis +--- + +import CommonAll from '../_common.md' +import CommonCartesian from './_common.md' +import CommonTicks from './_common_ticks.md' +import CommonTicksAll from '../_common_ticks.md' + +The logarithmic scale is used to chart numerical data. It can be placed on either the x or y-axis. As the name suggests, logarithmic interpolation is used to determine where a value lies on the axis. + +## Configuration Options + + + + +## Tick Configuration + +### Logarithmic Axis specific options + +| Name | Type | Default | Description +| ---- | ---- | ------- | ----------- +| `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 + + + + +## Internal data format + +Internally, the logarithmic scale uses numeric data. diff --git a/docs/docs/axes/cartesian/time.md b/docs/docs/axes/cartesian/time.mdx similarity index 88% rename from docs/docs/axes/cartesian/time.md rename to docs/docs/axes/cartesian/time.mdx index b7c81e9c7..c971e50a4 100644 --- a/docs/docs/axes/cartesian/time.md +++ b/docs/docs/axes/cartesian/time.mdx @@ -2,6 +2,10 @@ title: Time Cartesian Axis --- +import CommonAll from '../_common.md' +import CommonCartesian from './_common.md' +import CommonTicks from './_common_ticks.md' + The time scale is used to display times and dates. Data are spread according to the amount of time between data points. When building its ticks, it will automatically calculate the most comfortable unit base on the size of the scale. ## Date Adapters @@ -20,12 +24,12 @@ When providing data for the time scale, Chart.js uses timestamps defined as mill ## Configuration Options -The following options are provided by the time scale. You may also set options provided by the [common tick configuration](index.md#tick-configuration). +### Time Axis specific options | Name | Type | Default | Description | ---- | ---- | ------- | ----------- | `adapters.date` | `object` | `{}` | Options for adapter for external date library if that adapter needs or supports options -| `bounds` | `string` | `'data'` | Determines the scale bounds. [more...](#scale-bounds) +| `bounds` | `string` | `'data'` | Determines the scale bounds. [more...](./index.mdx#scale-bounds) | `ticks.source` | `string` | `'auto'` | How ticks are generated. [more...](#ticks-source) | `time.displayFormats` | `object` | | Sets how different time units are displayed. [more...](#display-formats) | `time.isoWeekday` | `boolean`\|`number` | `false` | If `boolean` and true and the unit is set to 'week', then the first day of the week will be Monday. Otherwise, it will be Sunday. If `number`, the index of the first day of the week (0 - Sunday, 6 - Saturday) @@ -36,7 +40,10 @@ The following options are provided by the time scale. You may also set options p | `time.stepSize` | `number` | `1` | The number of units between grid lines. | `time.minUnit` | `string` | `'millisecond'` | The minimum display format to be used for a time unit. -### Time Units + + + +#### Time Units The following time measurements are supported. The names can be passed as strings to the `time.unit` config option to force a certain unit. @@ -69,7 +76,7 @@ var chart = new Chart(ctx, { }); ``` -### Display Formats +#### Display Formats You may specify a map of display formats with a key for each unit: @@ -106,14 +113,7 @@ var chart = new Chart(ctx, { }); ``` -### Scale Bounds - -The `bounds` property controls the scale boundary strategy (bypassed by `min`/`max` time options). - -* `'data'`: makes sure data are fully visible, labels outside are removed -* `'ticks'`: makes sure ticks are fully visible, data outside are truncated - -### Ticks Source +#### Ticks Source The `ticks.source` property controls the ticks generation. @@ -121,12 +121,12 @@ The `ticks.source` property controls the ticks generation. * `'data'`: generates ticks from data (including labels from data `{x|y}` objects) * `'labels'`: generates ticks from user given `labels` ONLY -### Parser +#### Parser If this property is defined as a string, it is interpreted as a custom format to be used by the date adapter to parse the date. If this is a function, it must return a type that can be handled by your date adapter's `parse` method. -### Internal data format +## Internal data format Internally time scale uses milliseconds since epoch diff --git a/docs/docs/axes/index.md b/docs/docs/axes/index.mdx similarity index 65% rename from docs/docs/axes/index.md rename to docs/docs/axes/index.mdx index ea814b86f..b5b8950e2 100644 --- a/docs/docs/axes/index.md +++ b/docs/docs/axes/index.mdx @@ -2,9 +2,12 @@ title: Axes --- -Axes are an integral part of a chart. They are used to determine how data maps to a pixel value on the chart. In a cartesian chart, there is 1 or more X-axis and 1 or more Y-axis to map points onto the 2-dimensional canvas. These axes are known as ['cartesian axes'](./cartesian/index.md#cartesian-axes). +import Common from './_common.md' +import CommonTicks from './_common_ticks.md' -In a radial chart, such as a radar chart or a polar area chart, there is a single axis that maps points in the angular and radial directions. These are known as ['radial axes'](./radial/index.md#radial-axes). +Axes are an integral part of a chart. They are used to determine how data maps to a pixel value on the chart. In a cartesian chart, there is 1 or more X-axis and 1 or more Y-axis to map points onto the 2-dimensional canvas. These axes are known as ['cartesian axes'](./cartesian/index#cartesian-axes). + +In a radial chart, such as a radar chart or a polar area chart, there is a single axis that maps points in the angular and radial directions. These are known as ['radial axes'](./radial/index#radial-axes). Scales in Chart.js >v2.0 are significantly more powerful, but also different than those of v1.0. @@ -15,13 +18,47 @@ Scales in Chart.js >v2.0 are significantly more powerful, but also different tha ## Common Configuration -The following options are common to all axes provided by Chart.js. + + +## Tick Configuration + + + +## Axis Range Settings + +Given the number of axis range settings, it is important to understand how they all interact with each other. + +The `suggestedMax` and `suggestedMin` settings only change the data values that are used to scale the axis. These are useful for extending the range of the axis while maintaining the auto fit behaviour. + +```javascript +let minDataValue = Math.min(mostNegativeValue, options.suggestedMin); +let maxDataValue = Math.max(mostPositiveValue, options.suggestedMax); +``` + +In this example, the largest positive value is 50, but the data maximum is expanded out to 100. However, because the lowest data value is below the `suggestedMin` setting, it is ignored. + +```javascript +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 + } + } + } +}); +``` -| Name | Type | Default | Description -| ---- | ---- | ------- | ----------- -| `display` | `boolean`\|`string` | `true` | Controls the axis global visibility (visible when `true`, hidden when `false`). When `display: 'auto'`, the axis is visible only if at least one associated dataset is visible. -| `reverse` | `boolean` | `false` | Reverse the scale. -| `weight` | `number` | `0` | The weight used to sort the axis. Higher weights are further away from the chart area. +In contrast to the `suggested*` settings, the `min` and `max` settings set explicit ends to the axes. When these are set, some data points may not be visible. ### Callbacks diff --git a/docs/docs/axes/radial/linear.md b/docs/docs/axes/radial/linear.mdx similarity index 81% rename from docs/docs/axes/radial/linear.md rename to docs/docs/axes/radial/linear.mdx index 39536bfee..d52f22306 100644 --- a/docs/docs/axes/radial/linear.md +++ b/docs/docs/axes/radial/linear.mdx @@ -2,29 +2,28 @@ title: Linear Radial Axis --- +import CommonAll from '../_common.md' +import CommonTicksAll from '../_common_ticks.md' + The linear radial scale is used to chart numerical data. As the name suggests, linear interpolation is used to determine where a value lies in relation to the center of the axis. The following additional configuration options are provided by the radial linear scale. ## Configuration Options -The axis has configuration properties for ticks, angle lines (lines that appear in a radar chart outward from the center), pointLabels (labels around the edge in a radar chart). The following sections define each of the properties in those sections. +### Linear Radial Axis specific options | Name | Type | Default | Description | ---- | ---- | ------- | ----------- | `angleLines` | `object` | | Angle line configuration. [more...](#angle-line-options) | `beginAtZero` | `boolean` | `false` | if true, scale will include 0 if it is not already included. -| `gridLines` | `object` | | Grid line configuration. [more...](../styling.md#grid-line-configuration) -| `min` | `number` | | User defined minimum number for the scale, overrides minimum value from data. [more...](#axis-range-settings) -| `max` | `number` | | User defined maximum number for the scale, overrides maximum value from data. [more...](#axis-range-settings) | `pointLabels` | `object` | | Point label configuration. [more...](#point-label-options) -| `suggestedMax` | `number` | | Adjustment used when calculating the maximum data value. [more...](#axis-range-settings) -| `suggestedMin` | `number` | | Adjustment used when calculating the minimum data value. [more...](#axis-range-settings) -| `ticks` | `object` | | Tick configuration. [more...](#tick-options) -## Tick Options + + +## Tick Configuration -The following options are provided by the linear radial scale. They are all located in the `ticks` sub-options. The [common tick configuration](../styling.md#tick-configuration) options are supported by this axis. +### Linear Radial Axis specific options | Name | Type | Scriptable | Default | Description | ---- | ---- | ------- | ------- | ----------- @@ -37,6 +36,8 @@ The following options are provided by the linear radial scale. They are all loca | `stepSize` | `number` | | | User defined fixed step size for the scale. [more...](#step-size) | `showLabelBackdrop` | `boolean` | Yes | `true` | If true, draw a background behind the tick labels. + + The scriptable context has the following form: ```javascript diff --git a/docs/docs/axes/styling.md b/docs/docs/axes/styling.mdx similarity index 77% rename from docs/docs/axes/styling.md rename to docs/docs/axes/styling.mdx index 7d7d22adc..c12baff9a 100644 --- a/docs/docs/axes/styling.md +++ b/docs/docs/axes/styling.mdx @@ -38,16 +38,7 @@ The scriptable context has the following form: ## Tick Configuration -The tick configuration is nested under the scale configuration in the `ticks` key. It defines options for the tick marks that are generated by the axis. - -| Name | Type | Scriptable | Default | Description -| ---- | ---- | :-------------------------------: | ------- | ----------- -| `callback` | `function` | | | Returns the string representation of the tick value as it should be displayed on the chart. See [callback](../axes/labelling.md#creating-custom-tick-formats). -| `display` | `boolean` | | `true` | If true, show tick labels. -| `font` | `Font` | Yes | `defaults.font` | See [Fonts](../general/fonts.md) -| `major` | `object` | | `{}` | [Major ticks configuration](#major-tick-configuration). -| `padding` | `number` | | `0` | Sets the offset of the tick labels from the axis -| `z` | `number` | | `0` | z-index of tick layer. Useful when ticks are drawn on chart area. Values <= 0 are drawn under datasets, > 0 on top. + The scriptable context is the same as for the [Grid Line Configuration](#grid-line-configuration). diff --git a/docs/docs/general/fonts.md b/docs/docs/general/fonts.md index 3c7aaa841..0256113cd 100644 --- a/docs/docs/general/fonts.md +++ b/docs/docs/general/fonts.md @@ -32,8 +32,8 @@ let chart = new Chart(ctx, { | `style` | `string` | `'normal'` | Default font style. Does not apply to tooltip title or footer. Does not apply to chart title. Follows CSS font-style options (i.e. normal, italic, oblique, initial, inherit). | `weight` | `string` | `undefined` | Default font weight (boldness). (see [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight)). | `lineHeight` | number|string | `1.2` | Height of an individual line of text (see [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/line-height)). -| `lineWidth` | `number` | `0` | Stroke width around the text. Currently only supported by [ticks](../axes/styling.md#tick-configuration). -| `strokeStyle` | `string` | `` | The color of the stroke around the text. Currently only supported by [ticks](../axes/styling.md#tick-configuration). +| `lineWidth` | `number` | `0` | Stroke width around the text. Currently only supported by [ticks](../axes/styling#tick-configuration). +| `strokeStyle` | `string` | `` | The color of the stroke around the text. Currently only supported by [ticks](../axes/styling#tick-configuration). ## Missing Fonts diff --git a/docs/sidebars.js b/docs/sidebars.js index 941c8870a..3300e2114 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -49,7 +49,8 @@ module.exports = { 'axes/cartesian/category', 'axes/cartesian/linear', 'axes/cartesian/logarithmic', - 'axes/cartesian/time' + 'axes/cartesian/time', + 'axes/cartesian/timeseries' ]}, {Radial: [ 'axes/radial/index',