chart.js 中文文档 翻译

摘要：高亮最近的元素高亮同样值的数据高亮所有的数据原色，当鼠标悬浮到块是值被选中。关键字代表的是从构造函数创建的对象。高亮最近的数据悬浮时动画执行的时间，单位，毫秒调用被触发的任何事件动画设置以下动画设置都可生效，全局设置在中定义。

tags: chart 文档 翻译

[TOC]

github上获得最新版本 dowload

只是使用cdn cdn

npm

npm install chart.js --save

click here to get info

Chart.js提供了两种不同的构建：Chart.js抑或Chart.min.js，都附带颜色解析库。如果使用了该版本，并且要使用时间轴，那么你需要先引入Moment.js

Chart.bundle.js 或者 Chart.bundle.min.js把Moment.js包含在了一个文件中。如果你需要时间轴并且希望二者在一个文件中，这是个好选择。

！如果你之前的版本中使用了Monment.js，那么就不要使用Chart.bundle.js版本了，因为可能造成未知问题

使用方法

使用老的样式引入Chart.js

使用牛X的方式引入模块

// Using CommonJS
var Chart = require("src/chart.js")
var myChart = new Chart({...})

// ES6
import Chart from "src/chart.js"
let myChart = new Chart({...})

// Using requirejs
require(["path/to/Chartjs"], function(Chart){
 var myChart = new Chart({...})
})

创建一个图表

创建图表我们需要实现图表类Chart class，要做到这些，我们需要传进一个节点，jquery实例，或者canvas都可以让我们在想要的地方绘制。例子如下

// 以下任何形式之一
var ctx = document.getElementById("myChart");
var ctx = document.getElementById("myChart").getContext("2d");
var ctx = $("#myChart");

一旦你创建了元素或者上下文context，你就可以去实现预定义的图标类型，或者自己定义。
下面是一个条状图标，显示的内容是对不同颜色的投票，y轴是从零开始。

不难吧，至此，你可以开始编写自己的图表了，可以是自定义缩放、工具提示、标签、颜色、动作等。

Global Configuration全局设置

Chart.js 提供了一些选项来改变创建的图表的外表。这设置选项可以在创建图表时以设置对象的形式传入到工厂函数中。
此外，全局的设置能够影响到每一个新创建的图表。

Chart Data 图表数据。

显示数据，必须传入一个所需要显示的信息的给图表(chart),这个信息是data object --data 对象，它包含以下信息。

Name	Type	Description
datasets	Array[object]	包含每组的数据
labels	Array[string]	可选的参数，用来显示每个轴的类别
xLabels	Array[string]	可选参数，如果该轴是横轴适用于轴的种类
yLavels	Array[string]	可选参数，如果该轴是纵轴，使用于轴的种类

创建一个带有选项的图表

往Chartjs的构造函数中传入设置对象。
在下面的例子中，创建一个线性图表，并且自适应responsive为false。

var chartInstanc = new Chart(ctx, {
    type:"line",
    data:data,
    options:{
        responsive:false
    }
});

全局设置 Global Configuration

这个概念是在chart1.0版时引入，用来是保持DRY(不过多重复代码)，允许为不同类型图表设置全局选项，避免挨个设置每个图表，或者去更改默认设置。

chart.js可以在不改变图表类型和缩放适应性的情况下通过传递全局设置来统一改变他们的设置。因此，你既可以随意设置自定义的图表，又可以改变默认的设置。全局选项设置定义在Chart.defaults.global中，每个类型的图表的默认设置已经在文档中进行了论述。

下面的例子将设置hover mode为"sigle"，它作用于所有类型的图表。如果图表被默认的设置覆盖，或者在创建图表时自定义了这个属性，则不起作用。

Chart.defaults.global.hover.mode = "single";

// 这个图表将拥有上述的"single"设置，因为他没有自定义这个模式
var chartInstanceHoverModeSingle = new Chart(ctx, {
    type: "line",
    data: data,
});

// 这个图表的hover mode会是自己定义的label，因为single被覆盖了
var chartInstanceDifferentHoverMode = new Chart(ctx, {
    type: "line",
    data: data,
    options: {
        hover: {
            // Overrides the global setting
            mode: "label"
        }
    }
})

全局字体设置

有四个全局属性可被设置，他们定义在Chart.default.global中。

Name	Type	Default	Description
defaultFontColor	Color	"#666 "	默认全局字体颜色
defaultFontFamily	String	"Helvetica Neue", "Helvetica", "Arial", sans-serif"	默认所有字体
defaultFontSize	Number	12	默认字体大小（在现行缩放的labe两种无效 )

Common Chart Configuration 通用图标设置

下面的设置对所有的图表都是用，他们可以设置在 global configuration,或者在自己的图表中传递

Name	Type	Default	Description
responsive	Boolen	true	当容易改变大小时，自适应图表大小
responsiveAnimationDuration	Number	0	当resize事件触发时，动画执行的时间，单位毫秒
maintaionAspectRatio	Boolean	true	改变大小时，图表是否保持比例
events	Array[String]	["mouseover", "mouseout", "click", "touchstart", "touchemove", "touchend"]	hovering 和 工具提示应监听的事件
onClick	Function	null	在图标中点击触发或激活一些元素，函数的参数是元素数组
legendCallback	Function	function(char){}	生成一个legend表单，参数是chart对象，默认返回html文本
onResize	Function	null	当resize触发时调用，得到两个参数，图表实例和大小

Title Configuration 标题设置

标题设置是在options.title中设置的，全局设置是在Chart.defaults.global.title中定义。

Name	Type	Default	Description
display	Boolean	false	Display the titel block
position	String	"top"	设置位置，非全局只允许使用"top"/"bottom"
fullWdith	Boolean	true	设置宽度为canvas的宽度（其他盒子自动下沉不重叠）
fontSize	Number	12	继承全局字体大小
fontFamily	String	""Helvetica Neue", "Helvetica", "Arial", sans-serif"	继承全局字体设置
fontColor	Color	"#666"	继承全局字体颜色
fontStyle	String	"bold"	设置标题样式
padding	Number	10	上下内边距
text	String	""	标题内容文本

实例

下面例子创建了一个带有名为“Custom Chart Title”标题的图表。

var chartInstance = new Chart(ctx, {
    type: "line",
    data: data,
    options: {
        title: {
            display: true,
            text: "Custom Chart Title"
        }
    }
})

Legend Configuration 说明设置

在options.legend中设置legend，全局设置在Chart.defaults.global.legend定义

Name	Type	Default	Description
display	Boolean	true	Is the legend displayed
position	String	"top"	设置位置，非全局只允许使用"top"/"bottom"
fullWidth	Boolean	true	设置宽度为canvas的宽度（其他盒子自动下沉不重叠）
onClick	Function	function(event, legendItem){}	回调函数，注册在顶部标签上
labels	Object	-	查看Legend Label Configuration 说明（下）

Legend Label Configuration Legend标签设置

被设置在Legend的labels键中

Name	Type	Default	Description
boxWidth	Number	40	着色盒子的宽度
fontSize	Number	12	继承全局字体大小
fontFamily	String	""Helvetica Neue", "Helvetica", "Arial", sans-serif"	继承全局字体设置
fontColor	Color	"#666"	继承全局字体颜色
fontStyle	String	"bold"	设置标题样式
padding	Number	10	上下内边距
generateLabels:	Function	function(chart){}	生成legend的所有东西，默认执行返回文字加着色盒子，更多查看Legend Item
usePointStyle	Boolean	false	是否匹配相应的点样式

Legend item Interface Legend界面

该项被传递到legend 的onClick的回调函数中，从labels.generateLabels中返回，这项中必须实现下面的接口

{
    // Label that will be displayed
    text: String,

    // Fill style of the legend box
    fillStyle: Color,

    // If true, this item represents a hidden dataset. Label will be rendered with a strike-through effect
    hidden: Boolean,

    // For box border. See https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap
    lineCap: String,

    // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
    lineDash: Array[Number],

    // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
    lineDashOffset: Number,

    // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin
    lineJoin: String,

    // Width of box border
    lineWidth: Number,

    // Stroke style of the legend box
    strokeStyle: Color

    // Point style of the legend box (only used if usePointStyle is true)
    pointStyle: String
}

实例

下面例子将创建一个带有legend的图表，并且文字颜色为红色。

var chartInstance = new Chart(ctx, {
    type: "bar",
    data: data,
    options: {
        legend: {
            display: true,
            labels: {
                fontColor: "rgb(255, 99, 132)"
            }
        }
    }
});

Tooltips Configuration 提示工具设置

提示工具在options.tooltips中设置，全局在Chart.defaults.global.tooptips中设置

Name	Type	Default	Description
enable	Boolear	true	提示工具是否生效
custom	Function	null	查看section（下面）
mode	String	"single"	设置那种元素在tooltips，选择的设置有‘single’，‘label’，‘x-axis’。single：高亮最近的元素 label：高亮同样值的数据 x-axis：高亮所有的数据原色，当鼠标悬浮到块是x值被选中。
itemSort	Function	undefined	允许对tooltip项进行排序，但是执行传递到Array.prototype.sort中的函数
backgroundColor	Color	"rgba(0,0,0,0.8)"	背景颜色
titleFontFamily	String	""Helvetica Neue", "Helvetica", "Arial", sans-serif"	继承全局字体
titleFontSize	Number	12	继承全局字体大小
titleFontStyle	String	"bold"
titleFontColor	Color	"#fff"	字体颜色
titleSpacing	Number	2	行间距
titleMarginBottom	Number	6	标题底边距
bodyFontFamily	String	""Helvetica Neue", "Helvetica", "Arial", sans-serif"	继承全局字体
bodyFontSize	Number	12	字体大小
bodyFontStyle	String	"bold"
bodyFontColor	Color	"#fff"	字体颜色
bodySpacing	Number	2	行间距
footerFontFamily	String	""Helvetica Neue", "Helvetica", "Arial", sans-serif"	字体
footerFontSize	Number	12	字体大小
footerFontStyle	String	"bold"
footerFontColor	Color	"#fff"	字体颜色
footerSpacing	Number	2	行间距
footerMarginTop	Number	6	footer之间的间距
xPadding	Number	6	tooltip左右边距
yPadding	Number	6	tooltip上下边距
createSize	Number	5	tooltip箭头大小，像素单位
cornerRadius	Number	6	拐角比率
muliKeyBackground	Color	"#fff"	Color to draw behind the colored boxes when multiple items are in the tooltip
callbacks	Object	Name	查看callback section部分

Tooltip Callback 回调函数

tooltip callback设置项，被嵌套在tooltip configuration设置相中，使用callbacks关键字。tooltip有一下callback来提供文字。‘this’关键字代表的是从Chart.Tooltip构造函数创建的对象。

所有的函数拥有共同的参数，tooltip项、data对象，所有的函数都必须返回文字string或者数组，数组代表的是多行文字。

Callback	Arguments	Description
beforeTitle	Array[tooltipItem], data	渲染标题之前的文字
title	Array[tooltipItem], data	渲染成标题的文字
afterTitle	Array[tooltipItem], data	渲染标题之后的文字
beforeBody	Array[tooltipItem], data	body块之前的文字
beforeLabel	tooltipItem, data	个人标签之前的文字
label	tooltipItem, data	个人定义的标签文字
labelColor	tooltipItem, chartInstace	渲染颜色，有两个参数边框颜色borderColor和背景颜色backgroundColor
afterLabel	tooltipItem, data	个人标签之后的文字
afterBody	Array[tooltipItem], data	body之后的文字
beforeFooter	Array[tooltipItem], data	footer之前的文字
footer	Array[tooltipItem], data	footer文字
afterFooter	Array[tooltipItem], data	footer之后的文字

Tooltip Item Interface tooltip项接口

{
    // X Value of the tooltip as a string
    xLabel: String,

    // Y value of the tooltip as a string
    yLabel: String,

    // Index of the dataset the item comes from
    datasetIndex: Number,

    // Index of this data item in the dataset
    index: Number
}

Hover Configuration hover 设置

hover configuraton在options.hover中设置，全局设置是Chart.defaults.global.hover

Name	Type	Default	Description
mode	String	"single"	设置那种元素在tooltips，选择的设置有‘single’，‘label’，‘x-axis’。single：高亮最近的元素 label：高亮同样值的数据 x-axis：高亮所有的数据原色，当鼠标悬浮到块是x值被选中。 高亮最近的数据
animationDuration	Number	400	悬浮时动画执行的时间，单位，毫秒
onHover	Function	null	调用被触发的任何事件

Animation Configuration动画设置

以下动画设置都可生效，全局设置在Chart.defaults.global.animation中定义。

Name	Type	Default	Description
duration	Number	1000	动画执行时间，单位毫秒
easing	String	"easeOutQuart"	使用埃舍尔函数
onProgress	Function	none	动画的每一步执行的回调函数，传入一个对象参数，该对象包含一个图表实例，以及包含细节的动画对象
onComplete	Function	none	动画结束时调用的回调函数，参数与onProgress相同

Animation Callbacks 动画回调函数

图标动画的onProgress 和 onComplete回调函数在同步一个额外的绘制时是很有用的。他们的参数对象事先下面的接口。这些会掉函数的使用例子可以在这里找到.这个例子显示一个程序条，显示动画执行时间。

{
    // Chart object
    chartInstance,

    // Contains details of the on-going animation
    animationObject,
}

Animation Object动画对象

动画对象是Chart.Animation的一个类型实例，它包括下面的属性

{
    // Current Animation frame number
    currentStep: Number,

    // Number of animation frames
    numSteps: Number,

    // Animation easing to use
    easing: String,

    // Function that renders the chart
    render: Function,

    // User callback
    onAnimationProgress: Function,

    // User callback
    onAnimationComplete: Function
}

Element Configuration 元素设置

它在Chart.defaults.global.elements中定义全局设置

Options可以设置四中不同的元素类型：arc弧,lines线性,points点,ande rectangles矩形.一旦设置，该类型中的对象都将执行，除非在dataset中设置覆盖。

Arc Configuration

Arcs 被用在极地、环、饼状图标中。下面是他们的设置。全局arc设置保存在Chart.default.global.elements.arc

Name	Type	Default	Description
backgroundColor	Color	"rgba(0,0,0,0.1)"	默认的填充颜色
borderColor	Color	"#fff"	默认线条颜色
borderWidth	Number	2	默认线条宽度

Line Configuration 线性设置

线性元素用来描绘线性图表，其全局选项存储在Chart.defaults.global.elements.line中

Name	Type	Default	Description
tension	Number	0.4	默认贝塞尔曲线张力设置，设置为0时，没有曲线张力
backgroundColor	Color	"rgba(0,0,0,0.1)"	默认填充颜色
borderWidth	Number	3	线的宽度
borderColor	Color	"rgba(0,0,0,0.1)"	默认线的颜色
borderCapStyle	String	"butt"	默认线的一端的样式
borderDash	Array	[]	默认线条波折线样式
borderDashOffset	Number	0.0	默认波折线间距
borderJoinStyle	String	"miter"	默认线波折连接样式
capBezierPoints	Boolean	true	如果值为true则控制图表内部点，为false则不控制
fill	Boolean	true	如果是true则为线填充颜色
stepped	Boolean	false	如果是true则线的样式是折线，张力会无效

Point Configuration点型设置

点型元素用来设置线性或者泡泡型图表，它的全局选项存储在Chart.default.global.elements.point中。

Name	Type	Default	Description
radius	Number	3	默认半径
pointStyle	String	"circle"	默认样式
backgroundColor	Color	"rgba(0,0,0,0.1)"	默认填充颜色
borderWidth	Number	1	默认边的宽度
borderColor	Color	"rgba(0,0,0,0.1)"	默认边的颜色
hitRadius	Number	1	鼠标悬浮时额外增加的半径
hoverRadius	Number	4	鼠标放上去是的默认半径
hoverBorderWidth	Number	1	鼠标放上去时默认线宽

Rectangle Configuration矩形设置

矩形元素用来绘制条状图表，全局属性设置存储在Chart.defaults.global.element.rectangle中

Name	Type	Default	Description
backgroundColor	Color	"rgba(0,0,0,0.1)"	默认条颜色
borderWidth	Number	0	默认条的线宽
borderColor	Color	"rgba(0,0,0,0.1)"	默认条的线的颜色
borderSkipped	String	"bottom"	默认的跳跃边界

Color颜色

当给图表的选项设置颜色时，可以使用几种颜色格式。一、16进制文字; 二、RGB； 三、HSL符号。如果需要颜色但是又没有去自定义，图表就回去使用默认颜色。默认颜色存储在Chart.defaults.global.defaultColor.它的初始值是"rgb(0,0,0,0.1)"。

你也可以传递一个CanvasGradient对象，传递之前需先创建。

最后的设置项是传递一个CanvasPattern对象。例如，如果你想要填充数据到一个图片上，如下！

var img = new Image();
img.src = "https://example.com/my_image.png";
img.onload = function() {
    var ctx = document.getElementById("canvas").getContext("2d");
    var fillPattern = ctx.createPattern(img, "repeat");

    var chart = new Chart(ctx, {
        data: {
            labels: ["Item 1", "Item 2", "Item 3"],
            datasets: [{
                data: [10, 20, 30],
                backgroundColor: fillPattern
            }]
        }
    })
}