插件(Plugins)

插件是自定义或更改图表默认行为的最有效方式。它们已经在2.1.0 版本(仅限于全局插件)中引入,并且在2.5.0 版本(每个图表插件和选项)中进行了扩展。

使用插件

插件可以在图表实例之间共享:

  1. var plugin = {
  2. /* plugin implementation */
  3. };
  4. // chart1 and chart2 use "plugin"
  5. var chart1 = new Chart(ctx, {
  6. plugins: [plugin]
  7. });
  8. var chart2 = new Chart(ctx, {
  9. plugins: [plugin]
  10. });
  11. // chart3 doesn't use "plugin"
  12. var chart3 = new Chart(ctx, {});

插件也可以直接在图表插件配置(即内联插件)中定义:

  1. var chart = new Chart(ctx, {
  2. plugins: [
  3. {
  4. beforeInit: function(chart, options) {
  5. //..
  6. }
  7. }
  8. ]
  9. });

但是,当需要自定义选项适用于多个图表时,这种方法并不理想。

全局插件

插件可以在全局范围内注册,应用于所有图表(即全局插件):

  1. Chart.plugins.register({
  2. // plugin implementation
  3. });
注意: inline 插件不能全局注册

配置

插件 ID

插件必须定义一个唯一的 ID 以便可配置。

该 id 应该遵循npm 包名称约定

  • 不能以点或下划线开头
  • 不能包含任何非网址安全的字符
  • 不能包含大写字母
  • 简短并合理的描述
    如果打算公开发布一个插件,你可能要检查registry,看看该名字的插件是否已经存在。需要注意的是,在这种情况下,包名称应以 chartjs-plugin-为前缀,以显示在 Chart.js 插件注册表中。

插件选项

插件选项位于options.plugins配置下,并由插件 ID:options.plugins.{plugin-id}作为作用域。

  1. var chart = new Chart(ctx, {
  2. config: {
  3. foo: { ... }, // chart 'foo' option
  4. plugins: {
  5. p1: {
  6. foo: { ... }, // p1 plugin 'foo' option
  7. bar: { ... }
  8. },
  9. p2: {
  10. foo: { ... }, // p2 plugin 'foo' option
  11. bla: { ... }
  12. }
  13. }
  14. }
  15. });

禁用插件

要为特定图表禁用全局插件,插件选项必须设置为false

  1. Chart.plugins.register({
  2. id: "p1"
  3. // ...
  4. });
  5. var chart = new Chart(ctx, {
  6. config: {
  7. plugins: {
  8. p1: false // disable plugin 'p1' for this instance
  9. }
  10. }
  11. });

插件核心 API

可用钩子 (从 2.6 版本开始):

  • beforeInit
  • afterInit
  • beforeUpdate (cancellable)
  • afterUpdate
  • beforeLayout (cancellable)
  • afterLayout
  • beforeDatasetsUpdate (cancellable)
  • afterDatasetsUpdate
  • beforeRender (cancellable)
  • beforeDatasetUpdate (cancellable)
  • afterDatasetUpdate
  • beforeRender (cancellable)
  • afterRender
  • beforeDraw (cancellable)
  • afterDraw
  • beforeDatasetsDraw (cancellable)
  • afterDatasetsDraw
  • beforeEvent (cancellable)
  • beforeDatasetDraw (cancellable)
  • afterDatasetDraw
  • beforeEvent (cancellable)
  • afterEvent
  • resize
  • destroy