时间轴组件

ECharts 中时间轴组件包含了可以在多个 ECharts option 间进行切换、播放等操作的功能。ECharts 时间轴组件适用的范围是：非动态数据，坐标轴的数据已经确定好数据才便于展示，当然要实现动态数据也是可行的。那么如何才能快速上手 ECharts 时间轴组件呢？让我们先来看一个示例。

示例效果如下：

timeline 和其他组件有些不同，它需要操作“多个option”。 假设，我们把 ECharts 的传统的 option 称为 “原子 option”，那么使用 timeline 时，传入 ECharts 的 option 就成为了一个集合多个原子 option 的复合option。

如下示例：

// 如下，baseOption 是一个 『原子option』，options 数组中的每一项也是一个 『原子option』。
// 每个『原子option』中就是本文档中描述的各种配置项。
myChart.setOption(
    {
        baseOption: {
            timeline: {
                ...,
                data: ['2002-01-01', '2003-01-01', '2004-01-01']
            },
            title: {
                subtext: '数据来自国家统计局'
            },
            grid: {...},
            xAxis: [...],
            yAxis: [...],
            series: [
                { // 系列一的一些其他配置
                    type: 'bar',
                    ...
                },
                { // 系列二的一些其他配置
                    type: 'line',
                    ...
                },
                { // 系列三的一些其他配置
                    type: 'pie',
                    ...
                }
            ]
        },
        options: [
            { // 这是'2002-01-01' 对应的 option
                title: {
                    text: '2002年统计值'
                },
                series: [
                    {data: []}, // 系列一的数据
                    {data: []}, // 系列二的数据
                    {data: []}  // 系列三的数据
                ]
            },
            { // 这是'2003-01-01' 对应的 option
                title: {
                    text: '2003年统计值'
                },
                series: [
                    {data: []},
                    {data: []},
                    {data: []}
                ]
            },
            { // 这是'2004-01-01' 对应的 option
                title: {
                    text: '2004年统计值'
                },
                series: [
                    {data: []},
                    {data: []},
                    {data: []}
                ]
            }
        ]
    }
);

在上例中，timeline.data 中的每一项，对应于 options 数组中的每个 option。

使用注意与最佳实践：

公有的配置项，推荐配置在 baseOption 中。timeline 播放切换时，会把 options 数组中的对应的 option，与 baseOption 进行 merge 形成最终的 option。

options 数组中，如果某一数组项中配置了某个属性，那么其他数组项中也必须配置某个属性，而不能缺省。否则这个属性的执行效果会遗留。

复合 option 中的 options 不支持 merge。也就是说，当第二（或三、四、五 ...）次 chart.setOption(rawOption) 时，如果 rawOption 是复合 option（即包含 options 列表），那么新的 rawOption.options 列表不会和老的 options 列表进行 merge，而是简单替代。当然，rawOption.baseOption 仍然会正常和老的 option 进行merge。

与 ECharts 2 的兼容性：

ECharts 3 中不再支持 timeline.notMerge 参数，也就是不支持 notMerge 模式。

如果遇到这种场景需要使用，可在外部进行option管理，并用 setOption(option, true) 这样的notMerge方式设置。

ECharts 3 和 ECharts 2 相比，timeline 属性的定义位置有所不同，移到了 baseOption 中，统一作为一个普通的组件看待。但是，仍然兼容 ECharts2 的 timeline 定义位置，只是不再推荐这样写。

timeline.show

boolean [ 默认值 true ]

是否显示时间轴组件。如果设置为 false，不会显示，但是功能还存在。

timeline.type

string [ 默认值 'slider' ]

这个属性目前只支持为 slider，不需要更改。

timeline.axisType

string [ 默认值 'time' ]

轴的类型。可选值为：

• 'value' 数值轴，适用于连续数据。

• 'category' 类目轴，适用于离散的类目数据。

• 'time' 时间轴，适用于连续的时序数据，与数值轴相比时间轴带有时间的格式化，在刻度计算上也有所不同，例如会根据跨度的范围来决定使用月，星期，日还是小时范围的刻度。

timeline.currentIndex

number [ 默认值 0 ]

表示当前选中项是哪项。比如，currentIndex 为 0 时，表示当前选中项为 timeline.data[0]（即使用 options[0]）。

timeline.autoPlay

boolean [ 默认值 false ]

表示是否自动播放。

timeline.rewind

boolean [ 默认值 false ]

表示是否反向播放。

timeline.loop

boolean [ 默认值 true ]

表示是否循环播放。

timeline.playInterval

number [ 默认值 2000 ]

表示播放的速度（跳动的间隔），单位毫秒（ms）。

timeline.realtime

boolean [ 默认值 true ]

拖动圆点的时候，是否实时更新视图。

timeline.controlPosition

string [ 默认值 'left' ]

表示『播放』按钮的位置。可选值：'left'、'right'。

timeline.zlevel

number [ 默认值 0 ]

所有图形的 zlevel 值。

zlevel 用于 Canvas 分层，不同zlevel值的图形会放置在不同的 Canvas 中，Canvas 分层是一种常见的优化手段。我们可以把一些图形变化频繁（例如有动画）的组件设置成一个单独的zlevel。

需要注意的是过多的 Canvas 会引起内存开销的增大，在手机端上需要谨慎使用以防崩溃。 zlevel 大的 Canvas 会放在 zlevel 小的 Canvas 的上面。

timeline.z

number [ 默认值 2 ]

时间轴组件的所有图形的z值。控制图形的前后顺序。z值小的图形会被z值大的图形覆盖。

z 相比 zlevel 优先级更低，而且不会创建新的 Canvas。

timeline.left

string, number [ 默认值 'auto' ]

时间轴组件离容器左侧的距离。

left 的值可以是像 20 这样的具体像素值，可以是像 '20%' 这样相对于容器高宽的百分比，也可以是 'left', 'center', 'right'。

如果 left 的值为'left', 'center', 'right'，组件会根据相应的位置自动对齐。

timeline.top

string, number [ 默认值 'auto' ]

时间轴组件离容器上侧的距离。

top 的值可以是像 20 这样的具体像素值，可以是像 '20%' 这样相对于容器高宽的百分比，也可以是 'top', 'middle', 'bottom'。

如果 top 的值为'top', 'middle', 'bottom'，组件会根据相应的位置自动对齐。

timeline.right

string, number [ 默认值 'auto' ]

时间轴组件离容器右侧的距离。

right 的值可以是像 20 这样的具体像素值，可以是像 '20%' 这样相对于容器高宽的百分比。

默认自适应。

timeline.bottom

string, number [ 默认值 'auto' ]

时间轴组件离容器下侧的距离。

bottom 的值可以是像 20 这样的具体像素值，可以是像 '20%' 这样相对于容器高宽的百分比。

默认自适应。

timeline.padding

number, Array [ 默认值 5 ]

时间轴组件的内边距，单位为 px，默认各方向内边距为 5px，接受数组分别设定上右下左边距。

使用示例：

// 设置内边距为 5
padding: 5
// 设置上下的内边距为 5，左右的内边距为 10
padding: [5, 10]
// 分别设置四个方向的内边距
padding: [
    5,  // 上
    10, // 右
    5,  // 下
    10, // 左
]

timeline.orient

string [ 默认值 'horizontal' ]

摆放方式，可选值有：

timeline.inverse

boolean [ 默认值 false ]

是否反向放置 timeline，反向则首位颠倒过来。

timeline.symbol

string [ 默认值 'emptyCircle' ]

timeline 标记的图形。

ECharts 提供的标记类型包括 'circle', 'rect', 'roundRect', 'triangle', 'diamond', 'pin', 'arrow'

也可以通过 'image://url' 设置为图片，其中 url 为图片的链接，或者 dataURI。

可以通过 'path://' 将图标设置为任意的矢量路径。这种方式相比于使用图片的方式，不用担心因为缩放而产生锯齿或模糊，而且可以设置为任意颜色。路径图形会自适应调整为合适的大小。路径的格式参见 SVG PathData。可以从 Adobe Illustrator 等工具编辑导出。

timeline.symbolSize

number, Array [ 默认值 10 ]

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

timeline.symbolRotate

number timeline 标记的旋转角度。

注意在 markLine 中当 symbol 为 'arrow' 时会忽略 symbolRotate 强制设置为切线的角度。

timeline.symbolOffset

Array [ 默认值 [0, 0] ]

timeline 标记相对于原本位置的偏移。默认情况下，标记会居中置放在数据对应的位置，但是如果 symbol 是自定义的矢量路径或者图片，就有可能不希望 symbol 居中。这时候可以使用该配置项配置 symbol 相对于原本居中的偏移，可以是绝对的像素值，也可以是相对的百分比。

例如 [0, '50%'] 就是把自己向上移动了一半的位置，在 symbol 图形是气泡的时候可以让图形下端的箭头对准数据点。