d3-brush

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

Mona Lisa Histogram

Модуль d3-brush реализует выделение (brushing) для событий мыши и касания с помощью 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 не указан, возвращает текущую функцию доступа к области, которая по умолчанию:

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-элементов!)

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

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 — это type, необязательно после которого следует точка (.) и name, например brush.foo и brush.bar; имя позволяет регистрировать несколько обработчиков для одного type. Type должен быть одним из следующих:

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.