区域选择组件（brush）

brush

ECharts 图表的区域选择组件 brush 可以用来选择图表中的某部分的数据，并将所选择的数据展示给用户，或者可以展示一些统计的计算结果，这样的操作具有较大的方便性。

brush 的类型和启动按钮

目前 brush 组件支持的图表类型：scatter、bar、candlestick（parallel 本身自带刷选功能，但并非由 brush 组件来提供）。

点击 toolbox 中的按钮，能够进行『区域选择』、『清除选择』等操作。

以下是一个横向 brush 示例（点击 toolbox 中的按钮启动刷选）：

bar 图中的 brush（点击 toolbox 中的按钮启动刷选）：

启动 brush 的按钮既可以在 toolbox 中指定（参见 toolbox.feature.brush.type），也可以在 brush 组件的配置中指定（参见 brush.toolbox）。

brush 的按钮支持的选框有：矩形 brush，任意形状 brush，横向 brush，纵向 brush。参见 brush.toolbox。

您可以使用“保持选择”按钮，切换到单选和多选模式。

• 单选即同时只能存在一个选框，可单击空白区域消除选框。
• 多选即同时可存在多个选框，单击空白区域不能消除选框，需要点击『清除按钮』消除线框。

brush 和坐标系的关系

可以设置 brush 是『全局的』还是『属于坐标系的』。

1、全局 brush：

在 echarts 实例中任意地方刷选。这是默认情况。如果没有指定为『坐标系 brush』，就是『全局 brush』。

2、坐标系 brush：

在指定的坐标系中刷选。选框可以跟随坐标系的缩放和平移（roam 和 dataZoom）而移动。

坐标系 brush 实际更为常用，尤其是在 geo 中。

通过指定 brush.geoIndex 或 brush.xAxisIndex 或 brush.yAxisIndex 来规定可以在哪些坐标系中进行刷选。

这几个配置项的取值可以是：

• 'all'，表示所有
• number，如 0，表示这个 index 所对应的坐标系。
• Array，如 [0, 4, 2]，表示指定这些 index 所对应的坐标系。
• 'none' 或 null 或 undefined，表示不指定。

例如：

option = {
    geo: {
        ...
    },
    brush: {
        geoIndex: 'all', // 只可以在所有 geo 坐标系中刷选，也就是上面定义的 geo 组件中。
        ...
    }
};

例如：

option = {
    grid: [
        {...}, // grid 0
        {...}  // grid 1
    ],
    xAxis: [
        {gridIndex: 1, ...}, // xAxis 0，属于 grid 1。
        {gridIndex: 0, ...}  // xAxis 1，属于 grid 0。
    ],
    yAxis: [
        {gridIndex: 1, ...}, // yAxis 0，属于 grid 1。
        {gridIndex: 0, ...}  // yAxis 1，属于 grid 0。
    ],
    brush: {
        xAxisIndex: [0, 1], // 只可以在 xAxisIndex 为 `0` 和 `1` 的 xAxis 所在的直角坐标系中刷选。
        ...
    }
};

使用 API 控制选框 可以通过调用 dispatchAction 来用程序主动渲染选框，例如：

myChart.dispatchAction({
    type: 'brush',
    areas: [
        {
            geoIndex: 0,
            // 指定选框的类型。
            brushType: 'polygon',
            // 指定选框的形状。
            coordRange: [[119.72,34.85],[119.68,34.85],[119.5,34.84],[119.19,34.77]]
        }
    ]
});

brushLink

不同系列间，选中的项可以联动。

参见如下效果（刷选一个 scatter，其他 scatter 以及 parallel 图都会有选中效果）： brushLink 配置项是一个数组，内容是 seriesIndex，指定了哪些 series 可以被联动。例如可以是：

• [3, 4, 5] 表示 seriesIndex 为 3, 4, 5 的 series 可以被联动。
• 'all' 表示所有 series 都进行 brushLink。
• 'none' 或 null 或 undefined 表示不启用 brushLink 功能。

注意:brushLink 是通过 dataIndex 进行映射，所以需要保证，联动的每个系列的 data 都是 index 对应的。

例如：

option = {
    brush: {
        brushLink: [0, 1]
    },
    series: [
        {
            type: 'bar'
            data: [232,    4434,    545,      654]     // data 有四个项
        },
        {
            type: 'parallel',
            data: [[4, 5], [3, 5], [66, 33], [99, 66]] // data 同样有四个项，两个系列的 data 是对应的。
        }
    ]
};

throttle / debounce / 事件延迟

默认情况，刷选或者移动选区的时候，会不断得发 brushSelected 事件，从而告诉外界选中的内容。

但是频繁的事件可能导致性能问题，或者动画效果很差。所以 brush 组件提供了 brush.throttleType，brush.throttleDelay 来解决这个问题。

throttleType 取值可以是：

• 'debounce'：表示只有停止动作了（即一段时间没有操作了），才会触发事件。时间阈值由 brush.throttleDelay 指定。

• 'fixRate'：表示按照一定的频率触发时间，时间间隔由 brush.throttleDelay 指定。

例如这个 例子，就是使用了 debounce的效果：只有用户停止动作了，柱状图才更新。不然的话，如果柱状图的频繁更新，那么动画效果很差。

被选中项和未被选中项的视觉设置