chart.js 中文文档 翻译

farmerz

chart.js Configuration文档翻译

tags: chart 文档 翻译

[TOC]

Getting start开始

下载

github上获得最新版本 dowload

只是使用cdn cdn

安装

npm

npm install chart.js --save

bower方法

click here to get info

选择正确的构建

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

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

<h3 style="color: red;">!如果你之前的版本中使用了Monment.js,那么就不要使用Chart.bundle.js版本了,因为可能造成未知问题<h3>

使用方法

使用老的样式引入Chart.js

<script src="Chart.js"></script>
<script>
    var myChart = new Chart({...})
</script>

使用牛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都可以让我们在想要的地方绘制。例子如下

<canvas id="myChart" width="400" height="400"></canvas>


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

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

<canvas id="myChart" width="400" height="400"></canvas>
<script>
var ctx = document.getElementById("myChart");
var myChart = new Chart(ctx, {
    type: 'bar',
    data: {
        labels: ["Red", "Blue", "Yellow", "Green", "Purple", "Orange"],
        datasets: [{
            label: '# of Votes',
            data: [12, 19, 3, 5, 2, 3],
            backgroundColor: [
                'rgba(255, 99, 132, 0.2)',
                'rgba(54, 162, 235, 0.2)',
                'rgba(255, 206, 86, 0.2)',
                'rgba(75, 192, 192, 0.2)',
                'rgba(153, 102, 255, 0.2)',
                'rgba(255, 159, 64, 0.2)'
            ],
            borderColor: [
                'rgba(255,99,132,1)',
                'rgba(54, 162, 235, 1)',
                'rgba(255, 206, 86, 1)',
                'rgba(75, 192, 192, 1)',
                'rgba(153, 102, 255, 1)',
                'rgba(255, 159, 64, 1)'
            ],
            borderWidth: 1
        }]
    },
    options: {
        scales: {
            yAxes: [{
                ticks: {
                    beginAtZero:true
                }
            }]
        }
    }
});
</script>

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

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’。<bar>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’。<bar>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
            }]
        }
    })
}
阅读 15.8k

前端这两年(2016~)
近几年来前端的变化记录

可可西里,可可西里,我只是想去看一看。

1.2k 声望
53 粉丝
0 条评论

可可西里,可可西里,我只是想去看一看。

1.2k 声望
53 粉丝
宣传栏