mirror of
https://github.com/chartjs/Chart.js.git
synced 2024-10-06 12:19:08 +02:00
TypeScript updates (#8190)
* Update type definitions and docs for legends * Fix types for onHover and onClick callbacks core.controller.js's implementation also passes the Chart instance as `this`. However, that isn't documented, and it's my impression that Chart.js is moving away from passing items as `this`, so I didn't declare it in the type definitions. * Allow multi-line ticks * Stricter DeepPartial definition The previous definition resolved to `{}` (which can allow primitives) if it was given a function, so it was far too broad for any `Scriptable<>` properties. * Grammar and writing style * Updates to animation docs Document the `fn` option, since it's in the type definitions. Fix callback usage to match example code. * Fix AnimationEvent parameter The onProgress and onComplete events were mistakenly declared as taking the standard DOM AnimationEvent. (Should Chart.js's AnimationEvent be renamed to ChartAnimationEvent to avoid any possible ambiguity?) * Allow false for disabling animations * Add comments explaining the layout and usage of Rollup
This commit is contained in:
parent
04c45aacda
commit
efbaf2c082
@ -123,7 +123,7 @@ The default configuration is defined here: <a href="https://github.com/chartjs/C
|
||||
| [[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)
|
||||
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
|
||||
|
||||
@ -153,6 +153,7 @@ A property option is defined by the same options of the main [animation configur
|
||||
| `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`|`Color`|`boolean`</code> | `undefined` | Start value for the animation. Current value is used when `undefined`
|
||||
| `to` | <code>`number`|`Color`|`boolean`</code> | `undefined` | End value for the animation. Updated value is used when `undefined`
|
||||
| `fn` | <code><T>(from: T, to: T, factor: number) => T;</code> | `undefined` | Optional custom interpolator, instead of using a predefined interpolator from `type` |
|
||||
|
||||
## Animation properties collection configuration
|
||||
|
||||
@ -183,7 +184,7 @@ These default collections are overridden by most dataset controllers.
|
||||
|
||||
## Disabling 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`.
|
||||
To disable an animation configuration, the animation node must be set to `false`, with the exception for animation modes which can be disabled by setting the `duration` to `0`.
|
||||
|
||||
```javascript
|
||||
chart.options.animation = false; // disables the whole animation
|
||||
@ -232,7 +233,7 @@ See [Robert Penner's easing equations](http://robertpenner.com/easing/).
|
||||
|
||||
## Animation Callbacks
|
||||
|
||||
The animation configuration enables the callbacks which are useful for synchronizing an external draw to the chart animation.
|
||||
The animation configuration provides 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
|
||||
@ -240,7 +241,7 @@ The callbacks can be set only at main [animation configuration](#animation-confi
|
||||
| `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:
|
||||
The callback is passed the following object:
|
||||
|
||||
```javascript
|
||||
{
|
||||
@ -264,7 +265,7 @@ var chart = new Chart(ctx, {
|
||||
options: {
|
||||
animation: {
|
||||
onProgress: function(animation) {
|
||||
progress.value = animation.animationObject.currentStep / animation.animationObject.numSteps;
|
||||
progress.value = animation.currentStep / animation.numSteps;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
@ -82,6 +82,9 @@ Items passed to the legend `onClick` function are the ones returned from `labels
|
||||
// Label that will be displayed
|
||||
text: string,
|
||||
|
||||
// Index of the associated dataset
|
||||
datasetIndex: number,
|
||||
|
||||
// Fill style of the legend box
|
||||
fillStyle: Color,
|
||||
|
||||
|
2
types/core/index.d.ts
vendored
2
types/core/index.d.ts
vendored
@ -874,7 +874,7 @@ export const registry: Registry;
|
||||
|
||||
export interface Tick {
|
||||
value: number;
|
||||
label?: string;
|
||||
label?: string | string[];
|
||||
major?: boolean;
|
||||
}
|
||||
|
||||
|
28
types/core/interfaces.d.ts
vendored
28
types/core/interfaces.d.ts
vendored
@ -1,4 +1,4 @@
|
||||
import { Chart, Element, InteractionMode } from '.';
|
||||
import { ActiveElement, AnimationEvent, Chart, InteractionMode } from '.';
|
||||
import { ChartDataset } from '../interfaces';
|
||||
import { ParsingOptions } from '../controllers';
|
||||
import { PluginOptions } from '../plugins';
|
||||
@ -85,14 +85,14 @@ export interface HoverInteractionOptions extends CoreInteractionOptions {
|
||||
/**
|
||||
* Called when any of the events fire. Passed the event, an array of active elements (bars, points, etc), and the chart.
|
||||
*/
|
||||
onHover(event: ChartEvent, elements: Element[]): void;
|
||||
onHover(event: ChartEvent, elements: ActiveElement[], chart: Chart): void;
|
||||
}
|
||||
|
||||
export interface CoreChartOptions extends ParsingOptions {
|
||||
animation: Scriptable<AnimationOptions>;
|
||||
animation: Scriptable<AnimationOptions | false>;
|
||||
|
||||
datasets: {
|
||||
animation: Scriptable<AnimationOptions>;
|
||||
animation: Scriptable<AnimationOptions | false>;
|
||||
};
|
||||
|
||||
/**
|
||||
@ -131,7 +131,7 @@ export interface CoreChartOptions extends ParsingOptions {
|
||||
* @default 2
|
||||
*/
|
||||
aspectRatio: number;
|
||||
|
||||
|
||||
/**
|
||||
* Locale used for number formatting (using `Intl.NumberFormat`).
|
||||
* @default user's browser setting
|
||||
@ -162,12 +162,12 @@ export interface CoreChartOptions extends ParsingOptions {
|
||||
/**
|
||||
* Called when any of the events fire. Passed the event, an array of active elements (bars, points, etc), and the chart.
|
||||
*/
|
||||
onHover(event: ChartEvent, elements: Element[]): void;
|
||||
onHover(event: ChartEvent, elements: ActiveElement[], chart: Chart): void;
|
||||
|
||||
/**
|
||||
* Called if the event is of type 'mouseup' or 'click'. Passed the event, an array of active elements, and the chart.
|
||||
*/
|
||||
onClick(event: ChartEvent, elements: Element[]): void;
|
||||
onClick(event: ChartEvent, elements: ActiveElement[], chart: Chart): void;
|
||||
|
||||
layout: {
|
||||
padding: Scriptable<number | ChartArea>;
|
||||
@ -261,7 +261,7 @@ export interface AnimationPropertySpec extends AnimationCommonSpec {
|
||||
}
|
||||
|
||||
export type AnimationSpecContainer = AnimationCommonSpec & {
|
||||
[prop: string]: AnimationPropertySpec;
|
||||
[prop: string]: AnimationPropertySpec | false;
|
||||
};
|
||||
|
||||
export type AnimationOptions = AnimationSpecContainer & {
|
||||
@ -270,15 +270,15 @@ export type AnimationOptions = AnimationSpecContainer & {
|
||||
*/
|
||||
onProgress: (this: Chart, event: AnimationEvent) => void;
|
||||
/**
|
||||
*Callback called when all animations are completed.
|
||||
* Callback called when all animations are completed.
|
||||
*/
|
||||
onComplete: (this: Chart, event: AnimationEvent) => void;
|
||||
|
||||
active: AnimationSpecContainer;
|
||||
hide: AnimationSpecContainer;
|
||||
reset: AnimationSpecContainer;
|
||||
resize: AnimationSpecContainer;
|
||||
show: AnimationSpecContainer;
|
||||
active: AnimationSpecContainer | false;
|
||||
hide: AnimationSpecContainer | false;
|
||||
reset: AnimationSpecContainer | false;
|
||||
resize: AnimationSpecContainer | false;
|
||||
show: AnimationSpecContainer | false;
|
||||
};
|
||||
|
||||
export interface FontSpec {
|
||||
|
14
types/index.esm.d.ts
vendored
14
types/index.esm.d.ts
vendored
@ -1,3 +1,17 @@
|
||||
/**
|
||||
* Top-level type definitions. These are processed by Rollup and rollup-plugin-dts
|
||||
* to make a combined .d.ts file under dist; that way, all of the type definitions
|
||||
* appear directly within the "chart.js" module; that matches the layout of the
|
||||
* distributed chart.esm.js bundle and means that users of Chart.js can easily use
|
||||
* module augmentation to extend Chart.js's types and plugins within their own
|
||||
* code, like so:
|
||||
*
|
||||
* @example
|
||||
* declare module "chart.js" {
|
||||
* // Add types here
|
||||
* }
|
||||
*/
|
||||
|
||||
export * from './controllers';
|
||||
export * from './core';
|
||||
export * from './elements';
|
||||
|
17
types/interfaces.d.ts
vendored
17
types/interfaces.d.ts
vendored
@ -32,11 +32,18 @@ import {
|
||||
TimeScaleOptions,
|
||||
} from './scales';
|
||||
|
||||
export type DeepPartial<T> = T extends {}
|
||||
? {
|
||||
[K in keyof T]?: DeepPartial<T[K]>;
|
||||
}
|
||||
: T;
|
||||
// DeepPartial implementation taken from the utility-types NPM package, which is
|
||||
// Copyright (c) 2016 Piotr Witek <piotrek.witek@gmail.com> (http://piotrwitek.github.io)
|
||||
// and used under the terms of the MIT license
|
||||
export type DeepPartial<T> = T extends Function
|
||||
? T
|
||||
: T extends Array<infer U>
|
||||
? _DeepPartialArray<U>
|
||||
: T extends object
|
||||
? _DeepPartialObject<T>
|
||||
: T | undefined;
|
||||
interface _DeepPartialArray<T> extends Array<DeepPartial<T>> {}
|
||||
type _DeepPartialObject<T> = { [P in keyof T]?: DeepPartial<T[P]> };
|
||||
|
||||
export type DistributiveArray<T> = T extends unknown ? T[] : never
|
||||
|
||||
|
31
types/plugins/index.d.ts
vendored
31
types/plugins/index.d.ts
vendored
@ -41,59 +41,64 @@ export interface LegendItem {
|
||||
*/
|
||||
text: string;
|
||||
|
||||
/**
|
||||
* Index of the associated dataset
|
||||
*/
|
||||
datasetIndex: number;
|
||||
|
||||
/**
|
||||
* Fill style of the legend box
|
||||
*/
|
||||
fillStyle: CanvasLineCap;
|
||||
fillStyle?: Color;
|
||||
|
||||
/**
|
||||
* If true, this item represents a hidden dataset. Label will be rendered with a strike-through effect
|
||||
*/
|
||||
hidden: boolean;
|
||||
hidden?: boolean;
|
||||
|
||||
/**
|
||||
* For box border.
|
||||
* @see https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap
|
||||
*/
|
||||
lineCap: CanvasLineCap;
|
||||
lineCap?: CanvasLineCap;
|
||||
|
||||
/**
|
||||
* For box border.
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
|
||||
*/
|
||||
lineDash: number[];
|
||||
lineDash?: number[];
|
||||
|
||||
/**
|
||||
* For box border.
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
|
||||
*/
|
||||
lineDashOffset: number;
|
||||
lineDashOffset?: number;
|
||||
|
||||
/**
|
||||
* For box border.
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin
|
||||
*/
|
||||
lineJoin: CanvasLineJoin;
|
||||
lineJoin?: CanvasLineJoin;
|
||||
|
||||
/**
|
||||
* Width of box border
|
||||
*/
|
||||
lineWidth: number;
|
||||
lineWidth?: number;
|
||||
|
||||
/**
|
||||
* Stroke style of the legend box
|
||||
*/
|
||||
strokeStyle: Color;
|
||||
strokeStyle?: Color;
|
||||
|
||||
/**
|
||||
* Point style of the legend box (only used if usePointStyle is true)
|
||||
*/
|
||||
pointStyle: PointStyle;
|
||||
pointStyle?: PointStyle;
|
||||
|
||||
/**
|
||||
* Rotation of the point in degrees (only used if usePointStyle is true)
|
||||
*/
|
||||
rotation: number;
|
||||
rotation?: number;
|
||||
}
|
||||
|
||||
export interface LegendElement extends Element {}
|
||||
@ -129,11 +134,11 @@ export interface LegendOptions {
|
||||
*/
|
||||
onClick(this: LegendElement, e: ChartEvent, legendItem: LegendItem, legend: LegendElement): void;
|
||||
/**
|
||||
* A callback that is called when a 'mousemove' event is registered on top of a label item
|
||||
* A callback that is called when a 'mousemove' event is registered on top of a label item
|
||||
*/
|
||||
onHover(this: LegendElement, e: ChartEvent, legendItem: LegendItem, legend: LegendElement): void;
|
||||
/**
|
||||
* A callback that is called when a 'mousemove' event is registered outside of a previously hovered label item.
|
||||
* A callback that is called when a 'mousemove' event is registered outside of a previously hovered label item.
|
||||
*/
|
||||
onLeave(this: LegendElement, e: ChartEvent, legendItem: LegendItem, legend: LegendElement): void;
|
||||
|
||||
@ -176,7 +181,7 @@ export interface LegendOptions {
|
||||
pointStyle: PointStyle;
|
||||
|
||||
/**
|
||||
* Label style will match corresponding point style (size is based on the mimimum value between boxWidth and font.size).
|
||||
* Label style will match corresponding point style (size is based on the minimum value between boxWidth and font.size).
|
||||
* @default false
|
||||
*/
|
||||
usePointStyle: boolean;
|
||||
|
Loading…
Reference in New Issue
Block a user