Mirrors/Chart.js
1
0
Fork 0
mirror of https://github.com/chartjs/Chart.js.git synced 2024-10-06 12:19:08 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add some additional info and sections to animation documentation (#7685)

Browse Source
This commit is contained in:
stockiNail 2020-07-31 15:49:17 +02:00 committed by GitHub
parent b86880f746
commit 65c31cfd6e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 61 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
docs/docs/configuration/animations.mdx
View File

@ -115,17 +115,52 @@ The default configuration is defined here: <a href="https://github.com/chartjs/C
| `duration` | `number` | `1000` | The number of milliseconds an animation takes.
| `easing` | `string` | `'easeOutQuart'` | Easing function to use. [more...](#easing)
| `debug` | `boolean` | `undefined` | Running animation count + FPS display in upper left corner of the chart.
| `onProgress` | `function` | `null` | Callback called on each step of an animation. [more...](#animation-callbacks)
| `onComplete` | `function` | `null` | Callback called when all animations are completed. [more...](#animation-callbacks)
| `delay` | `number` | `undefined` | Delay before starting the animations.
| `loop` | `boolean` | `undefined` | If set to `true`, the animations loop endlessly.
| [[mode]](#animation-mode-configuration) | `object` | [defaults...](#default-modes) | Option overrides for update mode. Core modes: `'active'`, `'hide'`, `'reset'`, `'resize'`, `'show'`. See **Hide and show [mode]** example above.
| [[property]](#animation-property-configuration) | `object` | `undefined` | Option overrides for a single element `[property]`. These have precedence over `[collection]`. See **Looping tension [property]** example above.
| [[collection]](#animation-properties-collection-configuration) | `object` | [defaults...](#default-collections) | Option overrides for multiple properties, identified by `properties` array.
These defaults can be overridden in `options.animation` or `dataset.animation` and `tooltip.animation`. These keys are also [Scriptable](../general/options.md#scriptable-options)
## Animation mode configuration
Mode option configures how an update mode animates the chart.
The cores modes are `'active'`, `'hide'`, `'reset'`, `'resize'`, `'show'`.
A custom mode can be used by passing a custom `mode` to [update](../developers/api.md#updatemode).
A mode option is defined by the same options of the main [animation configuration](#animation-configuration).
### Default modes
| Mode | Option | Value | Description
| -----| ------ | ----- | -----
| `'active'` | duration | 400 | Override default duration to 400ms for hover animations
| `'resize'` | duration | 0 | Override default duration to 0ms (= no animation) for resize
| `'show'` | colors | `{ type: 'color', properties: ['borderColor', 'backgroundColor'], from: 'transparent' }` | Colors are faded in from transparent when dataset is shown using legend / [api](../developers/api.md#showdatasetIndex).
| | visible | `{ type: 'boolean', duration: 0 }` | Dataset visiblity is immediately changed to true so the color transition from transparent is visible.
| `'hide'` | colors | `{ type: 'color', properties: ['borderColor', 'backgroundColor'], to: 'transparent' }` | Colors are faded to transparent when dataset id hidden using legend / [api](../developers/api.md#hidedatasetIndex).
| | visible | `{ type: 'boolean', easing: 'easeInExpo' }` | Visibility is changed to false at a very late phase of animation
## Animation property configuration
Property option configures which element property to use to animate the chart and its starting and ending values.
A property option is defined by the same options of the main [animation configuration](#animation-configuration), adding the following ones:
| Name | Type | Default | Description
| ---- | ---- | ------- | -----------
| `type` | `string` | `typeof property` | Type of property, determines the interpolator used. Possible values: `'number'`, `'color'` and `'boolean'`. Only really needed for `'color'`, because `typeof` does not get that right.
| `from` | <code>`number`&#124;`Color`&#124;`boolean`</code> | `undefined` | Start value for the animation. Current value is used when `undefined`
| `active` | `object` | `{ duration: 400 }` | Option overrides for `active` animations (hover)
| `resize` | `object` | `{ duration: 0 }` | Option overrides for `resize` animations.
| [property] | `object` | `undefined` | Option overrides for a single element `[property]`. These have precedence over `[collection]`. See **Looping tension [property]** example above.
| [collection] | `object` | [defaults...](#default-collections) | Option overrides for multiple properties, identified by `properties` array. Collection can be named whatever you like, but should not collide with a `[property]` or `[mode]`.
| [mode] | `object` | [defaults...](#default-modes) | Option overrides for update mode. Core modes: `'active'`, `'hide'`, `'reset'`, `'resize'`, `'show'`. See **Hide and show [mode]** example above. A custom mode can be used by passing a custom `mode` to [update](../developers/api.md#updatemode)
| `to` | <code>`number`&#124;`Color`&#124;`boolean`</code> | `undefined` | End value for the animation. Updated value is used when `undefined`
## Animation properties collection configuration
Properties collection option configures which set of element properties to use to animate the chart.
Collection can be named whatever you like, but should not collide with a `[property]` or `[mode]`.
A properties collection option is defined by the same options of the [animation property configuration](#animation-property-configuration), adding the following one:
| Name | Type | Default | Description
| ---- | ---- | ------- | -----------
| `properties` | `string[]` | `undefined` | Set of properties to use to animate the chart.
### Default collections
@ -138,22 +173,22 @@ The default configuration is defined here: <a href="https://github.com/chartjs/C
Direct property configuration overrides configuration of same property in a collection.
These defaults can be overridden in `options.animation` or `dataset.animation` and `tooltip.animation`. These keys are also [Scriptable](../general/options.md#scriptable-options)
From collections, a property gets its configuration from first one that has its name in properties.
:::note
These default collections are overridden by most dataset controllers.
:::
### Default modes
## Disabling animation
| Mode | Option | Value | Description
| -----| ------ | ----- | -----
| `'active'` | duration | 400 | Override default duration to 400ms for hover animations
| `'resize'` | duration | 0 | Override default duration to 0ms (= no animation) for resize
| `'show'` | colors | `{ type: 'color', properties: ['borderColor', 'backgroundColor'], from: 'transparent' }` | Colors are faded in from transparent when dataset is shown using legend / [api](../developers/api.md#showdatasetIndex).
| | visible | `{ type: 'boolean', duration: 0 }` | Dataset visiblity is immediately changed to true so the color transition from transparent is visible.
| `'hide'` | colors | `{ type: 'color', properties: ['borderColor', 'backgroundColor'], to: 'transparent' }` | Colors are faded to transparent when dataset id hidden using legend / [api](../developers/api.md#hidedatasetIndex).
| | visible | `{ type: 'boolean', easing: 'easeInExpo' }` | Visibility is changed to false very at late phase of animation
To disable an animation configuration, the animation node must be set to `false`, with the exception for animation modes which can be disable setting the `duration` to `0`.
```javascript
chart.options.animation = false; // disables the whole animation
chart.options.animation.active.duration = 0; // disables the animation for 'active' mode
chart.options.animation.colors = false; // disables animation defined by the collection of 'colors' properties
chart.options.animation.x = false; // disables animation defined by the 'x' property
```
## Easing
@ -195,7 +230,15 @@ See [Robert Penner's easing equations](http://robertpenner.com/easing/).
## Animation Callbacks
The `onProgress` and `onComplete` callbacks are useful for synchronizing an external draw to the chart animation. The callback is passed following object:
The animation configuration enables the callbacks which are useful for synchronizing an external draw to the chart animation.
The callbacks can be set only at main [animation configuration](#animation-configuration).
| Name | Type | Default | Description
| ---- | ---- | ------- | -----------
| `onProgress` | `function` | `null` | Callback called on each step of an animation.
| `onComplete` | `function` | `null` | Callback called when all animations are completed.
The callback is passed following object:
```javascript
{