# d3-brush

刷取交互指在一维或二维空间内使用手势,比如点击然后拖拽鼠标拾取一块区域范围的操作.刷取操作经常用来选取一些离散的元素,比如散点图中的点或者桌面上的文件等等.它也可以被用来对感兴趣的区域进行放大操作,或者选择连续区域进行 cross-filtering data(交叉过滤数据) (opens new window):

(opens new window)

d3-brush模块的实现基于注册于 SVG (opens new window) 上的鼠标和触摸操作. 点击并且拖拽选区会对选区进行位置调整。点击并且拖拽选区的 handles(把手) 会调整对应的选区的边。点击并且拖拽隐藏的 overlay 会创建一个新的选区，按住 META (⌘) 键并点击可刷取范围内的点也会达到这种效果. 按住ALT (⌥)并移动鼠标时会已鼠标刚开始按下的点为中心调整已选中区域的大小,调整已选中区域大小的过程中按住 SPACE 时会将调整大小变为调整已选中区间位置,刷取过程中按住 shift 会固定刷取的方向.

刷取操作也支持编程控制, 例如通过监听 end events 事件, 然后对选中区间通过 brush.move 进行微调：

(opens new window)

或者点击已刷取外侧时重新对刷取范围进行位置调整：

(opens new window)

# Installing

使用 NPM 安装：npm install d3-brush. 还可以载最新版 (opens new window)，此外还可以直接从 d3js.org (opens new window) 作为一个标准的库 (opens new window) 或作为 D3 4.0 (opens new window)的一部分直接载入。支持 AMD，CommonJS 以及基本的标签引入形式，如果使用标签直接引入会暴露 d3 全局变量：

<script src="https://d3js.org/d3-color.v1.min.js"></script>
<script src="https://d3js.org/d3-dispatch.v1.min.js"></script>
<script src="https://d3js.org/d3-ease.v1.min.js"></script>
<script src="https://d3js.org/d3-interpolate.v1.min.js"></script>
<script src="https://d3js.org/d3-timer.v1.min.js"></script>
<script src="https://d3js.org/d3-selection.v1.min.js"></script>
<script src="https://d3js.org/d3-transition.v1.min.js"></script>
<script src="https://d3js.org/d3-drag.v1.min.js"></script>
<script src="https://d3js.org/d3-brush.v1.min.js"></script>
<script>

var brush = d3.brush();

</script>

在浏览器中测试d3-brush (opens new window)

# API Reference

# d3.brush() <源码> (opens new window)

创建一个新的二维刷取交互

# d3.brushX() <源码> (opens new window)

创建一个新的一维的 x - 方向的刷取交互

# d3.brushY() <源码> (opens new window)

创建一个新的一维的 y - 方向的刷取交互

# brush(group) <源码> (opens new window)

将刷取交互应用到指定的 group(分组元素)上, group 必须是一个 SVG [G 元素的](https://www.w3.org/TR/SVG/struct.html#Groups 选择集](https://github.com/xswei/d3js_doc/tree/master/API_Reference/d3-selection)(也可以直接应用到svg上,但是不建议这样用). 这个方法通常不直接调用,而是通过 selection.call (opens new window) 来使用,例如：

svg.append("g")
    .attr("class", "brush")
    .call(d3.brush().on("brush", brushed));

在内部 brush 使用 selection.on (opens new window) 方法来注册刷取所必需的事件监听器. 事件监听器使用 .brush 作为事件类名称, 所以当你需要取消选择集上的刷取事件监听器时,可以通过以下方式取消：

group.on(".brush", null);

刷取作会创建一些必要的 SVG 元素来显示刷取交互显示元素. 你可以添加, 移除或者修改这些元素的外观. 也可以将样式文件应用到这些元素上. 二维刷取所生成的元素结构如下:

<g class="brush" fill="none" pointer-events="all" style="-webkit-tap-highlight-color: rgba(0, 0, 0, 0);">
  <rect class="overlay" pointer-events="all" cursor="crosshair" x="0" y="0" width="960" height="500"></rect>
  <rect class="selection" cursor="move" fill="#777" fill-opacity="0.3" stroke="#fff" shape-rendering="crispEdges" x="112" y="194" width="182" height="83"></rect>
  <rect class="handle handle--n" cursor="ns-resize" x="107" y="189" width="192" height="10"></rect>
  <rect class="handle handle--e" cursor="ew-resize" x="289" y="189" width="10" height="93"></rect>
  <rect class="handle handle--s" cursor="ns-resize" x="107" y="272" width="192" height="10"></rect>
  <rect class="handle handle--w" cursor="ew-resize" x="107" y="189" width="10" height="93"></rect>
  <rect class="handle handle--nw" cursor="nwse-resize" x="107" y="189" width="10" height="10"></rect>
  <rect class="handle handle--ne" cursor="nesw-resize" x="289" y="189" width="10" height="10"></rect>
  <rect class="handle handle--se" cursor="nwse-resize" x="289" y="272" width="10" height="10"></rect>
  <rect class="handle handle--sw" cursor="nesw-resize" x="107" y="272" width="10" height="10"></rect>
</g>

其中 rect.overlay 表示由 brush.extent 定义的可刷取的整个区域. rect.selection 表示当前刷取选中的区域. handle.rect 表示已经刷取区域的边边角角, 用来定义事件以便对已刷取的区域进行微调. 以编程的方式对刷取范围进行调整请使用 brush.move.

# brush.move(group, selection) <源码> (opens new window)

通过编程的方式实现对刷取范围的调整,也就是将 group 的刷取范围设置为 selection. group 必须是一个SVG G 元素的 (opens new window)的选择集 (opens new window)或者过渡 (opens new window). selection 必须是一个数值类型的数组,或者 null(用以清空已选范围). 对于二维刷取来说,selection 必须是一个类似于 [[*x0*, *y0*], [*x1*, *y1*]] 的二维数组, x0 , y0 表示左上角坐标, x1, y1 表示右下角坐标. 如果刷取操作是一个 x - 方向的一维的,则 selection 为 [*x0*, *x1*] 表示 x 方向的一维区间,同理果是 y - 方向的, [y0, y1]也表示一个 y 方向的一维区间. 除此之外, selection 也可以是一个返回数组的方法, 这个方法会传递当前绑定的数据 d 和索引 i , 函数内部 this 表示当前的 DOM 元素, 返回的数组决定了刷取的范围。

# brush.extent([extent]) <源码> (opens new window)

设置或获取刷取操作的可刷取范围, extent 参数类似于 [[x0, y0], [x1, y1]], [x0, y0] 为左上角坐标, [x1, y1] 为右下角坐标. extent 也可以是一个返回数组的方法, 这个方法会传递当前绑定的数据 d 和索引 i, 方法内部 this 表示当前的 DOM 元素.如果没有指定则范湖当前刷取操作的可刷取范围,默认为当前元素所在的 SVG 的大小：

function extent() {
  var svg = this.ownerSVGElement || this;
  return [[0, 0], [svg.width.baseVal.value, svg.height.baseVal.value]];
}

默认的extent要求SVG有自己的width (opens new window) 和 height (opens new window) 属性,而不是使用CSS或者viewBox 属性; SVG没有现成的接口获取初始视口大小 (opens new window),但是可以通过element.getBoundingClientRect (opens new window)来计算获取(在Firefox中,element.clientWidth (opens new window) 和 element.clientHeight (opens new window)计算SVG元素的结果是 0 )

brush的extemt(边界)决定了rect.overlay的大小,同时也确定了可刷取范围,超出这个区域的不能进行刷取操作.

# brush.filter([filter]) <源码> (opens new window)

如果设置了 filter 则将过滤器设置为指定的函数并返回刷取操作,如果没有指定,则返回当前的过滤器,默认为：

function filter() {
  return !event.button;
}

如果过滤器返回假值,则忽略启动刷取的事件并且不进行刷取操作.因此过滤器用来决定哪些输入事件被忽略.默认情况下过滤器会忽略辅助按钮上的 mousedown 事件,因为这些按钮通常有其他用途.

# brush.handleSize([size]) <源码> (opens new window)

设置或获取调整刷取范围的把柄的大小. rect.handle 的大小,这个大小决定了鼠标距离 rect.selection 多远时就能触发调整操作.默认为 6px.这个方法必须在应用brush到selection之前执行.这个方法不会对已经渲染的刷取操作生效.

# brush.on(typenames[, listener]) <源码> (opens new window)

如果指定了listener句柄则将指定的句柄应用到对应的typenames事件类型上.如果typenames已经有句柄存在,则会被替换掉.如果listener为null则表示取消对应的typenames事件句柄.如果没有指定listener则返回对应的当前typenames上已经注册的句柄.

当触发一个事件时,对应的事件句柄将会被调用,其方式和参数与selection.on (opens new window)一样：当前绑定的数据d,索引i,this指向当前的DOM元素.

typenames是一个可以由空格分开的一个或多个typename.每个typename都可以由一个type可一个可选的name组成(由.连接).比如 brush.foo and brush.bar;这样就允许一种事件类型绑定多个事件句柄.type必须为以下几种：

start - 刷取事件开始,比如mousedown事件
brush - 刷取移动时,比如mousemove事件
end - 刷取结束时,比如mouseup事件

参考 dispatch.on (opens new window) 和 Brush Events 获取更多信息.

# d3.brushSelection(node) <源码> (opens new window)

返回指定node的刷取区间.在内部元素的刷取状态存储在element.__brush属性上；但是不能直接使用这个属性.如果给定的node没有应用刷取操作,则返回null.selection被定义为数组.对于二维刷取操作,由[[x0, y0], [x1, y1]]表示.对于一维的x 或 y方向刷取,则由[x0, x1] 和 [y0, y1]表示.

# Brush Events

当brush event listener被调用时, d3.event (opens new window) 被设置为当前的刷取事件对象.当前的event对象有以下几个属性:

target - 触发 brush 行为的元素.
type - 字符串 “start”, “brush” 或 “end”; 参考 brush.on.
selection - 当前的刷取选择集.
sourceEvent - 原始事件,比如mousemove 或 touchmove.

← d3-axis d3-chord →