echarts 4.0.4 → 4.1.0

package/src/coord/Axis.js

@@ -1,27 +1,40 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements.  See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership.  The ASF licenses this file
+* to you under the Apache License, Version 2.0 (the
+* "License"); you may not use this file except in compliance
+* with the License.  You may obtain a copy of the License at
+*
+*   http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing,
+* software distributed under the License is distributed on an
+* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+* KIND, either express or implied.  See the License for the
+* specific language governing permissions and limitations
+* under the License.
+*/
+
+import {each, map} from 'zrender/src/core/util';
+import {linearMap, getPixelPrecision} from '../util/number';
+import {
+    createAxisTicks,
+    createAxisLabels,
+    calculateCategoryInterval
+} from './axisTickLabelBuilder';
+
+var NORMALIZED_EXTENT = [0, 1];
 
-import * as zrUtil from 'zrender/src/core/util';
-import * as numberUtil from '../util/number';
-import * as axisHelper from './axisHelper';
-
-var linearMap = numberUtil.linearMap;
-
-function fixExtentWithBands(extent, nTick) {
-    var size = extent[1] - extent[0];
-    var len = nTick;
-    var margin = size / len / 2;
-    extent[0] += margin;
-    extent[1] -= margin;
-}
-
-var normalizedExtent = [0, 1];
 /**
- * @name module:echarts/coord/CartesianAxis
+ * Base class of Axis.
  * @constructor
  */
 var Axis = function (dim, scale, extent) {
 
     /**
-     * Axis dimension. Such as 'x', 'y', 'z', 'angle', 'radius'
+     * Axis dimension. Such as 'x', 'y', 'z', 'angle', 'radius'.
      * @type {string}
      */
     this.dim = dim;
@@ -48,12 +61,6 @@ var Axis = function (dim, scale, extent) {
      * @type {boolean}
      */
     this.onBand = false;
-
-    /**
-     * @private
-     * @type {number}
-     */
-    this._labelInterval;
 };
 
 Axis.prototype = {
@@ -95,7 +102,7 @@ Axis.prototype = {
      * @return {number}
      */
     getPixelPrecision: function (dataExtent) {
-        return numberUtil.getPixelPrecision(
+        return getPixelPrecision(
             dataExtent || this.scale.getExtent(),
             this._extent
         );
@@ -128,7 +135,7 @@ Axis.prototype = {
             fixExtentWithBands(extent, scale.count());
         }
 
-        return linearMap(data, normalizedExtent, extent, clamp);
+        return linearMap(data, NORMALIZED_EXTENT, extent, clamp);
     },
 
     /**
@@ -146,7 +153,7 @@ Axis.prototype = {
             fixExtentWithBands(extent, scale.count());
         }
 
-        var t = linearMap(coord, extent, normalizedExtent, clamp);
+        var t = linearMap(coord, extent, NORMALIZED_EXTENT, clamp);
 
         return this.scale.scale(t);
     },
@@ -162,57 +169,70 @@ Axis.prototype = {
     },
 
     /**
-     * @return {Array.<number>}
+     * Different from `zrUtil.map(axis.getTicks(), axis.dataToCoord, axis)`,
+     * `axis.getTicksCoords` considers `onBand`, which is used by
+     * `boundaryGap:true` of category axis and splitLine and splitArea.
+     * @param {Object} [opt]
+     * @param {number} [opt.tickModel=axis.model.getModel('axisTick')]
+     * @param {boolean} [opt.clamp] If `true`, the first and the last
+     *        tick must be at the axis end points. Otherwise, clip ticks
+     *        that outside the axis extent.
+     * @return {Array.<Object>} [{
+     *     coord: ...,
+     *     tickValue: ...
+     * }, ...]
      */
-    getTicksCoords: function (alignWithLabel) {
-        if (this.onBand && !alignWithLabel) {
-            var bands = this.getBands();
-            var coords = [];
-            for (var i = 0; i < bands.length; i++) {
-                coords.push(bands[i][0]);
-            }
-            if (bands[i - 1]) {
-                coords.push(bands[i - 1][1]);
-            }
-            return coords;
-        }
-        else {
-            return zrUtil.map(this.scale.getTicks(), this.dataToCoord, this);
-        }
+    getTicksCoords: function (opt) {
+        opt = opt || {};
+
+        var tickModel = opt.tickModel || this.getTickModel();
+
+        var result = createAxisTicks(this, tickModel);
+        var ticks = result.ticks;
+
+        var ticksCoords = map(ticks, function (tickValue) {
+            return {
+                coord: this.dataToCoord(tickValue),
+                tickValue: tickValue
+            };
+        }, this);
+
+        var alignWithLabel = tickModel.get('alignWithLabel');
+        fixOnBandTicksCoords(
+            this, ticksCoords, result.tickCategoryInterval, alignWithLabel, opt.clamp
+        );
+
+        return ticksCoords;
     },
 
     /**
-     * Coords of labels are on the ticks or on the middle of bands
-     * @return {Array.<number>}
+     * @return {Array.<Object>} [{
+     *     formattedLabel: string,
+     *     rawLabel: axis.scale.getLabel(tickValue)
+     *     tickValue: number
+     * }, ...]
      */
-    getLabelsCoords: function () {
-        return zrUtil.map(this.scale.getTicks(), this.dataToCoord, this);
+    getViewLabels: function () {
+        return createAxisLabels(this).labels;
     },
 
     /**
-     * Get bands.
-     *
-     * If axis has labels [1, 2, 3, 4]. Bands on the axis are
-     * |---1---|---2---|---3---|---4---|.
-     *
-     * @return {Array}
+     * @return {module:echarts/coord/model/Model}
      */
-        // FIXME Situation when labels is on ticks
-    getBands: function () {
-        var extent = this.getExtent();
-        var bands = [];
-        var len = this.scale.count();
-        var start = extent[0];
-        var end = extent[1];
-        var span = end - start;
-
-        for (var i = 0; i < len; i++) {
-            bands.push([
-                span * i / len + start,
-                span * (i + 1) / len + start
-            ]);
-        }
-        return bands;
+    getLabelModel: function () {
+        return this.model.getModel('axisLabel');
+    },
+
+    /**
+     * Notice here we only get the default tick model. For splitLine
+     * or splitArea, we should pass the splitLineModel or splitAreaModel
+     * manually when calling `getTicksCoords`.
+     * In GL, this method may be overrided to:
+     * `axisModel.getModel('axisTick', grid3DModel.getModel('axisTick'));`
+     * @return {module:echarts/coord/model/Model}
+     */
+    getTickModel: function () {
+        return this.model.getModel('axisTick');
     },
 
     /**
@@ -245,39 +265,78 @@ Axis.prototype = {
     getRotate: null,
 
     /**
-     * Get interval of the axis label.
-     * To get precise result, at least one of `getRotate` and `isHorizontal`
-     * should be implemented.
-     * @return {number}
+     * Only be called in category axis.
+     * Can be overrided, consider other axes like in 3D.
+     * @return {number} Auto interval for cateogry axis tick and label
      */
-    getLabelInterval: function () {
-        var labelInterval = this._labelInterval;
-        if (!labelInterval) {
-            var axisModel = this.model;
-            var labelModel = axisModel.getModel('axisLabel');
-            labelInterval = labelModel.get('interval');
-
-            if (this.type === 'category'
-                && (labelInterval == null || labelInterval === 'auto')
-            ) {
-                labelInterval = axisHelper.getAxisLabelInterval(
-                    zrUtil.map(this.scale.getTicks(), this.dataToCoord, this),
-                    axisModel.getFormattedLabels(),
-                    labelModel.getFont(),
-                    this.getRotate
-                        ? this.getRotate()
-                        : (this.isHorizontal && !this.isHorizontal())
-                        ? 90
-                        : 0,
-                    labelModel.get('rotate')
-                );
+    calculateCategoryInterval: function () {
+        return calculateCategoryInterval(this);
+    }
+
+};
+
+function fixExtentWithBands(extent, nTick) {
+    var size = extent[1] - extent[0];
+    var len = nTick;
+    var margin = size / len / 2;
+    extent[0] += margin;
+    extent[1] -= margin;
+}
+
+// If axis has labels [1, 2, 3, 4]. Bands on the axis are
+// |---1---|---2---|---3---|---4---|.
+// So the displayed ticks and splitLine/splitArea should between
+// each data item, otherwise cause misleading (e.g., split tow bars
+// of a single data item when there are two bar series).
+// Also consider if tickCategoryInterval > 0 and onBand, ticks and
+// splitLine/spliteArea should layout appropriately corresponding
+// to displayed labels. (So we should not use `getBandWidth` in this
+// case).
+function fixOnBandTicksCoords(axis, ticksCoords, tickCategoryInterval, alignWithLabel, clamp) {
+    var ticksLen = ticksCoords.length;
+
+    if (!axis.onBand || alignWithLabel || !ticksLen) {
+        return;
+    }
+
+    var axisExtent = axis.getExtent();
+    var last;
+    if (ticksLen === 1) {
+        ticksCoords[0].coord = axisExtent[0];
+        last = ticksCoords[1] = {coord: axisExtent[0]};
+    }
+    else {
+        var shift = (ticksCoords[1].coord - ticksCoords[0].coord);
+        each(ticksCoords, function (ticksItem) {
+            ticksItem.coord -= shift / 2;
+            var tickCategoryInterval = tickCategoryInterval || 0;
+            // Avoid split a single data item when odd interval.
+            if (tickCategoryInterval % 2 > 0) {
+                ticksItem.coord -= shift / ((tickCategoryInterval + 1) * 2);
             }
+        });
+        last = {coord: ticksCoords[ticksLen - 1].coord + shift};
+        ticksCoords.push(last);
+    }
 
-            this._labelInterval = labelInterval;
-        }
-        return labelInterval;
+    var inverse = axisExtent[0] > axisExtent[1];
+
+    if (littleThan(ticksCoords[0].coord, axisExtent[0])) {
+        clamp ? (ticksCoords[0].coord = axisExtent[0]) : ticksCoords.shift();
+    }
+    if (clamp && littleThan(axisExtent[0], ticksCoords[0].coord)) {
+        ticksCoords.unshift({coord: axisExtent[0]});
+    }
+    if (littleThan(axisExtent[1], last.coord)) {
+        clamp ? (last.coord = axisExtent[1]) : ticksCoords.pop();
+    }
+    if (clamp && littleThan(last.coord, axisExtent[1])) {
+        ticksCoords.push({coord: axisExtent[1]});
     }
 
-};
+    function littleThan(a, b) {
+        return inverse ? a > b : a < b;
+    }
+}
 
-export default Axis;
+export default Axis;

package/src/coord/View.js

@@ -1,3 +1,22 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements.  See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership.  The ASF licenses this file
+* to you under the Apache License, Version 2.0 (the
+* "License"); you may not use this file except in compliance
+* with the License.  You may obtain a copy of the License at
+*
+*   http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing,
+* software distributed under the License is distributed on an
+* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+* KIND, either express or implied.  See the License for the
+* specific language governing permissions and limitations
+* under the License.
+*/
+
 /**
  * Simple view coordinate system
  * Mapping given x, y to transformd view x, y

package/src/coord/axisDefault.js

@@ -1,30 +1,51 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements.  See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership.  The ASF licenses this file
+* to you under the Apache License, Version 2.0 (the
+* "License"); you may not use this file except in compliance
+* with the License.  You may obtain a copy of the License at
+*
+*   http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing,
+* software distributed under the License is distributed on an
+* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+* KIND, either express or implied.  See the License for the
+* specific language governing permissions and limitations
+* under the License.
+*/
+
 import * as zrUtil from 'zrender/src/core/util';
 
 var defaultOption = {
     show: true,
-    zlevel: 0,                  // 一级层叠
-    z: 0,                       // 二级层叠
-    // 反向坐标轴
+    zlevel: 0,
+    z: 0,
+    // Inverse the axis.
     inverse: false,
 
-    // 坐标轴名字，默认为空
+    // Axis name displayed.
     name: '',
-    // 坐标轴名字位置，支持'start' | 'middle' | 'end'
+    // 'start' | 'middle' | 'end'
     nameLocation: 'end',
-    // 坐标轴名字旋转，degree。
-    nameRotate: null, // Adapt to axis rotate, when nameLocation is 'middle'.
+    // By degree. By defualt auto rotate by nameLocation.
+    nameRotate: null,
     nameTruncate: {
         maxWidth: null,
         ellipsis: '...',
         placeholder: '.'
     },
-    // 坐标轴文字样式，默认取全局样式
+    // Use global text style by default.
     nameTextStyle: {},
-    // 文字与轴线距离
+    // The gap between axisName and axisLine.
     nameGap: 15,
 
-    silent: false, // Default false to support tooltip.
-    triggerEvent: false, // Default false to avoid legacy user event listener fail.
+    // Default `false` to support tooltip.
+    silent: false,
+    // Default `false` to avoid legacy user event listener fail.
+    triggerEvent: false,
 
     tooltip: {
         show: false
@@ -32,64 +53,52 @@ var defaultOption = {
 
     axisPointer: {},
 
-    // 坐标轴线
     axisLine: {
-        // 默认显示，属性show控制显示与否
         show: true,
         onZero: true,
         onZeroAxisIndex: null,
-        // 属性lineStyle控制线条样式
         lineStyle: {
             color: '#333',
             width: 1,
             type: 'solid'
         },
-        // 坐标轴两端的箭头
+        // The arrow at both ends the the axis.
         symbol: ['none', 'none'],
         symbolSize: [10, 15]
     },
-    // 坐标轴小标记
     axisTick: {
-        // 属性show控制显示与否，默认显示
         show: true,
-        // 控制小标记是否在grid里
+        // Whether axisTick is inside the grid or outside the grid.
         inside: false,
-        // 属性length控制线长
+        // The length of axisTick.
         length: 5,
-        // 属性lineStyle控制线条样式
         lineStyle: {
             width: 1
         }
     },
-    // 坐标轴文本标签，详见axis.axisLabel
     axisLabel: {
         show: true,
-        // 控制文本标签是否在grid里
+        // Whether axisLabel is inside the grid or outside the grid.
         inside: false,
         rotate: 0,
-        showMinLabel: null, // true | false | null (auto)
-        showMaxLabel: null, // true | false | null (auto)
+        // true | false | null/undefined (auto)
+        showMinLabel: null,
+        // true | false | null/undefined (auto)
+        showMaxLabel: null,
         margin: 8,
         // formatter: null,
-        // 其余属性默认使用全局文本样式，详见TEXTSTYLE
         fontSize: 12
     },
-    // 分隔线
     splitLine: {
-        // 默认显示，属性show控制显示与否
         show: true,
-        // 属性lineStyle（详见lineStyle）控制线条样式
         lineStyle: {
             color: ['#ccc'],
             width: 1,
             type: 'solid'
         }
     },
-    // 分隔区域
     splitArea: {
-        // 默认不显示，属性show控制显示与否
         show: false,
-        // 属性areaStyle（详见areaStyle）控制区域样式
         areaStyle: {
             color: ['rgba(250,250,250,0.3)','rgba(200,200,200,0.3)']
         }
@@ -99,7 +108,7 @@ var defaultOption = {
 var axisDefault = {};
 
 axisDefault.categoryAxis = zrUtil.merge({
-    // 类目起始和结束两端空白策略
+    // The gap at both ends of the axis. For categoryAxis, boolean.
     boundaryGap: true,
     // Set false to faster category collection.
     // Only usefull in the case like: category is
@@ -115,43 +124,61 @@ axisDefault.categoryAxis = zrUtil.merge({
     splitLine: {
         show: false
     },
-    // 坐标轴小标记
     axisTick: {
         // If tick is align with label when boundaryGap is true
         alignWithLabel: false,
         interval: 'auto'
     },
-    // 坐标轴文本标签，详见axis.axisLabel
     axisLabel: {
         interval: 'auto'
     }
 }, defaultOption);
 
 axisDefault.valueAxis = zrUtil.merge({
-    // 数值起始和结束两端空白策略
+    // The gap at both ends of the axis. For value axis, [GAP, GAP], where
+    // `GAP` can be an absolute pixel number (like `35`), or percent (like `'30%'`)
     boundaryGap: [0, 0],
 
     // TODO
     // min/max: [30, datamin, 60] or [20, datamin] or [datamin, 60]
 
-    // 最小值, 设置成 'dataMin' 则从数据中计算最小值
+    // Min value of the axis. can be:
+    // + a number
+    // + 'dataMin': use the min value in data.
+    // + null/undefined: auto decide min value (consider pretty look and boundaryGap).
     // min: null,
-    // 最大值，设置成 'dataMax' 则从数据中计算最大值
+
+    // Max value of the axis. can be:
+    // + a number
+    // + 'dataMax': use the max value in data.
+    // + null/undefined: auto decide max value (consider pretty look and boundaryGap).
     // max: null,
+
     // Readonly prop, specifies start value of the range when using data zoom.
     // rangeStart: null
+
     // Readonly prop, specifies end value of the range when using data zoom.
     // rangeEnd: null
-    // 脱离0值比例，放大聚焦到最终_min，_max区间
+
+    // Optional value can be:
+    // + `false`: always include value 0.
+    // + `true`: the extent do not consider value 0.
     // scale: false,
-    // 分割段数，默认为5
+
+    // AxisTick and axisLabel and splitLine are caculated based on splitNumber.
     splitNumber: 5
-    // Minimum interval
+
+    // Interval specifies the span of the ticks is mandatorily.
+    // interval: null
+
+    // Specify min interval when auto calculate tick interval.
     // minInterval: null
+
+    // Specify max interval when auto calculate tick interval.
     // maxInterval: null
+
 }, defaultOption);
 
-// FIXME
 axisDefault.timeAxis = zrUtil.defaults({
     scale: true,
     min: 'dataMin',