{{ target: series-pictorialBar }}

series.pictoialBar(Object)

象形柱图

象形柱图是可以设置各种具象图形元素（如图片、SVG PathData 等）的柱状图。往往用在信息图中。用于有至少一个类目轴或时间轴的直角坐标系上。

示例： ~800x400

布局

象形柱图可以被想象为：它首先是个柱状图，但是柱状图的柱子并不显示。这些柱子我们称为『基准柱（reference bar）』，根据基准柱来定位和显示各种象形图形（包括图片）。

每个象形图形根据基准柱的定位，是通过 symbolPosition、symbolOffset 来调整其于基准柱的相对位置。

参见例子： ~800x600

可以使用 symbolSize 调整大小，从而形成各种视图效果。

参见例子： ~800x600

象形图形类型

每个图形可以配置成『单独』和『重复』两种类型，即通过 symbolRepeat 来设置。

  • 设置为 false（默认），则一个图形来代表一个数据项。
  • 设置为 true，则一组重复的图形来代表一个数据项。

参见例子： ~800x400

每个象形图形可以是基本图形（如 'circle', 'rect', ...）、SVG PathData、图片，参见：symbolType。

参见例子： ~800x400

可以使用 symbolClip 对图形进行剪裁。

参见例子： ~800x600

var maxData = 2000;

option = { tooltip: { }, xAxis: { max: maxData, splitLine: {show: false}, offset: 10, axisLine: { lineStyle: { color: ‘#999’ } }, axisLabel: { margin: 10 } }, yAxis: { data: [‘2013’, ‘2014’, ‘2015’, ‘2016’], inverse: true, axisTick: {show: false}, axisLine: {show: false}, axisLabel: { margin: 10, color: ‘#999’, fontSize: 16 } }, grid: { top: ‘center’, height: 200, left: 70, right: 100 }, series: [{ // current data type: ‘pictorialBar’, symbol: spirit, symbolRepeat: ‘fixed’, symbolMargin: ‘5%’, symbolClip: true, symbolSize: 30, symbolBoundingData: maxData, data: [891, 1220, 660, 1670], z: 10 }] };

type(string) = ‘pictorialBar’

{{ use: partial-component-id( prefix = “#” ) }}

{{ use: partial-series-name() }}

{{ use: partial-legend-hover-link() }}

{{ use: partial-coord-sys( seriesType = “pictorialBar”, coordSysDefault = “‘cartesian2d’”, cartesian2d = true, polar = false, geo = false ) }}

{{ use: partial-cursor() }}

label(Object)

{{ use: partial-label-desc() }}

{{ use: partial-label( prefix = “##”, defaultPosition = “‘inside’”, formatter = true ) }}

labelLine(Object)

{{ use: partial-label-line-desc() }}

{{ use: partial-label-line( prefix = ‘##’, length2 = true, minTurnAngle = true, showAbove = true, smooth = true ) }}

labelLayout(Object|Function)

{{ use: partial-label-layout( prefix = “##” ) }}

itemStyle(Object)

{{ use: partial-item-style-desc() }}

{{ use: partial-item-style( prefix = “##”, useColorPalatte = true, hasCallback = false, useDecal = true ) }}

emphasis(Object)

高亮状态配置。

{{ use: partial-focus-blur-scope() }}

{{ use: pictoialBar-state( prefix = “##” ) }}

blur(Object)

{{ use: partial-version( version = “5.0.0” ) }}

淡出状态配置。开启 emphasis.focus 后有效。

{{ use: pictoialBar-state( prefix = “##” ) }}

select(Object)

{{ use: partial-version( version = “5.0.0” ) }}

选中状态配置。开启 selectedMode 后有效。

{{ use: partial-selected-mode( version = ‘5.0.0’ ) }}

{{ use: pictoialBar-state( prefix = “##” ) }}

{{ use: partial-barGrid( seriesType = ‘pictorialBar’, barGapDefault = “-100%” ) }}

{{ use: pictorialBar-symbol-attrs( prefix = “#” ) }}

{{ use: partial-series-dimensions( prefix = “#” ) }}

{{ use: partial-series-encode( prefix = “#” ) }}

{{ use: partial-series-group-id() }}

data(Array)

{{ use: partial-2d-data-desc() }}

name(string)

数据项名称。

value(number)

单个数据项的数值。

{{ use: partial-data-group-id( prefix = ‘##’ ) }}

{{ use: pictorialBar-symbol-attrs( prefix = “##”, useZ2 = true ) }}

label(Object)

单个柱条文本的样式设置。

{{ use: partial-label( prefix = “###”, defaultPosition = “inside” ) }}

labelLine(Object)

{{ use: partial-label-line-desc() }}

{{ use: partial-label-line( prefix = ‘###’, length2 = true, minTurnAngle = true, showAbove = true, smooth = true ) }}

itemStyle(Object)

{{ use: partial-item-style( prefix = “###”, useDecal = true ) }}

emphasis(Object)

单个数据的高亮状态配置。

{{ use: partial-bar-state( prefix = “###” ) }}

blur(Object)

{{ use: partial-version( version = “5.0.0” ) }}

单个数据的淡出状态配置。

{{ use: partial-bar-state( prefix = “###” ) }}

select(Object)

{{ use: partial-version( version = “5.0.0” ) }}

单个数据的选中状态配置。

{{ use: partial-bar-state( prefix = “###” ) }}

{{ use: partial-tooltip-in-series-data() }}

{{ use: partial-marker( prefix = “#”, seriesType = “pictorialBar”, hasCoord = true, hasType = true ) }}

{{ use: partial-z-zlevel( prefix = “#”, componentName = “象形柱图” ) }}

{{ use: partial-silent( prefix = “#” ) }}

{{ use: partial-animation( prefix = “#”, noAnimationDelay = true ) }}

{{ use: partial-universal-transition( prefix = “#” ) }}

{{ use: pictorialBar-animation-delay( prefix = “##” ) }}

{{ use: partial-tooltip-in-series() }}

{{ target: pictorialBar-symbol-attrs }}

#${prefix} symbol(string) = ‘circle’

图形类型。

{{ use: partial-icon() }}

例子： ~800x400

{{ use: pictorialBar-symbol-attrs-cascade( attrName = ‘symbol’ ) }}

#${prefix} symbolSize(number|Array) = [‘100%’, ‘100%’]

图形的大小。

可以用数组分开表示宽和高，例如 [20, 10] 表示标记宽为20，高为10，也可以设置成诸如 10 这样单一的数字，表示 [10, 10]。

可以设置成绝对值（如 10），也可以设置成百分比（如 '120%'、['55%', 23]）。

当设置为百分比时，图形的大小是基于 基准柱 的尺寸计算出来的。

例如，当基准柱基于 x 轴（即柱子是纵向的），symbolSize 设置为 ['30%', '50%']，那么最终图形的尺寸是：

  • 宽度：基准柱的宽度 * 30%。
  • 高度：

基准柱基于 y 轴（即柱子是横向的）的情况类似对调可得出。

例子： ~800x600

{{ use: pictorialBar-symbol-attrs-cascade( attrName = ‘symbolSize’ ) }}

#${prefix} symbolPosition(string) = ‘start’

图形的定位位置。可取值：

  • 'start'：图形边缘与柱子开始的地方内切。
  • 'end'：图形边缘与柱子结束的地方内切。
  • 'center'：图形在柱子里居中。

例子： ~800x600

{{ use: pictorialBar-symbol-attrs-cascade( attrName = ‘symbolPosition’ ) }}

#${prefix} symbolOffset(Array) = [0, 0]

图形相对于原本位置的偏移。symbolOffset 是图形定位中最后计算的一个步骤，可以对图形计算出来的位置进行微调。

可以设置成绝对值（如 10），也可以设置成百分比（如 '120%'、['55%', 23]）。

当设置为百分比时，表示相对于自身尺寸 symbolSize 的百分比。

例如 [0, '-50%'] 就是把图形向上移动了自身尺寸的一半的位置。

例子： ~800x600

{{ use: pictorialBar-symbol-attrs-cascade( attrName = ‘symbolOffset’ ) }}

#${prefix} symbolRotate(number)

图形的旋转角度。

注意，symbolRotate 并不会影响图形的定位（哪怕超出基准柱的边界），而只是单纯得绕自身中心旋转。

{{ use: pictorialBar-symbol-attrs-cascade( attrName = ‘symbolRotate’ ) }}

#${prefix} symbolRepeat(boolean|number|string)

指定图形元素是否重复。值可为：

  • false/null/undefined：不重复，即每个数据值用一个图形元素表示。
  • true：使图形元素重复，即每个数据值用一组重复的图形元素表示。重复的次数依据 data 计算得到。
  • a number：使图形元素重复，即每个数据值用一组重复的图形元素表示。重复的次数是给定的定值。
  • 'fixed'：使图形元素重复，即每个数据值用一组重复的图形元素表示。重复的次数依据 symbolBoundingData 计算得到，即与 data 无关。这在此图形被用于做背景时有用。

例子： ~800x400

{{ use: pictorialBar-symbol-attrs-cascade( attrName = ‘symbolRepeat’ ) }}

#${prefix} symbolRepeatDirection(string) = ‘start’

指定图形元素重复时，绘制的顺序。这个属性在两种情况下有用处：

  • 当 symbolMargin 设置为负值时，重复的图形会互相覆盖，这是可以使用 symbolRepeatDirection 来指定覆盖顺序。

  • 当 animationDelay 或 animationDelayUpdate 被使用时，symbolRepeatDirection 指定了 index 顺序。

这个属性的值可以是：'start' 或 'end'。

例子： ~800x400

{{ use: pictorialBar-symbol-attrs-cascade( attrName = ‘symbolRepeatDirection’ ) }}

#${prefix} symbolMargin(number|string)

图形的两边间隔（『两边』是指其数值轴方向的两边）。可以是绝对数值（如 20），或者百分比值（如 '-30%'），表示相对于自身尺寸 symbolSize 的百分比。只有当 symbolRepeat 被使用时有意义。

可以是正值，表示间隔大；也可以是负数。当 symbolRepeat 被使用时，负数时能使图形重叠。

可以在其值结尾处加一个 "!"，如 "30%!" 或 25!，表示第一个图形的开始和最后一个图形结尾留白，不紧贴边界。默认会紧贴边界。

注意：

  • 当 symbolRepeat 为 true/'fixed' 的时候： 这里设置的 symbolMargin 只是个参考值，真正最后的图形间隔，是根据 symbolRepeat、symbolMargin、symbolBoundingData 综合计算得到。
  • 当 symbolRepeat 为一个固定数值的时候： 这里设置的 symbolMargin 无效。

例子： ~800x600

{{ use: pictorialBar-symbol-attrs-cascade( attrName = ‘symbolMargin’ ) }}

#${prefix} symbolClip(boolean) = false

是否剪裁图形。

  • false/null/undefined：图形本身表示数值大小。
  • true：图形被剪裁后剩余的部分表示数值大小。

symbolClip 常在这种场景下使用：同时表达『总值』和『当前数值』。在这种场景下，可以使用两个系列，一个系列是完整的图形，当做『背景』来表达总数值，另一个系列是使用 symbolClip 进行剪裁过的图形，表达当前数值。

例子： ~800x600

在这个例子中：

  • 『背景系列』和『当前值系列』使用相同的 symbolBoundingData，使得绘制出的图形的大小是一样的。
  • 『当前值系列』设置了比『背景系列』更高的 z，使得其覆盖在『背景系列』上。

{{ use: pictorialBar-symbol-attrs-cascade( attrName = ‘symbolClip’ ) }}

#${prefix} symbolBoundingData(number|Array)

这个属性是『指定图形界限的值』。它指定了一个 data，这个 data 映射在坐标系上的位置，是图形绘制的界限。也就是说，如果设置了 symbolBoundingData，图形的尺寸则由 symbolBoundingData 决定。

当柱子是水平的，symbolBoundingData 对应到 x 轴上，当柱子是竖直的，symbolBoundingData 对应到 y 轴上。

规则：

  • 没有使用 symbolRepeat 时：

    symbolBoundingData 缺省情况下和『参考柱』的尺寸一样。图形的尺寸由零点和 symbolBoundingData 决定。举例，当柱子是竖直的，柱子对应的 data 为 24，symbolSize 设置为 [30, '50%']，symbolBoundingData 设置为 124，那么最终图形的高度为 124 * 50% = 62。如果 symbolBoundingData 不设置，那么最终图形的高度为 24 * 50% = 12。

  • 使用了 symbolRepeat 时：

    symbolBoundingData 缺省情况取当前坐标系所显示出的最值。symbolBoundingData 定义了一个 bounding，重复的图形在这个 bounding 中，依据 symbolMargin 和 symbolRepeat 和 symbolSize 进行排布。这几个变量决定了图形的间隔大小。

在这些场景中，你可能会需要设置 symbolBoundingData：

  • 使用了 symbolCilp 时：

    使用一个系列表达『总值』，另一个系列表达『当前值』的时候，需要两个系列画出的图形一样大。那么就把两个系列的 symbolBoundingData 设为一样大。

例子： ~800x600

  • 使用了 symbolRepeat 时：

    如果需要不同柱子中的图形的间隔保持一致，那么可以把 symbolBoundingData 设为一致的数值。当然，不设置 symbolBoundingData 也是可以的，因为其缺省值就是一个定值（坐标系所显示出的最值）。

例子： ~800x600

参见例子： ~800x400

{{ use: pictorialBar-symbol-attrs-cascade( attrName = ‘symbolBoundingData’ ) }}

#${prefix} symbolPatternSize(number) = 400

可以使用图片作为图形的 pattern。

var textureImg = new Image();
textureImg.src = 'data:image/jpeg;base64,...'; // dataURI
// 或者
// textureImg.src = 'http://xxx.xxx.xxx/xx.png'; // URL
...
itemStyle: {
    color: {
        image: textureImg,
        repeat: 'repeat'
    }
}

这时候，symbolPatternSize 指定了 pattern 的缩放尺寸。比如 symbolPatternSize 为 400 时表示图片显示为 400px * 400px 的尺寸。

例子： ~800x400

{{ use: pictorialBar-symbol-attrs-cascade( attrName = ‘symbolPatternSize’ ) }}

{{ if: ${useZ2} }} #${prefix} z(number)

指定图形元素间的覆盖关系。数值越大，越在层叠的上方。 {{ /if }}

#${prefix} hoverAnimation(boolean) = false

是否开启 hover 在图形上的提示动画效果。

{{ use: pictorialBar-symbol-attrs-cascade( attrName = ‘hoverAnimation’ ) }}

{{ use: partial-animation( prefix = “##”, noAnimationDelay = true ) }}

{{ use: pictorialBar-animation-delay( prefix = “##” ) }}

{{ target: pictorialBar-animation-delay }}

#${prefix} animationDelay(number|Function) = 0

动画开始之前的延迟，支持回调函数，可以通过每个数据返回不同的 delay 时间实现更戏剧的更新动画效果。

如下示例：

animationDelay: function (dataIndex, params) {
    return params.index * 30;
}
或者反向：
animationDelay: function (dataIndex, params) {
    return (params.count - 1 - params.index) * 30;
}

例子： ~800x400

#${prefix} animationDelayUpdate(number|Function) = 0

数据更新动画的延迟，支持回调函数，可以通过每个数据返回不同的 delay 时间实现更戏剧的更新动画效果。

如下示例：

animationDelay: function (dataIndex, params) {
    return params.index * 30;
}
或者反向：
animationDelay: function (dataIndex, params) {
    return (params.count - 1 - params.index) * 30;
}

例子： ~800x400

{{ target: pictorialBar-symbol-attrs-cascade }}

此属性可以被设置在系列的 根部，表示对此系列中所有数据都生效；也可以被设置在 data 中的 每个数据项中，表示只对此数据项生效。

例如：

series: [{
    ${attrName}: ... // 对 data 中所有数据项生效。
    data: [23, 56]
}]
或者
series: [{
    data: [{
        value: 23
        ${attrName}: ... // 只对此数据项生效
    }, {
        value: 56
        ${attrName}: ... // 只对此数据项生效
    }]
}]

{{ target: pictoialBar-state }}

#${prefix} label(Object)

{{ use: partial-label( prefix = “#” + ${prefix}, formatter = ${prefix} === ‘##’ ) }}

#${prefix} labelLine(Object)

{{ use: partial-label-line-desc() }}

{{ use: partial-label-line( prefix = “#” + ${prefix} ) }}

#${prefix} itemStyle(Object)

{{ use: partial-item-style( prefix = “#” + ${prefix} ) }}