Параметры выделения

// Спецификация отдельного представления
{
  ...,
  "params": [ // Массив именованных параметров
    {
      "name": ...,
      "select": { // Определение выделения
        "type": ...,
        ...
      }
    }
  ],
  "mark": ...,
  "encoding": ...,
  ...
}

Параметр выделения превращает действия пользователя, например щелчки и перетаскивание, в запрос к данным. Для его создания добавьте свойство select к параметру. На этой странице описаны свойства объекта select.

Содержание страницы

Общие свойства выделений

Точечное и интервальное выделения поддерживают следующие свойства:

Свойство Тип Описание
type "point", "interval" Обязательное. Определяет стандартную обработку событий и запрос к данным. "point" выбирает несколько дискретных значений: первое — щелчком, последующие добавляются или удаляются щелчком с Shift. "interval" выбирает непрерывный диапазон перетаскиванием.
encodings SingleDefUnitChannel[] Массив каналов кодирования. Значения соответствующих полей данных должны совпадать, чтобы запись принадлежала выделению. См. проекцию через encodings и fields.
fields FieldName[] Массив имён полей, значения которых должны совпадать, чтобы запись принадлежала выделению. См. проекцию через encodings и fields.
on Stream, string Поток событий Vega — объект или селектор, запускающий выделение. Для интервального выделения поток должен задавать начальное и конечное события. См. примеры on.
clear Stream, string, boolean Очищает выделение, удаляя все значения. Принимает поток событий Vega либо false, чтобы отключить очистку. По умолчанию: dblclick. См. примеры clear.
resolve SelectionResolution В многослойных и составных представлениях задаёт способ объединения запросов выделений при фильтрации, условном кодировании или задании области значений шкалы.
"global" — один прямоугольник выделения на всю матрицу SPLOM; начало нового перетаскивания очищает предыдущие выделения.
"union" — у каждой ячейки свой прямоугольник; точка выделена, если попадает хотя бы в один.
"intersect" — у каждой ячейки свой прямоугольник; точка выделена, если попадает во все.
По умолчанию: "global". См. примеры resolve.

Тип type

Тип выделения определяет, какие значения считаются выбранными по умолчанию:

  • При "point" выбираются значения, с которыми пользователь взаимодействовал непосредственно, например щёлкнул по ним.
  • При "interval" выбираются значения, которые попадают одновременно в горизонтальный (x) и вертикальный (y) диапазоны выделения.

Проекция выделения: encodings и fields

Проекция определяет, по каким полям данных или каналам кодирования проверять принадлежность записи выделению. На диаграмме рассеяния ниже попробуйте разные сочетания полей Cylinders и Origin:

Выделять по полям: .

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

Ограничить выделение измерениями: .

Ограничения проекции

  • Выделения, проецируемые на агрегированные поля или каналы, можно применять только в том представлении, где они определены.
  • Интервальное выделение проецируется только через encodings.
  • Интервальное выделение по полю, разбитому на интервалы (bin) или преобразованному через timeUnit, остаётся непрерывным. Поэтому условное кодирование перестаёт работать, если визуальное кодирование делает поле дискретным. Используйте слои, как в примере ниже: столбцы дискретизируют разбитое на интервалы поле Acceleration, поэтому выбранные столбцы подсвечиваются вторым слоем, а не условным кодированием цвета в том же представлении.

Событие on

Свойство on меняет событие, запускающее выделение. Оно принимает селектор потока событий Vega. Для точечного выделения достаточно одного события, например pointerover или click; для интервального поток должен включать начало и конец действия.

Ниже ячейка тепловой карты выбирается при наведении указателя:

"select": {"type": "point", "on": "pointerover"}

Очистка clear

Свойство clear задаёт событие, после которого выделение опустошается. Значение по умолчанию — dblclick. Можно указать другой поток событий или false, чтобы отключить очистку. Поведение пустого выделения дополнительно регулируется свойством empty предиката.

Здесь ячейка выбирается щелчком и очищается двойным щелчком:

В следующем примере прямоугольник выделения очищается при отпускании кнопки мыши:

"select": {"type": "interval", "clear": "pointerup"}

Очистка не возвращает обычное выделение к начальному значению: оно становится пустым. При привязке выделения к шкалам очистка ведёт себя иначе и восстанавливает исходные области значений шкал. Переместите и масштабируйте диаграмму, затем дважды щёлкните по ней:

Объединение resolve

В панельной или повторённой диаграмме каждое представление может иметь своё выделение. Например, в матрице диаграмм рассеяния нужно решить, будет ли один прямоугольник на всю матрицу или отдельный в каждой ячейке.

  • "global" — значение по умолчанию: во всей матрице существует одно выделение; создание нового удаляет предыдущее.
  • "union" — в каждой ячейке своё выделение; точка подсвечивается, если попадает хотя бы в одно из них.
  • "intersect" — в каждой ячейке своё выделение; точка подсвечивается, если попадает во все выделения.

Нажмите на название режима выше и перетащите прямоугольники в разных ячейках.

Свойства точечного выделения

Помимо общих свойств, точечному выделению доступны:

Свойство Тип Описание
toggle string, boolean Управляет добавлением и удалением значений из точечного выделения.
true — стандартное поведение, соответствующее выражению "event.shiftKey": значения переключаются при взаимодействии с удерживаемой Shift.
false — переключение отключено; выделение содержит только одно значение, соответствующее последнему взаимодействию.
Выражение Vega пересчитывается при взаимодействии. При результате true значение добавляется или удаляется; при false выделение сначала очищается, затем значение добавляется. Например, выражение "true" переключает значения без удерживания Shift.
По умолчанию: true. См. примеры toggle.
nearest boolean При true вычисляется невидимая диаграмма Вороного, ускоряющая дискретное выделение. В выделение добавляется значение, ближайшее к указателю мыши. По умолчанию: false — для добавления требуется непосредственное взаимодействие со значением, например щелчок. См. примеры nearest.

Переключение toggle

toggle управляет добавлением значения в выделение и удалением уже выбранного значения. Ниже попробуйте щёлкать по точкам, удерживая разные клавиши:

Переключать выбранные точки при щелчке с клавишами: .

Ближайшая точка nearest

При nearest: true невидимая диаграмма Вороного ускоряет выбор ближайшей точки. Сравните два варианта: наведение на ближайшую точку и наведение непосредственно на точку.

nearest учитывает и проекцию на позиционные каналы. Ниже вертикальная линия и подпись привязываются к ближайшему значению date:

Текущие ограничения

Свойство nearest не поддерживает многосоставные графические примитивы line и area. Для них можно наложить отдельный точечный слой с opacity: 0, как в предыдущем примере.

Свойства интервального выделения

Помимо общих свойств, интервальному выделению доступны:

Свойство Тип Описание
mark BrushConfig Интервальное выделение добавляет прямоугольный примитив, показывающий границы интервала. Свойство mark настраивает его внешний вид. См. примеры mark.
translate string, boolean При истинном значении позволяет интерактивно перемещать интервальное выделение. Принимает true, false (отключить перемещение) или определение потока событий Vega с начальным и конечным событиями для непрерывного перемещения. Дискретное перемещение, например клавишами со стрелками, заявлено для будущих версий.
По умолчанию: true, соответствующее [pointerdown, window:pointerup] > window:pointermove!. Щелчок и перетаскивание внутри выделения перемещают его. См. примеры translate.
zoom string, boolean При истинном значении позволяет интерактивно менять размер интервального выделения. Принимает true, false (отключить масштабирование) или определение потока событий Vega. Поддерживаются только события wheel, но собственные потоки могут задавать фильтрацию, задержку после серии событий (debounce) и ограничение частоты (throttle). Расширение набора событий заявлено для будущих версий.
По умолчанию: true, соответствующее wheel!: размер выделения меняется колёсиком мыши. См. примеры zoom.

Прямоугольник mark

Интервальное выделение добавляет на диаграмму прямоугольник, показывающий его границы. Свойство mark позволяет настроить его вид:

Свойство Тип Описание
cursor Cursor Указатель мыши над прямоугольником интервала. Допускается любой допустимый CSS-тип указателя.
fill Color Цвет заливки прямоугольника интервала. По умолчанию: "#333333".
fillOpacity number Непрозрачность заливки от 0 до 1. По умолчанию: 0.125.
stroke Color Цвет обводки прямоугольника интервала. По умолчанию: "#ffffff".
strokeOpacity number Непрозрачность обводки от 0 до 1.
strokeWidth number Толщина обводки прямоугольника интервала.
strokeDash number[] Массив чередующихся длин штрихов и промежутков для пунктирных и точечных линий.
strokeDashOffset number Смещение начала рисунка штриховки обводки, в пикселях.

В примере два пользователя, Алекс и Морган, могут создавать отдельные выделения. Морган должен удерживать Shift, а Алекс — создавать выделение без Shift, чтобы выделения не конфликтовали. Выделение Алекса показано стандартным серым прямоугольником, а Моргана — настроенным прямоугольником с красной обводкой:

Перемещение translate

Свойство translate позволяет перемещать выделенную область. Укажите false, чтобы отключить перемещение, true для стандартного перетаскивания или поток событий Vega для собственного жеста. Например, перетаскивание только с Shift:

"select": {
  "type": "interval",
  "translate": "[pointerdown[event.shiftKey], window:pointerup] > window:pointermove!"
}

Сравните перемещение прямоугольника и всей диаграммы обычным перетаскиванием и с Shift:

Перемещать при .

Масштабирование zoom

Свойство zoom позволяет изменять размер интервального выделения. Значение false отключает масштабирование, стандартное true использует событие wheel!, а собственный поток событий может требовать клавишу-модификатор. Например:

"select": {
  "type": "interval",
  "zoom": "wheel![event.shiftKey]"
}

Попробуйте масштабировать область или всю диаграмму колёсиком мыши с Shift и без него:

Масштабировать с помощью .