android开源图表库MPAndroidChart文档翻译（上）

MPAndroidChart 是 Android 系统上一款开源的图表库。目前提供线图和饼图，支持选择、缩放和拖放。

android开源图表库MPAndroidChar的githu地址：

https://github.com/PhilJay/MPAndroidChart

文档地址：https://github.com/PhilJay/MPAndroidChart/wiki

API地址：https://jitpack.io/com/github/PhilJay/MPAndroidChart/v2.2.5/javadoc/

一、入门

1、创建

在Xml文件中定义LineChart, BarChart, ScatterChart, CandleStickChart, PieChart, BubbleChart or RadarChart ,

 <com.github.mikephil.charting.charts.LineChart
        android:id="@+id/chart"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

在Activity或者Fragment中引用

 // in this example, a LineChart is initialized from xml
    LineChart chart = (LineChart) findViewById(R.id.chart);

或者直接创建

// programmatically create a LineChart
    LineChart chart = new LineChart(Context);

    // get a layout defined in xml
    RelativeLayout rl = (RelativeLayout) findViewById(R.id.relativeLayout);
    rl.add(chart); // add the programmatically created chart

2、刷新

invalidate():这个方法能使图表重绘.要使图表更改生效，这个方法是必要的。
notifyDataSetChanged(): 让图表知道它的基础数据发生更改，并执行所有必要的重新计算(offsets, legend, maxima, minima, ...)。 动态添加数据时，这是必须调用的。

3、打印日志

setLogEnabled(boolean enabled): 设置为true会激活log输出。 使用这种log会对性能造成影响, 没有必要用的话关掉它。

4、图表样式

一些样式相关方法，可以直接使用

有关更详尽单独图表类型的样式和设置，请看看具体的图表设置的wiki页面specific chart settings
setBackgroundColor(int color): 设置整个图表视图的背景
setDescription(String desc): 右下角对图表的描述信息
setDescriptionColor(int color): 描述信息的颜色
setDescriptionPosition(float x, float y): 自定义描述信息位置.
setDescriptionTypeface(Typeface t): 自定义描述信息字体
setDescriptionTextSize(float size): 自定义描述信息字体大小, 最小值6f, 最大值16f.
setNoDataTextDescription(String desc): 设置空表的描述信息
setDrawGridBackground(boolean enabled): 是否绘制网格背景
setGridBackgroundColor(int color): 设置网格背景颜色
setDrawBorders(boolean enabled): 是否绘制边线
setBorderColor(int color):边线颜色
setBorderWidth(float width):边线宽度，单位dp
setMaxVisibleValueCount(int count): 设置图表绘制可见标签数量最大值. 仅在setDrawValues() 启用时生效

二、图表的交互

这个库允许你自定义手势与图表视图的交互的回调方法。

1、启用/禁用交互

setTouchEnabled(boolean enabled): 启用图表触摸事件
setDragEnabled(boolean enabled): 启用图表拖拽事件
setScaleEnabled(boolean enabled): 启用图表缩放事件
setScaleXEnabled(boolean enabled): 启用X轴上的缩放
setScaleYEnabled(boolean enabled):启用Y轴上的缩放
setPinchZoom(boolean enabled): XY同时缩放
setDoubleTapToZoomEnabled(boolean enabled): 启用双击缩放
setHighlightPerDragEnabled(boolean enabled): 拖拽超过图标绘制画布时高亮显示
setHighlightPerTapEnabled(boolean enabled): 双击高亮显示

2、图表的减速器

setDragDecelerationEnabled(boolean enabled):抬起之后继续滚动
setDragDecelerationFrictionCoef(float coef): 减速插值，取值范围[0，1)。0表示立停止。值越大速度下降越缓慢

3、高亮方式

highlightValues(Highlight[] highs): 高亮点的集合，如果为空，全部不高亮
highlightValue(int xIndex, int dataSetIndex): x轴上的数据集合高亮。如果为-1，全部不高两
getHighlighted():获取高亮点的集合

高亮显示使用OnChartValueSelectedListener不会生成一个回调。可以通过ChartData或DataSet对象启用和禁用高亮显示。

4、自定义高亮符号

所有的用户输入在内部被默认ChartHighlighter类处理。它可以用下面的方法自定义实现替换默认highligher：
setHighlighter(ChartHighlighter highlighter): 通过继承ChartHighlighter类实现自定义高亮符号。通过setHighlighter设置点击等操作高亮显示的符号

5、选择回调

该库提供了交互后的一些后回调。其中之一是OnChartValueSelectedListener监听器，通过触摸高亮值时回调：

public interface OnChartValueSelectedListener {
    /**
    * Called when a value has been selected inside the chart.
    *
    * @param e The selected Entry.
    * @param dataSetIndex The index in the datasets array of the data object
    * the Entrys DataSet is in.
    * @param h the corresponding highlight object that contains information
    * about the highlighted position
    */
    public void onValueSelected(Entry e, int dataSetIndex, Highlight h);
    /**
    * Called when nothing has been selected or an "un-select" has been made.
    */
    public void onNothingSelected();
}

让你的需要接收回调的类实现接口，将它作为监听器设置给chart

chart.setOnChartValueSelectedListener(this);

6、手势回调

OnChartGestureListener 这个回调可以定制手势操作相关回调

public interface OnChartGestureListener {

    /**
     * Callbacks when a touch-gesture has started on the chart (ACTION_DOWN)
     *
     * @param me
     * @param lastPerformedGesture
     */
    void onChartGestureStart(MotionEvent me, ChartTouchListener.ChartGesture lastPerformedGesture);

    /**
     * Callbacks when a touch-gesture has ended on the chart (ACTION_UP, ACTION_CANCEL)
     *
     * @param me
     * @param lastPerformedGesture
     */
    void onChartGestureEnd(MotionEvent me, ChartTouchListener.ChartGesture lastPerformedGesture);

    /**
     * Callbacks when the chart is longpressed.
     * 
     * @param me
     */
    public void onChartLongPressed(MotionEvent me);

    /**
     * Callbacks when the chart is double-tapped.
     * 
     * @param me
     */
    public void onChartDoubleTapped(MotionEvent me);

    /**
     * Callbacks when the chart is single-tapped.
     * 
     * @param me
     */
    public void onChartSingleTapped(MotionEvent me);

    /**
     * Callbacks then a fling gesture is made on the chart.
     * 
     * @param me1
     * @param me2
     * @param velocityX
     * @param velocityY
     */
    public void onChartFling(MotionEvent me1, MotionEvent me2, float velocityX, float velocityY);

   /**
     * Callbacks when the chart is scaled / zoomed via pinch zoom gesture.
     * 
     * @param me
     * @param scaleX scalefactor on the x-axis
     * @param scaleY scalefactor on the y-axis
     */
    public void onChartScale(MotionEvent me, float scaleX, float scaleY);

   /**
    * Callbacks when the chart is moved / translated via drag gesture.
    *
    * @param me
    * @param dX translation distance on the x-axis
    * @param dY translation distance on the y-axis
    */
    public void onChartTranslate(MotionEvent me, float dX, float dY);
}

三、轴AxisBase 

主要是AxisBase 这个类，他是XAxis 和YAxis的基类。
下面提到的方法可以应用到这两个轴。
轴类允许自定义样式和(可以包含)由以下组件/部件:
标签(在垂直(y轴)或水平(x轴)对齐),其中包含轴描述值
绘制了一个所谓的“axis-line”,在标签旁边直接绘制，与标签平行
LimitLines,允许存在特殊的信息,如边界或限制。

1、控制应该绘制哪些部分（轴）

setEnabled(boolean enabled): 是否启用轴，如果禁用，关于轴的设置所有属性都将被忽略
setDrawLabels(boolean enabled): 是否绘制标签
setDrawAxisLine(boolean enabled): 是否绘制轴线
setDrawGridLines(boolean enabled):是否和网格轴线

2、修改轴的样式

setTextColor(int color): 设置轴标签颜色
setTextSize(float size): 设置轴标签字体大小，单位dp
setTypeface(Typeface tf): 设置轴标签字体
setGridColor(int color): 设置网格颜色
setGridLineWidth(float width):设置网格宽度.
setAxisLineColor(int color): 设置轴线颜色
setAxisLineWidth(float width): 设置轴线宽度
enableGridDashedLine(float lineLength, float spaceLength, float phase): 使网格线在虚线画模式，
lineLength控制线长度 , spaceLength控制线之间空格长度, phase 控制起点

3、LimitLine 类

两轴支持，所谓LimitLines允许显示特殊信息,如边界或限制。LimitLine在水平方向时添加到YAxis,而在垂直方向时添加到XAxis。这是如何从轴添加和删除LimitLines

addLimitLine(LimitLine l): 在轴上添加新的 LimitLine 
removeLimitLine(LimitLine l): 从轴上移除 LimitLine 
还有更多添加/移除可用的方法。
setDrawLimitLinesBehindData(boolean enabled):允许控制LimitLines之间的z轴上的实际的数据顺序。如果设置为true,LimitLines在真实数据后边绘制，,否则在上面。默认false

正如它的名字LimitLine,可以用来为用户提供额外限制的信息。

例如,你的图表可能显示不同哟用户的血压测量结果。为了通知用户超过140毫米汞柱的收缩压被认为是一种健康的风险,你可以添加一个LimitLine 140提供这些信息。

YAxis leftAxis = chart.getAxisLeft();

LimitLine ll = new LimitLine(140f, "Critical Blood Pressure");
ll.setLineColor(Color.RED);
ll.setLineWidth(4f);
ll.setTextColor(Color.BLACK);
ll.setTextSize(12f);
// .. and more styling options

leftAxis.addLimitLine(ll);

四、X轴XAxis

XAxis是AxisBase的子类。
XAxis类(在2.0.0版本包含调用),是所有的数据和信息的容器与水平轴有关。。XAxis显示什么是交给ChartData对象作为一个ArrayList<String> 或者String[]。

XAxis类允许自定义样式和以下部分:

水平对齐标签绘制,其中包含轴描述值,为图表X轴提供的数据对象设置。
在标签旁边与标签平行绘制了一个“axis-line”。
每个在垂直方向坐标轴标签的网格线。

获取实例方法

XAxis xAxis = chart.getXAxis();

1、自定义轴的值

setLabelsToSkip(int count): 设置应该在轴线绘制下一个标签前要跳过标签的数量。这将禁用自动计算轴标签之间的空间的功能，设置跳过由该方法提供的固定数量的标签数。调用resetLabelsToSkip（...）重新启用自动计算
resetLabelsToSkip():禁用标记被跳过的自定义的数目，自动计算轴标签之间的空间
setAvoidFirstLastClipping(boolean enabled):如果设置为true,将避免图表或屏幕的边缘的第一个和最后一个轴中的标签条目被裁剪。
setSpaceBetweenLabels(int characters):设置应该x轴标签之间的被排除在外字符，默认空间：4。
setPosition(XAxisPosition pos): x轴应该出现的位置。顶部底部都出现，顶部，底部，BOTH_SIDED，TOP_INSIDE或BOTTOM_INSIDE之间进行选择。

2、格式化值

setValueFormatter(XAxisValueFormatter formatter)：在绘制之前，动态的设置自定义格式，详细信息

3、代码示例

XAxis xAxis = chart.getXAxis();
xAxis.setPosition(XAxisPosition.BOTTOM);
xAxis.setTextSize(10f);
xAxis.setTextColor(Color.RED);
xAxis.setDrawAxisLine(true);
xAxis.setDrawGridLines(false);
// set a custom value formatter
xAxis.setXValueFormatter(new MyCustomFormatter()); 
// and more...

五、Y轴YAxis

YAxis 是AxisBase的子类。
YAxis 类是与垂直轴相关的所有数据和信息容器，与左边右边垂直的轴相关。RadarChart 只有一个Y轴，默认情况下，图标的两个轴都启用绘制。

1、获取Y轴实例的方法

YAxis leftAxis = chart.getAxisLeft();
YAxis rightAxis = chart.getAxisRight();

YAxis leftAxis = chart.getAxis(AxisDependency.LEFT);

YAxis yAxis = radarChart.getYAxis(); // this method radarchart only

2、自定义轴的值

setAxisMaxValue(float max): 设置轴的最大值。如果设置，此值不会自动根据提供的数据计算。
resetAxisMaxValue():撤销之前设置的最大值，将自动计算最大值。
setAxisMinValue(float min): 设置轴的最小值。这样设置将不会根据提供的数据自动计算。
resetAxisMinValue(): 撤销之前设置的轴最小值，将自动计算最小值
setStartAtZero(boolean enabled): 已经过时- 使用setAxisMinValue(...) 或者setAxisMaxValue(...) 
setInverted(boolean enabled): 反转该轴，如果为true，最大值在底部，顶部是最小值。
setSpaceTop(float percent): 设置轴上最高位置在表中最高位置的顶部间距，占总轴的百分比。
setSpaceBottom(float percent): 设置轴上最低位置在表中最低位置的底部间距，占总轴的百分比。
setShowOnlyMinMax(boolean enabled):如果启用，此轴直线式最大值和最小值架构忽略定义的标签数。
setLabelCount(int count, boolean force): 设置轴的标签数目，不是精确值，如果强制设置，可能导致轴线不均匀
setPosition(YAxisLabelPosition pos): 设置轴线绘制位置. Either INSIDE_CHART or OUTSIDE_CHART.
setGranularity(float gran):设置Y轴最小间隔
setGranularityEnabled(boolean enabled): 是否启用Y轴最小间隔

必须在设置数据之前设置属性才能生效。

3、自定义标签格式

setValueFormatter(YAxisValueFormatterf): 在轴上设置一个自定义ValueFormatter。可以格式化原始标签文本,返回一个定制的文本。更多

4、zeroline

除了网格线，在水平方向Y轴的每个值，有所谓的zeroline，这是在0位置轴线上值绘制的，是类似于网格线，但可以单独配置。

// data has AxisDependency.LEFT
YAxis left = mChart.getAxisLeft();
left.setDrawLabels(false); // no axis labels
left.setDrawAxisLine(false); // no axis line
left.setDrawGridLines(false); // no grid lines
left.setDrawZeroLine(true); // draw a zero line
mChart.getAxisRight().setEnabled(false); // no right axis

6、更多实例代码

YAxis yAxis = mChart.getAxisLeft();
yAxis.setTypeface(...); // set a different font
yAxis.setTextSize(12f); // set the textsize
yAxis.setAxisMaxValue(100f); // the axis maximum is 100
yAxis.setTextColor(Color.BLACK);
yAxis.setValueFormatter(new MyValueFormatter());
yAxis.setLabelCount(6, true); // force 6 labels
//... and more

欢迎扫描二维码，关注公众账号