Mon 21 Jul 22:43:21 CEST 2025
This commit is contained in:
parent
77584e2952
commit
f9a5bbcd8d
132
js/ui/chart/docs/developers/plugins.md
Normal file
132
js/ui/chart/docs/developers/plugins.md
Normal file
|
@ -0,0 +1,132 @@
|
|||
# Plugins
|
||||
|
||||
Plugins are the most efficient way to customize or change the default behavior of a chart. They have been introduced at [version 2.1.0](https://github.com/chartjs/Chart.js/releases/tag/2.1.0) (global plugins only) and extended at [version 2.5.0](https://github.com/chartjs/Chart.js/releases/tag/v2.5.0) (per chart plugins and options).
|
||||
|
||||
## Using plugins
|
||||
|
||||
Plugins can be shared between chart instances:
|
||||
|
||||
```javascript
|
||||
var plugin = { /* plugin implementation */ };
|
||||
|
||||
// chart1 and chart2 use "plugin"
|
||||
var chart1 = new Chart(ctx, {
|
||||
plugins: [plugin]
|
||||
});
|
||||
|
||||
var chart2 = new Chart(ctx, {
|
||||
plugins: [plugin]
|
||||
});
|
||||
|
||||
// chart3 doesn't use "plugin"
|
||||
var chart3 = new Chart(ctx, {});
|
||||
```
|
||||
|
||||
Plugins can also be defined directly in the chart `plugins` config (a.k.a. *inline plugins*):
|
||||
|
||||
```javascript
|
||||
var chart = new Chart(ctx, {
|
||||
plugins: [{
|
||||
beforeInit: function(chart, options) {
|
||||
//..
|
||||
}
|
||||
}]
|
||||
});
|
||||
```
|
||||
|
||||
However, this approach is not ideal when the customization needs to apply to many charts.
|
||||
|
||||
## Global plugins
|
||||
|
||||
Plugins can be registered globally to be applied on all charts (a.k.a. *global plugins*):
|
||||
|
||||
```javascript
|
||||
Chart.plugins.register({
|
||||
// plugin implementation
|
||||
});
|
||||
```
|
||||
|
||||
> Note: *inline* plugins can't be registered globally.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Plugin ID
|
||||
|
||||
Plugins must define a unique id in order to be configurable.
|
||||
|
||||
This id should follow the [npm package name convention](https://docs.npmjs.com/files/package.json#name):
|
||||
|
||||
- can't start with a dot or an underscore
|
||||
- can't contain any non-URL-safe characters
|
||||
- can't contain uppercase letters
|
||||
- should be something short, but also reasonably descriptive
|
||||
|
||||
If a plugin is intended to be released publicly, you may want to check the [registry](https://www.npmjs.com/search?q=chartjs-plugin-) to see if there's something by that name already. Note that in this case, the package name should be prefixed by `chartjs-plugin-` to appear in Chart.js plugin registry.
|
||||
|
||||
### Plugin options
|
||||
|
||||
Plugin options are located under the `options.plugins` config and are scoped by the plugin ID: `options.plugins.{plugin-id}`.
|
||||
|
||||
```javascript
|
||||
var chart = new Chart(ctx, {
|
||||
options: {
|
||||
foo: { ... }, // chart 'foo' option
|
||||
plugins: {
|
||||
p1: {
|
||||
foo: { ... }, // p1 plugin 'foo' option
|
||||
bar: { ... }
|
||||
},
|
||||
p2: {
|
||||
foo: { ... }, // p2 plugin 'foo' option
|
||||
bla: { ... }
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
#### Disable plugins
|
||||
|
||||
To disable a global plugin for a specific chart instance, the plugin options must be set to `false`:
|
||||
|
||||
```javascript
|
||||
Chart.plugins.register({
|
||||
id: 'p1',
|
||||
// ...
|
||||
});
|
||||
|
||||
var chart = new Chart(ctx, {
|
||||
options: {
|
||||
plugins: {
|
||||
p1: false // disable plugin 'p1' for this instance
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## Plugin Core API
|
||||
|
||||
Available hooks (as of version 2.7):
|
||||
|
||||
* `beforeInit`
|
||||
* `afterInit`
|
||||
* `beforeUpdate` *(cancellable)*
|
||||
* `afterUpdate`
|
||||
* `beforeLayout` *(cancellable)*
|
||||
* `afterLayout`
|
||||
* `beforeDatasetsUpdate` *(cancellable)*
|
||||
* `afterDatasetsUpdate`
|
||||
* `beforeDatasetUpdate` *(cancellable)*
|
||||
* `afterDatasetUpdate`
|
||||
* `beforeRender` *(cancellable)*
|
||||
* `afterRender`
|
||||
* `beforeDraw` *(cancellable)*
|
||||
* `afterDraw`
|
||||
* `beforeDatasetsDraw` *(cancellable)*
|
||||
* `afterDatasetsDraw`
|
||||
* `beforeDatasetDraw` *(cancellable)*
|
||||
* `afterDatasetDraw`
|
||||
* `beforeEvent` *(cancellable)*
|
||||
* `afterEvent`
|
||||
* `resize`
|
||||
* `destroy`
|
Loading…
Reference in New Issue
Block a user