d3-brush

Взаимодействие с областью выделения — это интерактивное определение одномерной или двумерной области выбора с помощью жестов указателя, таких как щелчок и перетаскивание мыши. Выделение часто используется для выбора отдельных элементов, таких как точки в диаграмме рассеяния или файлы на рабочем столе. Также оно может использоваться для приближения к области интереса или для выбора непрерывных областей для фильтрации данных по пересечению или живых гистограмм:

Mona Lisa Histogram

Модуль d3-brush реализует выделение для событий мыши и касания с использованием SVG. Щелкните и перетащите выделение области, чтобы переместить выделение. Щелкните и перетащите одну из маркеров выделения, чтобы переместить соответствующий край (или края) выделения. Щелкните и перетащите прозрачное наложение, чтобы определить новое выделение области, или щелкните где угодно внутри области выделения, удерживая клавишу META (⌘). Удержание клавиши ALT (⌥) при перемещении области выделения смещает её вокруг центра, а удержание клавиши ПРОБЕЛ фиксирует текущий размер области выделения, позволяя только перемещать её.

Области выделения также поддерживают программно управляемое изменение. Например, вы можете прослушивать события end, а затем инициировать переход с помощью brush.move, чтобы привязать выделение области к семантическим границам:

Brush Snapping

Или вы можете заставить область выделения центрироваться при щелчке за пределами текущего выделения:

Click-to-Recenter

Установка

Если вы используете NPM, npm install d3-brush. В противном случае, скачайте последнюю версию. Вы также можете загрузить её напрямую с d3js.org, как самостоятельную библиотеку или как часть D3 4.0. Поддерживаются среды AMD, CommonJS и vanilla. В vanilla-среде экспортируется глобальная переменная 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

d3.brush() Источник

Создаёт новую двумерную область выделения.

d3.brushX() Источник

Создаёт новую одномерную область выделения по оси x.

d3.brushY() Источник

Создаёт новую одномерную область выделения по оси y.

brush(group) Источник

Применяет область выделения к указанной группе group, которая должна быть выборкой SVG-элементов G. Эта функция обычно не вызывается напрямую и вызывается через selection.call. Например, чтобы отобразить область выделения:

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

Внутри область выделения использует 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="#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>

Прямоугольник overlay покрывает область выделения, определённую brush.extent. Прямоугольник selection покрывает область, определённую текущим выделением области. Прямоугольники handle покрывают края и углы выделения области, позволяя интерактивно изменять соответствующее значение в выделении области. Чтобы программно изменить выделение области, используйте brush.move.

brush.move(group, selection) Источник

Устанавливает активное выделение области выделения на указанную группу, которая должна быть выборкой или переходом SVG-элементов G. Выделение должно быть определено как массив чисел или null для очистки выделения. Для двумерной области выделения оно должно быть определено как [[x0, y0], [x1, y1]], где x0 — минимальное значение x, y0 — минимальное значение y, x1 — максимальное значение x, а y1 — максимальное значение y. Для x-области выделения оно должно быть определено как [x0, x1]; для y-области выделения — как [y0, y1]. Выделение также может быть указано как функция, которая возвращает такой массив; если функция, она вызывается для каждого выбранного элемента, принимая текущий элемент данных d и индекс i, с this контекстом как текущим DOM-элементом. Возвращаемый массив определяет выделение области для этого элемента.

brush.extent([extent]) Источник

Если extent указан, устанавливает область выделения в указанный массив точек [[x0, y0], [x1, y1]], где [x0, y0] — верхний левый угол, а [x1, y1] — нижний правый, и возвращает эту область выделения. Extent также может быть указан как функция, возвращающая такой массив; если функция, она вызывается для каждого выбранного элемента, принимая текущий элемент данных d и индекс i, с this контекстом как текущим DOM-элементом. Если extent не указан, возвращает текущий аксессор extent, по умолчанию:

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

Эта реализация по умолчанию требует, чтобы у родительского SVG-элемента были заданы атрибуты width и height, а не (например) CSS-свойства или атрибут viewBox; SVG не предоставляет программируемого метода для получения начального размера области просмотра. В качестве альтернативы, рассмотрите использование element.getBoundingClientRect. (В Firefox, element.clientWidth и element.clientHeight равны нулю для SVG-элементов!)

Область выделения определяет размер прозрачного наложения и также ограничивает область выделения; область выделения не может выйти за пределы области выделения.

brush.filter([filter]) Источник

Если filter указан, устанавливает фильтр в указанную функцию и возвращает область выделения. Если filter не указан, возвращает текущий фильтр, который по умолчанию:

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

Если фильтр возвращает ложное значение, инициирующее событие игнорируется, и жест области выделения не начинается. Таким образом, фильтр определяет, какие события ввода будут игнорироваться. Фильтр по умолчанию игнорирует события mousedown на дополнительных кнопках, так как эти кнопки обычно предназначены для других целей, таких как контекстное меню.

brush.handleSize([size]) Источник

Если size указан, устанавливает размер маркеров выделения в указанное число и возвращает область выделения. Если size не указан, возвращает текущий размер маркера, который по умолчанию равен шести. Этот метод должен быть вызван перед применением области выделения к выборке; изменение размера маркеров не влияет на области выделения, которые были ранее отображены.

brush.on(typenames[, listener]) Источник

Если listener указан, устанавливает обработчик событий listener для указанных typenames и возвращает область выделения. Если обработчик событий уже был зарегистрирован для того же типа и имени, существующий обработчик удаляется перед добавлением нового обработчика. Если listener равен null, удаляются текущие обработчики событий для указанных typenames, если таковые есть. Если listener не указан, возвращает первый текущий обработчик, соответствующий указанным typenames, если таковой есть. При отправке указанного события каждый listener будет вызван с тем же контекстом и аргументами, что и обработчики selection.on: текущий элемент данных d и индекс i, с this контекстом как текущим DOM-элементом.

Typenames — это строка, содержащая одно или несколько имён typename, разделённых пробелами. Каждое typename — это тип, необязательно после которого следует точка (.) и имя, например brush.foo и brush.bar; имя позволяет регистрировать несколько обработчиков для одного типа. Тип должен быть одним из следующих:

start — в начале жеста области выделения, например, при mousedown.
brush — когда область выделения перемещается, например, при mousemove.
end — в конце жеста области выделения, например, при mouseup.

См. dispatch.on и События области выделения для получения более подробной информации.

d3.brushSelection(node) Источник

Возвращает текущий выбор кисти для указанного узла. Внутренне, состояние кисти элемента хранится как element.__brush; однако, вы должны использовать этот метод, а не обращаться к нему напрямую. Если у данного узла нет выбора, возвращает null. В противном случае, выбор определяется как массив чисел. Для двумерной кисти он представляет собой [[x0, y0], [x1, y1]], где x0 — минимальное значение x, y0 — минимальное значение y, x1 — максимальное значение x, а y1 — максимальное значение y. Для x-кисти он равен [x0, x1]; для y-кисти он равен [y0, y1].

События кисти

Когда вызывается обработчик событий кисти обработчик событий кисти, d3.event устанавливается на текущее событие кисти. Объект события предоставляет несколько полей:

target - связанное поведение кисти.
type - строка “start”, “brush” или “end”; см. brush.on.
selection - текущий выбор кисти.
sourceEvent - основное событие ввода, например, mousemove или touchmove.