Chart.js（未完）

https://chartjs.cn/docs/latest/

• v4.4

Chart.js

• 社区维护的 图表类型
• 可通过 自定义插件 高度自定义，以创建注释、缩放或拖放功能等等
• 可以直接使用 Chart.js 或利用维护良好的封装程序包，以便与你选择的框架进行更原生的集成。Vue

新手入门

• 建议为图表提供 responsiveness 自己的容器
  • 注释：canvas的父元素 size 改变会触发图表重绘

<div>
  <canvas id="myChart"></canvas>
</div>

安装

• Chart.js 是 tree-shakeable 的，因此有必要导入并注册你将要使用的控制器、元素、比例尺和插件
• 每种类型的图表都有自己的最低要求（通常是类型的控制器、该控制器使用的元素和比例尺）：

逐步指南

• legend
  • 注释：图例，图表图例用于显示图表上出现的数据集的相关信息，可用于显隐数据集
• tooltips
  • 注释：工具提示，图表上hover时展示的信息
• 气泡图 允许同时展示三个维度的数据：x 和 y 轴上的位置表示两个维度，第三个维度由单个气泡的大小表示
• 使用插件微调图表
  • 可以使用简单的临时插件为其自定义 canvas 背景 或 添加边框
• 插件被定义为具有 name 的对象以及在扩展点中定义的一个或多个回调函数。
  • 注释：定义插件就是定义一个对象，在对象中提供了一些回调函数，这些回调函数能够接受到通过option配置项传入插件的值
  • 注释：canvas在绘制时使用同一个对象ctx的相同属性，为了不影响外部的绘制，在开始新绘制前要通过ctx.save()来把绘图状态缓存到栈中，在绘制结束后通过ctx.restore()恢复栈中的最后一个状态。

// ...

  const chartAreaBorder = {
    id: 'chartAreaBorder',

    beforeDraw(chart, args, options) {
      const { ctx, chartArea: { left, top, width, height } } = chart;

      ctx.save();
      ctx.strokeStyle = options.borderColor;
      ctx.lineWidth = options.borderWidth;
      ctx.setLineDash(options.borderDash || []);
      ctx.lineDashOffset = options.borderDashOffset;
      ctx.strokeRect(left, top, width, height);
      ctx.restore();
    }
  };

  new Chart(
    document.getElementById('dimensions'),
    {
      type: 'bubble',
      plugins: [ chartAreaBorder ],
      options: {
        plugins: {
          chartAreaBorder: {
            borderColor: 'red',
            borderWidth: 2,
            borderDash: [ 5, 5 ],
            borderDashOffset: 2,
          }
        },
        aspectRatio: 1,

// ...

可访问性

• 对于 canvas，必须使用 canvas 元素上的 ARIA 属性添加可访问性，或者使用放置在开始和结束画布标签中的内部回退内容来添加
  • 注释：屏幕阅读器

颜色

• 图表支持三种颜色选项
  • 对于几何元素，你可以更改背景和边框颜色；
  • 对于文本元素，你可以更改字体颜色。
  • 还可以更改整个 canvas 背景
• 如果未指定颜色，则使用 Chart.defaults 中的全局默认颜色：
  • 可以通过更新 Chart.defaults 的这些属性来重置默认颜色：
• 可以为每个数据集设置 backgroundColor 和 borderColor
  • 使用内置的 Colors 插件。它将循环显示七种 Chart.js 品牌颜色的调色板
    • 只需要导入并注册插件Chart.register(Colors);
    • 如果你使用的是 UMD 版本的 Chart.js，此插件将默认启用。你可以通过将 enabled 选项设置为 false 来禁用它：
• 默认情况下，颜色插件仅在你初始化图表且未指定任何边框或背景颜色时才起作用。如果你想强制颜色插件始终为数据集着色，例如，在运行时使用动态数据集时，你需要将 forceOverride 选项设置为 true：
• 颜色格式
  • HSL 或 HSLA
    • 注释：HSL (色相，饱和度，亮度)
  • 可以传递 CanvasPattern 或 CanvasGradient 对象而不是字符串颜色来实现一些有趣的效果
    • 注释：CanvasPattern 表示一种基于图像的模式，这种模式可以用来填充图形的内部。即一种图片即在绘制时应当如何拉伸还是重复。用于画笔样式上
    • 注释：CanvasGradient 用于创建渐变颜色的效果

数据结构

• data 属性的 labels 属性，它必须包含与具有最多值的数据集相同数量的元素。
  • 如果你需要多行标签，你可以提供一个数组，其中每一行作为数组中的一个条目。

data值的类型

• Primitive[]
  • 当 data 是数字数组时，相同索引处的 labels 数组中的值用于索引轴（x 用于垂直图表，y 用于水平图表）

const cfg = {
  type: 'bar',
  data: {
    datasets: [{
      data: [20, 10],
    }],
    labels: ['a', 'b']
  }
}

• Object[]
  • 注释：Object中是固定属性x，y
  • 提供的值必须可以由关联的尺度或关联尺度的内部格式解析。一个常见的错误是为 category 标度提供整数，它使用整数作为内部格式，其中每个整数代表标签数组中的一个索引。
  • null 可用于跳过的值。
  • 可以通过在图表选项或数据集中指定 parsing: false 来禁用解析。如果禁用解析，则必须对数据进行排序，并采用相关图表类型和比例在内部使用的格式。
    • 注释：会自动解析数据进行排序，例如：x: '2016-12-25'时，可以手动关闭解析，手动关闭解析后需要自己维护数据的顺序

const cfg = {
  type: 'line',
  data: {
    datasets: [{
      data: [{x: 10, y: 20}, {x: 15, y: null}, {x: 20, y: 10}]
    }]
  }
}

const cfg = {
  type: 'line',
  data: {
    datasets: [{
      data: [{x: '2016-12-25', y: 20}, {x: '2016-12-26', y: 10}]
    }]
  }
}

const cfg = {
  type: 'bar',
  data: {
    datasets: [{
      data: [{x: 'Sales', y: 20}, {x: 'Revenue', y: 10}]
    }]
  }
}

• Object[] 使用自定义属性

const cfg = {
  type: 'bar',
  data: {
    datasets: [{
      data: [{id: 'Sales', nested: {value: 1500}}, {id: 'Purchases', nested: {value: 500}}]
    }]
  },
  options: {
    parsing: {
      xAxisKey: 'id', 
      yAxisKey: 'nested.value' // 如果键中包含点，则需要使用双斜杠进行转义 data\\.key
    }
  }
}

• 当使用饼图/圆环图、雷达或 polarArea 图表类型时，parsing 对象应该有一个指向要查看的值的 key 项

const cfg = {
  type: 'doughnut',
  data: {
    datasets: [{
      data: [{id: 'Sales', nested: {value: 1500}}, {id: 'Purchases', nested: {value: 500}}]
    }]
  },
  options: {
    parsing: {
      key: 'nested.value'
    }
  }
}

• 使用 typescript 时，如果要使用不是默认数据结构的数据结构，则需要在实例化数据变量时将其传递给类型接口

import {ChartData} from 'chart.js';

const datasets: ChartData <'bar', {key: string, value: number} []> = {
  datasets: [{
    data: [{key: 'Sales', value: 20}, {key: 'Revenue', value: 10}],
    parsing: {
      xAxisKey: 'key',
      yAxisKey: 'value'
    }
  }],
};

• data是对象不是数组
• 在此模式下，属性名称用于 index 比例，值用于 value 比例。对于垂直图表，索引刻度为 x，值刻度为 y

const cfg = {
  type: 'line',
  data: {
    datasets: [{
      data: {
        January: 10,
        February: 20
      }
    }]
  }
}

数据集配置

• label 出现在图例和工具提示中的数据集标签。
• data 该数据集的数据
• clip 如何相对于 chartArea 进行裁剪。正值允许溢出，负值会限制 chartArea 内的许多像素。0 = 在图表区域剪辑。裁剪也可以每边配置：clip:
• order 数据集的绘制顺序。还会影响堆叠、工具提示和图例的顺序。
• stack 此数据集所属组的 ID（堆叠时，每个组将是一个单独的堆栈）。默认为数据集 type。
• parsing 如何解析数据集。可以通过指定解析来禁用解析：在图表选项或数据集处为 false。如果禁用解析，则必须对数据进行排序，并采用相关图表类型和比例在内部使用的格式。
• hidden 配置数据集的可见性。使用 hidden: true 将隐藏数据集，使其不在图表中渲染。

字体

• 全局设置可以更改图表上的所有字体。这些选项在 Chart.defaults.font 中
  • family 所有文本的默认字体系列，遵循 CSS 字体系列选项
    • 如果字体未缓存且需要加载，则在加载字体后需要更新使用该字体的图表。这可以使用 字体加载 API 来完成
  • size 文本的默认字体大小（以像素为单位）。不适用于 radialLinear 刻度点标签。
  • style 默认字体样式。不适用于工具提示标题或页脚。不适用于图表标题。遵循 CSS 字体样式选项（即正常、斜体、倾斜、初始、继承）。
  • weight 默认字体粗细（粗体）
  • lineHeight 单个文本行的高度
• 在此图表中，除图例中的标签外，文本的字体大小为 16px

Chart.defaults.font.size = 16;
let chart = new Chart(ctx, {
    type: 'line',
    data: data,
    options: {
        plugins: {
            legend: {
                labels: {
                    // This more specific font property overrides the global property
                    font: {
                        size: 14
                    }
                }
            }
        }
    }
});