diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 3cef98f6..35863807 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -75,6 +75,7 @@ module.exports = { 'usage', 'options', 'animations', + 'developers', ], '/samples/': [ 'basic', diff --git a/docs/guide/developers.md b/docs/guide/developers.md new file mode 100644 index 00000000..ac389382 --- /dev/null +++ b/docs/guide/developers.md @@ -0,0 +1,29 @@ +# Developers + +You can extend chartjs-plugin-zoom with support for [custom scales](https://www.chartjs.org/docs/latest/developers/axes.html) by using the zoom plugin's `zoomFunctions` and `panFunctions` members. These objects are indexed by scale types (scales' `id` members) and give optional handlers for zoom and pan functionality. + +```js +import {Scale} from 'chart.js'; +import zoomPlugin from 'chartjs-plugin-zoom'; + +class MyScale extends Scale { + /* extensions ... */ +} +MyScale.id = 'myScale'; +MyScale.defaults = defaultConfigObject; + +zoomPlugin.zoomFunctions.myScale = (scale, zoom, center, limits) => false; +zoomPlugin.panFunctions.myScale = (scale, delta, limits) => false; +``` + +The zoom and pan functions take the following arguments: + +| Name | Type | For | Description +| ---- | ---- | --- | ---------- +| `scale` | `Scale` | Zoom, Pan | The custom scale instance (usually derived from `Chart.Scale`) +| `zoom` | `number` | Zoom | The zoom fraction; 1.0 is unzoomed, 0.5 means zoomed in to 50% of the original area, etc. +| `center` | `{x, y}` | Zoom | Pixel coordinates of the center of the zoom operation. `{x: 0, y: 0}` is the upper left corner of the chart's canvas. +| `pan` | `number` | Pan | Pixel amount to pan by +| `limits` | [Limits](./options#limits) | Zoom, Pan | Zoom and pan limits (from chart options) + +For examples, see chartjs-plugin-zoom's [default zoomFunctions and panFunctions handling for standard Chart.js axes](https://github.com/chartjs/chartjs-plugin-zoom/blob/v1.0.1/src/scale.types.js#L128). diff --git a/types/index.d.ts b/types/index.d.ts index d12549b9..c0911f91 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -1,6 +1,6 @@ -import { Plugin, ChartType, Chart, Scale, UpdateMode } from 'chart.js'; +import { Plugin, ChartType, Chart, Scale, UpdateMode, ScaleTypeRegistry } from 'chart.js'; import { DistributiveArray } from 'chart.js/types/utils'; -import { ZoomPluginOptions } from './options'; +import { LimitOptions, ZoomPluginOptions } from './options'; type Point = { x: number, y: number }; type ZoomAmount = number | Partial & { focalPoint?: Point }; @@ -8,8 +8,8 @@ type PanAmount = number | Partial; type ScaleRange = { min: number, max: number }; declare module 'chart.js' { - // eslint-disable-next-line @typescript-eslint/no-unused-vars - interface PluginOptionsByType { + // eslint-disable-next-line @typescript-eslint/no-unused-vars + interface PluginOptionsByType { zoom: ZoomPluginOptions; } @@ -26,7 +26,19 @@ declare module 'chart.js' { } } -declare const Zoom: Plugin; +export type ZoomFunction = (scale: Scale, zoom: number, center: Point, limits: LimitOptions) => boolean; +export type PanFunction = (scale: Scale, delta: number, limits: LimitOptions) => boolean; + +type ScaleFunctions = { + [scaleType in keyof ScaleTypeRegistry]?: T | undefined; +} & { + default: T; +}; + +declare const Zoom: Plugin & { + zoomFunctions: ScaleFunctions; + panFunctions: ScaleFunctions; +}; export default Zoom;