echarts 3.6.1 → 3.7.2

package/src/util/graphic.js

@@ -16,6 +16,8 @@ define(function(require) {
     var mathMax = Math.max;
     var mathMin = Math.min;
 
+    var EMPTY_OBJ = {};
+
     var graphic = {};
 
     graphic.Group = require('zrender/container/Group');
@@ -135,7 +137,6 @@ define(function(require) {
      * @return {Object} Modified param
      */
     graphic.subPixelOptimizeLine = function (param) {
-        var subPixelOptimize = graphic.subPixelOptimize;
         var shape = param.shape;
         var lineWidth = param.style.lineWidth;
 
@@ -162,7 +163,6 @@ define(function(require) {
      * @return {Object} Modified param
      */
     graphic.subPixelOptimizeRect = function (param) {
-        var subPixelOptimize = graphic.subPixelOptimize;
         var shape = param.shape;
         var lineWidth = param.style.lineWidth;
         var originX = shape.x;
@@ -190,7 +190,7 @@ define(function(require) {
      * @param {boolean=} positiveOrNegative Default false (negative).
      * @return {number} Optimized position.
      */
-    graphic.subPixelOptimize = function (position, lineWidth, positiveOrNegative) {
+    var subPixelOptimize = graphic.subPixelOptimize = function (position, lineWidth, positiveOrNegative) {
         // Assure that (position + lineWidth / 2) is near integer edge,
         // otherwise line will be fuzzy in canvas.
         var doubledPosition = round(position * 2);
@@ -224,7 +224,8 @@ define(function(require) {
 
             var normalStyle = {};
             for (var name in hoverStyle) {
-                if (hoverStyle.hasOwnProperty(name)) {
+                // See comment in `doSingleEnterHover`.
+                if (hoverStyle[name] != null) {
                     normalStyle[name] = el.style[name];
                 }
             }
@@ -249,7 +250,46 @@ define(function(require) {
             el.__zr && el.__zr.addHover(el, el.__hoverStl);
         }
         else {
-            el.setStyle(el.__hoverStl);
+            var style = el.style;
+            var insideRollbackOpt = style.insideRollbackOpt;
+
+            // Consider case: only `position: 'top'` is set on emphasis, then text
+            // color should be returned to `autoColor`, rather than remain '#fff'.
+            // So we should rollback then apply again after style merging.
+            insideRollbackOpt && rollbackInsideStyle(style);
+
+            // styles can be:
+            // {
+            //     label: {
+            //         normal: {
+            //             show: false,
+            //             position: 'outside',
+            //             fontSize: 18
+            //         },
+            //         emphasis: {
+            //             show: true
+            //         }
+            //     }
+            // },
+            // where properties of `emphasis` may not appear in `normal`. We previously use
+            // module:echarts/util/model#defaultEmphasis to merge `normal` to `emphasis`.
+            // But consider rich text and setOption in merge mode, it is impossible to cover
+            // all properties in merge. So we use merge mode when setting style here, where
+            // only properties that is not `null/undefined` can be set. The disadventage:
+            // null/undefined can not be used to remove style any more in `emphasis`.
+            style.extendFrom(el.__hoverStl);
+
+            // Do not save `insideRollback`.
+            if (insideRollbackOpt) {
+                applyInsideStyle(style, style.insideOriginalTextPosition, insideRollbackOpt);
+
+                // textFill may be rollbacked to null.
+                if (style.textFill == null) {
+                    style.textFill = insideRollbackOpt.autoColor;
+                }
+            }
+
+            el.dirty(false);
             el.z2 += 1;
         }
 
@@ -269,6 +309,8 @@ define(function(require) {
             el.__zr && el.__zr.removeHover(el);
         }
         else {
+            // Consider null/undefined value, should use
+            // `setStyle` but not `extendFrom(stl, true)`.
             normalStl && el.setStyle(normalStl);
             el.z2 -= 1;
         }
@@ -391,27 +433,346 @@ define(function(require) {
     };
 
     /**
-     * Set text option in the style
+     * @param {Object|module:zrender/graphic/Style} normalStyle
+     * @param {Object} emphasisStyle
+     * @param {module:echarts/model/Model} normalModel
+     * @param {module:echarts/model/Model} emphasisModel
+     * @param {Object} opt Check `opt` of `setTextStyleCommon` to find other props.
+     * @param {Object} [opt.defaultText]
+     * @param {module:echarts/model/Model} [opt.labelFetcher] Fetch text by
+     *      `opt.labelFetcher.getFormattedLabel(opt.labelDataIndex, 'normal'/'emphasis', null, opt.labelDimIndex)`
+     * @param {module:echarts/model/Model} [opt.labelDataIndex] Fetch text by
+     *      `opt.textFetcher.getFormattedLabel(opt.labelDataIndex, 'normal'/'emphasis', null, opt.labelDimIndex)`
+     * @param {module:echarts/model/Model} [opt.labelDimIndex] Fetch text by
+     *      `opt.textFetcher.getFormattedLabel(opt.labelDataIndex, 'normal'/'emphasis', null, opt.labelDimIndex)`
+     * @param {Object} [normalSpecified]
+     * @param {Object} [emphasisSpecified]
+     */
+    graphic.setLabelStyle = function (
+        normalStyle, emphasisStyle,
+        normalModel, emphasisModel,
+        opt,
+        normalSpecified, emphasisSpecified
+    ) {
+        opt = opt || EMPTY_OBJ;
+        var labelFetcher = opt.labelFetcher;
+        var labelDataIndex = opt.labelDataIndex;
+        var labelDimIndex = opt.labelDimIndex;
+
+        // This scenario, `label.normal.show = true; label.emphasis.show = false`,
+        // is not supported util someone requests.
+
+        var showNormal = normalModel.getShallow('show');
+        var showEmphasis = emphasisModel.getShallow('show');
+
+        // Consider performance, only fetch label when necessary.
+        // If `normal.show` is `false` and `emphasis.show` is `true` and `emphasis.formatter` is not set,
+        // label should be displayed, where text is fetched by `normal.formatter` or `opt.defaultText`.
+        var baseText = (showNormal || showEmphasis)
+            ? zrUtil.retrieve2(
+                labelFetcher
+                    ? labelFetcher.getFormattedLabel(labelDataIndex, 'normal', null, labelDimIndex)
+                    : null,
+                opt.defaultText
+            )
+            : null;
+        var normalStyleText = showNormal ? baseText : null;
+        var emphasisStyleText = showEmphasis
+            ? zrUtil.retrieve2(
+                labelFetcher
+                    ? labelFetcher.getFormattedLabel(labelDataIndex, 'emphasis', null, labelDimIndex)
+                    : null,
+                baseText
+            )
+            : null;
+
+        // Optimize: If style.text is null, text will not be drawn.
+        if (normalStyleText != null || emphasisStyleText != null) {
+            // Always set `textStyle` even if `normalStyle.text` is null, because default
+            // values have to be set on `normalStyle`.
+            // If we set default values on `emphasisStyle`, consider case:
+            // Firstly, `setOption(... label: {normal: {text: null}, emphasis: {show: true}} ...);`
+            // Secondly, `setOption(... label: {noraml: {show: true, text: 'abc', color: 'red'} ...);`
+            // Then the 'red' will not work on emphasis.
+            setTextStyle(normalStyle, normalModel, normalSpecified, opt);
+            setTextStyle(emphasisStyle, emphasisModel, emphasisSpecified, opt, true);
+        }
+
+        normalStyle.text = normalStyleText;
+        emphasisStyle.text = emphasisStyleText;
+    };
+
+    /**
+     * Set basic textStyle properties.
+     * @param {Object|module:zrender/graphic/Style} textStyle
+     * @param {module:echarts/model/Model} model
+     * @param {Object} [specifiedTextStyle] Can be overrided by settings in model.
+     * @param {Object} [opt] See `opt` of `setTextStyleCommon`.
+     * @param {boolean} [isEmphasis]
+     */
+    var setTextStyle = graphic.setTextStyle = function (
+        textStyle, textStyleModel, specifiedTextStyle, opt, isEmphasis
+    ) {
+        setTextStyleCommon(textStyle, textStyleModel, opt, isEmphasis);
+        specifiedTextStyle && zrUtil.extend(textStyle, specifiedTextStyle);
+        textStyle.host && textStyle.host.dirty && textStyle.host.dirty(false);
+
+        return textStyle;
+    };
+
+    /**
+     * Set text option in the style.
+     * @deprecated
      * @param {Object} textStyle
      * @param {module:echarts/model/Model} labelModel
-     * @param {string} color
+     * @param {string|boolean} defaultColor Default text color.
+     *        If set as false, it will be processed as a emphasis style.
      */
-    graphic.setText = function (textStyle, labelModel, color) {
-        var labelPosition = labelModel.getShallow('position') || 'inside';
-        var labelOffset = labelModel.getShallow('offset');
-        var labelColor = labelPosition.indexOf('inside') >= 0 ? 'white' : color;
-        var textStyleModel = labelModel.getModel('textStyle');
-        zrUtil.extend(textStyle, {
-            textDistance: labelModel.getShallow('distance') || 5,
-            textFont: textStyleModel.getFont(),
-            textPosition: labelPosition,
-            textOffset: labelOffset,
-            textFill: textStyleModel.getTextColor() || labelColor
-        });
+    graphic.setText = function (textStyle, labelModel, defaultColor) {
+        var opt = {isRectText: true};
+        var isEmphasis;
+
+        if (defaultColor === false) {
+            isEmphasis = true;
+        }
+        else {
+            // Support setting color as 'auto' to get visual color.
+            opt.autoColor = defaultColor;
+        }
+        setTextStyleCommon(textStyle, labelModel, opt, isEmphasis);
+        textStyle.host && textStyle.host.dirty && textStyle.host.dirty(false);
     };
 
+    /**
+     * {
+     *      disableBox: boolean, Whether diable drawing box of block (outer most).
+     *      isRectText: boolean,
+     *      autoColor: string, specify a color when color is 'auto',
+     *              for textFill, textStroke, textBackgroundColor, and textBorderColor.
+     *              If autoColor specified, it is used as default textFill.
+     *      useInsideStyle:
+     *              `true`: Use inside style (textFill, textStroke, textStrokeWidth)
+     *                  if `textFill` is not specified.
+     *              `false`: Do not use inside style.
+     *              `null/undefined`: use inside style if `isRectText` is true and
+     *                  `textFill` is not specified and textPosition contains `'inside'`.
+     *      forceRich: boolean
+     * }
+     */
+    function setTextStyleCommon(textStyle, textStyleModel, opt, isEmphasis) {
+        // Consider there will be abnormal when merge hover style to normal style if given default value.
+        opt = opt || EMPTY_OBJ;
+
+        if (opt.isRectText) {
+            var textPosition = textStyleModel.getShallow('position')
+                || (isEmphasis ? null : 'inside');
+            // 'outside' is not a valid zr textPostion value, but used
+            // in bar series, and magric type should be considered.
+            textPosition === 'outside' && (textPosition = 'top');
+            textStyle.textPosition = textPosition;
+            textStyle.textOffset = textStyleModel.getShallow('offset');
+            var labelRotate = textStyleModel.getShallow('rotate');
+            labelRotate != null && (labelRotate *= Math.PI / 180);
+            textStyle.textRotation = labelRotate;
+            textStyle.textDistance = zrUtil.retrieve2(
+                textStyleModel.getShallow('distance'), isEmphasis ? null : 5
+            );
+        }
+
+        var ecModel = textStyleModel.ecModel;
+        var globalTextStyle = ecModel && ecModel.option.textStyle;
+
+        // Consider case:
+        // {
+        //     data: [{
+        //         value: 12,
+        //         label: {
+        //             normal: {
+        //                 rich: {
+        //                     // no 'a' here but using parent 'a'.
+        //                 }
+        //             }
+        //         }
+        //     }],
+        //     rich: {
+        //         a: { ... }
+        //     }
+        // }
+        var richItemNames = getRichItemNames(textStyleModel);
+        var richResult;
+        if (richItemNames) {
+            richResult = {};
+            for (var name in richItemNames) {
+                if (richItemNames.hasOwnProperty(name)) {
+                    // Cascade is supported in rich.
+                    var richTextStyle = textStyleModel.getModel(['rich', name]);
+                    // In rich, never `disableBox`.
+                    setTokenTextStyle(richResult[name] = {}, richTextStyle, globalTextStyle, opt, isEmphasis);
+                }
+            }
+        }
+        textStyle.rich = richResult;
+
+        setTokenTextStyle(textStyle, textStyleModel, globalTextStyle, opt, isEmphasis, true);
+
+        if (opt.forceRich && !opt.textStyle) {
+            opt.textStyle = {};
+        }
+
+        return textStyle;
+    }
+
+    // Consider case:
+    // {
+    //     data: [{
+    //         value: 12,
+    //         label: {
+    //             normal: {
+    //                 rich: {
+    //                     // no 'a' here but using parent 'a'.
+    //                 }
+    //             }
+    //         }
+    //     }],
+    //     rich: {
+    //         a: { ... }
+    //     }
+    // }
+    function getRichItemNames(textStyleModel) {
+        // Use object to remove duplicated names.
+        var richItemNameMap;
+        while (textStyleModel && textStyleModel !== textStyleModel.ecModel) {
+            var rich = (textStyleModel.option || EMPTY_OBJ).rich;
+            if (rich) {
+                richItemNameMap = richItemNameMap || {};
+                for (var name in rich) {
+                    if (rich.hasOwnProperty(name)) {
+                        richItemNameMap[name] = 1;
+                    }
+                }
+            }
+            textStyleModel = textStyleModel.parentModel;
+        }
+        return richItemNameMap;
+    }
+
+    function setTokenTextStyle(textStyle, textStyleModel, globalTextStyle, opt, isEmphasis, isBlock) {
+        // In merge mode, default value should not be given.
+        globalTextStyle = !isEmphasis && globalTextStyle || EMPTY_OBJ;
+
+        textStyle.textFill = getAutoColor(textStyleModel.getShallow('color'), opt)
+            || globalTextStyle.color;
+        textStyle.textStroke = getAutoColor(textStyleModel.getShallow('textBorderColor'), opt)
+            || globalTextStyle.textBorderColor;
+        textStyle.textStrokeWidth = zrUtil.retrieve2(
+            textStyleModel.getShallow('textBorderWidth'),
+            globalTextStyle.textBorderWidth
+        );
+
+        if (!isEmphasis) {
+            if (isBlock) {
+                // Always set `insideRollback`, for clearing previous.
+                var originalTextPosition = textStyle.textPosition;
+                textStyle.insideRollback = applyInsideStyle(textStyle, originalTextPosition, opt);
+                // Save original textPosition, because style.textPosition will be repalced by
+                // real location (like [10, 30]) in zrender.
+                textStyle.insideOriginalTextPosition = originalTextPosition;
+                textStyle.insideRollbackOpt = opt;
+            }
+
+            // Set default finally.
+            if (textStyle.textFill == null) {
+                textStyle.textFill = opt.autoColor;
+            }
+        }
+
+        // Do not use `getFont` here, because merge should be supported, where
+        // part of these properties may be changed in emphasis style, and the
+        // others should remain their original value got from normal style.
+        textStyle.fontStyle = textStyleModel.getShallow('fontStyle') || globalTextStyle.fontStyle;
+        textStyle.fontWeight = textStyleModel.getShallow('fontWeight') || globalTextStyle.fontWeight;
+        textStyle.fontSize = textStyleModel.getShallow('fontSize') || globalTextStyle.fontSize;
+        textStyle.fontFamily = textStyleModel.getShallow('fontFamily') || globalTextStyle.fontFamily;
+
+        textStyle.textAlign = textStyleModel.getShallow('align');
+        textStyle.textVerticalAlign = textStyleModel.getShallow('verticalAlign')
+            || textStyleModel.getShallow('baseline');
+
+        textStyle.textLineHeight = textStyleModel.getShallow('lineHeight');
+        textStyle.textWidth = textStyleModel.getShallow('width');
+        textStyle.textHeight = textStyleModel.getShallow('height');
+        textStyle.textTag = textStyleModel.getShallow('tag');
+
+        if (!isBlock || !opt.disableBox) {
+            textStyle.textBackgroundColor = getAutoColor(textStyleModel.getShallow('backgroundColor'), opt);
+            textStyle.textPadding = textStyleModel.getShallow('padding');
+            textStyle.textBorderColor = getAutoColor(textStyleModel.getShallow('borderColor'), opt);
+            textStyle.textBorderWidth = textStyleModel.getShallow('borderWidth');
+            textStyle.textBorderRadius = textStyleModel.getShallow('borderRadius');
+
+            textStyle.textBoxShadowColor = textStyleModel.getShallow('shadowColor');
+            textStyle.textBoxShadowBlur = textStyleModel.getShallow('shadowBlur');
+            textStyle.textBoxShadowOffsetX = textStyleModel.getShallow('shadowOffsetX');
+            textStyle.textBoxShadowOffsetY = textStyleModel.getShallow('shadowOffsetY');
+        }
+
+        textStyle.textShadowColor = textStyleModel.getShallow('textShadowColor')
+            || globalTextStyle.textShadowColor;
+        textStyle.textShadowBlur = textStyleModel.getShallow('textShadowBlur')
+            || globalTextStyle.textShadowBlur;
+        textStyle.textShadowOffsetX = textStyleModel.getShallow('textShadowOffsetX')
+            || globalTextStyle.textShadowOffsetX;
+        textStyle.textShadowOffsetY = textStyleModel.getShallow('textShadowOffsetY')
+            || globalTextStyle.textShadowOffsetY;
+    }
+
+    function getAutoColor(color, opt) {
+        return color !== 'auto' ? color : (opt && opt.autoColor) ? opt.autoColor : null;
+    }
+
+    function applyInsideStyle(textStyle, textPosition, opt) {
+        var useInsideStyle = opt.useInsideStyle;
+        var insideRollback;
+
+        if (textStyle.textFill == null
+            && useInsideStyle !== false
+            && (useInsideStyle === true
+                || (opt.isRectText
+                    && textPosition
+                    // textPosition can be [10, 30]
+                    && typeof textPosition === 'string'
+                    && textPosition.indexOf('inside') >= 0
+                )
+            )
+        ) {
+            insideRollback = {
+                textFill: null,
+                textStroke: textStyle.textStroke,
+                textStrokeWidth: textStyle.textStrokeWidth
+            };
+            textStyle.textFill = '#fff';
+            // Consider text with #fff overflow its container.
+            if (textStyle.textStroke == null) {
+                textStyle.textStroke = opt.autoColor;
+                textStyle.textStrokeWidth == null && (textStyle.textStrokeWidth = 2);
+            }
+        }
+
+        return insideRollback;
+    }
+
+    function rollbackInsideStyle(style) {
+        var insideRollback = style.insideRollback;
+        if (insideRollback) {
+            style.textFill = insideRollback.textFill;
+            style.textStroke = insideRollback.textStroke;
+            style.textStrokeWidth = insideRollback.textStrokeWidth;
+        }
+    }
+
     graphic.getFont = function (opt, ecModel) {
-        var gTextStyleModel = ecModel && ecModel.getModel('textStyle');
+        // ecModel or default text style model.
+        var gTextStyleModel = ecModel || ecModel.getModel('textStyle');
         return [
             // FIXME in node-canvas fontWeight is before fontStyle
             opt.fontStyle || gTextStyleModel && gTextStyleModel.getShallow('fontStyle') || '',
@@ -449,7 +810,7 @@ define(function(require) {
             }
 
             duration > 0
-                ? el.animateTo(props, duration, animationDelay || 0, animationEasing, cb)
+                ? el.animateTo(props, duration, animationDelay || 0, animationEasing, cb, !!cb)
                 : (el.stopAnimation(), el.attr(props), cb && cb());
         }
         else {
@@ -640,5 +1001,35 @@ define(function(require) {
         }
     };
 
+    /**
+     * @param {string} iconStr Support 'image://' or 'path://' or direct svg path.
+     * @param {Object} [opt] Properties of `module:zrender/Element`, except `style`.
+     * @param {Object} [rect] {x, y, width, height}
+     * @return {module:zrender/Element} Icon path or image element.
+     */
+    graphic.createIcon = function (iconStr, opt, rect) {
+        opt = zrUtil.extend({rectHover: true}, opt);
+        var style = opt.style = {strokeNoScale: true};
+        rect = rect || {x: -1, y: -1, width: 2, height: 2};
+
+        if (iconStr) {
+            return iconStr.indexOf('image://') === 0
+                ? (
+                    style.image = iconStr.slice(8),
+                    zrUtil.defaults(style, rect),
+                    new graphic.Image(opt)
+                )
+                : (
+                    graphic.makePath(
+                        iconStr.replace('path://', ''),
+                        opt,
+                        rect,
+                        'center'
+                    )
+                );
+        }
+
+    };
+
     return graphic;
 });

package/src/util/layout.js

@@ -29,6 +29,7 @@ define(function(require) {
     function boxLayout(orient, group, gap, maxWidth, maxHeight) {
         var x = 0;
         var y = 0;
+
         if (maxWidth == null) {
             maxWidth = Infinity;
         }
@@ -36,6 +37,7 @@ define(function(require) {
             maxHeight = Infinity;
         }
         var currentLineMaxSize = 0;
+
         group.eachChild(function (child, idx) {
             var position = child.position;
             var rect = child.getBoundingRect();
@@ -43,10 +45,12 @@ define(function(require) {
             var nextChildRect = nextChild && nextChild.getBoundingRect();
             var nextX;
             var nextY;
+
             if (orient === 'horizontal') {
                 var moveX = rect.width + (nextChildRect ? (-nextChildRect.x + rect.x) : 0);
                 nextX = x + moveX;
                 // Wrap when width exceeds maxWidth or meet a `newline` group
+                // FIXME compare before adding gap?
                 if (nextX > maxWidth || child.newline) {
                     x = 0;
                     nextX = moveX;
@@ -54,6 +58,7 @@ define(function(require) {
                     currentLineMaxSize = rect.height;
                 }
                 else {
+                    // FIXME: consider rect.y is not `0`?
                     currentLineMaxSize = Math.max(currentLineMaxSize, rect.height);
                 }
             }
@@ -124,7 +129,7 @@ define(function(require) {
      * @param {number|string} [positionInfo.y]
      * @param {number|string} [positionInfo.x2]
      * @param {number|string} [positionInfo.y2]
-     * @param {Object} containerRect
+     * @param {Object} containerRect {width, height}
      * @param {string|number} margin
      * @return {Object} {width, height}
      */
@@ -193,20 +198,23 @@ define(function(require) {
             height = containerHeight - bottom - verticalMargin - top;
         }
 
-        // If width and height are not given
-        // 1. Graph should not exceeds the container
-        // 2. Aspect must be keeped
-        // 3. Graph should take the space as more as possible
-        if (isNaN(width) && isNaN(height)) {
-            if (aspect > containerWidth / containerHeight) {
-                width = containerWidth * 0.8;
-            }
-            else {
-                height = containerHeight * 0.8;
+        if (aspect != null) {
+            // If width and height are not given
+            // 1. Graph should not exceeds the container
+            // 2. Aspect must be keeped
+            // 3. Graph should take the space as more as possible
+            // FIXME
+            // Margin is not considered, because there is no case that both
+            // using margin and aspect so far.
+            if (isNaN(width) && isNaN(height)) {
+                if (aspect > containerWidth / containerHeight) {
+                    width = containerWidth * 0.8;
+                }
+                else {
+                    height = containerHeight * 0.8;
+                }
             }
-        }
 
-        if (aspect != null) {
             // Calculate width or height with given aspect
             if (isNaN(width)) {
                 width = aspect * height;
@@ -247,11 +255,11 @@ define(function(require) {
         top = top || 0;
         if (isNaN(width)) {
             // Width may be NaN if only one value is given except width
-            width = containerWidth - left - (right || 0);
+            width = containerWidth - horizontalMargin - left - (right || 0);
         }
         if (isNaN(height)) {
             // Height may be NaN if only one value is given except height
-            height = containerHeight - top - (bottom || 0);
+            height = containerHeight - verticalMargin - top - (bottom || 0);
         }
 
         var rect = new BoundingRect(left + margin[3], top + margin[0], width, height);
@@ -281,6 +289,8 @@ define(function(require) {
      * @param {number|string} [positionInfo.top]
      * @param {number|string} [positionInfo.right]
      * @param {number|string} [positionInfo.bottom]
+     * @param {number|string} [positionInfo.width] Only for opt.boundingModel: 'raw'
+     * @param {number|string} [positionInfo.height] Only for opt.boundingModel: 'raw'
      * @param {Object} containerRect
      * @param {string|number} margin
      * @param {Object} [opt]
@@ -322,6 +332,7 @@ define(function(require) {
             }
         }
 
+        // The real width and height can not be specified but calculated by the given el.
         positionInfo = layout.getLayoutRect(
             zrUtil.defaults(
                 {width: rect.width, height: rect.height},
@@ -372,7 +383,8 @@ define(function(require) {
      * @param {Object} targetOption
      * @param {Object} newOption
      * @param {Object|string} [opt]
-     * @param {boolean|Array.<boolean>} [opt.ignoreSize=false] Some component must has width and height.
+     * @param {boolean|Array.<boolean>} [opt.ignoreSize=false] Used for the components
+     *  that width (or height) should not be calculated by left and right (or top and bottom).
      */
     layout.mergeLayoutParam = function (targetOption, newOption, opt) {
         !zrUtil.isObject(opt) && (opt = {});