d3-brush

优质

小牛编辑

131浏览

2023-12-01

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

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

刷取操作也支持编程控制, 例如通过监听 Installing

使用 NPM 安装：npm install d3-brush. 还可以载最新版，此外还可以直接从 d3js.org 作为一个标准的库或作为 D3 4.0的一部分直接载入。支持 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

API Reference

"https://github.com/d3/d3-brush/blob/master/src/brush.js" title="Source" target="_blank" rel="noopener noreferrer"><源码>

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

"https://github.com/d3/d3-brush/blob/master/src/brush.js" title="Source" target="_blank" rel="noopener noreferrer"><源码>

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

"https://github.com/d3/d3-brush/blob/master/src/brush.js" title="Source" target="_blank" rel="noopener noreferrer"><源码>

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

"https://github.com/d3/d3-brush/blob/master/src/brush.js" title="Source" target="_blank" rel="noopener noreferrer"><源码>

将刷取交互应用到指定的 group(分组元素)上, group 必须是一个 SVG [G 元素的](https://www.w3.org/TR/SVG/struct.html"https://github.com/xswei/d3js_doc/blob/master/API_Reference/d3-selection/README.md" target="_blank" rel="noopener noreferrer">selection.call 来使用,例如：

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

在内部 brush 使用 selection.on 方法来注册刷取所必需的事件监听器. 事件监听器使用 .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=""https://github.com/d3/d3-brush/blob/master/src/brush.js" title="Source" target="_blank" rel="noopener noreferrer"><源码>
 通过编程的方式实现对刷取范围的调整,也就是将 group 的刷取范围设置为 selection. group 必须是一个SVG G 元素的的选择集或者过渡. 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 元素, 返回的数组决定了刷取的范围。
 "https://github.com/d3/d3-brush/blob/master/src/brush.js" title="Source" target="_blank" rel="noopener noreferrer"><源码>
 设置或获取刷取操作的可刷取范围, 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 和 height 属性,而不是使用CSS或者viewBox 属性; SVG没有现成的接口获取初始视口大小,但是可以通过element.getBoundingClientRect来计算获取(在Firefox中,element.clientWidth 和 element.clientHeight计算SVG元素的结果是 0 )
 brush的extemt(边界)决定了rect.overlay的大小,同时也确定了可刷取范围,超出这个区域的不能进行刷取操作.
 "https://github.com/d3/d3-brush/blob/master/src/brush.js" title="Source" target="_blank" rel="noopener noreferrer"><源码>
 如果设置了 filter 则将过滤器设置为指定的函数并返回刷取操作,如果没有指定,则返回当前的过滤器,默认为：
 function filter() {
  return !event.button;
}
如果过滤器返回假值,则忽略启动刷取的事件并且不进行刷取操作.因此过滤器用来决定哪些输入事件被忽略.默认情况下过滤器会忽略辅助按钮上的 mousedown 事件,因为这些按钮通常有其他用途.
 Brush Events 
当brush event listener被调用时, d3.event 被设置为当前的刷取事件对象.当前的event对象有以下几个属性:
 target - 触发 brush 行为的元素.
 type - 字符串 “start”, “brush” 或 “end”; 参考 brush.on.
 selection - 当前的刷取选择集.
 sourceEvent - 原始事件,比如mousemove 或 touchmove.